Migrating from Kapitan 0.29 to 0.30

Changes

The major changes in Kapitan 0.30 which are relevant for Commodore are:

  • Kapitan 0.30 calls out to the system helm binary for fetching and rendering Helm charts, see Kapitan PR#701.

  • The reclass version regression present in Kapitan 0.29.5 has been fixed, see Kapitan PR#703.

Helm templating

With the change to using the system helm binary, Kapitan now supports both Helm 2 and Helm 3.

Selecting the Helm version

Users can specify which helm binary should be used by default by setting environment variable KAPITAN_HELM_PATH. Additionally, users can require a specific binary for individual Helm chart compilations by setting parameter helm_path. If neither the environment variable nor parameter helm_path are specified, Kapitan uses the helm command in $PATH.

Despite the naming of the variable and parameter, you don’t have to specify the full path to the Helm binary. Kapitan will search $PATH for a binary with the given name, if you just provide a name like helm3.

The Commodore Docker image provides Helm 3 as binary /usr/local/bin/helm3 and /usr/local/bin/helm, and Helm 2 as binary /usr/local/bin/helm2. This allows users of the Docker image to specify the Helm version to use for individual compilations as helm_path: helm3 and helm_path: helm2. Users who want to run Commodore locally should ensure that their $PATH contains helm3 and helm pointing to Helm 3, and helm2 pointing to Helm 2.

Example helm compilation with helm_path set
parameters:
  kapitan:
    compile:
      - input_paths:
          - path/to/helm/chart
        input_type: helm
        helm_values: {
          # arbitrary Helm values
        }
        helm_path: helm3 (1)
        helm_params: {
          # parameters for helm binary
        }
        output_path: path/to/output/
1 Set parameter helm_path to helm2 or helm3

Changes to fields in helm_params

Previously helm_params.release_name was used to specify the name of the Helm release. Currently this is in use by most Commodore components which compile Helm charts.

However, Helm 3 has a command line flag --release-name which has a different effect. Therefore the old use of release_name has been deprecated, and components should switch to using helm_params.name to specify the name of the Helm release.

In Kapitan 0.30, the parameter helm_params can be used to specify most command line arguments which Helm understands. Kapitan includes flags --include-crds=true and --skip-tests=true by default.

The following flags aren’t supported by Kapitan:

  • --dry-run

  • --generate-name

  • --help

  • --output-dir

  • --show-only

See the Kapitan Helm input type documentation for more details.

Catalog output

When first compiling a cluster catalog with Kapitan 0.30, the contents of some Helm chart output files appear in a different order than for Kapitan 0.29. Additionally, there’s a lot of noise in the resulting catalog diff because the value of the app.kubernetes.io/managed-by and heritage labels for resources generated by Helm changes from Tiller to Helm for charts compiled with Helm 3.

To make it easier to identify real changes in the catalog diff, we’ve added an optional command line flag -m, --migration to the catalog compile command. The flag takes a value specifying which migration Commodore should consider when rendering the catalog diff. Currently Commodore only knows a single migration: kapitan-0.29-to-0.30. To suppress diffs which only contain reordered objects or the aforementioned label changes, you can compile the catalog with

commodore catalog compile ${CLUSTER_ID} -m kapitan-0.29-to-0.30