Kustomize Tutorial: Managing Kubernetes Manifests Without Helm

We often need to customize Kubernetes deployments, and while Helm has become the dominant tool, Kustomize offers a native alternative that is built into kubectl since version 1.14.

Philosophy

Kustomize follows the same declarative principles as Kubernetes, Docker, and Git: you describe the desired state, layer modifications on top of base files, and optionally source the base from a remote repository.

Usage

Base

Start with raw YAML files stored in ./k8s/base/ . These files are never edited directly; instead, customizations are applied on top of them. You can apply the base with:

kubectl apply -f ./k8s/base/

Example base files (Service and Deployment) are shown below:

apiVersion: v1
kind: Service
metadata:
  name: sl-demo-app
spec:
  ports:
  - name: http
    port: 8080
  selector:
    app: sl-demo-app

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sl-demo-app
spec:
  selector:
    matchLabels:
      app: sl-demo-app
  template:
    metadata:
      labels:
        app: sl-demo-app
    spec:
      containers:
      - name: app
        image: foo/bar:latest
        ports:
        - containerPort: 8080
          name: http
          protocol: TCP

Create a kustomization.yaml that lists these resources:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- service.yaml
- deployment.yaml

Apply the base with:

kubectl apply -k k8s/base

To preview the rendered manifests, use:

kustomize build k8s/base

Overlays (Customization)

Create an overlay directory, e.g., k8s/overlays/prod , with its own kustomization.yaml that references the base:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
bases:
- ../../base

Build the overlay to see the same output as the base.

Adding Environment Variables

Define a patch file custom-env.yaml that adds an env block to the Deployment, then reference it in the overlay's patches list:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sl-demo-app
spec:
  template:
    spec:
      containers:
      - name: app
        env:
        - name: CUSTOM_ENV_VARIABLE
          value: Value defined by Kustomize ❤️

After building, the env variable appears in the final Deployment.

Changing Replica Count and Rollout Strategy

Create replica-and-rollout-strategy.yaml with the desired replica number and rolling‑update settings, then add it to the patches list. The resulting manifest includes replicas: 10 and the specified strategy.

Generating Secrets

Use the command kustomize edit add secret sl-demo-app --from-literal=db-password=12345 inside the overlay directory. This adds a secretGenerator entry to kustomization.yaml and creates an opaque Secret whose name is hashed (e.g., sl-demo-app-gkmm8tkdd7 ).

To consume the secret in a pod, add a layer file (e.g., database-secret.yaml ) that references the secret via valueFrom.secretKeyRef and include it in the overlay's patches list.

Updating Image Tags

Set an environment variable with the desired tag (e.g., TAG_VERSION=3.4.5 ) and run kustomize edit set image foo/bar=foo/bar:$TAG_VERSION . Kustomize adds an images entry to kustomization.yaml , and the built Deployment will use foo/bar:3.4.5 .

Summary

These examples demonstrate how Kustomize lets you declaratively compose and customize Kubernetes manifests without templates, using layered YAML files, patches, secret generators, and image transformers. Advanced features such as mixins, inheritance, and name/label/namespace generators are also available for more complex scenarios.