Teams should keep per-cluster configuration in separate, version-controlled overlays or parameter files, so the base manifest stays consistent while only approved values change. The usual pattern is a shared template with cluster-specific values for namespaces, replicas, ingress, or feature flags, validated before merge. That avoids copy-and-paste drift and makes promotion differences explicit.
How to Structure Per-Cluster Values Without Forking the Base Manifest
Per-cluster configuration should stay small, explicit, and easy to diff. The shared manifest defines the workload once, while cluster overlays or parameter files carry only the settings that genuinely vary, such as replica counts, ingress hosts, namespaces, or feature flags. That keeps promotion predictable and makes it clear which changes are environment-specific rather than application changes.
A clean overlay model also helps teams avoid accidental drift between clusters. When values are isolated from the base, reviewers can see whether a change is a local exception or a reusable default. If the configuration pattern starts to accumulate repeated patches, it is usually a sign that the base should be refactored or that the cluster split is carrying more policy than it should.
For teams adopting GitOps at scale, the practical goal is not to create more files, but to make the configuration boundary obvious. A well-structured repo should answer two questions at a glance: what is common across clusters, and what is intentionally different. GitOps Security Guide is a useful reference for the surrounding security model, including repository credentials, drift control, and multi-tenancy considerations.
Why Per-Cluster Overlays Reduce Drift and Deployment Surprises
Per-cluster overlays reduce the risk of hidden divergence because the differences are expressed in version control instead of being recreated by hand in each environment. That matters when a cluster needs a different ingress controller, resource limit, or feature gate, because the exception is then reviewable and repeatable. It also gives operators a stable baseline for promotion, rollback, and incident review.
This pattern works best when teams treat overlays as a narrow exception layer rather than a place to accumulate unrelated changes. If the overlay begins to carry business logic, copied manifests, or ad hoc patches, it becomes harder to reason about rollout safety and much easier to miss a bad default. Good GitOps hygiene depends on keeping the base manifest reusable and the override surface deliberately small.
Validation before merge is part of that safety boundary. The goal is to catch malformed values, unsupported combinations, and environment-specific assumptions before they reach the controller. That is especially important when the same application is deployed to clusters with different capacity, network policy, or trust boundaries.
For the control baseline behind this approach, NIST SP 800-53 Rev 5 Security and Privacy Controls is relevant because configuration management and system integrity both depend on controlled, reviewable changes.
What Good Per-Cluster GitOps Practice Looks Like in Review and Promotion
Good practice is to make cluster-specific values obvious in code review, not buried in generated output or environment-specific scripts. Reviewers should be able to confirm that the overlay changes only the intended fields and that the base template still represents the desired application shape. That is the difference between a controlled promotion and an untracked fork.
Teams should also decide which settings are allowed to vary by cluster and which must stay fixed everywhere. If a value changes operational behavior, such as a replica count or ingress endpoint, it should be explicitly allowed and documented. If it changes application semantics, such as a feature flag or a policy-sensitive toggle, it deserves closer review because the cluster boundary is now affecting runtime behavior.
One useful discipline is to keep the override mechanism consistent across repositories, so operators and reviewers do not need to relearn the layout for every service. Consistency in file naming, directory structure, and value precedence makes it easier to detect accidental edits and easier to automate policy checks.
The broader operational principle is aligned with CISA Secure by Design, which favours secure defaults, predictable configuration, and reduction of unnecessary variation.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
NIST SP 800-53 Rev 5 and CIS Controls v8 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | CM-2 — Baseline Configuration | Per-cluster overlays depend on controlled baselines and explicit deviations. |
| CM-3 — Configuration Change Control | GitOps promotion and merge review are configuration changes that need approval and traceability. | |
| SI-7 — Software, Firmware, and Information Integrity | Validated manifests reduce the chance that unsafe or unintended config reaches runtime. | |
| Recommendation — Define a baseline manifest and track cluster-specific deviations as controlled exceptions. Require review and approval for overlay changes before they reach a cluster. Validate rendered configuration before deployment to catch integrity-breaking changes. | ||
| CIS Controls v8 | 5 — Account Management | GitOps repo and cluster access should be limited to approved operators and automation. |
| 16 — Application Software Security | Per-cluster values affect deployment safety and should be tested like application changes. | |
| Recommendation — Restrict who can change overlays, templates, and deployment credentials. Test configuration changes in CI before promoting them to production clusters. | ||
Practitioner Guidance
What to verify: Before promotion, verify that each cluster overlay changes only the fields it is meant to own, and that those fields are the same ones enforced by your review and admission checks. If a cluster-specific file contains broad edits outside the expected parameters, treat that as a design smell rather than a routine exception.
Common mistake: The most common failure is using per-cluster files as a convenience layer for one-off fixes, which slowly turns a clean GitOps model into a hidden branching strategy. Once that happens, drift becomes normalised and the repo no longer tells the truth about what is deployed.
Decision rule: If a setting differs because the cluster itself is different, keep it in the overlay. If it differs because the application is being changed, move it back into the base manifest and promote it through the normal release path.
Practitioner takeaway: Per-cluster configuration should express controlled exception, not local invention, because the value of GitOps is preserving one trusted source of truth while making every deliberate deviation visible.
Related resources from NHI Mgmt Group
- How should security teams handle Snowflake configuration recovery after mistakes or incidents?
- How should security teams handle secrets exposure caused by configuration drift?
- Why do DLP programs fail when organisations handle GDPR as a one-time configuration exercise?
- Why do AI coding agents create new risk when they are allowed to handle application infrastructure and configuration?
Deepen Your Knowledge
Free weekly newsletter
Subscribe to the NHI & AI Identity Journal
The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.
Bonus 33% off our NHI Course when you subscribe.
Reviewed and updated by the NHIMG editorial team on November 6, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org