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 andlocal.meta
from the package.- --merge-local
Merge any files in
local
into thedefault
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]
inapp.conf
. This must be the app folder name for any app published to Splunkbase.
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
. Common prefixes are removed such asv
orrelease-
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.
See also
More sophisticated builds can be achieved using the BuildManager