CLI Reference | .kapitan config file
.kapitan
Kapitan allows you to coveniently override defaults by specifying a local .kapitan file — also written dot-kapitan or dot kapitan — in the root of your repository (relative to the kapitan configuration):
This comes handy to make sure Kapitan runs consistently for your specific setup.
Info
Any Kapitan command can be overridden in the .kapitan dotfile, but here are some of the most common examples.
version
To enforce the Kapitan version used for compilation (for consistency and safety), you can add version to .kapitan:
version: 0.30.0
...
This constrain can be relaxed to allow minor versions to be also accepted:
version: 0.30 # Allows any 0.30.x release to run
...
Command line flags
You can also permanently define all command line flags in the .kapitan config file. For example:
...
compile:
indent: 4
parallelism: 8
would be equivalent to running:
kapitan compile --indent 4 --parallelism 8
For flags which are shared by multiple commands, you can either selectively define them for single commmands in a section with the same name as the command, or you can set any flags in section global, in which case they're applied for all commands.
If you set a flag in both the global section and a command's section, the value from the command's section takes precedence over the value from the global section.
As an example, you can configure the inventory-path in the global section of the Kapitan dotfile to make sure it's persisted across all Kapitan runs.
...
global:
inventory-path: ./some_path
which would be equivalent to running any command with --inventory-path=./some_path.
Another flag that you may want to set in the global section is inventory-backend to select a non-default inventory backend implementation.
global:
inventory-backend: reclass
which would be equivalent to always running Kapitan with --inventory-backend=reclass.
Please note that the inventory-backend flag currently can't be set through the command-specific sections of the Kapitan config file.
Full flag reference
The tables below are generated directly from Kapitan's argument parser at docs-build time, so they always match the installed version. Each section maps to a top-level key in .kapitan: set a flag under the matching command, or under global to apply it to every command.
global
| Key | Default | Description |
|---|---|---|
mp-method |
spawn |
set multiprocessing start method |
profile |
False |
enable CPU profiling via pyinstrument for the parent process |
profile-workers |
False |
also CPU-profile multiprocessing workers; one report per worker PID. Requires --profile. |
profile-serial |
False |
run target compilation serially in the parent process (no multiprocessing.Pool). Produces a single unified pyinstrument report with full call-stack depth. Slower wall-clock but the only way to see all stacks (including kadet/jinja/jsonnet internals) in one flame graph. Implies/pairs well with --profile. |
profile-format |
html |
pyinstrument output format (default: html) |
profile-interval |
0.001 |
pyinstrument sampling interval in seconds (default: 0.001) |
profile-output-dir |
kapitan-profiles |
directory for profile reports (default: ./kapitan-profiles) |
memory-profile |
False |
enable memory profiling via tracemalloc; writes a top-N text report |
memory-profile-top |
30 |
number of top allocators to include in the memory report (default: 30) |
eval
| Key | Default | Description |
|---|---|---|
output |
yaml |
set output format, default is "yaml" |
vars |
set variables | |
search-paths |
["."] |
set search paths, default is ["."] |
compile
| Key | Default | Description |
|---|---|---|
inventory-backend |
reclass |
Select the inventory backend to use (default=reclass) |
migrate |
False |
Migrate your inventory to your selected inventory backend. |
compose-target-name |
False |
Create same subfolder structure from inventory/targets inside compiled folder |
enable-class-wildcards |
False |
Enable glob pattern expansion in classes: lists (default: off). Patterns such as clusters., dev- and * are expanded to all matching class names discovered under inventory/classes/. This flag is intentionally opt-in: inventories that contain literal glob metacharacters in class names (e.g. config[html]) or Reclass references that include ? would be incorrectly treated as patterns if expansion were always on. |
search-paths |
[".", "lib"] |
set search paths, default is ["."] |
jinja2-filters |
lib/jinja2_filters.py |
load custom jinja2 filters from any file, default is to put them inside lib/jinja2_filters.py |
verbose |
False |
set verbose mode |
prune |
False |
prune jsonnet output |
quiet |
False |
set quiet mode, only critical output |
output-path |
. |
set output path, default is "." |
fetch |
False |
fetch remote inventories and/or external dependencies |
force-fetch |
False |
overwrite existing inventory and/or dependency item |
force |
False |
overwrite existing inventory and/or dependency item |
validate |
False |
validate compile output against schemas as specified in inventory |
parallelism |
Number of concurrent compile processes, default is min(len(targets), available CPU count) | |
indent |
2 |
Indentation spaces for YAML/JSON, default is 2 |
refs-path |
./refs |
set refs path, default is "./refs" |
reveal |
False |
reveal refs (warning: this will potentially write sensitive data) |
embed-refs |
False |
embed ref contents |
inventory-path |
./inventory |
set inventory path, default is "./inventory" |
inventory-pool-cache |
True |
enable passing inventory object cache to process pool, setting to False might speed up compilation for large inventories, default is True |
cache |
False |
enable compilation caching to $XDG_CACHE_HOME/kapitan, default is False [this is EXPERIMENTAL] |
ignore-version-check |
False |
ignore the version from .kapitan |
use-go-jsonnet |
False |
use go-jsonnet |
schemas-path |
./schemas |
set schema cache path, default is "./schemas" |
yaml-multiline-string-style |
literal |
set multiline string style to STYLE, default is 'literal' |
yaml-dump-null-as-empty |
False |
dumps all none-type entries as empty, default is dumping as 'null' |
yaml-use-rapidyaml |
False |
use the rapidyaml emitter, fallback to PyYaml if rapidyaml not installed, default is False |
targets |
targets to compile, default is all | |
labels |
compile targets matching the labels, default is all |
inventory
| Key | Default | Description |
|---|---|---|
inventory-backend |
reclass |
Select the inventory backend to use (default=reclass) |
migrate |
False |
Migrate your inventory to your selected inventory backend. |
compose-target-name |
False |
Create same subfolder structure from inventory/targets inside compiled folder |
enable-class-wildcards |
False |
Enable glob pattern expansion in classes: lists (default: off). Patterns such as clusters., dev- and * are expanded to all matching class names discovered under inventory/classes/. This flag is intentionally opt-in: inventories that contain literal glob metacharacters in class names (e.g. config[html]) or Reclass references that include ? would be incorrectly treated as patterns if expansion were always on. |
target-name |
set target name, default is all targets | |
inventory-path |
./inventory |
set inventory path, default is "./inventory" |
flat |
False |
flatten nested inventory variables |
pattern |
filter pattern (e.g. parameters.mysql.storage_class, or storage_class, or storage_*), default is "" | |
verbose |
False |
set verbose mode |
indent |
2 |
Indentation spaces for inventory output, default is 2 |
topics |
show aggregated topics instead of target inventory | |
multiline-string-style |
double-quotes |
set multiline string style to STYLE, default is 'double-quotes' |
searchvar
| Key | Default | Description |
|---|---|---|
inventory-path |
./inventory |
set inventory path, default is "./inventory" |
verbose |
False |
set verbose mode |
pretty-print |
False |
Pretty print content of var |
refs
| Key | Default | Description |
|---|---|---|
inventory-backend |
reclass |
Select the inventory backend to use (default=reclass) |
migrate |
False |
Migrate your inventory to your selected inventory backend. |
compose-target-name |
False |
Create same subfolder structure from inventory/targets inside compiled folder |
enable-class-wildcards |
False |
Enable glob pattern expansion in classes: lists (default: off). Patterns such as clusters., dev- and * are expanded to all matching class names discovered under inventory/classes/. This flag is intentionally opt-in: inventories that contain literal glob metacharacters in class names (e.g. config[html]) or Reclass references that include ? would be incorrectly treated as patterns if expansion were always on. |
write |
write ref token | |
update |
update GPG recipients for ref token | |
update-targets |
False |
update target secret refs |
validate-targets |
False |
validate target secret refs |
base64 |
False |
base64 encode file content |
binary |
False |
file content should be handled as binary data |
reveal |
False |
reveal refs |
tag |
specify ref tag to reveal, e.g. "?{gkms:my/ref:123456}" | |
ref-file |
read ref file, set "-" for stdin | |
file |
read file or directory, set "-" for stdin | |
target-name |
grab recipients from target name | |
inventory-path |
./inventory |
set inventory path, default is "./inventory" |
recipients |
set GPG recipients | |
key |
set KMS key | |
vault-auth |
set authentication type for vault secrets | |
vault-mount |
secret |
set mount point for vault secrets, default is 'secret' |
vault-path |
set path for vault secrets where the secret gets stored on vault, default is the secret_path | |
vault-key |
set key for vault secrets | |
refs-path |
./refs |
set refs path, default is "./refs" |
verbose |
False |
set verbose mode (warning: this will potentially show sensitive data) |
lint
| Key | Default | Description |
|---|---|---|
fail-on-warning |
False |
exit with failure code if warnings exist, default is False |
skip-class-checks |
False |
skip checking for unused classes, default is False |
skip-yamllint |
False |
skip running yamllint on inventory, default is False |
search-secrets |
False |
searches for plaintext secrets in inventory, default is False |
refs-path |
./refs |
set refs path, default is "./refs" |
compiled-path |
./compiled |
set compiled path, default is "./compiled" |
inventory-path |
./inventory |
set inventory path, default is "./inventory" |
init
| Key | Default | Description |
|---|---|---|
directory |
./ |
set path, in which to generate the project skeleton,assumes directory already exists. default is "./" |
template_git_url |
https://github.com/kapicorp/kapitan-reference.git |
Cruft template_git_url, default is https://github.com/kapicorp/kapitan-reference.git |
checkout_ref |
copier |
Cruft checkout_ref, default is copier |