26.4d kustomize: overlay-based configuration management without templating¶

🧭 Context Introduction¶

When managing Kubernetes configurations for AI workloads, engineers often face a challenge: how to maintain multiple variations of the same application (e.g., development, staging, and production) without duplicating entire YAML files. Traditional templating tools like Helm use variables and templates, which can become complex and hard to debug. Kustomize offers a different approach—it uses overlays to layer modifications on top of a base configuration, without any templating language. This makes configurations more readable, maintainable, and native to Kubernetes.

⚙️ What is Kustomize?¶

• Kustomize is a Kubernetes-native configuration management tool that works directly with standard YAML files.
• It uses a declarative approach: you define what you want, not how to achieve it.
• No templating syntax (like {{ .Values.replicas }}) is needed—everything is pure YAML.
• Kustomize is built into kubectl since version 1.14, so no separate installation is required.

📊 Core Concepts: Base and Overlays¶

Kustomize organizes configurations into two layers:

🧱 Base¶

• The base directory contains the common, shared configuration for an application.
• This is the "source of truth" that all environments share.
• Example contents: a Deployment, a Service, and a ConfigMap.

🧩 Overlays¶

• Overlays are directories that contain patches or modifications to the base.
• Each overlay represents a specific environment (dev, staging, prod) or use case.
• Overlays can add, modify, or remove resources from the base.

🛠️ How Overlays Work (Without Templating)¶

• Kustomize uses a patch-and-merge strategy instead of variable substitution.
• You define only the differences from the base in each overlay.
• The tool automatically merges these changes into the final output.

Common Operations in Overlays¶

📊 Visual Representation: Kustomize Overlay Manifest inheritance¶

This diagram displays Kustomize overlay structures: inheriting from a shared base directory to modify configuration variables.

🕵️ Key Benefits for AI Infrastructure¶

• No templating complexity: Engineers work with familiar YAML, not custom syntax.
• Environment isolation: Each overlay is self-contained and easy to audit.
• Reusability: The base configuration is shared, reducing duplication.
• Native Kubernetes: Kustomize output is pure Kubernetes YAML—no conversion needed.
• GPU-specific patches: Easily add GPU resource limits, tolerations, or node selectors per environment.

📋 Practical Example Structure¶

A typical AI application configuration might look like this:

ai-training-app/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── patch_replicas.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   ├── patch_gpu.yaml
    │   └── patch_resources.yaml
    └── prod/
        ├── kustomization.yaml
        ├── patch_gpu.yaml
        ├── patch_resources.yaml
        └── patch_hpa.yaml

🔄 Workflow: From Base to Final Configuration¶

1. Define the base with common resources (e.g., a Deployment for a model inference service).
2. Create an overlay for each environment.
3. In each overlay's kustomization.yaml, reference the base and list patches.
4. Run kustomize to generate the final YAML for that environment.
5. Apply the output directly to the Kubernetes cluster.

✅ Why Engineers Choose Kustomize for AI Workloads¶

• Simplicity: No learning curve for templating languages.
• Transparency: The final YAML is exactly what gets applied—no hidden transformations.
• GitOps friendly: Overlays can be version-controlled and reviewed like any other code.
• Scalable: Works well for small teams and large GPU fleets alike.
• Composable: Overlays can be stacked and combined for complex scenarios.

🧠 Key Takeaway¶

Kustomize empowers engineers to manage Kubernetes configurations for AI infrastructure using pure YAML overlays—no templating, no extra syntax. This approach reduces complexity, improves maintainability, and keeps configurations transparent and auditable across development, staging, and production environments.