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.

If both layering and templating are in use at the same time, be aware that templates are rendered prior to layering operations. This allows, for example, one layer to include a simple indexes.conf file and another layer to include an indexes.conf.j2 template.

usage: ksconf package [-h] [-f SPL] [--app-name APP_NAME]
                      [--blocklist BLOCKLIST] [--allowlist ALLOWLIST]
                      [--layer-method {dir.d,disable}] [-I PATTERN]
                      [-E PATTERN] [--enable-handler {jinja}]
                      [--template-vars TEMPLATE_VARS] [--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. Placeholder variables, such as {{app_id}} can be used here.

--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, -a

Remove a pattern that was previously added to the blocklist.

--enable-handler

Possible choices: jinja

Enable optional file handling support

--template-vars

Set template variables as key=value or YAML/JSON, if filename prepend with @

--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: 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

app_id

app.conf

Get id from [package] in app.conf. This must be the app folder name for any app published to Splunkbase.

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. Common prefixes are removed such as v or release- from the tag name.

git_last_rev

git

Run git log -n1 --pretty=format:%h -- .

git_head

git

Run git rev-parse --short HEAD

layers_list

layers

List of unique ksconf layers used to build the app. Layers are separated by an double underscores (__). If no layers were used then an empty string is returned.

layers_hash

layers

Unique hash of unique ksconf layers used. This is a truncated SHA256 of the layers_list variable.

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 MyApp \
    --set-version={{git_tag}} \
    -f dist/my_app-{{version}}.tgz \
    --release-file=.artifact
echo "Build complete, upload $(<.artifact) to SplunkBase"

This will output a message like: Build complete, upload dist/my_app-1.3.0.tgz to SplunkBase

And of course this workflow could be further automated using Splunkbase API calls.