Overlays work well when each environment differs from the base in its own way. They start to hurt when the same change has to appear in some environments but not others. You end up copying the same patch into three overlays, or you build a chain of overlays where staging inherits from dev and prod inherits from staging, and nobody remembers why.
Components fix this. A component is a kustomization that packages one feature (a PodDisruptionBudget, a debug setting, a topology spread rule) so any overlay can switch it on with one line. This guide builds a small app with three components, wires them into a dev and a prod overlay, and then covers how Kustomize orders the work and what the common errors mean.
Components have been in Kustomize since v3.7.0, so any current kustomize binary or kubectl kustomize can run the examples. The design is described in the Kustomize components KEP.
Step 1: write the base
The base holds what every environment shares: one Deployment and a generated ConfigMap with the app's settings. Nothing in it is optional. Keep it that way, because anything optional in the base has to be removed by a patch later, and removal patches are harder to read than additions.
mkdir -p app/base
cat <<'EOF' > app/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
configMapGenerator:
- name: web-config
literals:
- LOG_LEVEL=info
EOF
cat <<'EOF' > app/base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
labels:
app: web
spec:
replicas: 2
selector:
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: nginx:1.27
envFrom:
- configMapRef:
name: web-config
EOF
Step 2: create a component that adds a resource
The first component adds a PodDisruptionBudget, so a node drain can't take down every replica at once. Production needs it. Dev doesn't, and on a small dev cluster that people drain and rebuild all the time, a PDB mostly gets in the way.
A component's kustomization file looks like a normal one with two differences. It sets kind: Component, and its apiVersion is kustomize.config.k8s.io/v1alpha1 instead of v1beta1. The file is still named kustomization.yaml.
mkdir -p app/components/pdb
cat <<'EOF' > app/components/pdb/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
resources:
- pdb.yaml
EOF
cat <<'EOF' > app/components/pdb/pdb.yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: web
spec:
minAvailable: 1
selector:
matchLabels:
app: web
EOF
Step 3: create a component that patches the base
The second component changes resources it doesn't own. It spreads the web pods across zones with a strategic merge patch on the base's Deployment. This is the part a plain base can't do: a base can only change its own resources, while a component works on everything the including overlay has gathered so far.
mkdir -p app/components/zone-spread
cat <<'EOF' > app/components/zone-spread/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
patches:
- path: spread.yaml
EOF
cat <<'EOF' > app/components/zone-spread/spread.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: web
spec:
template:
spec:
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
labelSelector:
matchLabels:
app: web
EOF
The patch has no target, so Kustomize matches it by the kind and name in its own metadata. It finds the Deployment named web from the base.
Step 4: create a component that changes generated config
The third component turns on debug logging. It uses configMapGenerator with behavior: merge, which adds or overwrites keys in the base's web-config instead of creating a second ConfigMap. The hash suffix changes because the content changes, so the Deployment rolls when you switch the component on or off.
mkdir -p app/components/debug
cat <<'EOF' > app/components/debug/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
configMapGenerator:
- name: web-config
behavior: merge
literals:
- LOG_LEVEL=debug
EOF
Leave out behavior: merge and the build fails, because the component would try to create a second ConfigMap with an ID that already exists.
Step 5: wire the components into overlays
Now each overlay lists the base under resources and the features it wants under components. Dev gets debug logging and nothing else. Prod gets the PDB and the zone spread, plus a name prefix and more replicas of its own.
mkdir -p app/overlays/dev app/overlays/prod
cat <<'EOF' > app/overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
components:
- ../../components/debug
EOF
cat <<'EOF' > app/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: prod-
resources:
- ../../base
components:
- ../../components/pdb
- ../../components/zone-spread
replicas:
- name: web
count: 4
EOF
You can also add a component from the command line. Run kustomize edit add component from the overlay directory with the path to the component. It appends the path to components and skips it if it's already there.
cd app/overlays/prod
kustomize edit add component ../../components/debug
cd -
Undo that change before you continue, or prod will log at debug level too.
Step 6: build and compare
Build each overlay and read the result before you apply anything. Dev should have one Deployment and one ConfigMap with LOG_LEVEL=debug. Prod should have a Deployment named prod-web with four replicas and the spread constraint, a ConfigMap whose key is still info, and a PodDisruptionBudget named prod-web.
kustomize build app/overlays/dev
kustomize build app/overlays/prod
If you only have kubectl, kubectl kustomize app/overlays/prod builds the same thing, and kubectl diff -k app/overlays/prod shows what would change in the cluster.
Notice that the PDB got the prod- prefix even though the overlay's namePrefix knows nothing about the component. That comes from the order Kustomize does the work, which is worth understanding before your components get bigger.
How Kustomize orders the work
When Kustomize builds a kustomization, it first loads everything under resources and runs the generators. Then it processes the components, one at a time in the order you listed them. Last, it runs the kustomization's own transformers (patches, namePrefix, namespace, replicas, replacements and the rest) and validators. The source of KustTarget.accumulateTarget in the Kustomize repo says this in a comment: components run after resources and generators, before transformers.
A component doesn't get its own isolated build. Kustomize hands it the set of resources gathered so far, and the component adds its own resources and generators to that set, then applies its own transformers to everything in it. That is why the zone-spread patch can find the base's Deployment, and why the overlay's namePrefix, which runs after all components, renames the PDB.
It also means the order of the components list matters. Each component sees what the overlay gathered plus what the earlier components added, and nothing that comes after it. Say a component sets nameSuffix: -b and you list it before a component that adds a Deployment named proxy. The suffix applies to the base's resources but not to proxy, because proxy didn't exist yet when the suffix ran. Swap the two and you get proxy-b. If a component's transformers should touch everything, list it last, or move the transformer up into the overlay itself.
Components can include other components through their own components field, and the same ordering rules apply inside them. Use this sparingly. One level of components is easy to follow, while three levels is a puzzle.
Errors you will hit
Most component errors come from listing something in the wrong field. Kustomize checks the kind of each directory against where you listed it.
If you put a component directory under resources, the build stops with an error that contains expected kind != 'Component' for path. Move it to components.
If you put a normal kustomization under components, the error says expected kind 'Component' for path '...' but got 'Kustomization'. The same message appears when you forget the kind line in a component, because Kustomize fills in Kustomization when kind is missing. The apiVersion line is optional: with kind: Component set, Kustomize fills in v1alpha1 for you.
If you set kind: Component with apiVersion: kustomize.config.k8s.io/v1beta1, Kustomize rejects it with apiVersion for Component should be kustomize.config.k8s.io/v1alpha1. Copying a kustomization and only changing the kind is the usual way this happens.
If you list a YAML file under components, the build fails because a component must be a directory. Put the file in a directory with a kustomization.yaml of kind Component, or list it under resources instead.
Finally, two components can't add the same resource. If both list a Deployment named proxy, or both include the same base, the second one fails with may not add resource with an already registered id. When two features need the same object, put the object in the base and let each component patch it.
When to reach for a component
Use a component when a feature is optional and more than one overlay needs it. A single overlay's one-off change belongs in that overlay, where readers expect to find it. A change every environment needs belongs in the base.
Keep each component to one feature, named after what it does, not after the environment that uses it today. A directory called components/prod-stuff will grow until it's a second overlay. A directory called components/pdb stays small, and the day staging needs a PDB, adding it is one line in staging's components list.