kustomize: template-free YAML customization for Kubernetes

What kustomize solves, and who it is for

The README states the problem plainly: kustomize lets you customize raw, template-free YAML files for multiple purposes, leaving the original YAML untouched and usable as is. That single constraint drives most of the design. If you have ever opened a Helm chart to find out what the rendered output actually looks like, the appeal here is that the input is already valid Kubernetes YAML. You can kubectl apply it without kustomize and it works.

The audience is platform and application engineers who already keep manifests in Git and who need the same workload to run in development, staging and production with small differences. The README frames it with two analogies: it is like make, in that what it does is declared in a file, and like sed, in that it emits edited text. Neither analogy suggests a package manager, and that is the honest way to read the tool.

The repository is sponsored by sig-cli, the Kubernetes CLI special interest group, and the project lives under the kubernetes-sigs organization. The last push to master was on 2026-11-01, and the most recent tagged release is kustomize/v5.8.3 from 2026-10-08.

The base and overlay mechanism, and what a build actually emits

A kustomization file declares resources and the customization to apply to them. The README's first example puts a kustomization.yaml next to deployment.yaml and service.yaml, listing both as resources and adding a common label. A build reads that directory, loads the referenced resources, applies the declared transformations, and prints YAML to stdout.

Overlays are the second half. The README describes managing traditional variants such as development, staging and production using overlays that modify a common base. An overlay is itself a directory with its own kustomization.yaml, which points at the base and adds patches. The examples directory in the repository carries the same idea under names like multibases, components and patchMultipleObjects, so the pattern is documented in more than one place.

Generators are the other mechanism worth understanding before adopting. The repository ships examples/configGeneration.md, examples/generatorOptions.md and examples/secretGeneratorPlugin.md, which indicate that config generation is a documented part of the tool.

Because the output is plain YAML on stdout, it composes with anything that reads stdin. The README shows the direct pipeline into the cluster, and the same output can be written to a file, diffed in review, or fed to a GitOps controller.

Installing kustomize and running a first build

The README does not inline installation steps. It links to Installation instructions at kubectl.docs.kubernetes.io, and separately documents the copy embedded in kubectl. That second path is the one to check first, because if your kubectl is recent enough you may not need a separate binary at all.

Run this to see which kustomize version your kubectl carries. The README gives this exact example and the output shows both a client version and a Kustomize Version line.

kubectl version --client

The README's compatibility table maps kubectl versions to embedded kustomize versions: kubectl v1.21 ships v4.0.5, v1.22 ships v4.2.0, v1.23 ships v4.4.1, v1.24 ships v4.5.4, v1.25 and v1.26 ship v4.5.7, and v1.27 ships v5.0.1. Anything before v1.14 has no embedded kustomize. If you need a version newer than your kubectl's, install the standalone CLI from the installation page rather than waiting for a Kubernetes upgrade.

For a first real use, follow the README's file structure. Create a directory with your existing manifests and a kustomization.yaml beside them. This is the shape the README describes, with the resources listed in the kustomization file.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

Build it to see the rendered output without touching a cluster. The README gives kustomize build ~/someApp as the command, and the result is YAML on stdout.

kustomize build ~/someApp

Once the output looks right, the README shows the direct apply pipeline. Read the generated YAML before piping it the first time; the whole point of the tool is that the diff is reviewable.

kustomize build ~/someApp | kubectl apply -f -

To go further, create an overlay directory whose kustomization.yaml references the base directory under resources and adds patches. The examples/components.md and examples/multibases.md files in the repository cover the two common ways to structure that.

Where kustomize is the wrong tool

kustomize has no dependency resolver and no package registry. If your deployment depends on a third-party chart that itself depends on other charts, and you want versions pinned and fetched, kustomize does not do that job. The README's make and sed analogies are accurate: it transforms text you already have, and it does not acquire anything for you.

The embedded-kubectl problem is the second real constraint, and it is the one that bites teams in practice. The README states that the kustomize flow in kubectl remained frozen at v2.0.3 until kubectl v1.21 updated it to v4.0.5, and that updates going forward will be reflected in Kubernetes release notes. That means the version you get from kubectl is tied to your cluster tooling's release cadence, not to kustomize's. A team that develops against the standalone binary and applies through an older kubectl can hit behaviour differences that are hard to attribute, because the failure shows up as unexpected output rather than an error.

There is also a schema boundary. The README says kustomize targets kubernetes and understands and can patch kubernetes style API objects. The repository includes examples/customOpenAPIschema.md, which suggests a path for supplying schemas, but this is not the default experience.

Finally, if your manifests are already generated by a program you control, adding a kustomization layer puts two transformation systems in the same pipeline. That is usually worse than picking one.

kustomize compared with Helm, and with plain kubectl apply

The usual comparison is kustomize versus Helm, and the difference is structural rather than cosmetic. Helm is a package manager: a chart is a versioned artifact, values are substituted into templates, and releases are tracked in the cluster. kustomize is a transformer: the input is valid YAML, the output is valid YAML, and nothing is recorded in the cluster about the transformation. If you delete and reapply, kustomize has no release history to consult because it never created one.

That difference decides most adoption questions. Helm fits when you consume software written by someone else and want versioned upgrades. kustomize fits when you own the manifests and want to vary them per environment while keeping the base readable. The two are not mutually exclusive, but combining them means one tool renders and the other patches the rendered result, which is a pipeline you have to reason about in full.

The comparison with plain kubectl apply is simpler. kubectl apply -f dir/ takes a directory of manifests and applies them as they are. kustomize adds the layer that lets one directory serve several environments without duplicating files. If you have exactly one environment and no variation, kustomize is overhead.

Maintenance, releases and the Apache-2.0 licence

The repository is not archived and the last push was on 2026-11-01, so it is under current development rather than dormant. Three coordinated releases landed on 2026-10-08: kustomize/v5.8.3, api/v0.21.3 and cmd/config/v0.21.3. The Makefile pins LATEST_RELEASE=v5.8.3, which matches the newest tagged kustomize release.

The repository is a Go workspace, visible in the top-level go.work and go.work.sum files, with separate modules under kustomize/, kyaml/, api/, cmd/ and plugin/. That layout matters for upgrade cost: kyaml and cmd/config version independently of the kustomize CLI, so a change you want in the CLI may arrive on a different schedule than a change in the library you import. Building from source uses the Makefile target that runs go install inside the kustomize directory with ldflags injecting a build date and a version derived from git describe.

Licensing is Apache-2.0, and the repository carries both LICENSE and LICENSE_TEMPLATE files, with source files marked by an SPDX-License-Identifier header. Apache-2.0 includes an explicit patent grant and requires that notices be preserved. If you vendor kustomize source into a product, or ship a modified binary, the notice and attribution obligations apply to your distribution. That is a description of the licence text, not legal advice; get counsel if the distribution model is unusual.

Editorial conclusion

Adopt kustomize when your manifests are plain YAML you want to keep valid on their own and you need per-environment overlays rather than a packaging system. Do not adopt it if you need dependency resolution, chart versioning or a package registry; that is what Helm does. Before committing, check the Kustomize Version reported by kubectl version --client, because the copy inside kubectl is pinned to the Kubernetes release and may not match the standalone binary you develop against.

Frequently asked questions

Official sources

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