Kustomize

History

Kustomize was developed by Google and is now a part of the SIG CLI group in the Kubernetes project. It was officially integrated into kubectl starting with Kubernetes v1.14, allowing native support via the command:

  kubectl apply -k ./path

Its goal was to solve configuration drift across environments (dev, staging, prod) without needing additional tools like Helm, which uses Go templating.

Value Proposition

Kustomize addresses a key pain point in Kubernetes: managing multiple environment configurations without copying and modifying the same YAML over and over. It:

• Eliminates duplication by separating base resources from environment-specific patches.
• Works natively with YAML, reducing complexity for DevOps and Platform teams.
• Provides declarative, layered configuration without introducing a new language.

Key Features

• Overlays and bases: Define a base configuration and apply environment-specific customizations as overlays.
• Patching resources: Modify parts of manifests (like labels, replica counts) without altering the original files.
• NamePrefix/NameSuffix: Automatically add environment-specific prefixes or suffixes to resource names.
• ConfigMapGenerator & SecretGenerator: Dynamically create ConfigMaps and Secrets from files or literals.
• Native support in kubectl: No additional installation required for basic use.

How Kustomize Works

Kustomize operates by building a resource tree based on a file called kustomization.yaml. This file defines which base files to include, what patches to apply, and how to transform the output.

Example file structure:

  .
├── base
│   ├── deployment.yaml
│   └── kustomization.yaml
└── overlays
    └── production
        ├── kustomization.yaml
        └── replica-patch.yaml

The base/kustomization.yaml might include:

  resources:
  - deployment.yaml

While overlays/production/kustomization.yaml might include:

  bases:
  - ../../base
patchesStrategicMerge:
  - replica-patch.yaml

replica-patch.yaml:

  apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 5

When you run kubectl apply -k overlays/production, Kustomize merges the base and overlay into a single manifest with 5 replicas.

Use Cases

1. Environment-Specific Deployments

Easily manage different configurations for dev, staging, and prod without duplicating YAMLs. For example:

• Use 1 replica in dev, 5 in prod
• Enable autoscaling only in staging
• Apply different labels or annotations per environment

2. Multi-Tenant Applications

If you deploy the same application for multiple customers, Kustomize lets you reuse a common base and add tenant-specific overlays (e.g., name prefixes, resource quotas, logging levels).

3. GitOps with ArgoCD or Flux

Kustomize is natively supported by GitOps tools like ArgoCD and Flux, allowing teams to apply configuration changes through Git commits using a declarative approach.

4. Separation of Concerns

Developers write base app YAMLs, while platform engineers maintain overlays for production-grade configurations like node selectors, security contexts, or network policies.

Challenges

• No logic or conditionals: Kustomize avoids templating entirely. This makes it simple, but it lacks conditionals or loops found in tools like Helm.
• Harder to create dynamic configurations: If you need complex branching logic or parameterization, Kustomize may require workarounds.
• Limited secret management: While it can generate Secrets, managing them securely often requires integration with other tools (e.g., Sealed Secrets or SOPS).

Comparison: Kustomize vs. Helm

Best Practices

• Keep your base clean and generic—no hardcoded environment values.
• Organize overlays by team, environment, or region.
• Use config generators for secrets and config maps to avoid hardcoding values.
• Combine Kustomize with GitOps for scalable, auditable deployments.

See Also

• Helm
• ArgoCD
• Sealed Secrets
• SOPS