Release mutations

The fields, types, admission rules and subresource of the Release mutation pipeline.

mutations is a top-level field of a Release, next to spec. It is an ordered list. convoy runs it after rendering, and before it calculates the renderRef. For the behavior, see Mutations.


Path	`Release.mutations`
List type	atomic: a write replaces the full list
Subresource	`releases/mutations` (GET, PUT, PATCH)
Changes `metadata.generation`	No

Example#

A celTransform mutation that reads its CEL expression from a ConfigMap:

yaml
mutations:
  - type: celTransform
    target: { group: apps, version: v1, kind: Deployment }
    from: { kind: ConfigMap, name: mutation-cel-transform, path: transform.cel }

mutations/configmap-cel-transform.yaml
# celTransform content sourced from a ConfigMap.
#
# The CEL expression returns a map overlay that is RFC7386-merged onto each
# matched object. Available variables:
#   cluster -> the target Cluster's name (cluster.name) + its Spec.Metadata keys
#              (e.g. cluster.region)
#   self    -> the Release's name / namespace / labels / annotations
#   object  -> the object being mutated
#
#   mutations:
#     - type: celTransform
#       target: { group: apps, version: v1, kind: Deployment }
#       from: { kind: ConfigMap, name: mutation-cel-transform, path: transform.cel }
#   from.name and from.path may themselves be templated with {.cluster,.self}
#   (release-level only, no .object), e.g. name: "{{ .cluster.name }}-transform".
apiVersion: v1
kind: ConfigMap
metadata:
  name: mutation-cel-transform
  namespace: default
data:
  transform.cel: |
    {
      "metadata": {
        "labels": {"convoy.kumodo.io/release": self.name},
        "annotations": {"convoy.kumodo.io/region": cluster.region}
      }
    }

Types#

`type`	Required content	What it does
`jsonPatch`	`patches`: RFC 6902 operations	Applies the operations to each matching object. convoy executes the patch as a Go template per object.
`strategicMergePatch`	`inline` or `from`	Merges each document into each matching object as a strategic merge patch. Built-in kinds only.
`goTemplate`	`inline` or `from`	Executes each document as a Go template per object, and merges the result as an RFC 7386 merge patch.
`celTransform`	`inline` or `from`	Evaluates each document as a CEL expression per object. The result map is merged as an RFC 7386 merge patch.
`syncWave`	`waveStrategy`	Sets the `convoy.kumodo.io/sync-*` annotations on each matching object.

Fields of a mutation#

Field	Meaning
`target`	Selects objects by `group`, `version`, `kind`, `name` and `namespace`. An empty field matches all values. Without `target`, the mutation matches all objects.
`inline`	A list of strings. Each string is one document: a template, a patch or a CEL expression.
`from`	Reads one more document from another object. `kind` is `GitRepository`, `ConfigMap` or `Secret`. `path` is the file path in the repository, or the data key. `ref` selects the Git branch, tag or commit.
`patches`	The operations of a `jsonPatch` mutation.
`waveStrategy`	The `wave`, `strategy` and `timeout` of a `syncWave` mutation.

Template and CEL context#

Name	Value
`cluster`	The `spec.metadata` keys of the target `Cluster`, and `cluster.name`
`self`	The `name`, `namespace`, `labels` and `annotations` of the Release
`object`	The object, as the previous mutation left it

Go templates use missingkey=zero and have no Sprig functions. from.name and from.path are also Go templates, with cluster and self only.

Admission rules#

type is jsonPatch, strategicMergePatch, goTemplate, celTransform or syncWave.
jsonPatch has at least one patch. Each patch has an op (add, remove, replace, move, copy or test) and a path.
strategicMergePatch, goTemplate and celTransform have inline or from.
syncWave has waveStrategy. strategy, if set, is waitForApplied, waitForHealthy or waitForHealthyWithTimeout.
from.namespace is empty or the namespace of the Release.

Admission does not parse templates, compile CEL or check from.kind. These errors show only at render time, as Applied=False with reason DeployFailed or Unsupported.

