Every application needs to run in more than one place, and those places are never exactly alike.

One app, many environments

A real application usually lives in several environments. Developers test on a small development cluster. A staging cluster mimics production for final checks. Production serves real customers. Some companies add more copies for different regions or different customers. In every one of these places the application is the same program, but the settings around it differ.

The development copy might need one replica and a tiny memory limit. Production might need twelve replicas, large limits, and a different database address. Staging might use a different domain name. The container image version might be newer in development than in production. All of these are small differences, yet each one lives inside a Kubernetes manifest file, which is the text file that describes what you want the cluster to run.

The copy and paste trap

The simplest way to handle this is to copy the whole set of files once per environment and edit the copies. It works on day one. By month three, someone fixes a bug in the production copy and forgets the other two. By month six, nobody remembers which differences were intentional and which were accidents. The files drift apart, and every release becomes a nervous comparison exercise.

Where Kustomize fits

Kustomize attacks drift directly. You keep one shared set of plain Kubernetes files, and for each environment you write a small description of the changes. Kustomize combines the two and produces the final files. The shared part is written once, the differences are tiny and easy to read, and nothing is copied.

Kustomize reads ordinary Kubernetes files, applies your changes, and prints new ordinary Kubernetes files.

A tool that edits files, not a template engine

Many people first meet the idea of reuse through templates. A template is a file with holes in it, such as a placeholder for the number of replicas, which a tool fills in with values at the last moment. Template files are not valid Kubernetes files until they are filled in, which makes them hard to read, hard to check, and hard to open in normal editors.

Kustomize takes a different road. Every file you give it is a complete and valid Kubernetes file that could be applied to a cluster exactly as it is. Kustomize does not fill in holes. Instead it takes those complete files and applies a series of precise edits on top, such as “change the replica count to five” or “add this label to everything”. The output is again complete, valid Kubernetes files.

Where it lives

Kustomize started as its own separate program and was later built into the standard Kubernetes command line tool, kubectl. This means that on most machines where kubectl is installed, you already have Kustomize available without installing anything. A standalone Kustomize program also exists, and it often has newer features than the version embedded inside kubectl.

The shape of the idea

flowchart LR
  A[Plain Kubernetes files] --> C[Kustomize]
  B[Kustomization file with your changes] --> C
  C --> D[Final Kubernetes files]
  D --> E[Applied to the cluster]
        

There are three important ideas hiding in this picture. First, the input files stay untouched on disk. Second, the change list is its own small file that names what to modify. Third, the output is generated fresh every time, so there is nothing to keep in sync by hand.

A handful of words cover almost everything in Kustomize.

How the words connect

You write a base, which is a folder of normal manifests and one kustomization file. You then write one overlay per environment, each with its own kustomization file that names the base and lists patches and transformers. When you ask Kustomize to build an overlay, it loads the base first, applies the overlay’s changes, and prints the result.

Layering is the single idea that makes everything else fit together.

The layered folder structure

The classic project layout has one folder for the base and a parent folder for the overlays, with one subfolder per environment. Each folder contains its own kustomization file. The base folder also holds the real manifests. The overlay folders usually hold only a kustomization file and a few small patch files.

flowchart TD
  B[Base with shared manifests]
  D[Development overlay]
  S[Staging overlay]
  P[Production overlay]
  B --> D
  B --> S
  B --> P
  D --> DO[Dev output]
  S --> SO[Staging output]
  P --> PO[Production output]
        

What an overlay can do

An overlay can add new objects that only exist in that environment, remove or replace parts of existing objects, change names, move everything into a different namespace, attach labels and notes, and choose different container image versions. Because every overlay starts from the same base, a fix made once in the base automatically reaches all environments the next time they are built.

Overlays can stack

An overlay may itself serve as the base for another overlay. A company might have a shared overlay for all production clusters, and then region specific overlays that build on it. Layers can nest as deeply as needed, but each added layer makes it harder to understand the final output, so most teams stop at two or three.

Every Kustomize folder is controlled by one small file that acts as its table of contents and its change list.

What goes inside

The kustomization file is itself a Kubernetes style document. It carries an API version and a kind, and then a set of fields that tell Kustomize what to do. Most fields are optional. A tiny kustomization file might do nothing more than list the manifests to include. A large one might hold dozens of instructions.

Why a small file is a feature

Because the file is short and declarative, a reviewer can read it in under a minute and know exactly what an environment changes. Compare this with reading a fully copied set of fifty files and hunting for differences. Kustomize makes the differences the star of the show.

