study.

Compose Environment Overlays with Kustomize · Kubernetes

Keep a common base and add only environment-specific differences.

← Kubernetes

Learn with progress and quizzes

First, understand the concepts.

Base and overlay

Separating shared resources from environment changes avoids maintaining large copied YAML files. Kustomize composes resources rather than relying on text-template substitution.

Render first

kubectl kustomize prints the final YAML without deploying it. Verify images, namespace, and replicas before applying with -k.

How this differs from GitOps

Storing files in Git alone does not synchronize a cluster. GitOps uses a separate controller to continuously reconcile repository declarations with cluster state.

Why it matters

Copying separate development and production YAML can cause shared changes to drift. Keep common resources in a base and describe environment differences in overlays.

Work through the reasoning

Read rendered output

kubectl kustomize prints the combined result. Compare the base and overlay replica settings in the final YAML, and review image, namespace, and names before applying.

Separate rendering from operations

apply -k submits rendered resources. Kustomize itself does not watch Git and continuously deploy changes; GitOps requires a separate controller.

Learn by doing.

Use kubectl, a personal practice Kubernetes cluster, and a POSIX shell. Check the context and use the dedicated namespace in each lab. Cleanup deletes all resources in that practice namespace.

Create a base and a dev overlay in a temporary directory, render two replicas, and apply them. This lab does not install a GitOps controller.

kubectl config current-context
kubectl create namespace study-k8s-overlay --dry-run=client -o yaml | kubectl apply -f -
study_overlay_dir=$(mktemp -d)
mkdir -p "$study_overlay_dir/base" "$study_overlay_dir/dev"
cat > "$study_overlay_dir/base/deployment.yaml" <<'YAML'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels: {app: web}
  template:
    metadata:
      labels: {app: web}
    spec:
      containers:
      - name: web
        image: nginx:stable-alpine
YAML
printf 'resources:
- deployment.yaml
' > "$study_overlay_dir/base/kustomization.yaml"
cat > "$study_overlay_dir/dev/kustomization.yaml" <<'YAML'
resources:
- ../base
namespace: study-k8s-overlay
replicas:
- name: web
  count: 2
YAML
kubectl kustomize "$study_overlay_dir/dev"
kubectl apply -k "$study_overlay_dir/dev"
kubectl rollout status deployment/web -n study-k8s-overlay --timeout=120s
kubectl get deployment web -n study-k8s-overlay

How to check your result

Look for namespace study-k8s-overlay and replicas: 2 in rendered YAML. After applying, confirm two ready replicas. For file errors, inspect relative resource paths.

Clean up practice resources

Run after checking the result. Confirm these resources belong to your practice run and contain no data you need to keep.

kubectl delete namespace study-k8s-overlay

Apply what you learned

The base has one replica and the development overlay requests two. How can you verify two without modifying the base?

Reveal the reasoning after trying

Render the development overlay with kubectl kustomize and inspect spec.replicas. Render other overlays separately to check that unintended changes did not propagate.

Ready to check your understanding?

Which command prints the final YAML without changing the cluster?

  1. kubectl apply -k
  2. kubectl kustomize
  3. kubectl delete -k
  4. kubectl rollout restart
Reveal the reasoning after trying

kubectl kustomize

kubectl kustomize renders configuration. apply -k sends the changes to the API.

Official documentation · Compose Environment Overlays with Kustomize