Compose Environment Overlays with Kustomize · Kubernetes
Keep a common base and add only environment-specific differences.
Learn with progress and quizzesFirst, 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-overlayHow 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-overlayApply 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?
- kubectl apply -k
- kubectl kustomize
- kubectl delete -k
- 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