Transformers are the broad brushes of Kustomize.

Why built-in helpers exist

Some changes apply to nearly every object. Giving every object an environment label, moving all of them into one namespace, or pointing every container at a new image version are all examples. Writing a separate patch for each object would be tedious and error prone. Transformers do these jobs in one line each.

The selector trap with labels

Kubernetes connects services and workloads through label selectors. A service finds its pods by asking for pods carrying certain labels. A deployment finds the pods it owns the same way. The selector on an existing deployment cannot be changed after it is created. If a transformer blindly adds a new label to the selectors as well as to the objects, applying the result on top of an existing deployment will be rejected by the cluster.

Older Kustomize features called “common labels” always touched selectors, which surprised many teams. The newer labels field lets you decide, label by label, whether selectors and pod templates should receive the label. For labels that are only informational, such as an ownership tag, leave selectors alone.

When a change is specific to one object, a patch is the right tool.

Two flavors of patch

Kustomize supports two styles of patch, and each has its place. Both are listed under the patches field of the kustomization file and both can point at their targets by kind, name, namespace, or even by label.

Strategic merge patches in practice

A strategic merge patch looks like a thin version of the original object. It names the object it wants to change through its kind and name, and then includes only the fields to be altered. Kustomize merges it into the base. When a field already exists, the patch value wins. When a list such as the list of containers is involved, Kustomize matches items by their name, so a patch that names one container changes only that container and leaves the rest alone.

JSON patches in practice

A JSON patch is a list of steps. Each step says what to do, where to do it, and, for adds and replacements, what value to use. The location is a path that walks from the top of the object down to the exact spot, much like a postal address from country down to house number. JSON patches shine when you need to remove something, when you edit a custom resource type that strategic merging does not understand, or when you must insert an item at a precise position.

Choosing a target

A patch can aim at exactly one object by name, at all objects of a certain kind, or at any set of objects selected by label or annotation. Broad targeting is powerful but risky, because a patch that quietly matches more objects than expected will alter things you never meant to touch. Prefer precise targets and confirm by reading the output.

Generators create objects for you and fix a subtle problem that has bitten many teams.

The configuration problem

Applications need settings, such as feature switches or database host names. Kubernetes stores these in a configuration object, called a ConfigMap, and passwords and tokens in a Secret object. Writing these objects by hand means wrapping each file or value in a lot of ceremony. Generators let you point at plain files or list simple key and value pairs, and Kustomize builds the full objects.

The hash suffix trick

Here is a classic Kubernetes surprise. You change a setting inside a configuration object and apply it. The object updates, but the running pods that use it are not restarted, so they keep working with old values until something else triggers a restart. Many teams have spent hours wondering why a change did not take effect.

Kustomize solves this elegantly. By default, a generated object gets a short random looking tag at the end of its name, calculated from its content. If the content changes, the tag changes, so the object gets a new name. Kustomize then automatically updates every deployment that refers to it. Because the deployment now points at a different name, its pod definition has changed, and Kubernetes performs a normal rolling update with the new settings. Config changes now behave like code changes.

sequenceDiagram
  participant D as Developer
  participant K as Kustomize
  participant C as Cluster
  D->>K: Change a setting value
  K->>K: Calculate new content tag
  K->>K: Name config object with new tag
  K->>K: Update deployment references
  K->>C: Apply new files
  C->>C: Roll pods to the new config
        

When to turn the suffix off

The suffix can be disabled through generator options. This is useful when another system refers to the object by a fixed name, or when you intentionally want changes to be picked up without restarts. Be aware that turning it off brings back the original surprise, so you will need another way to restart workloads when settings change.

Secrets need extra care

A secret generator can read values from files or literals, but the source files still sit in your repository in readable form. Storing real passwords this way defeats the purpose. Production teams combine Kustomize with sealed or external secret tools, so the repository holds only encrypted or reference information, and the real values are delivered to the cluster another way.

Kustomize does more than text replacement. It understands how Kubernetes objects point at each other.

Objects refer to each other by name

A deployment names the configuration object it mounts. A service account is named by the workloads that use it. An ingress names the service it sends traffic to. A role binding names both a role and a subject. These are all connections made by name, and a simple search and replace would easily miss or damage them.

When a transformer changes a name, adds a prefix, or when a generator adds a hash suffix, Kustomize walks through its built-in knowledge of Kubernetes fields and updates every reference it recognizes. That is why renaming an object in an overlay does not silently break its neighbors.

