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 combine command.

-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] in app.conf
version app.conf Get version from [launcher] in app.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