Skip to main content
Mapagam

Working with Kustomize

1. Understanding Kustomize Concepts

Kustomize is a tool that allows you to customize Kubernetes resources without modifying the original manifests. It enables you to manage configurations in a declarative way, making it easier to maintain and scale your deployments.

Concept Description Usage
Kustomization Represents a set of resources and their customization rules. Defined in kustomization.yaml
Base A directory containing Kubernetes manifests and a kustomization.yaml file. Serves as the starting point for customization.
Overlay A directory that extends or modifies a base using patches and transformers. Used to create environment-specific configurations (e.g., dev, staging, prod).
Transformer Modifies resources (e.g., adding labels, changing image tags). Applied via transformers.yaml or inline in kustomization.yaml.
Patch Modifies specific fields in a resource (e.g., adding or updating annotations). Can be applied as JSON patches or strategic merge patches.

Example: Basic Kustomization Structure

my-app/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── patch.yaml
    └── prod/
        ├── kustomization.yaml
        └── patch.yaml
Note: Kustomize is built into kubectl since v1.14, so no separate installation is required.

Key Benefits of Kustomize

  • Declarative Configuration: Define configurations in a structured way.
  • Environment Isolation: Use overlays to manage different environments.
  • Reusability: Share base configurations across multiple overlays.
  • Version Control: Track changes to configurations using Git.

2. Creating kustomization.yaml

The kustomization.yaml file is the core configuration file for Kustomize, defining how to build and customize Kubernetes manifests. It specifies resources, patches, and other Kustomize-specific configurations.

Field Description Example
resources List of Kubernetes resource files or directories to include in the output. 
resources:
- deployment.yaml
- service.yaml
patches Defines how to patch existing resources, including strategic merge or JSON patches. 
patches:
- path: patch.yaml
  target:
    kind: Deployment
configMapGenerator Generates ConfigMaps from literal values or files. 
configMapGenerator:
- name: app-config
  literals:
  - ENV=production
secretGenerator Generates Secrets from literal values or files. 
secretGenerator:
- name: app-secret
  literals:
  - DB_PASSWORD=secret123
images Replaces image names and tags in resources. 
images:
- name: my-app
  newName: my-registry/my-app
  newTag: v2.0

Example: Basic kustomization.yaml

resources:
- deployment.yaml
- service.yaml

configMapGenerator:
- name: app-config
  literals:
  - ENV=production
  - LOG_LEVEL=info

secretGenerator:
- name: app-secret
  literals:
  - DB_PASSWORD=secret123

images:
- name: my-app
  newName: my-registry/my-app
  newTag: v2.0

3. Applying Kustomize Manifests

Command Description Example
kubectl apply -k <path-to-kustomization> Applies the Kustomize manifests in the specified directory kubectl apply -k ./overlays/prod
kubectl kustomize <path-to-kustomization> Outputs the rendered manifests without applying them kubectl kustomize ./overlays/staging

Example: Applying Kustomize Manifests

kubectl apply -k ./overlays/prod
Note: Ensure that the kustomization.yaml file is present in the directory you're applying.
Warning: Be cautious when applying manifests to production environments. Always validate the rendered output with kubectl kustomize before applying.

4. Using Strategic Merge Patches

Field Description Example
strategicMergePatch Defines a strategic merge patch to modify resources 
{
  "metadata": {
    "annotations": {
      "app.kubernetes.io/version": "v1.2.3"
    }
  },
  "spec": {
    "replicas": 3
  }
}

Example: Applying Strategic Merge Patch

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
patchesStrategicMerge:
- patch.yaml
Note: Strategic merge patches are applied after the base resources and can override fields in the original resource.

5. Using JSON Patches

Field Description Example
patchesJson6902 Path to JSON patch files in the Kustomize directory patches/patch.json
patchesJson6902.name Name of the patch patch-name
patchesJson6902.path Path to the JSON patch file patches/patch.json

Example: Applying a JSON Patch

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patchesJson6902:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: my-deployment
  path: patches/patch.json

Example: JSON Patch Content

[{
  "op": "replace",
  "path": "/spec/replicas",
  "value": 3
}]
Note: JSON patches must follow the JSON Patch RFC format.

6. Configuring Name Prefixes

Field Description Example
namePrefix Prefix to be added to the names of all resources prod-

Example: Applying Name Prefix

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
metadata:
  name: my-app
namePrefix: prod-
Note: The namePrefix is applied to all resources defined in the Kustomization, including Deployments, Services, ConfigMaps, etc.