Older Kustomize versions used a variables feature for this kind of copying. It has been deprecated in favor of replacements, which are more explicit about their source and destination and easier to reason about.

Sometimes a bundle of changes belongs in some environments but not others, and does not fit neatly into one overlay.

The problem overlays cannot solve alone

Suppose you have an optional feature, such as extra monitoring, a caching layer, or an extra security helper container. Production needs it. Staging needs it. Development does not. A third group of customer specific clusters needs it only for some customers. Writing this feature into several overlays duplicates it, and putting it in the base forces it on everybody.

How components help

A component is a folder with its own kustomization file of a special kind. It contains the files and patches for one feature. Any overlay can include the component in a components list, and the feature is added. Overlays that do not list it are unaffected. One feature, written once, switched on wherever needed.

flowchart LR
  B[Base]
  M[Monitoring component]
  C[Cache component]
  P[Production overlay]
  S[Staging overlay]
  D[Development overlay]
  B --> P
  B --> S
  B --> D
  M --> P
  M --> S
  C --> P
        

Knowing the build pipeline makes surprising results easy to explain.

The build, step by step

Nothing is stored

Kustomize keeps no memory between runs. There is no state file, no database, and no record of what it produced before. Every build starts from the files on disk and produces the same output for the same input. This statelessness makes Kustomize easy to reason about and easy to run in any pipeline, but it also means Kustomize alone cannot tell you what to delete from the cluster when you remove something from your files.

The everyday loop is short: preview, compare, apply.

The three habits

The same output feeds many tools

Because Kustomize prints plain Kubernetes files, the same output can be piped into validators, policy checkers, scanners, or saved as an artifact for audit. Nothing about Kustomize locks you into one deployment method.

Working with remote bases

A kustomization file can pull in a base from a remote repository address. This is a convenient way to reuse a vendor’s or another team’s manifests and customize them locally without copying. The danger is that an address pointing at a moving branch can change under you. Always pin to a specific tag or commit so that your build is reproducible and a surprise upstream edit cannot reach production.

Kustomize fits naturally into workflows where Git is the source of truth.

A perfect match

In a GitOps workflow, a controller inside the cluster continuously compares the cluster with the files in a Git repository and corrects any difference. The two most popular tools for this, Argo CD and Flux, both understand Kustomize directly. You point them at an overlay folder and they run the build for you, then apply the result.

This pairing works well because both Git and Kustomize are declarative and predictable. A change to an overlay is a normal code change with a review, an approval, and a history. Rolling back is as simple as reverting a commit.

flowchart LR
  A[Developer changes overlay] --> B[Pull request review]
  B --> C[Merge to main branch]
  C --> D[GitOps controller sees change]
  D --> E[Controller builds with Kustomize]
  E --> F[Cluster updated to match]
        

Handling image versions in the pipeline

A common pattern is for the continuous integration system to build a new container image and then update the image tag inside the production overlay’s kustomization file. The commit is automatic, reviewed if desired, and the GitOps controller rolls it out. Every release becomes a one line change in Git with a clear author and time.

Pruning and cleanup

Because Kustomize is stateless, removing an object from your files does not delete it from the cluster by itself. GitOps tools solve this by tracking what they created and deleting what disappears from Git. If you use plain apply commands instead, you need a labeling strategy or a pruning option so that removed objects do not linger.

These two tools solve related problems in very different ways, and many teams use both.

Two philosophies

Helm packages an application as a chart, which is a collection of templates and a set of default values. Users install it by supplying their own values, and Helm keeps track of each installation as a release that can be upgraded or rolled back. Kustomize avoids templates entirely and works by layering changes on plain files.

Choosing between them

If you own the application and need to vary it across your own environments, Kustomize is often the lighter and clearer choice. If you publish software for many outside users who need many configurable options, Helm’s value system and release management are a stronger fit. If you consume a third party chart and want to adjust it, a very common pattern is to render the chart and then customize the result with Kustomize.

An honest look at the trade-offs helps you decide where Kustomize belongs in your toolbox.

When Kustomize is a great fit

Kustomize shines when you have a modest number of applications, a clear difference between environments, and a team that values readable files over clever logic. It is also excellent for adapting third party manifests with a few tweaks.

When to look elsewhere

If your configuration needs heavy computation, such as generating dozens of similar objects from a list, or if you need to distribute a product to outside users with many options, a templating tool or a configuration programming language may serve better. Recognizing this early saves you from forcing Kustomize into a role it was not designed for.

