ksconf package¶
Create a Splunk app or add on tarball (.spl
) file from an app directory.
ksconf package
can do useful things like, exclude unwanted files, combine layers, set the
application version and build number, drop or promote the local
directory into default
.
Note that some arguments, like the FILE
support special values that can be automatically
evaluated at runtime. For example the placeholders {{version}}
or {{git_tag}}
can be
expanded into the output tarball filename.
usage: ksconf package [-h] [-f SPL] [--app-name APP_NAME]
[--blocklist BLOCKLIST] [--allowlist ALLOWLIST]
[--layer-method {auto,dir.d,disable}] [-I PATTERN]
[-E PATTERN] [--follow-symlink] [--set-version VERSION]
[--set-build BUILD]
[--allow-local | --block-local | --merge-local]
[--release-file RELEASE_FILE]
SOURCE
Positional Arguments¶
SOURCE | Source directory for the Splunk app. |
Named Arguments¶
-f, --file | Name of splunk app file (tarball) to create. Placeholder variables in {{var}} syntax can be used here. |
--app-name | Specify the top-level app folder name. If this is not given, the app folder name is automatically extracted from the basename of SOURCE. |
--blocklist, -b | |
Pattern for files/directories to exclude. Can be given multiple times. You can load multiple exclusions from disk by using file://path which can be used with .gitignore for example. (Default includes: .git* , *.py[co] , __pycache__ , .DS_Store ) | |
--allowlist, -w | |
Remove a pattern that was previously added to the blocklist. | |
--follow-symlink, -l | |
Follow symbolic links pointing to directories. Symlinks to files are always followed. | |
--set-version | Set application version. By default the application version is read from default/app.conf. Placeholder variables such as {{git_tag}} can be used here. |
--set-build | Set application build number. |
--allow-local | Allow the local folder to be kept as-is WARNING: This goes against Splunk packaging practices, and will cause AppInspect to fail. However, this option can be useful for private package transfers between servers, app backups, or other admin-like tasks. |
--block-local | Block the local folder and local.meta from the package. |
--merge-local | Merge any files in local into the default folder during packaging. This is the default behavior. |
Layer filtering¶
If the app being packaged includes multiple layers, these arguments can be used to control which ones should be included in the final app file. If no layer options are specified, then all layers will be included.
--layer-method | Possible choices: auto, dir.d, disable Set the layer type used by SOURCE. Additional description provided in in the |
-I, --include | Name or pattern of layers to include. |
-E, --exclude | Name or pattern of layers to exclude from the target. |
Advanced Build Options¶
The following options are for more advanced app building workflows.
--release-file | Write the path of the newly generated archive file (SPL) after the archive is written. This is useful in build scripts when the SPL contains variables so the final name may not be known ahead of time. |
Variables¶
The following variables are currently available for use during package building.
These are referenced using the {{var}}
syntax.
See the implementation in AppVarMagic
if you’d like to contribute additional variables.
Supported Variables
Variable Source Notes build
app.conf Get build
from[install]
inapp.conf
version
app.conf Get version
from[launcher]
inapp.conf
git_tag
git Run git describe --tags --always --dirty
git_latest_rev
git Run git log -n1 --pretty=format:%h -- .
git_head
git Run git rev-parse --short HEAD
Example¶
ksconf package -f my_app.tgz MyApp
A more realistic example where the version number in app.conf
is managed by some external process, possibly a tool like bumpversion
.
bumpversion minor
ksconf package -f dist/my_app-{{version}}.tgz MyApp --release-file=.artifact
echo "Build complete, upload $(<.artifact) to SplunkBase"
This will output a message like: Build complete, upload dist/my_app-1.2.3.tgz to SplunkBase
And of course this workflow could be further automated using Splunkbase API calls.
See also¶
More sophisticated builds can be achieved using the BuildManager