# How to share optional features across overlays with Kustomize components

> Package optional features as Kustomize components, turn them on per overlay, and fix the errors people hit when they first use them.

Published: 2026-11-19
Author: k8wiz Team
URL: https://k8wiz.com/articles/share-optional-features-across-overlays-with-kustomize-components

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](https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/1802-kustomize-components/README.md).

## 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.

```bash
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`.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`.

```bash
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.
