Implementing Environment-Specific Configuration Overlays

Use Kustomize to inject environment-specific variables and resource constraints into base manifests without duplicating core application code.

In this lesson, you will learn how to maintain a single source of truth for your application manifests while applying environment-specific overrides using Kustomize.

As you progress through your GitOps journey, you've likely realized that while the core application logic (images, container ports, labels) remains the same across environments, operational parameters like resource constraints, replica counts, and environment variables must differ between dev, staging, and production. Manually duplicating these YAML files leads to "configuration drift," where your environments gradually diverge in ways that are difficult to track or audit.

The Kustomize Pattern: Base and Overlays

Kustomize solves this by separating your configuration into two distinct layers:

The Base: A directory containing your "common" manifests that define the core of your application.
The Overlays: Separate directories for each environment (e.g., overlays/prod/) that contain only the specific patches or modifications required for that environment.

Instead of copying the full deployment manifest, your overlay simply tells Kustomize what to change. For instance, to increase memory limits for a production environment without touching the base, you define a kustomization.yaml in your prod folder:

# overlays/prod/kustomization.yaml
resources:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      - op: replace
        path: /spec/template/spec/containers/0/resources/limits/memory
        value: 2Gi

When Kustomize runs, it effectively "renders" the final manifest by merging the base with your specific patch. This ensures that if you decide to change the container image version, you update the base once, and that change propagates cleanly to all environments simultaneously. By keeping your configuration declarative and hierarchical, you eliminate the need for complex templating engines and ensure that your GitOps pipeline is strictly auditing the differences between environments rather than entire file sets.

Key Takeaway: Use Kustomize overlays to apply targeted patches to a shared base configuration, ensuring your environment differences are explicit, minimal, and easily auditable within your GitOps workflow.