Subresource and CLI#

A write to releases/mutations changes only mutations, and requests a reconcile. Kubernetes RBAC controls releases/mutations separately from the Release.

sh
kubectl convoy release mutations get podinfo
kubectl convoy release mutations set podinfo -f mutations.yaml
kubectl convoy release mutations add podinfo -f extra.yaml

Fields#

Field	Type	Description
`mutations`	`[]ReleaseMutation`list type: atomic
`mutations[].from`	`ReleaseMutationFromSpec`	From is the source of the mutation.
`mutations[].from.kind` required	`string`	Kind is the kind of the source.
`mutations[].from.name` required	`string`	Name is the name of the source.
`mutations[].from.namespace`	`string`	Namespace is the namespace of the source.
`mutations[].from.path` required	`string`	Path is the path to the mutation within the source.
`mutations[].from.ref`	`ReleaseGitRepositoryRefSpec`	Ref is the reference for GitRepository used as a mutation source.
`mutations[].from.ref.branch`	`string`	Branch is the branch to track in the Git repository.
`mutations[].from.ref.commit`	`string`	Commit is the commit to track in the Git repository.
`mutations[].from.ref.semver`	`string`	Semver is the tag-based semantic version expression to track in the Git repository.
`mutations[].from.ref.tag`	`string`	Tag is the tag to track in the Git repository.
`mutations[].inline`	`[]string`list type: atomic	Inline is the inline mutation.
`mutations[].patches`	`[]ReleaseMutationPatchSpec`list type: atomic	Patches is the list of JSON patches to apply to the release.
`mutations[].patches[].from`	`string`	From is the path to the field within the release to copy or move from. Applicable only for move and copy operations.
`mutations[].patches[].op` required	`string`	Op is the JSON patch operation. `add` is the add JSON patch operation. `copy` is the copy JSON patch operation. `move` is the move JSON patch operation. `remove` is the remove JSON patch operation. `replace` is the replace JSON patch operation. `test` is the test JSON patch operation.
`mutations[].patches[].path` required	`string`	Path is the path to the field within the release to patch.
`mutations[].patches[].value`	`JSON`	Value is the value to patch.
`mutations[].target` required	`ReleaseMutationTarget`	Target define mutation target.
`mutations[].target.group` required	`string`	Group defines the API group of the target.
`mutations[].target.kind` required	`string`	Kind defines the kind of the target.
`mutations[].target.name`	`string`	Name defines the name of the target.
`mutations[].target.namespace`	`string`	Namespace defines the namespace of the target.
`mutations[].target.version` required	`string`	Version defines the API version of the target.
`mutations[].type` required	`string`	Type is the type of the mutation. `celTransform` is the mutation type that uses CEL as mutation source. `goTemplate` is the mutation type that uses Go template as mutation source. `jsonPatch` is the mutation type that uses JSON patch as mutation source. `strategicMergePatch` is the mutation type that uses Strategic merge patch as mutation source. `syncWave` is a special mutation type which is used to set the sync-related annotations on the rendered resources. These annotations could still be set using other mutation types, but it's typos-prone approach which is hard to debug. Dedicated mutation type in opposite provides the validated, targeted and typed way to produce those annotations.
`mutations[].waveStrategy`	`ReleaseWaveStrategySpec`	WaveStrategy is the sync-wave configuration applied as annotations to the defined target. Only applicable for "syncWave" mutation type.
`mutations[].waveStrategy.strategy` required	`string`	Strategy is the wave strategy. `waitForApplied` is the wave strategy that waits for all resources to be applied. `waitForHealthy` is the wave strategy that waits for all resources to be healthy. `waitForHealthyWithTimeout` is the wave strategy that waits for all resources to be healthy with a timeout.
`mutations[].waveStrategy.timeout`	`Duration`	Timeout is the timeout for the wave strategy. If not set, controller will wait indefinitely.
`mutations[].waveStrategy.wave` required	`integer`	Wave is the wave number.