Skip to content

11.04 The kustomization.yaml File

Abstract

The kustomization.yaml file is the main configuration file used by Kustomize.

It tells Kustomize:

  • Which Kubernetes YAML files to manage
  • Which customizations or transformations to apply
  • How to generate the final Kubernetes manifests

What Is kustomization.yaml?

Kustomize does not directly look for every YAML file in a folder.

Instead, it looks for a file named:

kustomization.yaml

This file acts as the entry point for Kustomize.

Note

The file must be named kustomization.yaml, kustomization.yml, or Kustomization.

The most common and recommended name is kustomization.yaml.

Example Folder Structure

Example Kubernetes manifest folder:

k8s/
├── nginx-depl.yml
├── nginx-service.yml
└── kustomization.yaml
File Purpose
nginx-depl.yml Deployment manifest
nginx-service.yml Service manifest
kustomization.yaml Kustomize configuration file

Basic kustomization.yaml Example

resources:
  - nginx-depl.yml
  - nginx-service.yml

commonLabels:
  company: KodeKloud

This file has two important sections:

Section Purpose
resources Lists Kubernetes manifests managed by Kustomize
commonLabels Adds labels to all listed resources

Tip

Think of resources as what Kustomize should manage, and transformations as what Kustomize should change.

Resources Section

The resources section lists all Kubernetes manifests that Kustomize should include.

resources:
  - nginx-depl.yml
  - nginx-service.yml

Kustomize reads these files and combines them into one final rendered output.

Warning

If a manifest is not listed under resources, Kustomize will not include it in the final output.

Customization Section

Customizations define changes that should be applied to the resources.

Example:

commonLabels:
  company: KodeKloud

This adds the label to every resource generated by Kustomize.

Example rendered output:

metadata:
  labels:
    company: KodeKloud

Example

If both a Deployment and Service are listed under resources, the company: KodeKloud label will be added to both.

Kustomize Build

To generate the final manifest output:

kustomize build k8s/

This command:

  1. Finds the kustomization.yaml file
  2. Loads all files listed under resources
  3. Applies the defined transformations
  4. Prints the final YAML output to the terminal

Note

kustomize build only renders YAML.

It does not deploy resources to the Kubernetes cluster.

Build Output Example

If commonLabels is configured, the final output includes the label in each resource.

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  labels:
    company: KodeKloud
spec:
  ports:
    - port: 80
      targetPort: 360
  selector:
    component: nginx

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    company: KodeKloud
spec:
  replicas: 1
  selector:
    matchLabels:
      component: nginx
  template:
    metadata:
      labels:
        component: nginx
        company: KodeKloud
    spec:
      containers:
        - name: nginx
          image: nginx

Applying Kustomize Output

kustomize build only displays the final manifest.

To apply it to a cluster, pipe the output to kubectl apply:

kustomize build k8s/ | kubectl apply -f -

Or use the built-in Kustomize support in kubectl:

kubectl apply -k k8s/

Success

In real projects, kubectl apply -k is the most common way to apply a Kustomize directory.

kustomize build vs kubectl apply -k

Command What It Does
kustomize build k8s/ Renders final YAML only
kustomize build k8s/ \| kubectl apply -f - Renders and applies YAML
kubectl apply -k k8s/ Builds and applies directly

Tip

Use kustomize build first when you want to review the final manifest before applying it.

Common Fields in kustomization.yaml

Field Purpose
resources Includes Kubernetes YAML files
commonLabels Adds labels to all resources
commonAnnotations Adds annotations to all resources
namePrefix Adds a prefix to resource names
nameSuffix Adds a suffix to resource names
namespace Sets namespace for resources
images Updates container images
replicas Updates replica count
configMapGenerator Generates ConfigMaps
secretGenerator Generates Secrets
patches Applies targeted changes

Example with Multiple Customizations

resources:
  - nginx-depl.yml
  - nginx-service.yml

namespace: dev

namePrefix: dev-

commonLabels:
  company: KodeKloud
  environment: dev

commonAnnotations:
  managed-by: kustomize

Result:

  • Resources are deployed to the dev namespace
  • Resource names get the dev- prefix
  • Labels are added to all resources
  • Annotations are added to all resources

Production Use Case

In production, kustomization.yaml is commonly used to define environment-specific overlays.

Example:

k8s/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
│
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── stg/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

Production overlay example:

resources:
  - ../../base

commonLabels:
  environment: prod

replicas:
  - name: nginx-deployment
    count: 5

Production Recommendation

Keep shared manifests in base/ and only production-specific changes in overlays/prod/.

Best Practices

