In this lesson, you will learn how to design a hierarchical GitOps repository structure that enables consistent, automated propagation of application changes across development, staging, and production environments using Kustomize overlays.
When managing complex deployments, the challenge is maintaining the balance between "Don't Repeat Yourself" (DRY) principles and the environmental uniqueness required for production. Instead of maintaining three completely separate manifest folders, we leverage a hierarchical overlay pattern. This structure centralizes your common base configuration while allowing environment-specific patches to flow downstream.
The Hierarchical Structure
Your repository should follow a clear directory hierarchy where a base folder defines the shared Kubernetes resources, and an overlays folder acts as the propagation engine:
├── base/
│ ├── deployment.yaml
│ └── service.yaml
└── overlays/
├── dev/
│ └── kustomization.yaml (refers to base + dev patches)
├── staging/
│ └── kustomization.yaml (refers to base + staging patches)
└── production/
└── kustomization.yaml (refers to base + prod patches)
In this setup, base contains the raw resources like ReplicaSet specs or ConfigMaps. The kustomization.yaml inside overlays/production then uses a patches strategy to swap out resource limits, ingress hostnames, or database connection strings.
Synchronization Logic
To orchestrate synchronization, your CI/CD pipeline treats the base as the "Source of Truth." When you push a change to the base directory, your GitOps controller (like ArgoCD or Flux) triggers a reconciliation loop that detects the new commit. Because each overlay inherits from this base, the controller automatically calculates the diff for all three environments simultaneously.
By defining your structure this way, you avoid "configuration drift" where staging and production inadvertently diverge due to manual edits. Promotion between environments is then simplified: you validate the change in dev, and the patch is promoted to staging and production by merging the updated patch files, ensuring the environment-specific differences are tracked with the same rigor as the application code itself.
Key Takeaway: Use a hierarchical overlay structure to treat your base configuration as the immutable source of truth, propagating changes to downstream environments through controlled, environment-specific patches.