5 min to read

What is Kustomize?

A comprehensive guide to Kustomize usage and implementation

Featured image

Image Reference


Overview

This post explores Kustomize, a powerful tool for customizing Kubernetes manifests.


What is Kustomize?

Kustomize is a tool for customizing Kubernetes manifests.
It focuses on applying modifications and transformations to base manifests without changing the original files.


Installation

curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
sudo mv kustomize /usr/local/bin/

Core Concepts

1. Base and Overlays

Kustomize operates on the concept of bases and overlays. The base contains the default resource definitions, while overlays apply environment-specific patches.

├── base
│   ├── kustomization.yaml
│   ├── nginx-deployment.yaml
│   ├── nginx-ingress.yaml
│   └── nginx-service.yaml
└── overlays
    ├── dev
    │   ├── ingress.yaml
    │   ├── kustomization.yaml
    │   └── replica-count.yaml
    ├── prod
    │   ├── ingress.yaml
    │   ├── kustomization.yaml
    │   └── replica-count.yaml
    └── qa
        ├── ingress.yaml
        ├── kustomization.yaml
        └── replica-count.yaml

2. Kustomization Files

Base Configuration
# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - nginx-deployment.yaml
  - nginx-service.yaml
  - nginx-ingress.yaml
Overlay Configuration
# overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - path: replica-count.yaml
    target:
      kind: Deployment
      name: nginx-deployment
  - path: ingress.yaml 
    target:
      kind: Ingress
      name: nginx-ingress
namePrefix: dev-
namespace: dev-nginx

Practical Implementation

Directory Structure

.
├── README.md
├── base
│   ├── kustomization.yaml
│   ├── nginx-deployment.yaml
│   ├── nginx-ingress.yaml
│   └── nginx-service.yaml
├── manifests
│   ├── dev-nginx.yaml
│   ├── prod-nginx.yaml
│   └── qa-nginx.yaml
└── overlays
    ├── dev
    ├── prod
    └── qa

Building Resources

# Generate environment-specific manifests
kustomize build overlays/dev
kustomize build overlays/qa
kustomize build overlays/prod

Saving Manifests

kustomize build overlays/dev > manifests/dev-nginx.yaml
kustomize build overlays/qa > manifests/qa-nginx.yaml
kustomize build overlays/prod > manifests/prod-nginx.yaml

Deployment

# Method 1: Using kustomize build
kustomize build overlays/dev | kubectl apply -f - --namespace=dev-nginx

# Method 2: Using kubectl directly
kubectl apply -k overlays/dev/

Verification

kubectl get po,svc,ingress -n dev-nginx

Example output:

NAME                                       READY   STATUS    RESTARTS   AGE
pod/dev-nginx-deployment-8d545c96d-48rqx   1/1     Running   0          2m37s

NAME                        TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)   AGE
service/dev-nginx-service   ClusterIP   10.233.6.66   <none>        80/TCP    2m37s

NAME                                          CLASS    HOSTS                   ADDRESS        PORTS   AGE
ingress.networking.k8s.io/dev-nginx-ingress   <none>   dev-nginx.somaz.link   10.10.100.22   80      2m37s

Testing

curl 10.233.6.66
# or
curl dev-nginx.somaz.link

Cleanup

kubectl delete -k overlays/dev


Common Kustomize Patches

1. Image Updates

images:
  - name: nginx
    newName: custom-registry/nginx
    newTag: v1.2.3

2. Resource Modifications

patches:
- patch: |-
    - op: replace
      path: /spec/replicas
      value: 3
  target:
    kind: Deployment
    name: nginx-deployment

3. ConfigMap/Secret Generation

configMapGenerator:
- name: nginx-config
  files:
    - nginx.conf
  literals:
    - FOO=Bar

secretGenerator:
- name: nginx-secrets
  files:
    - secret.file
  literals:
    - API_KEY=secret-value


⚙️ Best Practices
  • Directory Structure
    • Keep base configurations minimal and environment-agnostic
    • Use meaningful names for overlay directories
    • Maintain a clear separation between base and overlay resources
  • Version Control
    • Commit base configurations separately
    • Document environment-specific requirements
    • Include example configurations for new users
  • Resource Management
    • Use namePrefix or nameSuffix to avoid naming conflicts
    • Implement proper namespace management
    • Consider using commonLabels for resource tracking
  • Security Considerations
    • Never commit sensitive data in base configurations
    • Use secretGenerator for sensitive information
    • Implement proper RBAC configurations


Troubleshooting

1. Resource Not Found

# Verify the resource exists in base
kubectl kustomize base

# Check overlay configuration
kubectl kustomize overlays/dev

2. Patch Not Applied

# Debug patch application
kustomize build --load-restrictor LoadRestrictionsNone overlays/dev

# Verify patch syntax
kustomize build overlays/dev --enable-alpha-plugins

3. Namespace Issues

# Verify namespace configuration
kubectl config get-contexts
kubectl config set-context --current --namespace=target-namespace

Advanced Features

1. Strategic Merge Patches

patchesStrategicMerge:
- |-
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: nginx-deployment
  spec:
    template:
      spec:
        containers:
        - name: nginx
          resources:
            limits:
              memory: 512Mi

2. JSON Patches

patchesJson6902:
- target:
    version: v1
    kind: Deployment
    name: nginx-deployment
  path: patch.yaml

3. Composition

components:
- ../../components/nginx
- ../../components/monitoring


References