Deployments

The deployment.yaml file is the entrypoint for the deployment project. Included sub-deployments also provide a deployment.yaml file with the same structure as the initial one.

An example deployment.yaml looks like this:

deployments:
- path: nginx
- path: my-app
- include: monitoring

commonLabels:
  my.prefix/target: "{{ target.name }}"
  my.prefix/deployment-project: my-deployment-project

The following sub-chapters describe the available fields in the deployment.yaml

deployments

deployments is a list of deployment items. Multiple deployment types are supported, which is documented further down. Individual deployments are performed in parallel, unless a barrier is encountered which causes kluctl to wait for all previous deployments to finish.

Deployments can also be conditional by using the when field.

Simple deployments

Simple deployments are specified via path and are expected to be directories with Kubernetes manifests inside. Kluctl will internally generate a kustomization.yaml from these manifests and treat the deployment item the same way as it would treat a Kustomize deployment .

Example:

deployments:
- path: path/to/manifests

Kustomize deployments

When the deployment item directory specified via path contains a kustomization.yaml, Kluctl will use this file instead of generating one.

Please see Kustomize integration for more details.

Example:

deployments:
- path: path/to/deployment1
- path: path/to/deployment2
  waitReadiness: true

The path must point to a directory relative to the directory containing the deployment.yaml. Only directories that are part of the kluctl project are allowed. The directory must contain a valid kustomization.yaml.

waitReadiness is optional and if set to true instructs kluctl to wait for readiness of each individual object of the kustomize deployment. Readiness is defined in readiness .

Includes

Specifies a sub-deployment project to be included. The included sub-deployment project will inherit many properties of the parent project, e.g. tags, commonLabels and so on.

Example:

deployments:
- include: path/to/sub-deployment

The path must point to a directory relative to the directory containing the deployment.yaml. Only directories that are part of the kluctl project are allowed. The directory must contain a valid deployment.yaml.

Git includes

Specifies an external git project to be included. The project is included the same way with regular includes, except that the included project can not use/load templates from the parent project. An included project might also include further git projects.

Simple example:

deployments:
- git: git@github.com/example/example.git

This will clone the git repository at git@github.com/example/example.git, checkout the default branch and include it into the current project.

Advanced Example:

deployments:
- git:
    url: git@github.com/example/example.git
    ref: my-branch
    subDir: some/sub/dir

The url specifies the Git url to be cloned and checked out. ref is optional and specifies the branch or tag to be used. If ref is omitted, the default branch will be checked out. subDir is optional and specifies the sub directory inside the git repository to include.

Barriers

Causes kluctl to wait until all previous kustomize deployments have been applied. This is useful when upcoming deployments need the current or previous deployments to be finished beforehand. Previous deployments also include all sub-deployments from included deployments.

Example:

deployments:
- path: kustomizeDeployment1
- path: kustomizeDeployment2
- include: subDeployment1
- barrier: true
# At this point, it's ensured that kustomizeDeployment1, kustomizeDeployment2 and all sub-deployments from
# subDeployment1 are fully deployed.
- path: kustomizeDeployment3

deployments common properties

All entries in deployments can have the following common properties:

vars (deployment item)

A list of variable sets to be loaded into the templating context, which is then available in all deployment items and sub-deployments .

See templating for more details.

Example:

deployments:
- path: kustomizeDeployment1
  vars:
    - file: vars1.yaml
    - values:
        var1: value1
- path: kustomizeDeployment2
# all sub-deployments of this include will have the given variables available in their Jinj2 context.
- include: subDeployment1
  vars:
    - file: vars2.yaml

when

Each deployment item can be conditional with the help of the when field. It must be set to a Jinja2 based expression that evaluates to a boolean.

Example:

deployments:
- path: item1
- path: item2
  when: my.var == "my-value"

tags (deployment item)

A list of tags the deployment should have. See tags for more details. For includes, this means that all sub-deployments will get these tags applied to. If not specified, the default tags logic as described in tags is applied.

Example:

deployments:
- path: kustomizeDeployment1
  tags:
    - tag1
    - tag2
- path: kustomizeDeployment2
  tags:
    - tag3
# all sub-deployments of this include will get tag4 applied
- include: subDeployment1
  tags:
    - tag4

alwaysDeploy

Forces a deployment to be included everytime, ignoring inclusion/exclusion sets from the command line. See Deploying with tag inclusion/exclusion for details.

deployments:
- path: kustomizeDeployment1
  alwaysDeploy: true
- path: kustomizeDeployment2

Please note that alwaysDeploy will also cause kluctl render to always render the resources.

skipDeleteIfTags

Forces exclusion of a deployment whenever inclusion/exclusion tags are specified via command line. See Deleting with tag inclusion/exclusion for details.

deployments:
- path: kustomizeDeployment1
  skipDeleteIfTags: true
- path: kustomizeDeployment2

onlyRender

Causes a path to be rendered only but not treated as a deployment item. This can be useful if you for example want to use Kustomize components which you’d refer from other deployment items.

deployments:
- path: component
  onlyRender: true
- path: kustomizeDeployment2

vars (deployment project)

A list of variable sets to be loaded into the templating context, which is then available in all deployment items and sub-deployments .

See templating for more details.

commonLabels

A dictionary of labels and values to be added to all resources deployed by any of the kustomize deployments in this deployment project.

This feature is mainly meant to make it possible to identify all objects in a kubernetes cluster that were once deployed through a specific deployment project.

Consider the following example deployment.yaml:

deployments:
  - path: nginx
  - include: sub-deployment1

commonLabels:
  my.prefix/target: {{ target.name }}
  my.prefix/deployment-name: my-deployment-project-name
  my.prefix/label-1: value-1
  my.prefix/label-2: value-2

Every resource deployed by the kustomize deployment nginx will now get the two provided labels attached. All included sub-deployment projects (e.g. sub-deployment1) will also recursively inherit these labels and pass them to further down.

In case an included sub-deployment project also contains commonLabels, both dictionaries of common labels are merged inside the included sub-deployment project. In case of conflicts, the included common labels override the inherited.

The root deployment’s commonLabels is also used to identify objects to be deleted when performing kluctl delete or kluctl prune operations

Please note that these commonLabels are not related to commonLabels supported in kustomization.yaml files. It was decided to not rely on this feature but instead attach labels manually to resources right before sending them to kubernetes. This is due to an implementation detail in kustomize which causes commonLabels to also be applied to label selectors, which makes otherwise editable resources read-only when it comes to commonLabels.

overrideNamespace

A string that is used as the default namespace for all kustomize deployments which don’t have a namespace set in their kustomization.yaml.

tags (deployment project)

A list of common tags which are applied to all kustomize deployments and sub-deployment includes.

See tags for more details.

ignoreForDiff

A list of objects and fields to ignore while performing diffs. Consider the following example:

deployments:
  - ...

ignoreForDiff:
  - group: apps
    kind: Deployment
    namespace: my-namespace
    name: my-deployment
    fieldPath: spec.replicas

This will remove the spec.replicas field from every resource that matches the object. group, kind, namespace and name can be omitted, which results in all objects matching. fieldPath must be a valid JSON Path . fieldPath may also be a list of JSON paths.

The JSON Path implementation used in kluctl has extended support for wildcards in field names, allowing you to also specify paths like metadata.labels.my-prefix-*.

As an alternative, annotations can be used to control diff behavior of individual resources.