Managing Multi-Environment Deployments with Kustomize

In the world of modern DevOps and Kubernetes-native application development, managing configuration for different environments, like development, staging, QA, and production, is a major challenge. These environments often require slightly different configurations: different numbers of replicas, different environment variables, different secrets, and maybe even different base images. Traditionally, managing this complexity meant maintaining multiple, often duplicate YAML files for each environment. This approach quickly becomes difficult to scale, prone to human error, and hard to audit.

Kustomize is a purpose-built solution that helps developers and DevOps teams manage these challenges in a cleaner, more efficient, and scalable way. It allows you to customize raw, template-free YAML files for multiple environments without duplicating configuration or relying on templating engines. By integrating seamlessly with kubectl and focusing on declarative management of Kubernetes resources, Kustomize provides an elegant, scalable, and lightweight solution for environment-specific configuration management.

In this blog, we’ll dive deep into how Kustomize works, how to structure your Kubernetes manifests for multi-environment deployments, how it compares to traditional methods, and why it has become a go-to tool for Kubernetes-native deployments. This guide is written for developers and DevOps engineers who want to adopt scalable Kubernetes configuration practices using Kustomize.

‍

What is Kustomize and Why Should Developers Care?

Kustomize is a configuration customization tool specifically designed for Kubernetes. Unlike other tools like Helm that rely on templating languages and values injection, Kustomize works directly on standard YAML manifests. This means your configuration files remain completely valid Kubernetes YAML files, and you can understand and apply them with basic kubectl commands.

