replacements

Replacements are used to copy fields from one source into any number of specified targets.

The replacements field can support a path to a replacement:

kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

replacements:
  - path: replacement.yaml

replacement.yaml

source:
  kind: Deployment
  fieldPath: metadata.name
targets:
  - select:
      name: my-resource

Alternatively, replacements supports inline replacements:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

replacements:
- source:
    kind: Deployment
    fieldPath: metadata.name
  targets:
  - select:
      name: my-resource

Syntax

The full schema of replacements is as follows:

replacements:
- source:
    group: string
    version: string
    kind: string
    name: string
    namespace: string
    fieldPath: string
    options:
      delimiter: string
      index: int
      create: bool
  sourceValue: string
  targets:
  - select:
      group: string
      version: string
      kind: string
      name: string
      namespace: string
    reject:
    - group: string
      version: string
      kind: string
      name: string
      namespace: string
    fieldPaths:
    - string
    options:
      delimiter: string
      index: int
      create: bool

Field Descriptions

Source

The source field is a selector that determines the source of the value by finding a match to the specified GVKNN. All the subfields of source are optional, but the source selection must resolve to a single resource. Alternatively, you can specify the desired value directly in the sourceValue field.

Targets

Replacements will be applied to all targets that are matched by the select field and are NOT matched by the reject field, and will be applied to all listed fieldPaths.

Select

You can use any of the following fields to select the targets to replace: group, version, kind, name, namespace

For example, the following will select all the Deployments as targets of replacement.

select:
  kind: Deployment

Also, you can use multiple fields together to select only the resources that match all the conditions. For example, the following will select only the Deployments that are named my-deploy:

select:
- kind: Deployment
  name: my-deploy

Moreover, when the selected target is going to be transformed during the kustomization process, you can use either the original or the transformed resource id to select it.

For example, the name of the target could be changed because of the namePrefix field, as below:

namePrefix: my-

In this case, below will be enough if we wanted to select all the targets that were originally named deploy:

select:
- name: deploy

Alternatively, using the transformed name with the prefix will produce the same behaviour. So the following case will select all the resources that will be named my-deploy, along with all the resources that were originally named my-deploy.

select:
- name: my-deploy

Reject

The reject field is a selector that drops targets selected by select, overruling their selection.

For example, if we wanted to reject all Deployments named my-deploy:

reject:
- kind: Deployment
  name: my-deploy

This is distinct from the following:

reject:
- kind: Deployment
- name: my-deploy

The first case would only reject resources that are both of kind Deployment and named my-deploy. The second case would reject all Deployments, and all resources named my-deploy.

We can also reject more than one kind, name, etc. For example:

reject:
- kind: Deployment
- kind: StatefulSet

Moreover, when the selected target is going to be transformed during the kustomization process, you can use either the original or the transformed resource id to reject it.

For example, the name of the target could be changed because of the nameSuffix field, as below:

nameSuffix: -dev

You can use the original target name to prevent it from going through any replacement.

reject:
- name: my-deploy

Alternatively, using the transformed name with the suffix will produce the same behaviour.

reject:
- name: my-deploy-dev

Delimiter

This field is intended to be used in conjunction with the index field for partial string replacement. For example, say we have a value:

path: my/path/VALUE

In our replacement target, we can specify something like:

options:
  delimiter: '/'
  index: 2

and it would replace VALUE, e.g. path: my/path/NEW_VALUE.

Index

This field is intended to be used in conjunction with the delimiter field described above for partial string replacement. The default value is 0.

If the index is out of bounds, behavior depends on whether it is in a source or target. In a source, an index out of bounds will throw an error. For a target, a value less than 0 will cause the target to be prefixed, and a value beyond the length of the split will cause the target to be suffixed.

If the fields index and delimiter are specified on sources or targets that are not scalar values (e.g. mapping or list values), kustomize will throw an error.

Field Path format

The fieldPath and fieldPaths fields support a format of a '.'-separated path to a value. For example, the default:

metadata.name

You can escape the '.' one of two ways. For example, say we have the following resource:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    config.kubernetes.io/local-config: true # this is what we want to target

We can express our path:

1. With a '\': metadata.annotations.config\.kubernetes\.io/local-config

2. With '[]': metadata.annotations.[config.kubernetes.io/local-config]

Strings are used for mapping nodes. For sequence nodes, we support three options:

1. Index by number: spec.template.spec.containers.1.image

2. Index by key-value pair: spec.template.spec.containers.[name=nginx].image. If the key-value pair matches multiple elements in the sequence node, all matching elements will be targetted.

3. Index with a wildcard match: spec.template.spec.containers.*.env.[name=TARGET_ENV].value. This will target every element in the list.

Example

For example, suppose one specifies the name of a k8s Secret object in a container's environment variable as follows:

job.yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: hello
spec:
  template:
    spec:
      containers:
        - image: myimage
          name: hello
          env:
            - name: SECRET_TOKEN
              value: SOME_SECRET_NAME

Suppose you have the following resources:

resources.yaml

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - image: busybox
    name: myapp-container
  restartPolicy: OnFailure
---
apiVersion: v1
kind: Secret
metadata:
  name: my-secret

To (1) replace the value of SOME_SECRET_NAME with the name of my-secret, and (2) to add a restartPolicy copied from my-pod, you can do the following:

kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
- resources.yaml
- job.yaml

replacements:
- path: my-replacement.yaml
- source:
    kind: Secret
    name: my-secret
  targets:
  - select:
      name: hello
      kind: Job
    fieldPaths:
    - spec.template.spec.containers.[name=hello].env.[name=SECRET_TOKEN].value

my-replacement.yaml

source:
  kind: Pod
  name: my-pod
  fieldPath: spec.restartPolicy
targets:
- select:
    name: hello
    kind: Job
  fieldPaths:
  - spec.template.spec.restartPolicy
  options:
    create: true

The output of kustomize build will be:

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
---
apiVersion: batch/v1
kind: Job
metadata:
  name: hello
spec:
  template:
    spec:
      containers:
      - env:
        - name: SECRET_TOKEN
          value: my-secret # this value is copied from my-secret
        image: myimage
        name: hello
      restartPolicy: OnFailure # this value is copied from my-pod
---
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
  - image: busybox
    name: myapp-container
  restartPolicy: OnFailure