Patches Intro

In this lesson, we explore how to use patches with Kustomize to modify Kubernetes configurations. Patches offer a granular approach to updating specific sections of a Kubernetes resource, which is especially useful when you want to target one or a few objects rather than applying a broad change. For instance, if you need to update the replica count in a Deployment, a tailored patch that specifically addresses that object is ideal.

Patch Parameters

When creating a patch, you must specify three key parameters:

1. Operation Type:
   This parameter defines the type of change to perform. The primary operations include:

   • add: Adds an element to a list (e.g., adding a container to a Deployment’s container list).
   • remove: Deletes an element from the configuration (e.g., removing a container or label).
   • replace: Substitutes an existing value with a new one (e.g., updating a Deployment's replica count from 5 to 10).

2. Target:
   The target parameter specifies which Kubernetes resource or resources will be patched. You can match resources based on properties such as kind, version, name, namespace, label selectors, or annotation selectors. Multiple properties can be combined to precisely target the intended objects.

3. Value:
   For add or replace operations, this parameter defines the value to be added or used as a replacement. The remove operation does not require a value since it deletes the specified element.

Inline Patch Example

Consider the following example where we have a Deployment defined in deployment.yaml. We aim to change the deployment name from "api-deployment" to "web-deployment". Below is the original Deployment configuration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
    spec:
      containers:
      - name: nginx
        image: nginx

To perform the update, define the patch in your kustomization.yaml file under the patches property. The patch below specifies the target object (a Deployment with the name "api-deployment") and provides an inline patch to replace the metadata/name field:

patches:
  - target:
      kind: Deployment
      name: api-deployment
    patch: |-
      - op: replace
        path: /metadata/name
        value: web-deployment

After applying this patch, the rendered Deployment configuration becomes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
    spec:
      containers:
      - name: nginx
        image: nginx

Replacing the Replica Count

Next, let’s update the number of replicas. Assume the original Deployment configuration has one replica and you want to change it to five. The starting configuration is as follows:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
    spec:
      containers:
      - name: nginx
        image: nginx

Use an inline patch in your kustomization.yaml file to update the replica count:

patches:
- target:
    kind: Deployment
    name: api-deployment
  patch: |-
    - op: replace
      path: /spec/replicas
      value: 5

After applying this patch, the updated Deployment configuration appears as:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 5
  selector:
    matchLabels:
      component: api
  template:
    metadata:
      labels:
        component: api
    spec:
      containers:
      - name: nginx
        image: nginx

Patch Strategies: JSON 6902 vs. Strategic Merge Patch

There are two primary patch strategies in Kustomize: JSON 6902 patches and strategic merge patches.

JSON 6902 Patch

A JSON 6902 patch involves providing the target object and a list of operations including the patch details such as the operation (e.g., replace), the path of the property, and the new value. Here’s an example:

customization:
  patches:
    - target:
        kind: Deployment
        name: api-deployment
      patch:
        - op: replace
          path: /spec/replicas
          value: 5

Strategic Merge Patch

A strategic merge patch resembles a standard Kubernetes configuration file. It merges your partial configuration into the existing one, updating only the specified fields. Below is the equivalent strategic merge patch for the replica count change:

customization:
  patches:
    - patch: |-
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: api-deployment
        spec:
          replicas: 5

Both methods are effective; the choice depends on your preference. Strategic merge patches tend to be more readable and familiar for those used to standard Kubernetes configurations, while JSON 6902 patches offer higher precision for targeted modifications.

Key Takeaways

By understanding these patching techniques, you can tailor your Kubernetes configurations to meet specific requirements with the appropriate level of granularity. This flexibility in patching ensures that your deployments are both maintainable and scalable.

For more detailed information on Kubernetes configurations and best practices, see the Kubernetes Documentation.