In this lesson, you will learn how to design a hierarchical Git repository structure that enables reliable, automated promotion of applications across environments using the "Base and Overlay" pattern.
The Hierarchical Structure
When managing Kubernetes deployments via GitOps, the challenge is maintaining a balance between consistency and customization. We avoid duplicating code by separating the static "Base" configuration (common to all environments) from environment-specific "Overlays" (patches for staging, production, etc.).
A standard directory structure looks like this:
/manifests
├── base/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── kustomization.yaml
└── overlays/
├── staging/
│ ├── replica-count.yaml
│ └── kustomization.yaml
└── production/
├── ingress-tls.yaml
└── kustomization.yaml
How Promotion Works
The base/ directory contains the core application manifest. The overlays/ folder acts as the environment-specific layer. Inside overlays/staging/kustomization.yaml, you reference the base and apply specific patches (e.g., lower CPU limits or different environment variables).
When you are ready to promote code from staging to production, you aren't "moving" code; you are moving the version reference. By updating the image tag or configuration in the production/kustomization.yaml file, you trigger the GitOps controller's reconciliation loop. Because the production overlay inherits from the same base, you are mathematically guaranteed that the underlying deployment manifest remains identical to what was validated in staging, minus your intended environment-specific changes.
Why This Matters
This structure turns environment promotion into a declarative process. Instead of running imperative commands to change settings, you create a Pull Request that modifies an overlay. This ensures the Git history provides a clear audit trail of exactly what changed, when it was promoted, and why. By separating base logic from environment specifics, you minimize the "drift" that often occurs when manual, environment-specific tweaks are applied during troubleshooting.
Key Takeaway: Use a base-and-overlay architecture to ensure that your environment-specific configurations are modular, auditable, and derived from a single, consistent source of truth.