Kustomize overview — declarative customisation without templates

Kustomize is a declarative customisation tool for Kubernetes manifests, built into kubectl. This lesson walks the Kustomize model, the base + overlay pattern, the comparison with Helm, and the operational discipline.

The Kustomize model

flowchart LR
    A[Base manifests] --> B[kustomization.yaml]
    C[Overlay patches] --> B
    B -->|kustomize build| D[Rendered manifests]
    D -->|kubectl apply| E[Cluster]

The Kustomize model:

• Base. A directory with the common Kubernetes manifests (Deployment, Service, etc.).
• Overlay. A directory with patches that modify the base for a specific environment (dev, staging, prod).
• kustomization.yaml. The Kustomize configuration in each directory, declaring resources, patches, and other customisations.
• kustomize build. Renders the final manifests.

kubectl kustomize overlays/prod

The output is the rendered YAML manifests, ready to apply or to feed into kubectl apply -k.

A base example

app/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
├── overlays/
│   ├── dev/
│   │   └── kustomization.yaml
│   ├── staging/
│   │   └── kustomization.yaml
│   └── prod/
│       └── kustomization.yaml

The base directory contains the common manifests. The overlays contain environment-specific customisations.

A kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

commonLabels:
  app: myapp

namePrefix: ""
namespace: ""

The kustomization.yaml declares:

• resources — the input files.
• commonLabels — labels added to all resources.
• namePrefix — prefix added to resource names.
• namespace — namespace for all resources.

An overlay example

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: prod-app
namePrefix: prod-

patches:
  - target:
      kind: Deployment
      name: myapp
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
      - op: replace
        path: /spec/template/spec/containers/0/image
        value: myapp:2.0.0

The overlay references the base, sets the namespace and namePrefix, and applies a JSON 6902 patch to the Deployment.

Kustomize vs Helm

flowchart LR
    A[Kustomize] --> B[+ YAML is the input; no templating]
    A --> C[+ Built into kubectl]
    A --> D[+ Environment-specific patches]
    A --> E[- Less flexibility for complex logic]
    F[Helm] --> G[+ Powerful templating]
    G --> H[+ Values-based configuration]
    G --> I[+ Subcharts and dependencies]
    I --> J["- Complexity, requires helm CLI"]
    J --> K[- Release state in Secrets]

The trade-offs:

Kustomize:

• Pros: YAML is the input; no templating; built into kubectl; environment-specific patches are declarative.
• Cons: Less flexibility for complex logic; no subcharts.

Helm:

• Pros: Powerful templating; values-based configuration; subcharts and dependencies.
• Cons: Complexity; requires helm CLI; release state in Secrets.

Most production deployments use both: Kustomize for application manifests with environment overlays; Helm for third-party add-ons with complex configuration.

When to use Kustomize

flowchart TD
    A[Use case] --> B{Environment-specific patches?}
    B -->|Yes| C[Kustomize]
    B -->|No| D[Raw YAML]
    A --> E{Complex templating?}
    E -->|Yes| F[Helm]
    E -->|No| G[Raw YAML]

Kustomize is appropriate for:

• Applications with environment-specific configuration (different replicas, resources, image tags per environment).
• Multi-cluster deployments with cluster-specific patches.
• GitOps-driven deployments where the diff between base and overlay is the operational signal.

Helm is appropriate for:

• Third-party packages (ingress-nginx, cert-manager, Argo CD).
• Applications with complex templating needs.
• Releases with version history and rollback.

Quiz

The operational discipline

Kustomize in production rests on five non-negotiable elements:

• Base manifests are valid YAML. Apply the base directly; the overlay is a transformation.
• Patches are reviewed. Every overlay change is reviewed in the PR.
• Render before apply. Use kubectl kustomize to verify the output.
• Use overlays for environments. Not inline edits to base.
• Test in staging first. An overlay that breaks in production is a hot fix.

Kustomize is a powerful tool for environment-specific configuration. The discipline is to use overlays for environment changes and to review the patches.