Kustomize introduces a system of “bases” and “overlays” to allow you to define shared configurations in one place, then apply environment-specific changes without duplicating files. This allows teams to follow the DRY (Don't Repeat Yourself) principle, significantly reducing redundancy and the likelihood of configuration drift between environments.

It was added natively to kubectl in version 1.14, so no extra tooling or plugins are required to get started. All you need is kubectl apply -k, and Kustomize will handle the rest.

Why should developers care about Kustomize? Because it simplifies the complexity of deploying applications across multiple Kubernetes environments. Developers can focus on writing logical configurations instead of wrestling with template syntax. It also makes auditing easier, promotes reusability, improves consistency across deployments, and fits naturally into CI/CD and GitOps pipelines.

‍

The Core Concepts of Kustomize: Bases and Overlays

At the heart of Kustomize are two key concepts: bases and overlays.

• A base contains the common configuration shared across all environments. It typically includes the standard definitions for Kubernetes resources such as Deployments, Services, ConfigMaps, and Secrets.
  
  
• An overlay is a layer of customization that applies changes to the base configuration to fit a specific environment. For example, a dev overlay might reduce the number of replicas or change the container image to a non-production version.
  
  

This structure allows developers to manage multiple environments cleanly and predictably. By separating the generic configuration from the environment-specific configuration, Kustomize helps reduce redundancy, simplify updates, and improve maintainability across environments.

Let’s consider a directory structure that illustrates this pattern:

my-app/

├── base/

│   ├── deployment.yaml

│   ├── service.yaml

│   └── kustomization.yaml

└── overlays/

    ├── dev/

    │   ├── kustomization.yaml

    │   └── patch-deployment.yaml

    ├── staging/

    └── prod/

‍

Here, the base folder contains your generic configuration files. Each folder under overlays corresponds to a specific environment and includes its own kustomization.yaml file along with any patch files required to modify the base resources.

This organizational model not only brings clarity to your deployment workflows but also scales well for large teams or organizations managing many environments or services.

How to Use Kustomize in Practice: A Developer’s Workflow

Here’s how a typical developer might use Kustomize to manage multi-environment Kubernetes deployments:

1. Create a Base Configuration: Start by defining your core resources in the base/ folder. This includes your standard Deployment, Service, and ConfigMap files. Your base/kustomization.yaml should list all these resources using the resources: directive.
   
   
2. Add Common Transformations: You can add labels, name prefixes, or suffixes directly in the base’s kustomization.yaml file. This helps distinguish resources during deployment without modifying each file individually.
   
   

resources:

  - deployment.yaml

  - service.yaml

‍

commonLabels:

  app: myapp

namePrefix: myapp-

‍

3. Define Environment Overlays: For each environment (e.g., dev, staging, prod), create a corresponding folder in overlays/. Inside each, create a kustomization.yaml file and reference the base. Add any environment-specific patches here.
   
   

resources:

  - ../../base

‍

patchesStrategicMerge:

  - patch-deployment.yaml

‍

namespace: dev

commonLabels:

  environment: dev

‍

4. Patch Resources for the Environment: Modify base resources using patch files. This lets you change container images, replica counts, environment variables, etc., without editing the original YAML files.
   
   

apiVersion: apps/v1

kind: Deployment

metadata:

  name: myapp-deployment

spec:

  replicas: 2

  template:

    spec:

      containers:

      - name: myapp

        image: myapp:dev-latest

‍

5. Apply the Configuration: Use kubectl apply -k overlays/dev to deploy the application into the dev namespace. Kustomize builds the final configuration by merging the base and overlay.
   
   
6. Preview Before Applying: Always inspect the final YAML using kubectl kustomize overlays/dev to view the rendered output before deploying it. This ensures accuracy and prevents mistakes from slipping into production.
   
   

Powerful Built-in Features in Kustomize for Developers

Kustomize offers several powerful customization tools to help you manage complex Kubernetes configurations without sacrificing clarity:

• commonLabels: Automatically add labels to all resources, useful for grouping and monitoring.
  
  
• namePrefix / nameSuffix: Modify resource names dynamically to avoid conflicts between environments.
  
  
• ConfigMap and Secret Generators: Dynamically generate ConfigMaps and Secrets from files or literals. Kustomize even hashes the contents to force Kubernetes to restart pods when these values change.
  
  

configMapGenerator:

  - name: app-config

    files:

      - config.yaml

‍

secretGenerator:

  - name: db-credentials

    literals:

      - DB_USER=admin

      - DB_PASS=secret123

‍

• patchesStrategicMerge: Apply YAML fragments to modify existing resources in the base. This is ideal for updating replica counts, images, or resource limits.
  
  
• patchesJson6902: For more granular control, Kustomize supports JSON patches to precisely target individual fields.
  
  
• Replacements: Easily replace values in one resource using values from another. This is helpful when multiple components share a value such as a ConfigMap name or environment variable.
  
  

These features give developers the flexibility to maintain clean, DRY configurations while still adapting to the nuances of each deployment environment.

‍

How Kustomize Improves Over Traditional Methods

Before Kustomize, teams often managed multiple nearly-identical YAML files for each environment. This redundancy leads to several issues:

• Error-prone duplication: Changing a port or environment variable across environments could result in inconsistencies.
  
  
• Difficult maintenance: Making updates required touching multiple files, increasing the chance of human error.
  
  
• Hard to audit: It's challenging to understand what differs between dev and prod if the files are independent.
  
  

Kustomize solves these problems by keeping the common configuration centralized and pushing differences into lightweight overlays. This way, you update once in the base, and changes are inherited across environments.

Compared to templating tools like Helm, Kustomize avoids introducing an additional abstraction layer. It doesn’t require a special syntax or learning curve beyond standard Kubernetes YAML. Developers can reason about configuration changes directly from the source, which improves transparency and makes debugging easier.

‍

Best Practices When Using Kustomize in Large Projects

• Organize by Feature or Service: For microservices, maintain separate base/overlay folders per component (e.g., backend, frontend, worker). This modular approach keeps things maintainable.
  
  
• Use Component Reuse: Kustomize supports components, reusable pieces of configuration that can be shared across overlays. For example, a standard resource limits patch can be reused in dev, staging, and prod.
  
  
• Isolate Namespaces Per Environment: Always specify the namespace in overlays. This ensures resources don't conflict and gives you better access control.
  
  
• Document Your Overlays: Explain why certain patches exist, especially when overriding security settings, image tags, or environment variables.
  
  
• Validate Outputs: Regularly review kubectl kustomize output to audit changes. Consider using policy tools like kubeval or conftest to lint configurations automatically.
  
  

Integration with GitOps and CI/CD

Kustomize is especially powerful when integrated into GitOps workflows or CI/CD pipelines:

• In GitOps, overlays map neatly to Git branches or folders. ArgoCD or Flux can track changes and apply them automatically.
  
  
• In CI/CD, a deployment job can run:
  
  

kustomize build overlays/staging | kubectl apply -f -

‍

This allows you to codify deployments and continuously deliver changes to environments safely and predictably.

Kustomize’s YAML-as-code approach makes it easy to version control everything, review changes in pull requests, and promote changes through environments using Git history.

‍

Why Kustomize is Loved by Developers

Developers love Kustomize because it is:

• Simple: Works with plain YAML, no need to learn a new templating language.
  
  
• Safe: Centralizes changes, reduces duplication, and prevents misconfigurations.
  
  
• Scalable: Easily manage dozens or hundreds of environments or services.
  
  
• Git-friendly: Everything is file-based and easy to version control.
  
  
• CI/CD-ready: Works in any pipeline, with native support in kubectl.
  
  

In short, Kustomize helps developers take control of Kubernetes configuration and ship applications with confidence across multiple environments.