Stage 5 · Platform
Platform Engineering & Multi-Tenancy
Kustomize & GitOps
Bases, overlays, patches, and ArgoCD/Flux integration.
Kustomize Overview
Kustomize is a template-free way to customize Kubernetes manifests. Instead of templating, it uses overlays to patch and transform existing YAML files. This makes it safer than Helm for configuration management — you see the actual manifests before they're applied.
# Build and view rendered manifests
kubectl kustomize overlays/production
# Apply directly
kubectl apply -k overlays/production
# Build with kustomize binary
kustomize build overlays/production
# Diff against current state
kubectl diff -k overlays/productionkubectl kustomize renders the overlay to stdout. kubectl apply -k applies it. kustomize build uses the standalone binary (may have newer features). The -k flag tells kubectl to use kustomize.
Bases and Overlays
A base is a directory of Kubernetes manifests with a kustomization.yaml file. An overlay references one or more bases and applies modifications. This creates a hierarchy: base defines common resources, overlays customize for environments.
base/
kustomization.yaml
deployment.yaml
service.yaml
configmap.yaml
overlays/
dev/
kustomization.yaml
patch-replicas.yaml
staging/
kustomization.yaml
patch-replicas.yaml
patch-resources.yaml
production/
kustomization.yaml
patch-replicas.yaml
patch-resources.yaml
hpa.yamlThe base contains common manifests. Each overlay patches the base for its environment. Dev uses 1 replica, production uses 5 with HPA. Changes to the base propagate to all overlays automatically.
# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
- hpa.yaml
- networkpolicy.yaml
patches:
- path: patch-replicas.yaml
- path: patch-resources.yaml
- target:
group: apps
version: v1
kind: Deployment
name: my-app
patch: |-
- op: replace
path: /spec/template/spec/containers/0/image
value: my-app:2.0.0
commonLabels:
environment: production
team: platformresources includes the base and additional manifests. patches apply modifications. The target selector applies a patch to specific resources. commonLabels adds labels to all resources.
Strategic Merge and JSON Patches
Kustomize supports two patch types: strategic merge patches (default) and JSON patches. Strategic merge merges YAML structures intelligently. JSON patches use explicit operations (add, remove, replace) for precise modifications.
# patch-replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 5Strategic merge patch replaces or merges fields. This patch sets replicas to 5. For lists, strategic merge can merge by key (e.g., containers merge by name). This is simpler than JSON patches for most use cases.
# patch-resources.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
template:
spec:
containers:
- name: my-app
resources:
requests:
cpu: "500m"
memory: "512Mi"
limits:
cpu: "1"
memory: "1Gi"
env:
- name: LOG_LEVEL
value: "warn"JSON patches use op/path/value syntax. They are more explicit and can handle cases that strategic merge cannot: adding to lists, removing items, or replacing entire sections. Use strategic merge for simple field changes.
Image and Label Transformers
Kustomize provides built-in transformers for common operations: updating image tags, adding labels, adding annotations, and setting name prefixes/suffixes. These apply to all matching resources without manual patching.
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
images:
- name: my-app
newName: ghcr.io/my-org/my-app
newTag: "2.1.0"
- name: sidecar
newName: ghcr.io/my-org/sidecar
newTag: "1.0.3"
namePrefix: prod-
nameHash: true
commonAnnotations:
managed-by: kustomize
team: platformimages updates container image references across all resources. namePrefix adds a prefix to all resource names. nameHash appends a hash suffix to prevent name conflicts. commonAnnotations adds annotations to all resources.
ArgoCD Integration
ArgoCD watches Git repositories and syncs Kubernetes manifests to clusters. It natively understands Kustomize — point an ArgoCD Application at a kustomize overlay directory and it renders and applies the manifests automatically.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app-production
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/my-org/k8s-manifests
targetRevision: main
path: overlays/production
destination:
server: https://kubernetes.default.svc
namespace: production
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3mArgoCD renders the kustomize overlay and applies it. automated.sync prunes resources removed from Git. selfHeal reverts manual changes. retry handles transient failures.
Flux Integration
Flux v2 uses Kustomization CRDs (not kustomize the tool) to reconcile Git repositories. It watches for changes, renders manifests, and applies them. Flux supports health checks, dependencies, and custom reconcilers.
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
name: my-app
namespace: flux-system
spec:
interval: 5m
path: overlays/production
prune: true
sourceRef:
kind: GitRepository
name: k8s-manifests
healthChecks:
- apiVersion: apps/v1
kind: Deployment
name: my-app
namespace: production
timeout: 3mFlux reconciles every 5 minutes. path points to the kustomize overlay. healthChecks ensures the deployment is healthy before marking the reconciliation as successful. timeout limits how long to wait for health checks.
Kustomize works better for GitOps because it produces plain YAML (no templating). Helm charts require helm template or helm upgrade, which adds complexity. For GitOps, prefer kustomize overlays for configuration management.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.