> For the complete documentation index, see [llms.txt](https://dinush-chathurya.gitbook.io/kustomize-e-book/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dinush-chathurya.gitbook.io/kustomize-e-book/production-ready-practices/14-enterprise-gitops-with-kustomize.md).

# Enterprise GitOps with Kustomize

GitOps at enterprise scale requires robust workflows, strict controls, and clear promotion paths. In this chapter, we’ll explore patterns and practices for running Kustomize-based GitOps pipelines across large organizations.

***

## GitOps Principles at Scale

1. **Single Source of Truth**\
   All environments, applications, and policies live in Git.
2. **Automated Promotion**\
   Changes flow through environments (Dev → Staging → Prod) via pull requests.
3. **Immutable History**\
   Every change is recorded, auditable, and reversible.
4. **Self-Healing**\
   Controllers (e.g., ArgoCD) detect and correct drift automatically.

***

## Monorepo vs Polyrepo

| Strategy | Description                                       | Pros                                             | Cons                                               |
| -------- | ------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
| Monorepo | One repo holds all apps and environment overlays. | Easier cross-team coordination; single pipeline. | Can grow large; harder to delegate access.         |
| Polyrepo | Separate repos per app or environment.            | Fine-grained access control; smaller repos.      | More pipelines to manage; cross-repo dependencies. |

***

## Promotion Workflows

### Branch-Based Promotion

1. **`main`** = Prod
2. **`staging`** → merged into `main` on approval
3. **`dev`** → merged into `staging` after CI tests

Every merge triggers ArgoCD to sync the target environment.

### Pull-Request-Based Promotion

* Dev team opens PR against `staging` overlay
* QA reviews and approves → merge
* Automated CI runs integration tests
* Merge to `staging` triggers ArgoCD sync
* After validation, Ops opens PR from `staging` to `prod`

***

## Environment Isolation & Access Control

* **Git Branch Protections**: Require reviewers on `staging`/`prod` branches.
* **ArgoCD Projects**: Map Git repos/namespaces to specific teams.
* **RBAC Policies**: Limit who can sync or override in each project.
* **Namespace Separation**: Each application/environment in its own namespace.

***

## Drift Detection & Automated Remediation

* **ArgoCD Self-Heal**: Enable `selfHeal` in `syncPolicy`.
* **Notifications**: Alerts on drift via Slack/Teams integrations.
* **Automated PRs**: Use bots (e.g., Renovate) to update base images or configurations, triggering tests and promotions.

***

## Compliance & Audit

* **Immutable Tags/Digests**: Always pin image digests in overlays.
* **Signed Commits**: Enforce GPG-signed commits on protected branches.
* **Policy as Code**: Integrate OPA/Gatekeeper constraints in GitOps pipeline.
* **Audit Logs**: Maintain logs of GitOps actions, diff outputs, and manual interventions.

***

## Best Practices

* **Keep Overlays Small**: Only environment-specific patches in overlays; share logic in base.
* **Reusable Components**: Publish common Kustomize “components” across teams (e.g., logging, monitoring).
* **Automate Everything**: From PR linting to deployment and rollback.
* **Document Clearly**: Maintain `README.md` in each repo explaining workflow and folder structure.
* **Periodic Reviews**: Audit GitOps configs quarterly to remove drift or unused resources.

***

## Summary

Enterprise-grade GitOps with Kustomize combines disciplined repository strategies, gated promotions, and automated remediation to deliver secure, auditable, and scalable Kubernetes deployments. By adopting these patterns, large organizations can empower multiple teams to ship confidently and consistently.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://dinush-chathurya.gitbook.io/kustomize-e-book/production-ready-practices/14-enterprise-gitops-with-kustomize.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.