Kustomize itself is simple, but what it builds ends up running in your cluster, so safety habits matter.

Protect the source of truth

Your overlay folders decide what runs in production. Anyone who can change them can change your production environment. Protect these folders with the same review rules you apply to application code, including required reviews, protected branches, and clear ownership of production overlays.

Secrets

Keep real secret values out of the repository. Use an external secrets system, a sealed secrets approach, or a cloud secret manager, and let Kustomize handle only the references. Remember that the output of a build may contain secret objects in readable form, so never write build output to shared logs.

Remote content and load restrictions

By default Kustomize refuses to read files from outside the folder tree of the kustomization it is building. This is a protective rule, designed to stop a build from quietly reading unrelated files on the machine. A flag exists to relax this, but turning it off in a shared pipeline weakens a useful safety net. For remote bases, pin to exact versions as discussed earlier.

Plugins and external functions

Kustomize can run external plugins or containerized functions to generate or transform content. These run code during the build, so they need the same trust as any program in your pipeline. They are switched on by explicit flags, which is a deliberate speed bump. Allow only reviewed, pinned plugins in shared systems.

Validate the output

The final files can be checked by schema validators and policy tools before they reach the cluster. A pipeline that builds every overlay, validates the output, and fails on violations catches mistakes in minutes instead of in production.

Since Kustomize is a build step, the way to monitor it is to verify its output at every stage.

Build every overlay on every change

The cheapest safety net is a pipeline job that builds every overlay whenever any file changes. A broken patch, a missing file, or a bad reference shows up immediately as a failed build, long before it reaches a cluster. Building all overlays, not just the one you edited, catches changes to the base that accidentally break a different environment.

Observe what the cluster is doing

Once applied, normal cluster monitoring takes over. GitOps controllers report whether the cluster matches Git, how long syncs take, and which objects have drifted. Alerting on sync failures and on drift tells you when someone changed something by hand or when a build produced something the cluster rejected.

Record what was built

Saving the final built files as an artifact for each release gives you an exact record of what was applied and when. This is invaluable during audits and incident reviews, because the source files alone do not show the final merged result.

These patterns appear again and again in real organizations.

Teams that keep Kustomize tidy for years follow a few common habits.

Patterns to avoid

A short checklist helps you adopt Kustomize without learning every lesson the hard way.

Most Kustomize problems fall into a few recognizable families.

A calm debugging routine

Not for basic use, because the kubectl command line already contains a version of it. A standalone program also exists and is often newer, so install it if you need recent features.

No. It reads your files and prints a new result. The originals on disk stay exactly as you wrote them.

No, and that is by design. Kustomize intentionally has no template language. If you need that kind of logic, consider a templating tool or generate the input files before Kustomize runs.

A base is the shared, environment neutral definition. An overlay points at a base and adds the changes that are specific to one environment or purpose.

Start with strategic merge because it looks like the original object and handles Kubernetes lists intelligently. Use a JSON patch for removals, custom resource types, or exact position edits.

The short tag at the end is a hash of the content. It makes changes to settings trigger rolling updates automatically. You can disable it through generator options if you have a good reason.

Not by itself, because it is stateless. Use a delivery tool with pruning support, such as a GitOps controller, or use an explicit cleanup approach.

Yes. Kustomize can inflate a Helm chart when the right flag is enabled, or you can render a chart first and then use its output as a base for further customization.

Not in plain form. The generator reads source files that sit in your repository. Use encrypted or externally managed secrets and keep real values out of Git.

Build it and read the output. Combine that with a diff against the running cluster before you apply anything.

There is no fixed number, but if understanding one setting means opening more than three folders, the structure is probably too deep. Flatten it or use components.

No. Both recognize a folder containing a kustomization file and build it for you. Point them at the overlay folder for the environment you want to deploy.

Kustomize offers a calm, readable answer to one of the oldest headaches in Kubernetes, which is running the same application in many slightly different places. By keeping a single shared base and describing each environment as a small overlay, it removes copy and paste drift and makes differences visible and reviewable. Its patches, transformers, generators, and components cover most everyday needs without ever introducing a template language, and its stateless, predictable builds fit neatly into review pipelines and GitOps tools. The price of that simplicity is a lack of logic and lifecycle features, so teams choose it where clear, layered configuration matters more than cleverness. Used with pinned versions, careful targets, secrets kept out of Git, and a habit of reading the output, it becomes a quiet and dependable part of a Kubernetes platform.