kubectl kustomize

When to Use kubectl kustomize

kubectl kustomize renders Kustomize configurations into plain Kubernetes YAML. It processes a kustomization.yaml file that declares bases, overlays, patches, and transformations — producing the final set of manifests ready to apply.

How Kustomize Works

Kustomize follows a composition model rather than templates:

base/
  kustomization.yaml
  deployment.yaml
  service.yaml

overlays/
  staging/
    kustomization.yaml      # references ../base, adds patches
  production/
    kustomization.yaml      # references ../base, different patches

A base kustomization.yaml:

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

A staging overlay:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namePrefix: staging-
patches:
  - patch: |-
      - op: replace
        path: /spec/replicas
        value: 1
    target:
      kind: Deployment

Building and Previewing

# Render the staging overlay
kubectl kustomize overlays/staging

# Pipe to a file for review
kubectl kustomize overlays/production > /tmp/prod-manifests.yaml

# Diff against live cluster
kubectl kustomize overlays/staging | kubectl diff -f -

Applying Kustomizations

Two equivalent approaches:

# Method 1: Built-in -k flag
kubectl apply -k overlays/staging

# Method 2: Pipe through kustomize
kubectl kustomize overlays/staging | kubectl apply -f -

Method 2 gives you the opportunity to inspect or diff the output before applying.

Common Kustomization Features

ConfigMap and Secret Generators

configMapGenerator:
  - name: app-config
    literals:
      - DB_HOST=postgres.staging
      - LOG_LEVEL=debug

secretGenerator:
  - name: db-credentials
    literals:
      - username=admin
      - password=secret123

Kustomize appends a hash suffix to generated names and updates all references automatically, enabling safe rolling updates when config changes.

Strategic Merge Patches

patches:
  - path: increase-replicas.yaml
    target:
      kind: Deployment
      name: my-app

Where increase-replicas.yaml contains:

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

JSON Patches

patches:
  - patch: |-
      - op: add
        path: /spec/template/spec/containers/0/resources
        value:
          limits:
            memory: "512Mi"
            cpu: "500m"
    target:
      kind: Deployment

Environment-Specific Configurations

A typical multi-environment layout:

# Build each environment
kubectl kustomize overlays/dev       # dev settings
kubectl kustomize overlays/staging   # staging settings
kubectl kustomize overlays/prod      # production settings

# Compare environments
diff <(kubectl kustomize overlays/staging) <(kubectl kustomize overlays/prod)

Kustomize vs. Helm

| Feature | Kustomize | Helm | |---------|-----------|------| | Approach | Patch-based composition | Go template rendering | | Learning curve | Lower (plain YAML) | Higher (template syntax) | | Built into kubectl | Yes | No (separate binary) | | Package management | No | Yes (charts, repos) | | Conditional logic | Limited | Full Go template logic | | Reusability | Via bases and overlays | Via charts and values |

Many teams use both: Helm for third-party applications and Kustomize for internal workloads.

Version Differences

The kustomize version embedded in kubectl may trail the standalone binary. Check the version:

# Embedded version
kubectl version --client -o json | jq -r '.kustomizeVersion'

# Standalone version (if installed)
kustomize version

If you need features only in newer kustomize versions, use the standalone binary:

kustomize build overlays/production | kubectl apply -f -

CI/CD Pipeline Pattern

#!/bin/bash
ENVIRONMENT=$1

# Build and validate
kubectl kustomize "overlays/$ENVIRONMENT" > /tmp/manifests.yaml
kubectl apply --dry-run=server -f /tmp/manifests.yaml

# Diff for review
kubectl diff -f /tmp/manifests.yaml

# Apply
kubectl apply -f /tmp/manifests.yaml

# Verify
kubectl rollout status deployment/my-app -n "$ENVIRONMENT"