> For the complete documentation index, see [llms.txt](https://dinush-chathurya.gitbook.io/kustomize-e-book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinush-chathurya.gitbook.io/kustomize-e-book/advanced-kustomize-concepts/07-patch-techniques.md).

# Patch Techniques

In this chapter, we’ll dive deep into **patching**—a powerful feature in Kustomize that allows you to override and customize Kubernetes resources across different environments while reusing the same base.

## What Are Patches?

Patches allow you to **modify specific fields** in a Kubernetes resource without duplicating the entire file. This promotes **DRY (Don't Repeat Yourself)** principles in your configuration management.

Kustomize supports three main patch strategies:

* ✅ Strategic Merge Patches
* ✅ JSON 6902 Patches
* ✅ Inline Patches

### 1. Strategic Merge Patches (SMP)

Strategic Merge Patch is the most commonly used patch format. It merges your patch with the original resource based on the resource’s schema. This means you can add, remove, or modify fields without worrying about the order of the keys.

Example folder structure:

```yaml
kustomize/
└── overlays/
    └── dev/
        ├── kustomization.yaml
        └── patches/
            └── deployment-patch.yaml
```

`patches/deployment-patch.yaml`

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: my-app
          image: my-app:dev
```

`kustomization.yaml` reference:

```yaml
resources:
  - ../../base

patchesStrategicMerge:
  - patches/deployment-patch.yaml
```

✅ Best for: modifying resource fields like `replicas`, `containers`, and `labels`.

### 2. JSON 6902 Patch

Use `JSON 6902` for **precise, schema-less**, or **nested modifications**, especially when dealing with multiple containers or complex fields.

Example:

```yaml
# overlays/dev/kustomization.yaml
resources:
  - ../../base

patches:
  - target:
      group: apps
      version: v1
      kind: Deployment
      name: my-app
    path: patches/image-replace.json
```

`patches/image-replace.json`

```yaml
- op: replace
  path: /spec/template/spec/containers/0/image
  value: my-app:dev
```

✅ Ideal for: `deeply nested fields` or `Custom Resource Definitions (CRDs)`.

### 3. Inline Patches

Inline patches are embedded directly inside your `kustomization.yaml` file. They’re handy for quick, one-off tweaks.

```yaml
patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |
      - op: replace
        path: /spec/replicas
        value: 2
```

✅ Best for: `small, straightforward` changes without needing a separate file.

### Patching Secrets & ConfigMaps

While patches can be used for `Secrets` and `ConfigMaps`, it’s more common to **regenerate them in overlays** with:

```yaml
configMapGenerator:
  - name: app-config
    files:
      - config.properties
    behavior: merge
```

✅ Use `behavior: merge` to override base definitions.

## Patch Hierarchy in Kustomize

Kustomize applies resources in this order:

* 01.Base resources
* 02.Overlays (patches)
* 03.Customizations (transformers, generators)

Understanding this merge order helps when debugging unexpected results.

## Practical Example

Use the following to preview patched output before applying it to the cluster:

```bash
kustomize build overlays/staging | kubectl diff -f -
```

Or apply it directly:

```bash
kustomize build overlays/prod | kubectl apply -f -
```

## Best Practices

* Use **Strategic Merge** Patches for most environment-level overrides
* Use **JSON 6902** Patches for fine-grained or complex changes
* Prefer **Inline Patches** for minor, temporary edits
* Avoid bloated patches—keep them focused and well-named
* Use generators with `behavior: merge` for `Secrets` and `ConfigMaps`
* Always store patch files under a `patches/` folder per environment

## Summary

Patching is the backbone of environment customization in Kustomize. Whether you're tweaking replica counts or customizing deep-nested fields, you have flexible strategies to choose from. By understanding when and how to use each patching technique, you’ll write cleaner, more maintainable, and scalable configurations.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://dinush-chathurya.gitbook.io/kustomize-e-book/advanced-kustomize-concepts/07-patch-techniques.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.