mutate

mutate Generator

Published on kadet-hub: pin a released version by digest from its catalog page.

Kapitan kadet generator that patches the YAML an earlier compile entry wrote, typically a Helm chart rendered with Kapitan’s helm input, in place. It covers what the chart’s values do not expose: a field to set or remove, a container or environment variable to add, an image to pin by digest, an object to drop. Every mutation states which objects it expects to change, so a chart upgrade that renames an object fails the compile instead of dropping the patch silently.

It replaces the copy-paste patch step of the kadet-hub authors guide. Spec: docs/specs/mutate.md.

Usage

Two compile entries on the same output_path: the chart first, then mutate. Kapitan runs a target’s entries in order and gives the kadet entry that directory as compile_path; mutate reads every .yaml and .yml file in it and returns the files it changed under the same relative path, which Kapitan writes over the originals. output_type: plain is required (see Failure modes).

# inventory/classes/podinfo.yml
parameters:
  podinfo:
    mutations:
      replicas:
        match:
          kind: Deployment
          name: podinfo
        merge:
          spec:
            replicas: 2
  kapitan:
    dependencies:
      - type: oci
        source: ghcr.io/kadet-hub/mutate@sha256:<digest>
        output_path: lib/mutate
      - type: helm
        source: https://stefanprodan.github.io/podinfo
        chart_name: podinfo
        version: 6.15.0
        output_path: charts/podinfo
    compile:
      - input_type: helm
        input_paths:
          - charts/podinfo
        output_path: podinfo
        helm_params:
          name: podinfo
          namespace: apps
      - input_type: kadet
        input_paths:
          - lib/mutate
        output_path: podinfo
        output_type: plain
        input_params:
          mutations: ${podinfo:mutations}

mutations is a map keyed by mutation id, so a target or an environment class adds its own and overrides a class’s by id:

# inventory/targets/prod.yml
classes:
  - podinfo

parameters:
  podinfo:
    mutations:
      replicas:
        merge:
          spec:
            replicas: 4
      podinfo-sidecar:
        match:
          kind: Deployment
          name: podinfo
        merge_lists:
          containers: name
          env: name
        merge:
          spec:
            template:
              spec:
                containers:
                  - name: podinfo
                    env:
                      - name: PODINFO_UI_MESSAGE
                        value: prod
                  - name: proxy
                    image: docker.io/envoyproxy/envoy:<tag>
      pin-podinfo:
        match:
          kind: Deployment
        images:
          ghcr.io/stefanprodan/podinfo:
            digest: sha256:ec73780a8425f59ea49f5bc8cdff0d598805a224fbaa1f86c67a244f250fa9da
      no-hpa:
        match:
          kind: HorizontalPodAutoscaler
          name: podinfo
        delete: true

The fixture target complete uses every action on a vendored podinfo render.

Mutation schema

A mutation has exactly one of merge, json6902, delete and images. Unknown keys fail the compile. input_params takes mutations only.

Semantics

Failure modes

Every error starts with mutate: mutation <id>: and names the file when one document is concerned. Kapitan prints it in the traceback above Could not load Kadet module: mutate.

With Kapitan’s --cache, a kadet result is cached by the inventory, the input parameters and the target’s helm dependencies, not by the files mutate reads. A chart vendored without a helm dependency, or a copy source, can change without changing the cache key; the cached result then overwrites the new render with old content. Compile without --cache, or with a helm dependency, in that case.

Migrating

From the authors guide’s components/patch step: each patches entry <kind>/<name>: <patch> becomes a mutation {match: {kind: <kind>, name: <name>}, merge: <patch>} under an id of your choice; merge semantics are the same (maps recurse, lists replace), and a patch that matches nothing still fails. Set output_type: plain instead of auto, delete the component and depend on lib/mutate. Untouched files are no longer rewritten.

From kgenlib’s mutations (kapicorp/generators):

Not supported

Templating, regular expressions on the rendered text, Python hooks, rendering charts, moving objects between files or renaming files, and strategic merge patch.

Output

The files of the earlier entry, the changed ones rewritten. The manifest carries the kubernetes tag; schemas/ holds the Kubernetes 1.37.1 schemas of the kinds in the fixture output (Deployment, Service, ConfigMap, Pod, HorizontalPodAutoscaler).