Course outline

01 · Kubernetes Architecture Deep Dive

02 · Workloads & Scheduling

03 · Networking, Storage & Service Mesh

04 · Platform Engineering & Multi-Tenancy

05 · Networking & Service Mesh

06 · Observability & Autoscaling

07 · Configuration & Secrets Management

08 · Stateful Storage Operations

09 · Security, Identity & Admission

10 · Release Packaging with Helm & Kustomize

11 · Operators, CRDs & Controllers

12 · Production Troubleshooting & Operations

Stage 5 · Platform

Release Packaging with Helm & Kustomize

Kustomize Overlays

Bases, overlays, strategic merge patches, JSON patches, and image transformers.

7 min readKubernetes & Cloud NativePlatform

Kustomize Structure

Kustomize uses bases (common manifests) and overlays (environment-specific modifications). This creates a hierarchy where changes to the base propagate to all overlays. No templating — just YAML transformation.

Base kustomization.yaml


apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
- configmap.yaml
- serviceaccount.yaml
commonLabels:
  app.kubernetes.io/part-of: my-app
  team: platform
namespace: production

The base defines common resources and labels. commonLabels adds labels to all resources. namespace sets the default namespace. Overlays can override or extend these settings.

Strategic Merge Patches

Strategic merge patches modify YAML structures by merging. For maps, it adds/updates keys. For lists, it merges by key (if defined) or replaces entirely. This is the default patch type in Kustomize.

Strategic merge patch files


# patch-replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 5
---
# 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"

The first patch sets replicas to 5. The second patch updates container resources. Strategic merge matches containers by name and merges the resources block. Other fields remain unchanged.

JSON Patches

JSON patches use explicit operations: add, remove, replace, move, copy, test. They provide precise control over YAML modifications. Use them when strategic merge cannot express the change.

JSON patch operations


apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
      - name: my-app
        env:
        - name: LOG_LEVEL
          value: "warn"
---
# Add a new environment variable
# patches:
# - target:
#     kind: Deployment
#     name: my-app
#   patch: |-
#     - op: add
#       path: /spec/template/spec/containers/0/env/-
#       value:
#         name: NEW_VAR
#         value: "value"
# Replace an existing value
# - op: replace
#   path: /spec/replicas
#   value: 10
# Remove an item
# - op: remove
#   path: /spec/template/spec/containers/0/env/0

JSON patches use op/path/value syntax. add appends to arrays (path/-), replace updates existing values, remove deletes items. JSON patches are more explicit than strategic merge and handle edge cases better.

Image Transformers

Image transformers update container image references across all resources. They handle new image names, tags, and digest pinning. This is more reliable than patching individual deployments.

Image transformer and name prefix


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: init-container
  newName: ghcr.io/my-org/init
  newTag: "1.0.3"
  digest: sha256:abc123...
namePrefix: prod-
nameSuffix: "-v2"
commonLabels:
  version: v2
commonAnnotations:
  managed-by: kustomize
  deployment-date: "2024-01-15"

images updates all container references matching the name. namePrefix adds a prefix to all resource names. nameSuffix adds a suffix. These prevent name conflicts when deploying multiple instances.

Kustomize Components

Components are optional overlay modules. They can be enabled/disabled independently. Use them for optional features: monitoring sidecars, logging agents, or feature flags.

Kustomize components


apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
components:
- ../../components/monitoring
- ../../components/logging
---
# components/monitoring/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
patches:
- target:
    kind: Deployment
    labelSelector:
      app: my-app
  patch: |-
    - op: add
      path: /spec/template/spec/containers/-
      value:
        name: prometheus-sidecar
        image: prom/prometheus:v2.49.0
        ports:
        - containerPort: 9090

Components are referenced in the overlay's kustomization.yaml. They can add containers, volumes, patches, and other modifications. Components are self-contained and reusable across overlays.

Testing Overlays

Test kustomize overlays


# Render and inspect
kubectl kustomize overlays/production

# Diff against current state
kubectl diff -k overlays/production

# Apply and verify
kubectl apply -k overlays/production

# Validate with kubeconform
kustomize build overlays/production | kubeconform -strict

# Test with konfig (kustomize linting)
kustomize build overlays/production | kubeconform -summary

kustomize build renders the overlay. kubectl diff shows changes before applying. kubeconform validates the rendered manifests. Run these in CI to catch issues before deployment.

Kustomize vs Helm for configuration

Kustomize is better for configuration management (patching existing manifests). Helm is better for packaging (reusable charts with templates). Use Kustomize for GitOps overlays, Helm for distributable packages.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.