Kubernetes Kustomize Component Management

Kubernetes Kustomize Component Management is the practice of packaging optional, independently reusable configuration fragments as Kustomize Component resources, distinct from a base in that a component cannot be built standalone and exists specifically to be composed into one or more overlays as an opt-in unit, solving the cross-cutting configuration problem that a strict base-and-overlay hierarchy alone cannot express cleanly.

Components vs. Bases

The Key Structural Difference

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
resources:
  - sidecar-patch.yaml

A Component declares apiVersion: kustomize.config.k8s.io/v1alpha1, kind: Component rather than Kustomization, and kustomize build refuses to run directly against a directory containing only a component; a component only takes effect when referenced from an overlay's or another component's components field, making it inherently a building block rather than a complete, independently deployable unit.

kustomize build components/istio-sidecar/
# error: components must be included from a Kustomization

The Cross-Cutting Configuration Problem

Why a Strict Hierarchy Falls Short

A base-and-overlay hierarchy naturally expresses "one shared base, many environment-specific overlays," but struggles to express "an optional feature that some overlays want and others do not, regardless of environment" without either duplicating the feature's manifests across every overlay that needs it, or forcing every overlay to inherit it whether wanted or not; components exist specifically to let such optional, cross-cutting features be defined once and opted into selectively.

# overlays/production/kustomization.yaml
resources:
  - ../../base
components:
  - ../../components/istio-sidecar
  - ../../components/rate-limiting

# overlays/staging/kustomization.yaml
resources:
  - ../../base
components:
  - ../../components/istio-sidecar

Staging opts into the sidecar component but not rate limiting, while production opts into both, without either overlay needing to duplicate the sidecar patch's actual content.

Composing Multiple Components

Order-Dependent Application

components:
  - ../../components/security-baseline
  - ../../components/monitoring
  - ../../components/istio-sidecar

Components are applied in the order listed, following the same sequential application semantics as patches generally; a component that assumes a particular field already exists (added by an earlier component) will fail or behave unexpectedly if that ordering is reversed, making component composition order a meaningful design decision rather than an arbitrary listing.

What a Component Can Contain

Resources, Patches, and Generators Together

apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
resources:
  - network-policy.yaml
patches:
  - path: add-sidecar-container.yaml
    target:
      kind: Deployment
configMapGenerator:
  - name: sidecar-config
    literals:
      - PROXY_MODE=sidecar

A component can bundle new standalone resources, patches against resources introduced elsewhere (typically the base it will be combined with), and its own generators together, functioning as a self-contained, composable unit of related changes rather than being limited to any single transformation type.

Variables and Replacements Within Components

Parameterizing a Component Itself

# components/istio-sidecar/kustomization.yaml
replacements:
  - source:
      kind: ConfigMap
      name: sidecar-config
      fieldPath: data.PROXY_MODE
    targets:
      - select:
          kind: Deployment
        fieldPaths:
          - spec.template.metadata.annotations.[sidecar.istio.io/inject]

A component itself can use Kustomize's replacements mechanism to propagate a value from one of its own resources into another, letting a component remain internally consistent and parameterizable even before it is combined with whatever base or overlay ultimately includes it.

Typical Use Cases

Optional Platform Features

Components are the standard mechanism for platform-provided, optional capabilities, service mesh sidecar injection, a standard set of NetworkPolicy resources, a common logging sidecar, that individual application teams' overlays can choose to adopt without the platform team needing to fork or duplicate application-specific bases for every possible combination of optional features.

Feature Flags at the Manifest Level

components:
  - ../../components/beta-feature-x

An overlay including or omitting a specific component functions as a manifest-level feature flag, letting a specific environment or tenant opt into an experimental or gated capability declaratively, visible directly in the overlay's kustomization.yaml rather than hidden behind a runtime configuration flag.

Relationship to Kustomize Base Management and the Package Model

Components extend the base-and-overlay structure introduced by the broader Kustomize package model with a third, orthogonal composition axis, optional, cross-cutting inclusion, that complements rather than replaces the hierarchical base management discussed elsewhere: where a base provides the mandatory, shared foundation every overlay builds from, a component provides the optional, selectively adopted fragment that would otherwise force an awkward choice between duplication and unwanted universal inclusion.