This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Kluctl Projects

Kluctl project configuration, found in the .kluctl.yaml file.

1: targets

The .kluctl.yaml is the central configuration and entry point for your deployments. It defines which targets are available to invoke commands on.

Example

An example .kluctl.yaml looks like this:

discriminator: "my-project-{{ target.name }}"

targets:
  # test cluster, dev env
  - name: dev
    context: dev.example.com
    args:
      environment: dev
  # test cluster, test env
  - name: test
    context: test.example.com
    args:
      environment: test
  # prod cluster, prod env
  - name: prod
    context: prod.example.com
    args:
      environment: prod

args:
  - name: environment

Allowed fields

discriminator

Specifies a default discriminator template to be used for targets that don’t have their own discriminator specified.

See target discriminator for details.

targets

Please check the targets sub-section for details.

args

A list of arguments that can or must be passed to most kluctl operations. Each of these arguments is then available in templating via the global args object.

An example looks like this:

targets:
...

args:
  - name: environment
  - name: enable_debug
    default: false
  - name: complex_arg
    default:
      my:
        nested1: arg1
        nested2: arg2

These arguments can then be used in templating, e.g. by using {{ args.environment }}.

When calling kluctl, most of the commands will then require you to specify at least -a environment=xxx and optionally -a enable_debug=true

The following sub chapters describe the fields for argument entries.

name

The name of the argument.

default

If specified, the argument becomes optional and will use the given value as default when not specified.

The default value can be an arbitrary yaml value, meaning that it can also be a nested dictionary. In that case, passing args in nested form will only set the nested value. With the above example of complex_arg, running:

kluctl deploy -t my-target -a my.nested1=override`

will only modify the value below my.nested1 and keep the value of my.nested2.

aws

If specified, configures the default AWS configuration to use for awsSecretsManager vars sources and KMS based SOPS descryption.

Example:

aws:
  profile: my-local-aws-profile
  serviceAccount:
    name: service-account-name
    namespace: service-account-namespace

If any of the environment variables AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY or AWS_WEB_IDENTITY_TOKEN_FILE is set, Kluctl will ignore this AWS configuration and revert to using the environment variables based credentials.

profile

If specified, Kluctl will use this AWS config profile when found locally. If it is not found in your local AWS config, Kluctl will not try to use the specified profile.

serviceAccount

Optionally specifies the name and namespace of a service account to use for IRSA based authentication. The specified service accounts needs to have the eks.amazonaws.com/role-arn annotation set to an existing IAM role with a proper trust policy that allows this service account to assume that role. Please read the AWS documentation for details.

The service account is only used when profile was not specified or when it is not present locally. If a service account is specified and accessible (you need proper RBAC access), Kluctl will not try to perform default AWS config loading.

Using Kluctl without .kluctl.yaml

It’s possible to use Kluctl without any .kluctl.yaml. In that case, all commands must be used without specifying the target.

1 - targets

Required, defines targets for this kluctl project.

Specifies a list of targets for which commands can be invoked. A target puts together environment/target specific configuration and the target cluster. Multiple targets can exist which target the same cluster but with differing configuration (via args).

Each value found in the target definition is rendered with a simple Jinja2 context that only contains the target and args. The rendering process is retried 10 times until it finally succeeds, allowing you to reference the target itself in complex ways.

Target entries have the following form:

targets:
...
  - name: <target_name>
    context: <context_name>
    args:
      arg1: <value1>
      arg2: <value2>
      ...
    images:
      - image: my-image
        resultImage: my-image:1.2.3
    aws:
      profile: my-local-aws-profile
      serviceAccount:
        name: service-account-name
        namespace: service-account-namespace
    discriminator: "my-project-{{ target.name }}"
...

The following fields are allowed per target:

name

This field specifies the name of the target. The name must be unique. It is referred in all commands via the -t option.

context

This field specifies the kubectl context of the target cluster. The context must exist in the currently active kubeconfig. If this field is omitted, Kluctl will always use the currently active context.

args

This fields specifies a map of arguments to be passed to the deployment project when it is rendered. Allowed argument names are configured via deployment args.

images

This field specifies a list of fixed images to be used by images.get_image(...). The format is identical to the fixed images file.

aws

This field specifies target specific AWS configuration, which overrides what was optionally specified via the global AWS configuration.

discriminator

Specifies a discriminator which is used to uniquely identify all deployed objects on the cluster. It is added to all objects as the value of the kluctl.io/discriminator label. This label is then later used to identify all objects belonging to the deployment project and target, so that Kluctl can determine which objects got orphaned and need to be pruned. The discriminator is also used to identify all objects that need to be deleted when kluctl delete is called.

If no discriminator is set for a target, kluctl prune and kluctl delete are not supported.

The discriminator can be a template which is rendered at project loading time. While rendering, only the target and args are available as global variables in the templating context.

The rendered discriminator should be unique on the target cluster to avoid mis-identification of objects from other deployments or targets. It’s good practice to prefix the discriminator with a project name and at least use the target name to make it unique. Example discriminator to achieve this: my-project-name-{{ target.name }}.

If a target is meant to be deployed multiple times, e.g. by using external arguments, the external arguments should be taken into account as well. Example: my-project-name-{{ target.name }}-{{ args.environment_name }}.

A default discriminator can also be specified which is used whenever a target has no discriminator configured.