Recommended

  • Keep kustomization.yaml small and readable
  • Always list resources explicitly
  • Use base/ and overlays/ for multi-environment projects
  • Run kustomize build before applying changes
  • Store Kustomize manifests in Git
  • Use labels for ownership, environment, and application tracking
  • Validate rendered YAML in CI/CD pipelines

Do's

  • Use resources to clearly list managed manifests
  • Use commonLabels for shared labels
  • Use overlays for environment-specific changes
  • Preview output before applying
  • Keep base manifests reusable
  • Use Git review for production changes

Don'ts

  • Don't assume Kustomize automatically reads all YAML files
  • Don't put environment-specific changes directly in the base
  • Don't apply manifests without checking the final build output
  • Don't duplicate full manifests across environments
  • Don't store plain-text secrets in kustomization.yaml

Troubleshooting

Resource not included

Check whether the file is listed under resources.

resources:
  - nginx-depl.yml
  - nginx-service.yml

Build works but apply fails

Validate the rendered YAML:

kustomize build k8s/

Then check API versions, namespaces, and required CRDs.

Wrong labels applied

Check global transformations such as:

commonLabels:
  company: KodeKloud

These apply to all managed resources.

Useful Commands

Task Command
Build final manifests kustomize build k8s/
Apply using pipe kustomize build k8s/ \| kubectl apply -f -
Apply using kubectl kubectl apply -k k8s/
Preview using kubectl kubectl kustomize k8s/
Delete using kustomize kubectl delete -k k8s/

Kustomize ApiVersion & Kind

Abstract

A kustomization.yaml file can include apiVersion and kind, just like other Kubernetes-style configuration files.

These fields are technically optional, but adding them makes the file clearer, safer, and more future-proof.

Recommended Fields

Use the following values in kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

Full example:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - nginx-depl.yaml
  - nginx-service.yaml

commonLabels:
  company: KodeKloud

Note

Kustomize can still work without these fields because it can assume default values.

However, explicitly defining them is better for readability and long-term maintenance.

Why Add ApiVersion and Kind?

Field Purpose
apiVersion Defines the Kustomize config API version
kind Identifies this file as a Kustomization config

Tip

Treat kustomization.yaml like a normal Kubernetes manifest: define the API version, kind, metadata when needed, and the desired configuration clearly.

Production Recommendation

In production repositories, always include:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

This helps avoid confusion when:

  • multiple teams maintain manifests
  • Kustomize versions change
  • CI/CD tools validate YAML
  • GitOps tools render manifests
  • new engineers review the repository

Recommended

Hard-code apiVersion and kind in every kustomization.yaml file, especially for shared, production, or GitOps-managed environments.

What Happens If You Omit Them?

Kustomize may still process the file:

resources:
  - nginx-depl.yaml
  - nginx-service.yaml

commonLabels:
  company: KodeKloud

But this is less explicit.

Warning

Relying on defaults can become risky if tool behavior changes in the future.

Explicit values make your configuration easier to understand and safer to maintain.

Do's

  • Add apiVersion and kind to every kustomization.yaml
  • Use the supported Kustomize API version
  • Keep the file simple and readable
  • Use consistent structure across base and overlays
  • Validate output with kustomize build

Don'ts

  • Don't rely on implicit defaults in production
  • Don't mix Kustomize config fields with normal Kubernetes resource fields incorrectly
  • Don't rename kustomization.yaml randomly
  • Don't use unsupported or outdated API versions without checking compatibility

Quick Example: Base Kustomization

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - nginx-depl.yaml
  - nginx-service.yaml

commonLabels:
  app: nginx
  company: KodeKloud

Quick Example: Overlay Kustomization

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

patches:
  - path: replica-patch.yaml

commonLabels:
  environment: prod

Example

Base kustomizations usually contain shared resources.

Overlay kustomizations usually reference the base and apply environment-specific changes.

Summary

Quote

  • kustomization.yaml can include apiVersion and kind
  • These fields are optional but strongly recommended
  • Use apiVersion: kustomize.config.k8s.io/v1beta1
  • Use kind: Kustomization
  • Explicit fields make production manifests safer and easier to maintain

Kustomize Output

Abstract

kustomize build generates the final Kubernetes YAML output, but it does not create anything in the cluster by itself.

To deploy the generated output, you must pass it to kubectl apply.

Build Does Not Deploy

When you run:

kustomize build k8s/

Kustomize:

  1. Reads kustomization.yaml
  2. Loads all listed resources
  3. Applies transformations
  4. Prints the final manifest to the terminal

It does not create Deployments, Services, Pods, ConfigMaps, or any other resources.

Warning

kustomize build only renders YAML.

If you run kubectl get pods, kubectl get deployments, or kubectl get services after only running kustomize build, nothing new will be created.

Apply Kustomize Configs

