atelier/domains/gitops-operators/argocd.md

ArgoCD — Derived Rules

Derives from domains/gitops-operators/first-principles.md. Applies P1–P10 to ArgoCD specifically. For the ArgoCD-vs-Flux decision, see the decision matrix at the end of this doc and in flux.md.

What ArgoCD Is (P1 Git is the Source of Truth, P3 Pull, Don't Push)

• ArgoCD is a pull-based GitOps controller for Kubernetes. It runs inside the target cluster, pulls desired state from git, and reconciles the cluster to match. CI never holds kubectl rights against the cluster (P3).
• An Application is a declarative binding of "this git path" to "this cluster destination." The Application CRD is the unit of reconciliation. The cluster is a derivative of git, never the authority (P1).
• ArgoCD supports Helm charts, Kustomize overlays, ksonnet, and raw manifests as source formats — see domains/kubernetes/helm.md and domains/kubernetes/kustomize.md.

Application CRD (P2 Declarative Over Imperative, P4 Continuous Reconciliation)

• An Application declares source (repo, path, revision, chart), destination (server, namespace), and syncPolicy. The reconciler loops continuously; drift is corrected automatically, not on-demand (P4).

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: payments-api
  namespace: argocd
spec:
  source:
    repoURL: https://git.example.com/platform/payments
    targetRevision: 1.2.3
    path: manifests/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: payments
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=false

• automated.prune: true deletes resources removed from git. selfHeal: true corrects hand-edited drift back to git (P8). Disable both for workloads that need manual approval gates.

App-of-Apps (P6 Operators Encode Domain Knowledge, C6 Composability)

• The App-of-Apps pattern: one root Application points at a git directory of child Application manifests. The root app reconciles the children; the children reconcile the workloads. This is the ArgoCD expression of composition — a fleet of apps as a tree of Applications.
• Use App-of-Apps for cluster bootstrapping (one repo, many clusters, many apps). Do not use it as a substitute for a package manager; if you are templating hundreds of near-identical Applications, use a generator (ApplicationSet) instead.

Sync Waves and Hooks (P4 Continuous Reconciliation, P7 Reversibility)

• Sync waves order resources within a sync: PreSync → Sync → PostSync. Use waves to run a job before a Deployment, or a migration before the app that depends on it.
• Sync hooks (PreSync, Sync, PostSync, SyncFail) are Resources annotated to execute at a wave boundary. A SyncFail hook runs on sync failure — the abort path (P7).
• Wave ordering is a correctness mechanism, not a performance one. Mis-ordered waves (e.g., app starts before its migration job) are a correctness bug.

Health and Status (P9 Failure is Observable and Surfaced)

• ArgoCD assesses every resource's health (Healthy, Progressing, Degraded, Missing, Suspended) and surfaces the aggregate as Application status. Sync status (Synced, OutOfSync) reports drift against git.
• Health checks are pluggable via Lua scripts for custom CRDs. An Operator-managed CRD without a health check reads as Progressing forever — write one (see operators.md).
• Out-of-sync or degraded status must emit a notification (Slack, PagerDuty, webhook). Silent drift is the bug (P9). Wire status to domains/observability/metrics.md.

Diff and Drift (P8 Reconcile, Don't Mutate by Hand, P4)

• argocd app diff shows the diff between git and live cluster. A non-empty diff on a synced app is hand-edit drift — the recovery is selfHeal, not a manual kubectl apply (P8).
• Drift detection runs continuously (P4). The gap between "git changed" and "cluster matches git" is observable, not assumed.

RBAC and SSO (P10 Least Privilege Reconciliation)

• ArgoCD's own RBAC governs who can view, sync, and admin Applications. Bind to SSO (OIDC, SAML) for human identity; bind the controller's service account to a Role scoped to the namespaces it reconciles.
• The controller's credentials must not be cluster-admin (P10). Use namespace-scoped Roles via ApplicationSet namespaces or cluster-wide AppProject restrictions. See domains/kubernetes/rbac.md and domains/security/authorization.md.
• AppProjects bound the blast radius of what an Application can deploy (allowed repos, destinations, roles). One AppProject per team or environment; the default project is for nothing in production.

Multi-Cluster (P4 Locality, P10)

• ArgoCD registers external clusters by secret. The controller pulls from git and pushes to the registered cluster's API server. The "pull, don't push" boundary (P3) is between the target cluster's reconciler and CI — the controller-to-apiserver hop is internal to the platform.
• Scope each registered cluster's credentials to the namespaces ArgoCD manages there. Do not register a cluster with cluster-admin and call it done (P10).

Sync Windows (P5 Reversibility, P7)

• Sync windows restrict when automated sync runs (e.g., no syncs during business hours, or syncs only in a maintenance window). They are a reversibility mechanism: a bad commit lands in git, but the sync window holds it until review.
• Sync windows do not replace health monitoring (P9). A degraded app inside a window is still an incident.

Secrets (P10, cross-link security/secrets)

• Do not store raw Secrets in the GitOps repo. Use a sealed-secret controller (Bitnami Sealed Secrets, SOPS, External Secrets Operator) so the git store holds encrypted material only. See domains/security/secrets.md for the general secret-hygiene principles.

ArgoCD vs Flux — Decision Matrix (IDEATE-21, D-039)

Axis	ArgoCD	Flux
Architecture	Monolithic controller + Application CRD	Composable GitOps Toolkit controllers (source, kustomize, helm, notification)
Reconciliation unit	Application (one CRD per app)	Kustomization / HelmRelease (one per deploy unit)
UI	Web UI + CLI (full dashboard, tree view, diff viewer)	CLI-first; UI via Weave GitOps or FluxUI (add-on)
Sync model	Periodic poll or webhook; sync waves + hooks	Poll + webhook; runs continuously, no explicit sync waves
Multi-cluster	One ArgoCD manages many clusters (hub-and-spoke)	One Flux per cluster (per-cluster autonomy)
Templating in repo	Helm, Kustomize, ksonnet, raw manifests, Jsonnet	Helm, Kustomize, raw manifests
RBAC	Built-in RBAC + SSO + AppProjects	Kubernetes RBAC (no built-in RBAC layer)
Progressive delivery	Argo Rollouts (sister project, tight integration)	Flagger (sister project, tight integration)
Best for	Teams wanting a UI, multi-cluster from one pane, App-of-Apps bootstrapping	Teams wanting composable controllers, per-cluster autonomy, minimal footprint
Watch out for	Monolithic controller scaling, UI as ops crutch, AppProject sprawl	No native UI, steeper learning curve, manual multi-cluster orchestration

• Use ArgoCD when you want a UI, central multi-cluster management, and sync-wave ordering. Use Flux when you want composable controllers, per-cluster autonomy, and a minimal footprint.
• Both are CNCF graduated and both implement the OpenGitOps principles. The choice is architectural fit, not correctness. See flux.md for the Flux-side perspective.

What Violates ArgoCD Discipline

Violation	Principle
CI pipeline with kubectl rights pushing to the cluster	P3 Pull, Don't Push
argocd app set used as the steady state instead of git	P1 Git is the Source of Truth
selfHeal: false on a prod app with no manual gate	P8 Reconcile, Don't Mutate by Hand
Controller ServiceAccount bound to cluster-admin	P10 Least Privilege Reconciliation
Sync failure with no notification wired	P9 Failure is Observable and Surfaced
AppProject with no destination restrictions in prod	P10 Least Privilege Reconciliation
Raw Secret in the GitOps repo	P10, domains/security/secrets.md
Manual kubectl edit on an ArgoCD-managed resource	P8 Reconcile, Don't Mutate by Hand