Kustomize: Bases, Overlays & Patches for Kubernetes

Q: Is Kustomize part of kubectl?

Yes. kubectl apply -k <dir and kubectl kustomize <dir use an embedded Kustomize. The standalone kustomize binary is often newer, so pin one version for CI and local use.

Q: How do I see what Kustomize will apply?

Run kubectl kustomize <overlay to print the rendered manifests and kubectl diff -k <overlay to compare them with the cluster. In CI, render the overlay and post the diff on the pull request.

Kustomize

Most teams run the same application in several Kubernetes environments — development, staging, production, perhaps one per region — and the manifests differ only in a few places: replica counts, image tags, resource limits, a namespace, some configuration. Copying the whole set of YAML files per environment works until the copies drift apart. Templating them, as Helm does, works too, but turns plain manifests into a templating language.

Kustomize takes a third approach: keep ordinary Kubernetes YAML as the base, and describe each environment as an overlay that patches the base. There are no templates and no variables to render — just declarative transformations of real manifests. Kustomize is built into kubectl (kubectl apply -k), and GitOps tools such as Argo CD and Flux render it natively.

TL;DR

Put shared manifests in a base and per-environment differences in overlays that reference the base.
Describe changes declaratively in kustomization.yaml: namespace, labels, images, replicas, and patches.
Use generators for ConfigMaps and Secrets; their hashed names make Pods roll when configuration changes.
Always review the rendered output (kubectl kustomize, kubectl diff -k) before applying.
Reuse optional features across overlays with components.
Choose Helm when you need to package and distribute software with many configurable options; choose Kustomize for your own applications.

Quick Example

A base for a checkout service and a production overlay that pins the image, raises replicas, sets the namespace, and generates configuration:

The base stays valid, deployable YAML. Production differs only by what its overlay says.

Core Concepts

Bases, Overlays, and Resources

A kustomization.yaml lists resources — files, directories containing their own kustomization, or remote bases — and the transformations to apply to them. An overlay is simply a kustomization whose resources include a base. Overlays can stack: a production-eu overlay can build on production.

Transformers

Patches

Strategic merge patches look like partial manifests and merge into the matching resource — convenient for replicas, resources, or environment variables. JSON patches are precise operations on paths, useful for list positions or removals:

A target selector can apply one patch to many resources, such as adding a toleration to every Deployment in an overlay.

Generators

configMapGenerator and secretGenerator create ConfigMaps and Secrets from literals, files, or env files, and append a hash of the content to the name, updating every reference. Changing configuration therefore changes the Pod template and triggers a rolling update — instead of Pods silently running with stale configuration. Keep real secrets out of Git: generate Secrets in CI from a secrets manager, or use an external secrets operator. See Secrets Management.

Components

A component (kind: Component) is a reusable bundle of resources and patches — an HPA, a sidecar, extra monitoring — that overlays opt into with components:. It avoids copying the same feature into several overlays.

Reviewing What Will Change

Kustomize's output is plain YAML, which makes reviews straightforward:

Render in CI with kustomize build (or kubectl kustomize) and validate the result with schema and policy checks.
Post the rendered diff between the base branch and the pull request, so reviewers see the effective change rather than an overlay edit.
Use kubectl diff -k against the cluster before a manual apply, or let a GitOps controller show drift.

The kustomize CLI and the version embedded in kubectl can differ; pin the version your CI uses so local renders match. See GitOps.

Kustomize or Helm?

The two combine well: Kustomize can inflate a Helm chart (helmCharts: with --enable-helm) and patch the output, which is handy for tweaking an upstream chart without forking it.

Best Practices

Keep the Base Deployable

A base should be valid, minimal manifests with safe defaults. If the base only works after an overlay fixes it, the base has hidden coupling.

Prefer Small, Named Patches

Several focused patch files — replicas-patch.yaml, resources-patch.yaml — are easier to review than one large patch that rewrites half a Deployment.

Pin Images by Digest in Production

images: accepts digest:. Promoting the exact digest built in CI guarantees each environment runs the same bytes — see CI Pipeline Design and Quality Gates.

Pin Remote Bases

Remote bases (github.com/org/repo//path?ref=v1.2.0) must reference a tag or commit. An unpinned remote base changes your deployment whenever someone else pushes.

Common Mistakes

Labels That Rewrite Selectors

Copying the Base Into Every Overlay

Secrets Committed as Generator Literals

FAQ

Is Kustomize part of kubectl?

Yes. kubectl apply -k <dir> and kubectl kustomize <dir> use an embedded Kustomize. The standalone kustomize binary is often newer, so pin one version for CI and local use.

What is the difference between a base and an overlay?

A base is a set of shared manifests with a kustomization file. An overlay is a kustomization that includes a base as a resource and adds environment-specific changes such as a namespace, image tags, patches, or generated configuration.

Why do generated ConfigMaps have hash suffixes?

So that changing configuration changes the name referenced by the Pod template, which triggers a rolling update. Without the hash, Pods keep running with old configuration until something else restarts them. You can disable the suffix, but you lose that safety.

Should I use Kustomize or Helm?

Kustomize for your own applications with modest per-environment differences, where plain YAML and simple patches are enough. Helm for distributing software with many options, or when you want its release, upgrade, and rollback lifecycle. Many teams use both.

How do I see what Kustomize will apply?

Run kubectl kustomize <overlay> to print the rendered manifests and kubectl diff -k <overlay> to compare them with the cluster. In CI, render the overlay and post the diff on the pull request.