Manifests: Patches

Patches are a way to perform minor overrides to the configuration without having to create a separate config file. Patch functionality follows JSON Patch(RFC) semantics, as well as enhanced path selectors, as implemented by the yaml-jsonpath library.

Patches are compatible with kubectl manifests and inlineManifest.

Example

Patches are ideal for reflecting changes between different environments, e.g. dev, staging and production.

version: v2beta1
name: nginx-k8s

deployments:
  example:
    kubectl:
      manifests:
        - ./deployment.yaml
      patches:
        - target:
            apiVersion: apps/v1
            kind: Deployment
            name: nginx-deployment
          op: replace
          path: spec.template.spec.containers[0].image
          value: nginx:1.23.3

Explanation:

• The above example defines 1 patch for the deployment.yaml manifest
• During deployment, the patches are applied in-memory, changing in this case the image of the container

# In-Memory deployment BEFORE Applying Patches 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 4
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
            - containerPort: 80

# In-Memory deployment AFTER Applying Patches 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 4
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.23.3
          ports:
            - containerPort: 80

Array Paths

When you want to define a path that contains an array (e.g. containers), you have several options:

1. Use the index of the array item you want to patch, e.g. spec.template.spec.containers[0], spec.template.spec.containers/0
2. Use a wildcard selector to match all array item(s), e.g. spec.template.spec.containers.*,spec.template.spec.containers[*] or spec.template.spec.containers/*

Value For Replace / Add

If you use the replace or add operation, value is a mandatory property.

info

If value is defined, the new value must provide the correct type to be used when adding or replacing the existing value found under path using the newly provided value, e.g. an array must be replaced with an array.

Example: Match patches

version: v2beta1
name: nginx-k8s

deployments:
  example:
    kubectl:
      inlineManifest: |-
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: nginx-inline-deployment
        spec:
          selector:
            matchLabels:
              app: nginx
          replicas: 4
          template:
            metadata:
              labels:
                app: nginx
            spec:
              containers:
                - name: nginx
                  image: nginx:1.14.2
                  ports:
                    - containerPort: 80
                - name: busybox
                  image: busybox
                  command: ["sleep"]
                  args: ["infinity"]
                - name: alpine
                  image: alpine
                  command: ["sleep"]
                  args: ["infinity"]
      patches:
        # wildcard match
        - target:
            apiVersion: apps/v1 # Optional
            kind: Deployment    # Optional
            name: nginx-inline-deployment # Required
          op: add
          path: spec.template.spec.containers[*].env
          value: [{"name": "test", "value": "test123"}]

Explanation:

• The above example will patch and add an environment variable test=test123 to all containers in the deployment.

Example: Using target effectively

version: v2beta1
name: nginx-k8s

deployments:
  example:
    kubectl:
      inlineManifest: |-
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: nginx-inline-deployment
        spec:
          selector:
            matchLabels:
              app: nginx
          replicas: 4
          template:
            metadata:
              labels:
                app: nginx
            spec:
              containers:
                - name: nginx
                  image: nginx:1.14.2
                  ports:
                    - containerPort: 80
        ---
        apiVersion: v1
        kind: Service
        metadata:
          name: nginx-inline-deployment
          labels:
            app: nginx-inline-deployment
        spec:
          ports:
          - port: 80
            protocol: TCP
          selector:
            app: nginx-inline-deployment
      patch:
        - target:
            apiVersion: apps/v1         # Optional
            kind: Deployment    # Optional
            name: nginx-inline-deployment # Required
          op: add
          path: spec.template.metadata.labels.test
          value: test-deployment
        - target:
            apiVersion: v1 # Optional
            kind: Service    # Optional
            name: nginx-inline-deployment # Required
          op: add
          path: metadata.labels.test
          value: test-service

Explanation:

• The above example shows how you can address two resources with the same name, in this case nginx-inline-deployment.
• By using kind and apiVersion we can narrow down one patch to be applied only on apps/v1 - Deployment and the other only to v1 - Service

Configuration

patches required object[]

Patches are additional changes to the pod spec that should be applied

target required

Target describes where to apply a config patch

apiVersion required string

ApiVersion is the Kubernetes api of the target resource

kind required string

Kind is the kind of the target resource (eg: Deployment, Service ...)

name required string

Name is the name of the target resource

op required string

Operation is the path operation to do. Can be either replace, add or remove

path required string

Path is the config path to apply the patch to

value required

Value is the value to use for this patch.