Introduction

Kubernetes workloads almost always need environment-specific configuration. The important part is not just storing different values for dev, staging, and production, but doing it in a way that avoids copy-paste manifests drifting apart over time.

Start with a shared base

Most teams should keep one common base manifest for what stays the same across environments:

• deployment shape
• service definitions
• probes
• core labels

Then add environment-specific overrides for things like replica counts, image tags, resource limits, feature flags, and external service URLs.

This is much safer than keeping three nearly identical folders that gradually diverge.

Kustomize overlays are a strong default

Kustomize is built for exactly this use case. You define a base and then overlays per environment.

Base kustomization.yaml:

resources:
  - deployment.yaml
  - service.yaml

Production overlay:

1resources:
2  - ../../base
3
4replicas:
5  - name: my-app
6    count: 4
7
8configMapGenerator:
9  - name: app-config
10    literals:
11      - ENVIRONMENT=production
12      - LOG_LEVEL=info

Then apply it:

kubectl apply -k overlays/production

That keeps shared configuration centralized while still letting each environment differ where it should.

Helm values are another common pattern

If you already use Helm, the equivalent idea is environment-specific values files.

1# values-production.yaml
2replicaCount: 4
3image:
4  tag: "1.2.3"
5appConfig:
6  environment: production
7  logLevel: info

Deploy with:

helm upgrade --install my-app ./chart -f values-production.yaml

Helm is especially useful when the configuration surface is large and already templated.

Use ConfigMaps and Secrets for data, not duplicate manifests

Environment-specific data such as URLs, feature flags, and API endpoints usually belong in ConfigMaps or Secrets rather than hard-coded inline in the deployment spec.

That lets the workload template stay largely the same while values vary by environment.

Remember the split:

• ConfigMap for non-sensitive configuration
• Secret for sensitive configuration

Do not put secrets into plain environment-specific YAML just because it is convenient.

Typical environment differences

Real environment overrides commonly include:

• image tag or image repository
• replica count
• resource requests and limits
• ingress hostnames
• ConfigMap and Secret values
• autoscaling thresholds

Those are legitimate differences. The structure of the application deployment should usually change much less than the values it consumes.

Keep environment selection explicit

Avoid "magic" behavior where manifests detect the environment implicitly. Make the target environment explicit in your deployment command or CI pipeline so it is always obvious which configuration is being applied.

That makes review and troubleshooting much easier.

Make the rendered output easy to inspect

Whatever tool you use, keep it easy to render and review the final manifests before deployment. Comparing the generated dev and production output catches a surprising number of mistakes, especially around image tags, replica counts, and referenced ConfigMaps or Secrets.

Common Pitfalls

• Copying full manifests per environment and letting them drift independently.
• Mixing secrets into plain ConfigMaps or committed YAML files.
• Making environment differences implicit instead of explicit in deployment tooling.
• Overriding too much per environment and losing the benefit of a shared base.
• Using a templating tool without a clear convention for what belongs in base versus override values.

Summary

• Keep a shared base manifest and layer environment-specific overrides on top.
• Kustomize overlays and Helm values files are the two most common ways to do this.
• Put varying configuration data in ConfigMaps and Secrets rather than duplicating whole manifests.
• Make environment selection explicit in your deploy process.
• The goal is controlled differences, not separate manifest ecosystems for every environment.