7. Generating ConfigMaps

Field Description Example
apiVersion API version of the ConfigMap resource v1
kind Kind of the resource (must be ConfigMap) ConfigMap
metadata.name Name of the ConfigMap app-config
data Key-value pairs of configuration data 
database.url: "jdbc:postgresql://db:5432/myapp"
log.level: "INFO"

Example: Creating a ConfigMap from literals

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  database.url: "jdbc:postgresql://db:5432/myapp"
  log.level: "INFO"

Example: Creating a ConfigMap from a file

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  config.properties: |
    database.url=jdbc:postgresql://db:5432/myapp
    log.level=INFO
Note: ConfigMaps are not encrypted and should not contain sensitive data. Use Secrets for sensitive information.

8. Generating Secrets

Field Description Example
name Name of the secret db-secret
type Type of the secret (e.g., Opaque, tls) Opaque
data Key-value pairs of secret data (base64 encoded) { "password": "cGFzc3dvcmQ=" }

Example: Creating a Secret from Literal Values

apiVersion: v1
kind: Secret
metadata:
  name: db-secret
type: Opaque
data:
  password: cGFzc3dvcmQ=
  username: dXNlcg==

Example: Creating a Secret from a File

apiVersion: v1
kind: Secret
metadata:
  name: tls-secret
type: kubernetes.io/tls
data:
  tls.crt: LS0tLS1CRUdJTiBDRVJ...
  tls.key: LS0tLS1CRUdJTiBSU0E...
Note: Secret data is base64 encoded when defined in YAML. You can use kubectl create secret to handle encoding automatically.

9. Setting Common Labels

Label Key Value Description
app.kubernetes.io/name my-app Identifies the name of the application
app.kubernetes.io/version v1.2.3 Identifies the version of the application
app.kubernetes.io/instance my-app-instance-1 Identifies a unique instance of an application
app.kubernetes.io/component frontend Identifies the component within the architecture
app.kubernetes.io/part-of my-app Identifies the name of a higher-level application this one is part of
app.kubernetes.io/managed-by kustomize Identifies the tool managing this resource

Example: Setting Common Labels in Kustomize

labels:
  - pairs:
      app.kubernetes.io/name: my-app
      app.kubernetes.io/version: v1.2.3
      app.kubernetes.io/instance: my-app-instance-1
      app.kubernetes.io/component: frontend
      app.kubernetes.io/part-of: my-app
      app.kubernetes.io/managed-by: kustomize
Note: These labels follow the Kubernetes recommended label scheme to ensure consistency across deployments.

10. Using Overlays

Example: Basic Overlay Structure

my-app/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
├── overlays/
│   └── production/
│       ├── deployment.yaml
│       ├── kustomization.yaml
│       └── service.yaml
File Description Usage
overlays/production/kustomization.yaml Overlay configuration file Defines patches and resources to override base
overlays/production/deployment.yaml Deployment patch file Modifies base deployment (e.g., replicas, image)

Example: Overlay kustomization.yaml

resources:
  - ../../base
patchesStrategicMerge:
  - deployment.yaml
  - service.yaml
images:
  - name: my-app
    newName: my-app-prod
    newTag: v1.2.3

Example: Patch Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 5
  template:
    spec:
      containers:
        - name: app
          image: my-app-prod:v1.2.3
Note: Overlays allow you to customize configurations for different environments without modifying the base manifests.

11. Configuring Image Tags

Field Description Example
images List of image configurations to override 
[
  {
    "name": "my-app",
    "newTag": "v2.0.0"
  }
]

Example: Override image tag in Kustomization

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
images:
- name: my-app
  newTag: v2.0.0
Note: The name field matches the image name in your deployment manifests.
Warning: Ensure the new tag exists and is accessible to your cluster.

12. Building Kustomize Output

Example: Basic kustomize build command

kustomize build &lt;directory&gt;
Option Values Description
kustomize build kustomize build [directory] Builds the Kustomize output from a directory
--output -o &lt;file&gt; Writes the output to a file instead of stdout
--enable-alpha-plugins --enable-alpha-plugins Enables alpha plugins (experimental)
--enable-helm --enable-helm Enables Helm chart support
Note: The kustomize build command reads the kustomization.yaml file in the specified directory and generates the final Kubernetes manifest.

Example: Building with output to file

kustomize build . -o output.yaml

Example: Building with Helm support

kustomize build . --enable-helm

Was this article helpful?

Related Cheat Sheets