To apply the generated manifests, redirect the output of kustomize build into kubectl apply.

kustomize build k8s/ | kubectl apply -f -

What this means:

Part Meaning
kustomize build k8s/ Generates final YAML
| Pipes output from the first command to the second command
kubectl apply -f - Applies YAML from standard input

Tip

The pipe | is a Linux shell feature.

It sends the output of the command on the left into the command on the right.

Native Kubectl Apply

Kubectl has built-in Kustomize support.

Instead of using a pipe, you can run:

kubectl apply -k k8s/

Here, -k means kubectl should treat the directory as a Kustomize directory.

Success

kubectl apply -k k8s/ is shorter and commonly used in real projects.

Apply Command Comparison

kustomize build k8s/ | kubectl apply -f -

Use this when you want to explicitly see how Kustomize output is passed into kubectl.

kubectl apply -k k8s/

Use this for cleaner day-to-day usage.

kustomize build k8s/

Use this to inspect the final YAML before deploying.

Example Apply Output

kustomize build k8s/ | kubectl apply -f -

Example output:

service/nginx-loadbalancer-service created
deployment.apps/nginx-deployment created

This means Kubernetes created the resources generated by Kustomize.

Note

The final objects are still normal Kubernetes objects.

Kustomize only helps generate the manifests before they are applied.

Delete Kustomize Resources

Deleting works almost the same way as applying.

Use:

kustomize build k8s/ | kubectl delete -f -

This deletes the resources generated by the Kustomize build output.

Example output:

service "nginx-loadbalancer-service" deleted
deployment.apps "nginx-deployment" deleted

Native Kubectl Delete

You can also delete using kubectl directly:

kubectl delete -k k8s/

This tells kubectl to build the Kustomize directory and delete the generated resources.

Danger

Be careful with kubectl delete -k.

It deletes all resources generated from that Kustomize directory.

Delete Command Comparison

kustomize build k8s/ | kubectl delete -f -

kubectl delete -k k8s/

kustomize build k8s/

Review the output first so you know what will be deleted.

Production Workflow

A safe production workflow is:

kustomize build overlays/prod/

Review the output.

Then apply:

kubectl apply -k overlays/prod/

Verify:

kubectl get deployments
kubectl get services
kubectl get pods

Production Recommendation

Always preview production manifests before applying them, especially when overlays modify replicas, images, namespaces, labels, or security settings.

CI/CD Usage

In CI/CD pipelines, Kustomize is commonly used like this:

kustomize build overlays/prod/ > rendered.yaml
kubectl apply -f rendered.yaml

This gives you a saved copy of the rendered manifest.

Tip

Saving rendered YAML is useful for auditing, approvals, troubleshooting, and rollback investigation.

Best Practices for Kustomize Output

Recommended

  • Run kustomize build before applying changes
  • Use kubectl apply -k for normal deployment
  • Use kubectl delete -k carefully
  • Keep separate overlays for dev, stg, and prod
  • Validate rendered manifests in CI/CD
  • Store Kustomize configs in Git
  • Review production output before applying

Do's

  • Use kustomize build to preview generated YAML
  • Use kubectl apply -k for clean deployment
  • Use kubectl delete -k only when you are sure
  • Review resource names before deleting
  • Validate manifests before production rollout

Don'ts

  • Don't assume kustomize build deploys resources
  • Don't delete using -k without reviewing the target directory
  • Don't apply production overlays without checking rendered output
  • Don't mix unrelated apps in the same Kustomize directory
  • Don't store secrets directly in plain YAML

Common Mistakes

Mistake: Running only build

kustomize build k8s/

This only prints YAML. It does not deploy anything.

Mistake: Wrong directory

kubectl apply -k wrong-folder/

Make sure the directory contains a valid kustomization.yaml.

Mistake: Deleting the wrong overlay

kubectl delete -k overlays/prod/

This deletes production resources generated by that overlay.

Quick Reference

Task Command
Preview final YAML kustomize build k8s/
Apply using pipe kustomize build k8s/ \| kubectl apply -f -
Apply directly kubectl apply -k k8s/
Delete using pipe kustomize build k8s/ \| kubectl delete -f -
Delete directly kubectl delete -k k8s/

Summary

Quote

  • kustomize build generates final manifests only
  • It does not deploy anything by itself
  • Use kubectl apply -k to deploy Kustomize configs
  • Use kubectl delete -k to delete generated resources
  • In production, always preview and validate rendered YAML before applying

Summary

Quote

  • kustomization.yaml is the main Kustomize configuration file
  • It lists the resources Kustomize should manage
  • It defines transformations that should be applied
  • kustomize build renders final YAML but does not deploy it
  • Use kubectl apply -k to apply Kustomize manifests directly to a cluster