This is the multi-page printable view of this section. Click here to print.
kluctl offers a unified command line interface that allows to standardize all your deployments. Every project, no matter how different it is from other projects, is managed the same way.
You can always call kluctl --help or kluctl <command> --help for a help prompt.
Individual commands are documented in sub-sections.
A few sets of arguments are common between multiple commands. These arguments are still part of the command itself and must be placed after the command name.
These arguments are available for all commands.
Global arguments:
--cpu-profile string Enable CPU profiling and write the result to the given path
--debug Enable debug logging
--no-color Disable colored output
--no-update-check Disable update check on startup
These arguments are available for all commands that are based on a Kluctl project. They control where and how to load the kluctl project and deployment project.
Project arguments:
Define where and how to load the kluctl project and its components from.
-a, --arg stringArray Passes a template argument in the form of name=value. Nested args
can be set with the '-a my.nested.arg=value' syntax. Values are
interpreted as yaml values, meaning that 'true' and 'false' will
lead to boolean values and numbers will be treated as numbers. Use
quotes if you want these to be treated as strings. If the value
starts with @, it is treated as a file, meaning that the contents
of the file will be loaded and treated as yaml.
--args-from-file stringArray Loads a yaml file and makes it available as arguments, meaning that
they will be available thought the global 'args' variable.
--context string Overrides the context name specified in the target. If the selected
target does not specify a context or the no-name target is used,
--context will override the currently active context.
--git-cache-update-interval duration Specify the time to wait between git cache updates. Defaults to not
wait at all and always updating caches.
--local-git-group-override stringArray Same as --local-git-override, but for a whole group prefix instead
of a single repository. All repositories that have the given prefix
will be overridden with the given local path and the repository
suffix appended. For example,
'gitlab.com:some-org/sub-org=/local/path/to/my-forks' will override
all repositories below 'gitlab.com:some-org/sub-org/' with the
repositories found in '/local/path/to/my-forks'. It will however
only perform an override if the given repository actually exists
locally and otherwise revert to the actual (non-overridden) repository.
--local-git-override stringArray Specify a single repository local git override in the form of
'github.com:my-org/my-repo=/local/path/to/override'. This will
cause kluctl to not use git to clone for the specified repository
but instead use the local directory. This is useful in case you
need to test out changes in external git repositories without
pushing them.
-c, --project-config existingfile Location of the .kluctl.yaml config file. Defaults to
$PROJECT/.kluctl.yaml
--project-dir existingdir Specify the project directory. Defaults to the current working
directory.
-t, --target string Target name to run command for. Target must exist in .kluctl.yaml.
-T, --target-name-override string Overrides the target name. If -t is used at the same time, then the
target will be looked up based on -t <name> and then renamed to the
value of -T. If no target is specified via -t, then the no-name
target is renamed to the value of -T.
--timeout duration Specify timeout for all operations, including loading of the
project, all external api calls and waiting for readiness. (default
10m0s)
These arguments are available on some target based commands.
They control image versions requested by images.get_image(...)
calls
.
Image arguments:
Control fixed images and update behaviour.
-F, --fixed-image stringArray Pin an image to a given version. Expects
'--fixed-image=image<:namespace:deployment:container>=result'
--fixed-images-file existingfile Use .yaml file to pin image versions. See output of list-images
sub-command or read the documentation for details about the output format
--offline-images DEPRECATED: Omit contacting image registries and do not query for latest
image tags. This flag is by default set to true. At the same time, the
whole requesting of image tags from registries functionality is
deprecated and will be removed from kluctl in a future release. (default true)
-u, --update-images This causes kluctl to prefer the latest image found in registries, based
on the 'latest_image' filters provided to 'images.get_image(...)' calls.
Use this flag if you want to update to the latest versions/tags of all
images. '-u' takes precedence over '--fixed-image/--fixed-images-file',
meaning that the latest images are used even if an older image is given
via fixed images.
These arguments are available for some target based commands. They control inclusion/exclusion based on tags and deployment item pathes.
Inclusion/Exclusion arguments:
Control inclusion/exclusion.
--exclude-deployment-dir stringArray Exclude deployment dir. The path must be relative to the root
deployment project. Exclusion has precedence over inclusion, same as
in --exclude-tag
-E, --exclude-tag stringArray Exclude deployments with given tag. Exclusion has precedence over
inclusion, meaning that explicitly excluded deployments will always
be excluded even if an inclusion rule would match the same deployment.
--include-deployment-dir stringArray Include deployment dir. The path must be relative to the root
deployment project.
-I, --include-tag stringArray Include deployments with given tag.
In addition to arguments, Kluctl can be controlled via a set of environment variables.
All options/arguments accepted by kluctl can also be specified via environment variables. The name of the environment
variables always start with KLUCTL_ and end with the option/argument in uppercase and dashes replaced with
underscores. As an example, --dry-run can also be specified with the environment variable
KLUCTL_DRY_RUN=true.
If an argument needs to be specified multiple times through environment variables, indexed can be appended to the
names of the environment variables, e.g. KLUCTL_ARG_0=name1=value1 and KLUCTL_ARG_1=name2=value2.
A few additional environment variables are supported which do not belong to an option/argument. These are:
KLUCTL_REGISTRY_<idx>_HOST, KLUCTL_REGISTRY_<idx>_USERNAME, and so on. See
registries
for details.KLUCTL_GIT_<idx>_HOST, KLUCTL_GIT_<idx>_USERNAME, and so on.KLUCTL_SSH_DISABLE_STRICT_HOST_KEY_CHECKING. Disable ssh host key checking when accessing git repositories.Usage: kluctl delete [flags]
Delete a target (or parts of it) from the corresponding cluster Objects are located based on ‘commonLabels’, configured in ‘deployment.yaml’
WARNING: This command will also delete objects which are not part of your deployment project (anymore). It really only decides based on the ‘deleteByLabel’ labels and does NOT take the local target/state into account!
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--discriminator string Override the discriminator used to find objects for deletion.
--dry-run Performs all kubernetes API calls in dry-run mode.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--no-obfuscate Disable obfuscation of sensitive/secret data
-o, --output-format stringArray Specify output format and target file, in the format
'format=path'. Format can either be 'text' or 'yaml'. Can be
specified multiple times. The actual format for yaml is
currently not documented and subject to change.
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
-y, --yes Suppresses 'Are you sure?' questions and proceeds as if you
would answer 'yes'.
They have the same meaning as described in deploy .
Usage: kluctl deploy [flags]
Deploys a target to the corresponding cluster This command will also output a diff between the initial state and the state after deployment. The format of this diff is the same as for the ‘diff’ command. It will also output a list of prunable objects (without actually deleting them).
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--abort-on-error Abort deploying when an error occurs instead of trying the
remaining deployments
--dry-run Performs all kubernetes API calls in dry-run mode.
--force-apply Force conflict resolution when applying. See documentation for
details
--force-replace-on-error Same as --replace-on-error, but also try to delete and
re-create objects. See documentation for more details.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--no-obfuscate Disable obfuscation of sensitive/secret data
--no-wait Don't wait for objects readiness'
-o, --output-format stringArray Specify output format and target file, in the format
'format=path'. Format can either be 'text' or 'yaml'. Can be
specified multiple times. The actual format for yaml is
currently not documented and subject to change.
--readiness-timeout duration Maximum time to wait for object readiness. The timeout is
meant per-object. Timeouts are in the duration format (1s, 1m,
1h, ...). If not specified, a default timeout of 5m is used.
(default 5m0s)
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
--replace-on-error When patching an object fails, try to replace it. See
documentation for more details.
-y, --yes Suppresses 'Are you sure?' questions and proceeds as if you
would answer 'yes'.
kluctl implements deployments via
server-side apply
and a custom automatic conflict resolution algorithm. This algurithm is an automatic implementation of the
“
Don’t overwrite value, give up management claim
”
method. It should work in most cases, but might still fail. In case of such failure, you can use --force-apply to
use the “Overwrite value, become sole manager” strategy instead.
Please note that this is a risky operation which might overwrite fields which were initially managed by kluctl but were then overtaken by other managers (e.g. by operators). Always use this option with caution and perform a dry-run before to ensure nothing unexpected gets overwritten.
In some situations, patching Kubernetes objects might fail for different reasons. In such cases, you can try
--replace-on-error to instruct kluctl to retry with an update operation.
Please note that this will cause all fields to be overwritten, even if owned by other field managers.
This flag will cause the same replacement attempt on failure as with --replace-on-error. In addition, it will fallback
to a delete+recreate operation in case the replace also fails.
Please note that this is a potentially risky operation, especially when an object carries some kind of important state.
kluctl does not abort a command when an individual object fails can not be updated. It collects all errors and warnings and outputs them instead. This option modifies the behaviour to immediately abort the command.
Usage: kluctl diff [flags]
Perform a diff between the locally rendered target and the already deployed target The output is by default in human readable form (a table combined with unified diffs). The output can also be changed to output a yaml file. Please note however that the format is currently not documented and prone to changes. After the diff is performed, the command will also search for prunable objects and list them.
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--force-apply Force conflict resolution when applying. See documentation for
details
--force-replace-on-error Same as --replace-on-error, but also try to delete and
re-create objects. See documentation for more details.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--ignore-annotations Ignores changes in annotations when diffing
--ignore-labels Ignores changes in labels when diffing
--ignore-tags Ignores changes in tags when diffing
--no-obfuscate Disable obfuscation of sensitive/secret data
-o, --output-format stringArray Specify output format and target file, in the format
'format=path'. Format can either be 'text' or 'yaml'. Can be
specified multiple times. The actual format for yaml is
currently not documented and subject to change.
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
--replace-on-error When patching an object fails, try to replace it. See
documentation for more details.
--force-apply and --replace-on-error have the same meaning as in
deploy
.
Usage: kluctl helm-pull [flags]
Recursively searches for ‘helm-chart.yaml’ files and pre-pulls the specified Helm charts Kluctl requires Helm Charts to be pre-pulled by default, which is handled by this command. It will collect all required Charts and versions and pre-pull them into .helm-charts. To disable pre-pulling for individual charts, set ‘skipPrePull: true’ in helm-chart.yaml.
See helm-integration for more details.
The following sets of arguments are available:
-a)Usage: kluctl helm-update [flags]
Recursively searches for ‘helm-chart.yaml’ files and checks for new available versions Optionally performs the actual upgrade and/or add a commit to version control.
The following sets of arguments are available:
-a)In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--commit Create a git commit for every updated chart
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
-i, --interactive Ask for every Helm Chart if it should be upgraded.
--upgrade Write new versions into helm-chart.yaml and perform helm-pull
afterwards
Usage: kluctl list-images [flags]
Renders the target and outputs all images used via ‘images.get_image(…) The result is a compatible with yaml files expected by –fixed-images-file.
If fixed images (’-f/–fixed-image’) are provided, these are also taken into account, as described in the deploy command.
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--kubernetes-version string Specify the Kubernetes version that will be assumed. This will
also override the kubeVersion used when rendering Helm Charts.
--offline-kubernetes Run command in offline mode, meaning that it will not try to
connect the target cluster
-o, --output stringArray Specify output target file. Can be specified multiple times
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
--simple Output a simplified version of the images list
Usage: kluctl list-targets [flags]
Outputs a yaml list with all targets Outputs a yaml list with all targets
The following arguments are available:
Misc arguments:
Command specific arguments.
-o, --output stringArray Specify output target file. Can be specified multiple times
Usage: kluctl poke-images [flags]
Replace all images in target This command will fully render the target and then only replace images instead of fully deploying the target. Only images used in combination with ‘images.get_image(…)’ are replaced
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--dry-run Performs all kubernetes API calls in dry-run mode.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--no-obfuscate Disable obfuscation of sensitive/secret data
-o, --output-format stringArray Specify output format and target file, in the format
'format=path'. Format can either be 'text' or 'yaml'. Can be
specified multiple times. The actual format for yaml is
currently not documented and subject to change.
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
-y, --yes Suppresses 'Are you sure?' questions and proceeds as if you
would answer 'yes'.
Usage: kluctl prune [flags]
Searches the target cluster for prunable objects and deletes them
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--dry-run Performs all kubernetes API calls in dry-run mode.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--no-obfuscate Disable obfuscation of sensitive/secret data
-o, --output-format stringArray Specify output format and target file, in the format
'format=path'. Format can either be 'text' or 'yaml'. Can be
specified multiple times. The actual format for yaml is
currently not documented and subject to change.
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
-y, --yes Suppresses 'Are you sure?' questions and proceeds as if you
would answer 'yes'.
They have the same meaning as described in deploy .
Usage: kluctl render [flags]
Renders all resources and configuration files Renders all resources and configuration files and stores the result in either a temporary directory or a specified directory.
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--kubernetes-version string Specify the Kubernetes version that will be assumed. This will
also override the kubeVersion used when rendering Helm Charts.
--offline-kubernetes Run command in offline mode, meaning that it will not try to
connect the target cluster
--print-all Write all rendered manifests to stdout
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
Usage: kluctl validate [flags]
Validates the already deployed deployment This means that all objects are retrieved from the cluster and checked for readiness.
TODO: This needs to be better documented!
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<credentialsId>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-key-file stringArray Specify client certificate to use for Helm Repository
authentication. Must be in the form
--helm-key-file=<credentialsId>:<path>, where <credentialsId>
must match the id specified in the helm-chart.yaml.
--helm-password stringArray Specify password to use for Helm Repository authentication.
Must be in the form
--helm-password=<credentialsId>:<password>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-username stringArray Specify username to use for Helm Repository authentication.
Must be in the form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
-o, --output stringArray Specify output target file. Can be specified multiple times
--render-output-dir string Specifies the target directory to render the project into. If
omitted, a temporary directory is used.
--sleep duration Sleep duration between validation attempts (default 5s)
--wait duration Wait for the given amount of time until the deployment validates
--warnings-as-errors Consider warnings as failures