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
--gops-agent Start gops agent in the background
--gops-agent-addr string Specify the address:port to use for the gops agent (default "127.0.0.1:0")
--no-color Disable colored output
--no-update-check Disable update check on startup
--use-system-python Use the system Python instead of the embedded Python.
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.
--kubeconfig existingfile Overrides the kubeconfig to use.
--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.
--local-oci-group-override stringArray Same as --local-git-group-override, but for OCI repositories.
--local-oci-override stringArray Same as --local-git-override, but for OCI repositories.
-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
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.
These arguments control how command results are stored.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
--force-write-command-result Force writing of command results, even if the command is run in dry-run mode.
--keep-command-results-count int Configure how many old command results to keep. (default 5)
--keep-validate-results-count int Configure how many old validate results to keep. (default 2)
--write-command-result Enable writing of command results into the cluster. This is enabled by
default. (default true)
These arguments mainly control authentication to Git repositories.
Git arguments:
Configure Git authentication.
--git-ca-file stringArray Specify CA bundle to use for https verification. Must be in the
form --git-ca-file=<registry>/<repo>=<filePath>.
--git-password stringArray Specify password to use for Git basic authentication. Must be in
the form --git-password=<host>/<path>=<password>.
--git-ssh-key-file stringArray Specify SSH key to use for Git authentication. Must be in the form
--git-ssh-key-file=<host>/<path>=<filePath>.
--git-ssh-known-hosts-file stringArray Specify known_hosts file to use for Git authentication. Must be in
the form --git-ssh-known-hosts-file=<host>/<path>=<filePath>.
--git-username stringArray Specify username to use for Git basic authentication. Must be in
the form --git-username=<host>/<path>=<username>.
All the arguments from above can also be passed via environment variables. For example:
# for http(s) username/password auth
export KLUCTL_GIT_0_HOST="github.com"
export KLUCTL_GIT_0_USERNAME="my-user"
export KLUCTL_GIT_0_PASSWORD="my-password"
# in case you have self-signed certs or other non-standard CAs
export KLUCTL_GIT_0_CA_BUNDLE="/path/to/ca/bundle"
# for ssh auth
export KLUCTL_GIT_1_HOST="gitlab.com"
export KLUCTL_GIT_1_SSH_KEY="/path/to/ssh/key"
# optionally specify path glob to limit this credentials set to only a defined set of repos (can also be used with http auth)
export KLUCTL_GIT_1_PATH="my-org/*"
In addition to the provided credentials, Kluctl will also try to use default Git authentication mechanisms like git credentials helpers, default SSH keys and SSH agents.
These arguments mainly control authentication to Helm repositories.
Helm arguments:
Configure Helm authentication.
--helm-ca-file stringArray Specify ca bundle certificate to use for Helm Repository
authentication. Must be in the form
--helm-ca-file=<host>/<path>=<filePath> or in the deprecated
form --helm-ca-file=<credentialsId>:<filePath>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-cert-file stringArray Specify key to use for Helm Repository authentication. Must be
in the form --helm-cert-file=<host>/<path>=<filePath> or in
the deprecated form
--helm-cert-file=<credentialsId>:<filePath>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
--helm-creds stringArray This is a shortcut to --helm-username and --helm-password.
Must be in the form
--helm-creds=<host>/<path>=<username>:<password>, which
specifies the username and password for the same repository.
--helm-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--helm-insecure-skip-tls-verify=<host>/<path> or in the
deprecated 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=<host>/<path>=<filePath> or in the deprecated
form --helm-key-file=<credentialsId>:<filePath>, 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=<host>/<path>=<password>
or in the deprecated 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=<host>/<path>=<username>
or in the deprecated form
--helm-username=<credentialsId>:<username>, where
<credentialsId> must match the id specified in the helm-chart.yaml.
All the arguments from above can also be passed via environment variables. For example:
# for http(s) username/password auth
export KLUCTL_HELM_0_HOST="gitlab.com"
export KLUCTL_HELM_0_USERNAME="my-user"
export KLUCTL_HELM_0_PASSWORD="my-password"
export KLUCTL_HELM_0_PATH="api/v4/projects/1111111/packages/helm/stable"
# in case you have self-signed certs or other non-standard CAs
export KLUCTL_HELM_0_CA_FILE="/path/to/ca/bundle"
...
These arguments mainly control authentication to OCI based registries. This is used by the Helm integration and by the OCI includes integration.
Registry arguments:
Configure OCI registry authentication.
--registry-ca-file stringArray Specify CA bundle to use for https verification. Must be
in the form --registry-ca-file=<registry>/<repo>=<filePath>.
--registry-cert-file stringArray Specify certificate to use for OCI authentication. Must be
in the form --registry-cert-file=<registry>/<repo>=<filePath>.
--registry-creds stringArray This is a shortcut to --registry-username,
--registry-password and --registry-token. It can be
specified in two different forms. The first one is
--registry-creds=<registry>/<repo>=<username>:<password>,
which specifies the username and password for the same
registry. The second form is
--registry-creds=<registry>/<repo>=<token>, which
specifies a JWT token for the specified registry.
--registry-identity-token stringArray Specify identity token to use for OCI authentication. Must
be in the form
--registry-identity-token=<registry>/<repo>=<identity-token>.
--registry-insecure-skip-tls-verify stringArray Controls skipping of TLS verification. Must be in the form
--registry-insecure-skip-tls-verify=<registry>/<repo>.
--registry-key-file stringArray Specify key to use for OCI authentication. Must be in the
form --registry-key-file=<registry>/<repo>=<filePath>.
--registry-password stringArray Specify password to use for OCI authentication. Must be in
the form --registry-password=<registry>/<repo>=<password>.
--registry-plain-http stringArray Forces the use of http (no TLS). Must be in the form
--registry-plain-http=<registry>/<repo>.
--registry-token stringArray Specify registry token to use for OCI authentication. Must
be in the form --registry-token=<registry>/<repo>=<token>.
--registry-username stringArray Specify username to use for OCI authentication. Must be in
the form --registry-username=<registry>/<repo>=<username>.
All the arguments from above can also be passed via environment variables. For example:
# for http(s) username/password auth
export KLUCTL_REGISTRY_0_HOST="docker.io"
export KLUCTL_REGISTRY_0_USERNAME="my-user"
export KLUCTL_REGISTRY_0_PASSWORD="my-password"
export KLUCTL_REGISTRY_0_PATH="my-org/*"
# in case you have self-signed certs or other non-standard CAs
export KLUCTL_REGISTRY_0_CA_FILE="/path/to/ca/bundle"
...
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_SSH_DISABLE_STRICT_HOST_KEY_CHECKING. Disable ssh host key checking when accessing git repositories.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.
--only-names If provided --only-names will only output
-o, --output stringArray Specify output target file. Can be specified multiple times
Usage: kluctl controller run [flags]
Run the Kluctl controller This command will run the Kluctl Controller. This is usually meant to be run inside a cluster and not from your local machine.
The following arguments are available:
Misc arguments:
Command specific arguments.
--concurrency int Configures how many KluctlDeployments can be be reconciled
concurrently. (default 4)
--context string Override the context to use.
--controller-name string The controller name used for metrics and logs. (default
"kluctl-controller")
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--default-service-account string Default service account used for impersonation.
--dry-run Run all deployments in dryRun=true mode.
--health-probe-bind-address string The address the probe endpoint binds to. (default ":8081")
--kubeconfig string Override the kubeconfig to use.
--leader-elect Enable leader election for controller manager. Enabling this will
ensure there is only one active controller manager.
--metrics-bind-address string The address the metric endpoint binds to. (default ":8080")
--namespace string Specify the namespace to watch. If omitted, all namespaces are watched.
--source-override-bind-address string The address the source override manager endpoint binds to. (default
":8082")
Usage: kluctl webui run [flags]
Run the Kluctl Webui
The following arguments are available:
Misc arguments:
Command specific arguments.
--all-contexts Use all Kubernetes contexts found in the kubeconfig.
--context stringArray List of kubernetes contexts to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--host string Host to bind to. Pass an empty string to bind to all addresses. Defaults to
'localhost' when run locally and to all hosts when run in-cluster.
--in-cluster This enables in-cluster functionality. This also enforces authentication.
--in-cluster-context string The context to use fo in-cluster functionality.
--kubeconfig existingfile Overrides the kubeconfig to use.
--only-api Only serve API without the actual UI.
--path-prefix string Specify the prefix of the path to serve the webui on. This is required when
using a reverse proxy, ingress or gateway that serves the webui on another
path than /. (default "/")
--port int Port to bind to. (default 8080)
Auth arguments:
Configure authentication.
--auth-admin-rbac-user string Specify the RBAC user to use for admin access. (default
"kluctl-webui-admin")
--auth-logout-return-param string Specify the parameter name to pass to the logout redirect url,
containing the return URL to redirect back.
--auth-logout-url string Specify the logout URL, to which the user should be redirected
after clearing the Kluctl Webui session.
--auth-oidc-admins-group stringArray Specify admins group names.'
--auth-oidc-client-id string Specify the ClientID.
--auth-oidc-client-secret-key string Specify the secret name for the ClientSecret. (default
"oidc-client-secret")
--auth-oidc-client-secret-name string Specify the secret name for the ClientSecret. (default "webui-secret")
--auth-oidc-display-name string Specify the name of the OIDC provider to be displayed on the login
page. (default "OpenID Connect")
--auth-oidc-group-claim string Specify claim for the groups.' (default "groups")
--auth-oidc-issuer-url string Specify the OIDC provider's issuer URL.
--auth-oidc-param stringArray Specify additional parameters to be passed to the authorize endpoint.
--auth-oidc-redirect-url string Specify the redirect URL.
--auth-oidc-scope stringArray Specify the scopes.
--auth-oidc-user-claim string Specify claim for the username.' (default "email")
--auth-oidc-viewers-group stringArray Specify viewers group names.'
--auth-secret-key string Specify the secret key for the secret used for internal encryption
of tokens and cookies. (default "auth-secret")
--auth-secret-name string Specify the secret name for the secret used for internal encryption
of tokens and cookies. (default "webui-secret")
--auth-static-admin-secret-key string Specify the secret key for the admin password. (default
"admin-password")
--auth-static-login-enabled Enable the admin user. (default true)
--auth-static-login-secret-name string Specify the secret name for the admin and viewer passwords.
(default "webui-secret")
--auth-static-viewer-secret-key string Specify the secret key for the viewer password. (default
"viewer-password")
--auth-viewer-rbac-user string Specify the RBAC user to use for viewer access. (default
"kluctl-webui-viewer")
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.
--discriminator string Override the target discriminator.
--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.
--ignore-annotations Ignores changes in annotations when diffing
--ignore-kluctl-metadata Ignores changes in Kluctl related metadata (e.g. tags, discriminators, ...)
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
--force-apply and --replace-on-error have the same meaning as 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
--discriminator string Override the target discriminator.
--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.
--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.
--prune Prune orphaned objects directly after deploying. See the help for the 'prune'
sub-command for details.
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
-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 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.
--discriminator string Override the target discriminator.
--dry-run Performs all kubernetes API calls in dry-run mode.
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
-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 gitops diff [flags]
Trigger a GitOps diff This command will trigger an existing KluctlDeployment to perform a reconciliation loop with a forced diff. It does this by setting the annotation ‘kluctl.io/request-diff’ to the current time.
You can override many deployment relevant fields, see the list of command flags for details.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
Misc arguments:
Command specific arguments.
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
GitOps overrides:
Override settings for GitOps deployments.
--abort-on-error Abort deploying when an error occurs instead of trying the
remaining deployments
-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.
--dry-run Performs all kubernetes API calls in dry-run mode.
--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.
-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
--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.
--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.
--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.
--local-oci-group-override stringArray Same as --local-git-group-override, but for OCI repositories.
--local-oci-override stringArray Same as --local-git-override, but for OCI repositories.
--replace-on-error When patching an object fails, try to replace it. See documentation
for more details.
-t, --target string Target name to run command for. Target must exist in .kluctl.yaml.
--target-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.
-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.
Usage: kluctl gitops deploy [flags]
Trigger a GitOps deployment This command will trigger an existing KluctlDeployment to perform a reconciliation loop with a forced deployment. It does this by setting the annotation ‘kluctl.io/request-deploy’ to the current time.
You can override many deployment relevant fields, see the list of command flags for details.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
Misc arguments:
Command specific arguments.
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
GitOps overrides:
Override settings for GitOps deployments.
--abort-on-error Abort deploying when an error occurs instead of trying the
remaining deployments
-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.
--dry-run Performs all kubernetes API calls in dry-run mode.
--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.
-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
--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.
--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.
--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.
--local-oci-group-override stringArray Same as --local-git-group-override, but for OCI repositories.
--local-oci-override stringArray Same as --local-git-override, but for OCI repositories.
--no-wait Don't wait for objects readiness.
--prune Prune orphaned objects directly after deploying. See the help for
the 'prune' sub-command for details.
--replace-on-error When patching an object fails, try to replace it. See documentation
for more details.
-t, --target string Target name to run command for. Target must exist in .kluctl.yaml.
--target-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.
-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.
Usage: kluctl gitops logs [flags]
Show logs from controller Print and watch logs of specified KluctlDeployments from the kluctl-controller.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
Misc arguments:
Command specific arguments.
--all Follow all controller logs, including all deployments and non-deployment related logs.
-f, --follow Follow logs after printing old logs.
--reconcile-id string If specified, logs are filtered for the given reconcile ID.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
Usage: kluctl gitops prune [flags]
Trigger a GitOps prune This command will trigger an existing KluctlDeployment to perform a reconciliation loop with a forced prune. It does this by setting the annotation ‘kluctl.io/request-prune’ to the current time.
You can override many deployment relevant fields, see the list of command flags for details.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
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.
--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.
--replace-on-error When patching an object fails, try to replace it. See documentation for more
details.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
GitOps overrides:
Override settings for GitOps deployments.
--target-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.
Usage: kluctl gitops reconcile [flags]
Trigger a GitOps reconciliation This command will trigger an existing KluctlDeployment to perform a reconciliation loop. It does this by setting the annotation ‘kluctl.io/request-reconcile’ to the current time.
You can override many deployment relevant fields, see the list of command flags for details.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
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.
--replace-on-error When patching an object fails, try to replace it. See documentation for more details.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
GitOps overrides:
Override settings for GitOps deployments.
--no-wait Don't wait for objects readiness.
--prune Prune orphaned objects directly after deploying. See the help for the 'prune'
sub-command for details.
--target-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.
Usage: kluctl gitops resume [flags]
Resume a GitOps deployment This command will suspend a GitOps deployment by setting spec.suspend to ’true'.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
Misc arguments:
Command specific arguments.
--all If enabled, suspend all deployments.
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
Usage: kluctl gitops suspend [flags]
Suspend a GitOps deployment This command will suspend a GitOps deployment by setting spec.suspend to ’true'.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
Misc arguments:
Command specific arguments.
--all If enabled, suspend all deployments.
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
Usage: kluctl gitops validate [flags]
Trigger a GitOps validate This command will trigger an existing KluctlDeployment to perform a reconciliation loop with a forced validation. It does this by setting the annotation ‘kluctl.io/request-validate’ to the current time.
You can override many deployment relevant fields, see the list of command flags for details.
The following arguments are available:
GitOps arguments:
Specify gitops flags.
--context string Override the context to use.
--controller-namespace string The namespace where the controller runs in. (default "kluctl-system")
--kubeconfig existingfile Overrides the kubeconfig to use.
-l, --label-selector string If specified, KluctlDeployments are searched and filtered by this label
selector.
--local-source-override-port int Specifies the local port to which the source-override client should
connect to when running the controller locally.
--name string Specifies the name of the KluctlDeployment.
-n, --namespace string Specifies the namespace of the KluctlDeployment. If omitted, the current
namespace from your kubeconfig is used.
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.
-o, --output stringArray Specify output target file. Can be specified multiple times
--replace-on-error When patching an object fails, try to replace it. See documentation for more details.
--warnings-as-errors Consider warnings as failures
Command Results:
Configure how command results are stored.
--command-result-namespace string Override the namespace to be used when writing command results. (default
"kluctl-results")
Log arguments:
Configure logging.
--log-grouping-time duration Logs are by default grouped by time passed, meaning that they are printed in
batches to make reading them easier. This argument allows to modify the
grouping time. (default 1s)
--log-since duration Show logs since this time. (default 1m0s)
--log-time If enabled, adds timestamps to log lines
GitOps overrides:
Override settings for GitOps deployments.
--target-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.
Usage: kluctl oci push [flags]
Push to an oci repository The push command creates a tarball from the current project and uploads the artifact to an OCI repository.
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--annotation stringArray Set custom OCI annotations in the format '<key>=<value>'
--output string the format in which the artifact digest should be printed, can be 'json' or 'yaml'
--timeout duration Specify timeout for all operations, including loading of the project, all
external api calls and waiting for readiness. (default 10m0s)
--url string Specifies the artifact URL. This argument is required.
Usage: kluctl delete [flags]
Delete a target (or parts of it) from the corresponding cluster Objects are located based on the target discriminator.
WARNING: This command will also delete objects which are not part of your deployment project (anymore). It really only decides based on the discriminator 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.
--no-obfuscate Disable obfuscation of sensitive/secret data
--no-wait Don't wait for deletion of objects to finish.'
-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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
-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 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:
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:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--commit Create a git commit for every updated chart
-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.
--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 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.
--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.
--short-output When using the 'text' output format (which is the default), only names of
changes objects are shown instead of showing all changes.
-y, --yes Suppresses 'Are you sure?' questions and proceeds as if you would answer 'yes'.
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.
--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.
-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
Usage: kluctl controller install [flags]
Install the Kluctl controller This command will install the kluctl-controller to the current Kubernetes clusters.
The following sets of arguments are available:
In addition, the following arguments are available:
Misc arguments:
Command specific arguments.
--context string Override the context to use.
--dry-run Performs all kubernetes API calls in dry-run mode.
--kluctl-version string Specify the controller version to install.
-y, --yes Suppresses 'Are you sure?' questions and proceeds as if you would answer 'yes'.
Usage: kluctl webui build [flags]
Build the static Kluctl Webui This command will build the static Kluctl Webui.
The following arguments are available:
Misc arguments:
Command specific arguments.
--all-contexts Use all Kubernetes contexts found in the kubeconfig.
--context stringArray List of kubernetes contexts to use. Defaults to the current context.
--max-results int Specify the maximum number of results per target. (default 1)
--path string Output path.