Managing Kubernetes resources efficiently is essential for scalable cloud-native applications. The kubectl patch command lets you quickly update running Kubernetes resources — such as labels, container images, or replicas — without redeploying entire configurations. In this article, you’ll learn how to use kubectl patch within Azure Kubernetes Service (AKS), complete with practical examples.

What is the kubectl patch Command?

Patch is a command line option for updating Kubernetes API objects. You can use it to update a running configuration. You do this by supplying it with the section to update, instead of a completely new configuration, as you would with kubectl apply.

The command works by “patching” changes onto the current resource configuration. Unlike a kubectl replace operation, the patch operation only modifies specific fields in the resource configuration.

What can we do using Kubectl patch command?

With kubectl patch, you can quickly fix issues with updating the name, image, label, replicas, affinity/tolerations, environment variables, configaps, secrets, volumes, ports, etc. kubectl patch supports YAML and JSON formats. Using either format, you can drill into the specific field of the resource and change it to your desired value. Kubectl supports three different patching strategies: Strategic Merge (the default) and JSON Merge. You utilize these formats through the patching strategy.

“kubectl patch supports three strategies: Strategic Merge Patch (default), JSON Merge Patch, and JSON Patch. Each has different use cases depending on the complexity of your update.”

Sample deployment YAML file

Let’s say we have the following Nginx deployment YAML file, we originally had only one label (environment: prod), and we want to add a new label to specify the app we are running (app: nginx). We will use the –patch command to enter the new labels:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
            - containerPort: 80

Example 1: Patch the label to the deployment

Method 1: Patch using Inline JSON 

In our case, we would like to add environment for the deployment as prod, for this we would run the following command to add the new labels:

kubectl patch deployment nginx-deployment --patch '{\"metadata\": {\"labels\": {\"environment\": \"prod\"}}}'

For the patch command to work, you must correctly include the map and lists in the original YAML file, so Kubernetes knows exactly where to go to add/update the new value properly.

We are going to discuss very simple example of using the kubectl patch command to update fields in your Kubernetes deployment file.

If you want to patch from the YAML file, you can create file with the required update and save as .YAML as shown in below and execute the file using kubectl.

Method 2: Patch using YAML file

“This patch file only contains the section you want to update, not the full deployment manifest.

#Save the file using below manifest (patch.yaml)
metadata:
  labels:
    environment: prod

#execute the command to apply the new changes in the existing pod
kubectl patch deployment nginx-deployment --patch-file ./thi/patch.yaml

You can run the following to check the YAML for the new updates:

#View the YAML in the notpad
kubectl edit deployment nginx-deployment
#View the YAML in the console itself
kubectl get deployment nginx-deployment -o yaml

In return, we get the following YAML file:

Example 2: Patch the label to the Pod level

In this same scenario, if we wanted to update the labels within the Pod template, you would have to drill into the spec field instead of the metadata.

Usually, you would drill into the metadata and spec fields for kubectl patch, but this would also work with other YAML fields, such as status or even a new custom field you created through a CRD (custom resource definition).

In the following example, we are attempting to add a new label environment: prod to the existing labels within the pod template, as the following:

#replace : Modifies the value of an existing field.
#add: Adds/replace a new field or value to an array.
#remove: Removes a field or an element from an array.
#copy: Copies the value of one field to another
#test: Verifies that a specific field has a certain value. The patch operation will fail if the condition is not met
#move: Moves a value from one location to another within the object
kubectl patch deployment nginx-deployment --type='json' --patch='[{"op": "add", "path": "/spec/template/metadata/labels/environment", "value":"prod"}]

The above cmd will be used for both adding new or updating the existing fields. To check if the deployment got the new labels, you can run the following:

kubectl get deployment nginx-deployment --show-labels

Example 3: Update Pod label and container image

We will attempt to update the image of the ingress from older version to new version and update the label value together . This will require us to drill further into the list (the – is a list and will use [ ] to tap into it from the kubectl patch command) instead of a map (uses { }):

kubectl patch deployment nginx-deployment --patch '{\"spec\": {\"template\": {\"metadata\": {\"labels\": {\"environment\": \"production\"}}, \"spec\": {\"containers\": [{\"name\": \"nginx\", \"image\": \"nginx:1.14.2\"}]}}}}'

Conclusion

The kubectl patch command is a versatile tool for managing Kubernetes resources, particularly in dynamic environments like Azure Kubernetes Service. It allows for targeted updates with minimal effort, making it ideal for quick fixes and operational adjustments. By mastering the kubectl patch command, AKS administrators can maintain agility and efficiency in managing their clusters.

Whether you are adding labels, scaling deployments, or updating container images, kubectl patch ensures you can implement changes quickly and confidently. Embrace this command to streamline your Kubernetes workflows and keep your AKS environment optimized.

“Next time you’re troubleshooting or making small updates in AKS, try kubectl patch instead of redeploying. What’s your favorite kubectl command? Drop it in the comments 👇”

Frequently Asked Questions (FAQ)

1. When should I use kubectl patch instead of kubectl apply?

Use kubectl patch when you want to make quick, targeted changes to a Kubernetes resource without redeploying the entire manifest. For example, updating a label, changing an image tag, or adding an environment variable can be done faster with kubectl patch. If you need to manage large or version-controlled manifests, kubectl apply is still the better choice.

2. Can I rollback a kubectl patch?

No, kubectl patch itself does not provide a rollback mechanism. Once applied, the changes are immediately reflected in the resource. To revert, you must either:

• Manually patch again with the previous values, or

• Redeploy the original manifest using kubectl apply -f <file.yaml>.
  Using GitOps or storing manifests in source control is recommended to track and revert changes easily.

3. What are common errors with kubectl patch?

Some common errors include:

• Incorrect JSON/YAML syntax – forgetting quotes, brackets, or commas.

• Missing path values – targeting the wrong field (e.g., metadata vs spec.template.metadata).

• Unsupported patch type – not specifying --type=json when using JSON Patch operations.

• Read-only fields – trying to patch fields like status or metadata.uid, which cannot be modified.

4. Does kubectl patch work for all Kubernetes resources?

Yes, kubectl patch works for most standard Kubernetes resources like Deployments, Pods, Services, ConfigMaps, and Secrets. However, some Custom Resource Definitions (CRDs) may not fully support all patch types depending on their schema.

5. Is kubectl patch safe to use in production?

Yes, but with caution. Since it makes live changes to resources, there is no automatic rollback. It is best used for small, urgent fixes in production. For long-term changes, update your manifests and use kubectl apply to keep your deployments consistent.