Kustomize: Template-Free Kubernetes YAML Customization with Base/Overlay

What kustomize Does and Who It Is For

Kubernetes configuration management has a tension between keeping YAML files readable and creating environment-specific variants. Templating tools solve this by replacing values with placeholders, but the result is YAML that cannot be validated or applied directly without rendering the template first.

Kustomize takes a different approach. It leaves the original YAML files untouched and usable as-is. Customizations are declared separately in a kustomization.yaml file and applied at build time as patches. The README compares this to `make` (what it does is declared in a file) and to `sed` (it emits edited text).

The tool is aimed at operations and platform teams who manage multiple Kubernetes clusters or environments from the same source repository. It is written in Go, licensed under Apache-2.0, and officially part of the Kubernetes project under sig-cli. The repository received its last push on 27 September 2026, and version kustomize/v5.8.1 was released on 9 February 2026.

Base and Overlay: The Core Architecture

Kustomize organises configurations around two concepts: a base and overlays.

The base is a directory containing your Kubernetes YAML files (Deployments, Services, ConfigMaps, etc.) and a kustomization.yaml that declares them as resources. The base represents the canonical application configuration that all environments share.

An overlay is a separate directory with its own kustomization.yaml that references the base and applies patches on top of it. Each overlay represents one variant of the application, such as development, staging, or production. The patches in an overlay modify only the fields that differ between environments: replica counts, resource limits, image tags, or labels. They do not duplicate the full resource definition.

The README describes the file structure for a typical setup:

~/someApp
├── base
│   ├── deployment.yaml
│   ├── kustomization.yaml
│   └── service.yaml
└── overlays
    ├── development
    │   ├── cpu_count.yaml
    │   ├── kustomization.yaml
    │   └── replica_count.yaml
    └── production
        ├── cpu_count.yaml
        ├── kustomization.yaml
        └── replica_count.yaml

The base YAML files can be a fork of an upstream configuration from another repository. Because the overlay patches, rather than modifying the source files, rebasing from upstream to pick up changes is straightforward: update the base, and the overlays continue to apply their patches on top.

Building and Applying Kustomized YAML

The primary command generates the final merged YAML by combining the base with all overlay patches:

kustomize build ~/someApp

The output is standard Kubernetes YAML on stdout. It can be piped directly to kubectl:

kustomize build ~/someApp | kubectl apply -f -

For a specific overlay (the production variant in the example above):

kustomize build ~/someApp/overlays/production

And to apply that overlay:

kustomize build ~/someApp/overlays/production | kubectl apply -f -

The `kustomize build` output is plain YAML, so it can be stored in a file, diffed, reviewed in a pull request, or passed to any tool that accepts Kubernetes manifests. Nothing in the pipeline requires kustomize-specific tooling on the target cluster.

kubectl Integration and Standalone Installation

Kustomize is embedded in kubectl. The `kubectl kustomize` and `kubectl apply -k` subcommands call the embedded version directly without requiring a separate installation. To check which kustomize version is bundled in a given kubectl binary:

> kubectl version --client
Client Version: v1.31.0
Kustomize Version: v5.4.2

The README provides a full table mapping kubectl versions to embedded kustomize versions. The embedding started at kustomize v2.0.3 in kubectl v1.14 (released in 2019), stayed frozen at v2.0.3 through kubectl v1.20, jumped to v4.0.5 in kubectl v1.21, and has been updated regularly since. The README notes that kubectl v1.27 includes kustomize v5.0.1.

The standalone `kustomize` binary is installed separately for teams who need a newer version than what is embedded in their kubectl, or who want to use kustomize in CI without a full kubectl installation. Installation instructions are at kubectl.docs.kubernetes.io/installation/kustomize/.

For building kustomize from source, the Makefile in the repository provides targets. The Makefile lists `LATEST_RELEASE=v5.8.1` and the build installs the binary to the Go bin directory using `go install` with version provenance flags built in.

Patches, ConfigMap Generators, and Components

Beyond simple overlays, kustomize supports several customisation primitives that the examples directory covers in separate documents.

Strategic merge patches and JSON patches both allow modifying specific fields of a Kubernetes resource without replicating the full resource definition. The examples directory includes `jsonpatch.md`, `inlinePatch.md`, and `patchMultipleObjects.md` as worked examples.

ConfigMap generators create ConfigMap resources from file contents or literal key-value pairs, with automatic hash suffixes appended to ConfigMap names so that Deployments referencing a ConfigMap automatically roll over when the ConfigMap content changes. The example file `configGeneration.md` covers this pattern.

Components are a reusable kustomize primitive that lets teams extract common patches (such as enabling a logging sidecar or adding a standard security context) into a shared component directory and reference it from multiple overlays. The examples directory includes `components.md` for this pattern.

The `kustomize edit fix` subcommand is a maintenance tool that updates kustomization.yaml files to conform with current kustomize API versions, which matters when upgrading across major versions.

Kustomize vs. Helm: Different Problems

The related searches and search questions show users directly comparing kustomize to Helm. They solve overlapping but distinct problems.

Helm is a package manager for Kubernetes. It uses Go templates embedded in chart files to parameterise manifests. A Helm chart is a redistributable unit: it can be published to a registry, versioned, installed, upgraded, and rolled back as a named release. Helm tracks installed releases in the cluster and manages the full lifecycle.

Kustomize does not track releases or maintain cluster state. It generates YAML. There is no kustomize install, kustomize upgrade, or kustomize rollback. It has no template engine. The kustomization.yaml declares resource references and patches using native Kubernetes types, not template syntax.

The practical difference is use case: Helm suits teams distributing reusable application packages to external users; kustomize suits teams managing their own application configurations across environments in a single git repository. They are often used together: Helm renders chart output into a base directory, and kustomize overlays apply organisation-specific patches on top of that output.

Using kustomize with Argo CD and GitOps Workflows

Argo CD, the Kubernetes GitOps continuous delivery tool, has native support for kustomize: when an Argo CD Application points at a directory containing a kustomization.yaml, Argo CD calls kustomize build internally and applies the output. This makes kustomize a natural fit for GitOps workflows where the repository state drives cluster state.

The search data shows users querying "how to use kustomize with argocd", which reflects how common this combination is in practice. The integration works because both tools operate on the same artefact: plain Kubernetes YAML applied through kubectl. Argo CD handles the delivery and drift detection; kustomize handles the configuration generation.

One constraint to account for is the kustomize version that Argo CD embeds. Different versions of Argo CD ship different kustomize versions, and the kustomization.yaml files written for a newer kustomize may use fields not available in an older embedded version. Checking the Argo CD release notes for the embedded kustomize version is a required step before using newer kustomize features in a managed cluster.

Editorial conclusion

Kustomize is the right tool for teams who manage Kubernetes configurations across environments and want to keep the source YAML readable and unmodified. Teams who already use Helm for package management and need a full release lifecycle (rollback, versioned charts, dependency trees) will find kustomize does not replace those features. Before adopting it, verify which kustomize version is embedded in the kubectl binary already in use, since the embedded version may lag the standalone release. The last push to the repository was on 27 September 2026, and the latest standalone release is kustomize/v5.8.1.

Frequently asked questions

Official sources

1. Issues
2. kubernetes-sigs/kustomize on GitHub
3. License: Apache-2.0
4. README
5. Releases