Skip to main content

ADR 0001: GitOps Engine for Kubernetes

Historical ADR

This ADR is preserved as a historical Kubernetes-specific decision from the earlier golden path. It does not define the universal production operations model. For current production ownership boundaries, use Anchor Handoff.

Status​

Accepted

Context​

We need a standard GitOps engine for Kubernetes environments that can reconcile ops repo intent to clusters, support multi-environment separation, and provide an audit trail.

The requirements include:

  • Pull-based GitOps model (cluster pulls from Git)
  • Multi-environment support (dev, staging, prod)
  • Declarative application definitions
  • Audit trail and rollback capabilities
  • Visual UI for deployment status
  • Active community and enterprise support

Decision​

Adopt Argo CD as the default GitOps engine for Kubernetes environments.

Argo CD provides:

  • Native Kubernetes resource reconciliation
  • Application and App-of-Apps patterns for multi-environment management
  • Built-in RBAC and SSO integration
  • Web UI for visualization
  • Automated sync and health status
  • Strong CNCF ecosystem support

Consequences​

Positive​

  • Ops repo changes are reconciled by Argo CD in a pull-based model
  • Argo CD Application or App-of-Apps patterns are used per environment
  • Provides clear visibility into deployment status
  • Audit trail is maintained through Git history and Argo CD logs
  • Rollback is simplified through Git revert

Negative​

  • Learning curve for teams new to Argo CD
  • Additional infrastructure component to maintain
  • Requires cluster-level permissions for Argo CD installation

Neutral​

  • Teams can still use Flux in exceptional cases, but Argo CD is the golden path
  • Training materials and runbooks need to be created
  • Monitoring and alerting should be configured for Argo CD health