Mastering Kustomize: Flexible Kubernetes YAML Customization Without Templates

Kustomize Overview

Kustomize is a tool that manages native Kubernetes configuration using a merge‑based, template‑free approach. Users define a set of base files and generate final deployment manifests through overlays, allowing environment‑specific customizations without learning a new DSL.

How Kustomize Works

Kustomize maintains application configurations with a Base & Overlays strategy. Overlays describe differences from the base, enabling resource reuse while managing plain Kubernetes YAML files.

File Structure Example

app
├── base
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays
    ├── production
    │   └── kustomization.yaml
    ├── staging
    │   └── kustomization.yaml
    └── production-large
        └── kustomization.yaml

The app/base/kustomization.yaml declares resources and common customizations such as a shared label:

commonLabels:
  name: app
resources:
- deployment.yaml
- service.yaml

Running kustomize build app/base produces the full configuration with the common label applied to each resource.

Overlay Customizations

In app/overlays/staging/kustomization.yaml, a name prefix, environment label, and a patch set the replica count to 1:

bases:
- ../../base
commonLabels:
  env: staging
namePrefix: staging-
patches:
- target:
    kind: Deployment
    name: app
  patch: |
    [{"op":"replace","path":"/spec/replicas","value":1}]

Similarly, the production overlay sets replicas to 2, and the production‑large overlay sets replicas to 10 for large‑scale scenarios.

Deployments are performed by specifying the overlay path, e.g., kustomize build app/overlays/production | kubectl apply -f -.

Key Characteristics of Kustomize

Simple, clear functionality with direct kubectl support.

Acts as a pure YAML organization method without imposing a templating layer.

Provides a plugin system for generating ConfigMaps, Secrets, etc., from simple YAML definitions.

Allows injection of runtime Kubernetes data.

Kustomize vs. Helm

Kustomize is lighter than Helm, consisting of a single CLI tool that is integrated into kubectl, resulting in near‑zero configuration cost. It abandons templating, using a Base + Overlay model to derive applications from original YAML.

Base YAML control: Helm restricts customization to predefined options and requires templating, whereas Kustomize’s unrestricted overlays enable flexible overrides.

Template syntax: Kustomize removes template syntax, lowering the learning curve; advanced use still may require both tools.

Deployment: Both generate YAML and apply it directly; Helm 3 removed the Tiller dependency, narrowing the operational gap.

Workflow: Helm follows Chart → Fill → Run, limiting changes to what the chart defines. Kustomize allows independent Base and Overlay operations, making it easy to add new objects or modify unforeseen base content.

For complex, publicly released components, a well‑designed Helm chart offers users deep insight through values.yaml. For typical business applications with modest environment differences and rapid iteration, Kustomize provides a more agile solution.

SREWorks Kustomize Component Practice

In SREWorks’ appmanager, Kustomize and Helm are treated as component types. The following OAM YAML snippet shows a Kustomize component with dependencies and parameter mappings:

-revisionName: "KUSTOMIZE|[email protected]@test|_"
parameterValues:
- name: kubeconfig
  value: "{{ Global.kubeconfig }}"
  toFieldPaths:
  - spec.base64Kubeconfig
- name: path
  value: "./"
  toFieldPaths:
  - spec.path
dependencies:
- component: "CHART|sreworks@[email protected]"
- component: "STATUS|KUSTOMIZE@esonack-cluster-baselines|_"
  dependencies:
  - component: KUSTOMIZE|[email protected]@test
    parameterValues:
    - name: kubeconfig
      value: "{{ Global.kubeconfig }}"
      toFieldPaths:
      - spec.base64Kubeconfig
    - name: options
      value:
        groups:
        - namespace: sreworks-system
        labels:
          app: sreworks
        resources:
        - v1/pods
        toFieldPaths:
        - spec.options

The workflow inserts both Helm and Kustomize components, sets dependencies so that the Helm component deploys first, followed by the Kustomize component, and finally performs pod health checks before marking deployment complete.

Conclusion

Kustomize is a generic tool that customizes Kubernetes resources to produce new YAML files while preserving the original files. It operates directly on native YAML without templates, making it simple and easy to understand. Integrated into kubectl, it requires no extra installation, though older kubectl versions may ship with an outdated Kustomize version that needs a separate install until Kubernetes 1.20.