Imagine you’ve got a Deployment running happily in your cluster. Then someone comes along and says, "Hey, can you just change the number of replicas?"
You sigh. That means either:
Editing a massive YAML file and reapplying it.
Using kubectl edit, scrolling through an ocean of text, and praying you don’t fat-finger a bracket.
Deleting and recreating the resource, which feels like overkill for a tiny change.
There’s a better way: patching.
Patching lets you surgically modify Kubernetes resources without redeploying everything. It’s the difference between using a scalpel and redesigning the entire hospital just to fix a typo on a patient’s chart.
How Patching Works
There are three ways to patch resources in Kubernetes:
JSON Patch (precise and explicit)
Strategic Merge Patch (smart and Kubernetes-aware)
Merge Patch (simple but less flexible)
Let’s break them down.
1. JSON Patch: The Laser Scalpel
JSON Patch is the most precise way to update Kubernetes resources. You define exactly what to change, how to change it, and where.
Let’s say we have a Deployment called my-app, and we need to scale it to 5 replicas without touching anything else.
kubectl patch deployment my-app -n my-namespace --type='json' -p='[{"op": "replace", "path": "/spec/replicas", "value": 5}]'
Here’s what’s happening:
op: replace → We’re replacing an existing field.
path: /spec/replicas → We’re targeting the replicas field inside spec.
value: 5 → The new value is 5.
Why JSON Patch?
If you ever need to remove a field instead of replacing it:
kubectl patch deployment my-app -n my-namespace --type='json' -p='[{"op": "remove", "path": "/metadata/annotations"}]'
Boom. That erases all annotations without touching anything else.
2. Strategic Merge Patch: The Swiss Army Knife
Strategic Merge Patch is Kubernetes-aware. Instead of precisely targeting JSON paths, you can provide a partial YAML object with just the fields you want to change.
Let’s say we need to update the image for our my-app container inside a Deployment. Instead of replacing the whole thing, we just patch what’s necessary:
kubectl patch deployment my-app -n my-namespace --type='merge' -p='{"spec":{"template":{"spec":{"containers":[{"name":"app","image":"my-app:v2"}]}}}}'
Kubernetes intelligently merges this into the existing definition.
What’s happening here?
We only specify the fields we care about (no need to provide the entire YAML).
Kubernetes keeps the rest of the deployment untouched.
It’s easier to write than JSON Patch while still being efficient.
If you need to add a new environment variable to a container:
kubectl patch deployment my-app -n my-namespace --type='merge' -p='{"spec":{"template":{"spec":{"containers":[{"name":"app","env":[{"name":"LOG_LEVEL","value":"debug"}]}]}}}}'
This adds LOG_LEVEL=debug without removing existing environment variables.
Why Strategic Merge Patch?
It’s easier to write than JSON Patch.
It doesn’t require full YAML files.
Kubernetes merges intelligently instead of replacing entire objects.
3. Merge Patch: The Simple One
If you just need a quick-and-dirty change, Merge Patch is the easiest option. It’s similar to Strategic Merge Patch but less Kubernetes-aware.
Want to update the replica count?
kubectl patch deployment my-app -n my-namespace --type='merge' -p='{"spec":{"replicas": 3}}'
Kubernetes applies this directly, but unlike Strategic Merge Patch, it doesn’t understand lists properly. If you’re modifying something inside an array (like containers), it replaces the whole array instead of merging.
When to Use Each Patch Type
| Patch Type | Best For | Pros | Cons |
| JSON Patch | Precise, fine-grained control | Exact changes, minimal impact | Harder to write |
| Strategic Merge Patch | Updating specific fields without rewriting everything | Kubernetes-aware, easy to use | Lists can be tricky |
| Merge Patch | Quick, simple updates | Easy to write | Less intelligent about merging |
Example: Patching vs. Reapplying YAML
Let’s say you need to update an annotation. Normally, you’d have to:
kubectl edit deployment my-app
Scroll through tons of YAML, find the annotation, update it manually, and then save.
Instead, one command does it instantly:
kubectl patch deployment my-app -n my-namespace --type='merge' -p='{"metadata":{"annotations":{"restarted-at":"'"$(date +%s)"'"}}}'
This adds or updates an annotation called restarted-at with the current timestamp.
Patching in CI/CD Pipelines
When running Kubernetes in CI/CD, you often need to update specific fields dynamically. Patching is perfect for that.
For example, if your pipeline builds a new image, you can update the Deployment with:
kubectl patch deployment my-app -n my-namespace --type='merge' -p='{"spec":{"template":{"spec":{"containers":[{"name":"app","image":"my-app:'"$BUILD_ID"'"}]}}}}'
This injects a new image version without redeploying from scratch.
Final Thoughts
Patching is the fast, efficient way to modify Kubernetes resources without full redeployments. Whether you need to:
Scale up/down dynamically
Update container images without touching other settings
Add new labels, annotations, or environment variables
Remove unwanted fields without rewriting YAML
Patching lets you work smarter, not harder.
Stop treating Kubernetes like an immutable monolith—patch what you need, when you need it, without unnecessary redeployments. Your cluster (and your sanity) will thank you.
