Kustomize is a standalone tool to customize Kubernetes manifests in a template-free way. Unlike Helm, which uses templates, Kustomize uses base YAML files and applies a series of customizations to produce the final manifests. Kustomize became so popular that its functionality is now built into kubectl, so you can use kubectl kustomize to execute Kustomize builds.

Basic Kustomize Use Cases

  1. Resource Customization: Modify properties of native Kubernetes resources without changing the original YAML.
  2. Environment Separation: Generate different YAMLs for dev, staging, and prod from a single base configuration.
  3. Resource Composition: Compose and create new resources from existing ones.
  4. Secret Management: Generate and manage secrets outside the main YAML configurations.

Creating Variants with Overlays

Overlays allow you to define the differences between multiple environments while reusing a common base. The base contains all common configuration settings, and the overlay includes any modifications.

Directory Structure:

.
├── base
│   └── deployment.yaml
└── overlays
    ├── dev
    │   └── kustomization.yaml
    └── prod
        └── kustomization.yaml

kustomization.yaml in overlay directory:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
bases:
- ../../base
patchesStrategicMerge:
- deployment-patch.yaml

Kustomization Files Explained

A kustomization.yaml file is used to manage all the customizations you want. Key fields include:

  • resources: List of YAML manifests to be included.
  • bases: Another Kustomize directory to inherit resources from.
  • patchesStrategicMerge: List of patches to apply.
  • commonLabels or commonAnnotations: Add labels or annotations to all resources.
  • vars: Variables that can be substituted into the manifests.

Best Practices and Tips

  1. Keep it Simple: Start with a simple structure and evolve as requirements grow.
  2. Directory Organization: Keep a good folder structure distinguishing bases and overlays.
  3. Source Control: Always version control your base and overlay files.
  4. Avoid Deep Nesting: Deeply nested kustomizations can become hard to manage.
  5. Validate Before Applying: Use the following command to apply changes, but always check the output first to ensure it generates what you expect.
kubectl kustomize ./path | kubectl apply -f -

Troubleshooting Exercise

Setup Commands

Create a base deployment YAML file named base-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app
        image: nginx:1.14.2

Create a kustomization.yaml in the same directory:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- base-deployment.yaml
Exercise

You’ve applied your Kustomize changes, but the deployment is not scaling as expected. Troubleshoot the issue.

Debugging
  1. Check the generated YAML to see if the configurations look correct:
kubectl kustomize ./path > output.yaml
  1. Validate the deployed resources in Kubernetes:
kubectl get deployments
  1. Look for errors in the deployment:
kubectl describe deployment my-app
Solution

In this example, ensure that your kustomization.yaml is correctly referring to base-deployment.yaml. If the base YAML is misconfigured or not correctly referenced, your changes will not be applied. Always validate your YAML before applying to catch these issues.

kubectl kustomize ./path | kubectl apply -f -