CGOA cheat sheet

Desired state: the declarative, versioned specification of what the system should look like; stored in Git and treated as the single source of truth.

Actual state (live state): what is currently running in the target environment, observed by the reconciler via cluster APIs or cloud provider APIs.

Reconciliation (sync): the continuous loop that compares desired state to actual state and applies or reverts changes so the two converge.

Drift: any divergence between actual state and desired state, whether caused by manual edits, external controllers, or failed applies.

Reconciler/agent (e.g., Argo CD application controller, Flux kustomize-controller): the component that pulls desired state and pushes it into the environment.

Source of truth: the Git repository (branch, path, commit SHA) plus any referenced artifacts (Helm charts, OCI images, Kustomize overlays) that define desired state.

Environment/promotion: a target (dev, staging, prod) whose desired state is a specific ref or overlay; promotion is changing which ref/overlay an environment tracks.

Health/sync status: sync status compares revision and resource state (Synced/OutOfSync); health status reports whether workloads are actually running (Healthy/Degraded/Progressing).

Prune and self-heal: prune deletes live resources no longer present in desired state; self-heal reverts manual drift back to the declared spec.

Declarative: the entire desired state is expressed declaratively, so the system can be reconstructed from the description alone without imperative steps.

Versioned and immutable: desired state is stored in a source that keeps full history (Git commits, tags, immutable image digests) so any past state is reproducible.

Pulled automatically: software agents pull desired state from the source rather than external systems pushing changes into the cluster.

Continuously reconciled: agents continuously observe actual state and act to converge it toward desired state, correcting drift without human intervention.

Single source of truth: exactly one canonical store defines desired state; all changes flow through it, not through direct cluster mutation.

Change via pull/merge request: modifications are proposed as commits, reviewed, and merged, giving an auditable approval trail and rollback by revert.

Git as the audit log: commit history, authors, and approvals provide provenance for every deployed change without a separate deployment database.

Reconciliation is idempotent and converging: repeating the loop on an already-converged system produces no changes, and partial failures are retried until convergence.

CI vs CD split: CI builds and tests artifacts and publishes immutable images; GitOps CD takes the published artifact reference and reconciles it into environments.

Infrastructure as Code: Terraform, Pulumi, or Crossplane declare infrastructure; GitOps can reconcile IaC outputs or use controllers that own cloud resources directly.

Progressive delivery: canary, blue/green, and feature flags control blast radius; GitOps handles the desired-state change while the delivery controller handles traffic shifting.

Policy as Code: OPA/Gatekeeper, Kyverno, or Conftest validate manifests in CI and admission control enforces constraints at reconcile time.

Secrets management: SOPS, Sealed Secrets, External Secrets Operator, or Vault inject secrets; plaintext secrets never belong in Git.

Observability and SLOs: metrics, logs, and traces verify that reconciled state is healthy; health checks feed back into sync/health status and rollback decisions.

Supply chain security: signed images (cosign/Sigstore), SBOMs, and admission verification ensure only trusted artifacts reach the cluster.

Environment promotion and release management: same artifact promoted across environments via PRs to overlay repos, with change freeze and approval gates encoded as policy.

Repo-per-environment vs repo-per-team: separate repos give isolation and access control; a monorepo with path-based overlays simplifies atomic cross-environment changes.

App-of-apps (Argo CD) / hierarchical composition (Flux): a root application points to a directory of child Applications or Kustomizations, enabling bootstrap and fan-out.

Environment branches vs directory overlays: branches isolate promotion but merge conflicts grow; directories with Kustomize overlays or Helm values files are the more common pattern.

Pull request promotion: change image tag or overlay in a PR, get review and policy checks, merge, and the reconciler deploys; revert is a Git revert.

Image automation (Flux image-reflector/image-automator) or Argo CD Image Updater: controllers commit updated tags or digests back to Git when new images appear.

Multi-cluster fleet management: a management cluster reconciles many target clusters; credentials and cluster registration are themselves declared as resources.

Disaster recovery / cluster rebuild: because desired state is fully declarative and versioned, a lost cluster is recreated by pointing a new reconciler at the same source.

Drift detection and self-heal modes: choose automated sync with prune/self-heal for prod convergence, or manual sync for gated approval; alert on OutOfSync as a signal.

Argo CD: Kubernetes-native GitOps controller with Application CRD, UI, sync waves/hooks, app-of-apps, and multi-cluster management; supports Helm, Kustomize, plain YAML, Jsonnet.

Flux (v2): GitOps toolkit of composable controllers - source-controller, kustomize-controller, helm-controller, notification-controller, image automation - driven by GitRepository and Kustomization CRs.

Kustomize: template-free overlay tool built into kubectl; bases plus overlays patch manifests per environment; native to Argo CD and Flux.

Helm: package manager using charts and values; GitOps tools render charts at reconcile time or you commit rendered manifests for full auditability.

Jenkins X, Tekton, GitHub Actions, GitLab CI: CI systems that build/test images and open promotion PRs; they do not own cluster reconciliation in a GitOps model.

OpenGitOps / CNCF: the OpenGitOps project publishes the four GitOps principles; Argo CD and Flux are CNCF projects commonly used as reference implementations.

Secrets tooling: SOPS with age/KMS, Sealed Secrets, External Secrets Operator, and Vault integrate with reconcilers to inject secrets without storing plaintext in Git.

Policy and validation: Kyverno, OPA Gatekeeper, and Conftest validate manifests in CI or at admission; Argo CD and Flux expose health/sync metrics for alerting.

Desired state: the declarative, versioned specification of what the system should look like; stored in Git and treated as the single source of truth.

Actual state (live state): what is currently running in the target environment, observed by the reconciler via cluster APIs or cloud provider APIs.

Reconciliation (sync): the continuous loop that compares desired state to actual state and applies or reverts changes so the two converge.

Drift: any divergence between actual state and desired state, whether caused by manual edits, external controllers, or failed applies.

Reconciler/agent (e.g., Argo CD application controller, Flux kustomize-controller): the component that pulls desired state and pushes it into the environment.

Source of truth: the Git repository (branch, path, commit SHA) plus any referenced artifacts (Helm charts, OCI images, Kustomize overlays) that define desired state.

Environment/promotion: a target (dev, staging, prod) whose desired state is a specific ref or overlay; promotion is changing which ref/overlay an environment tracks.

Health/sync status: sync status compares revision and resource state (Synced/OutOfSync); health status reports whether workloads are actually running (Healthy/Degraded/Progressing).

Prune and self-heal: prune deletes live resources no longer present in desired state; self-heal reverts manual drift back to the declared spec.

Declarative: the entire desired state is expressed declaratively, so the system can be reconstructed from the description alone without imperative steps.

Versioned and immutable: desired state is stored in a source that keeps full history (Git commits, tags, immutable image digests) so any past state is reproducible.

Pulled automatically: software agents pull desired state from the source rather than external systems pushing changes into the cluster.

Continuously reconciled: agents continuously observe actual state and act to converge it toward desired state, correcting drift without human intervention.

Single source of truth: exactly one canonical store defines desired state; all changes flow through it, not through direct cluster mutation.

Change via pull/merge request: modifications are proposed as commits, reviewed, and merged, giving an auditable approval trail and rollback by revert.

Git as the audit log: commit history, authors, and approvals provide provenance for every deployed change without a separate deployment database.

Reconciliation is idempotent and converging: repeating the loop on an already-converged system produces no changes, and partial failures are retried until convergence.

CI vs CD split: CI builds and tests artifacts and publishes immutable images; GitOps CD takes the published artifact reference and reconciles it into environments.

Infrastructure as Code: Terraform, Pulumi, or Crossplane declare infrastructure; GitOps can reconcile IaC outputs or use controllers that own cloud resources directly.

Progressive delivery: canary, blue/green, and feature flags control blast radius; GitOps handles the desired-state change while the delivery controller handles traffic shifting.

Policy as Code: OPA/Gatekeeper, Kyverno, or Conftest validate manifests in CI and admission control enforces constraints at reconcile time.

Secrets management: SOPS, Sealed Secrets, External Secrets Operator, or Vault inject secrets; plaintext secrets never belong in Git.

Observability and SLOs: metrics, logs, and traces verify that reconciled state is healthy; health checks feed back into sync/health status and rollback decisions.

Supply chain security: signed images (cosign/Sigstore), SBOMs, and admission verification ensure only trusted artifacts reach the cluster.

Environment promotion and release management: same artifact promoted across environments via PRs to overlay repos, with change freeze and approval gates encoded as policy.

Repo-per-environment vs repo-per-team: separate repos give isolation and access control; a monorepo with path-based overlays simplifies atomic cross-environment changes.

App-of-apps (Argo CD) / hierarchical composition (Flux): a root application points to a directory of child Applications or Kustomizations, enabling bootstrap and fan-out.

Environment branches vs directory overlays: branches isolate promotion but merge conflicts grow; directories with Kustomize overlays or Helm values files are the more common pattern.

Pull request promotion: change image tag or overlay in a PR, get review and policy checks, merge, and the reconciler deploys; revert is a Git revert.

Image automation (Flux image-reflector/image-automator) or Argo CD Image Updater: controllers commit updated tags or digests back to Git when new images appear.

Multi-cluster fleet management: a management cluster reconciles many target clusters; credentials and cluster registration are themselves declared as resources.

Disaster recovery / cluster rebuild: because desired state is fully declarative and versioned, a lost cluster is recreated by pointing a new reconciler at the same source.

Drift detection and self-heal modes: choose automated sync with prune/self-heal for prod convergence, or manual sync for gated approval; alert on OutOfSync as a signal.

Argo CD: Kubernetes-native GitOps controller with Application CRD, UI, sync waves/hooks, app-of-apps, and multi-cluster management; supports Helm, Kustomize, plain YAML, Jsonnet.

Flux (v2): GitOps toolkit of composable controllers - source-controller, kustomize-controller, helm-controller, notification-controller, image automation - driven by GitRepository and Kustomization CRs.

Kustomize: template-free overlay tool built into kubectl; bases plus overlays patch manifests per environment; native to Argo CD and Flux.

Helm: package manager using charts and values; GitOps tools render charts at reconcile time or you commit rendered manifests for full auditability.

Jenkins X, Tekton, GitHub Actions, GitLab CI: CI systems that build/test images and open promotion PRs; they do not own cluster reconciliation in a GitOps model.

OpenGitOps / CNCF: the OpenGitOps project publishes the four GitOps principles; Argo CD and Flux are CNCF projects commonly used as reference implementations.

Secrets tooling: SOPS with age/KMS, Sealed Secrets, External Secrets Operator, and Vault integrate with reconcilers to inject secrets without storing plaintext in Git.

Policy and validation: Kyverno, OPA Gatekeeper, and Conftest validate manifests in CI or at admission; Argo CD and Flux expose health/sync metrics for alerting.

Desired state: the declarative, versioned specification of what the system should look like; stored in Git and treated as the single source of truth.

Actual state (live state): what is currently running in the target environment, observed by the reconciler via cluster APIs or cloud provider APIs.

Reconciliation (sync): the continuous loop that compares desired state to actual state and applies or reverts changes so the two converge.

Drift: any divergence between actual state and desired state, whether caused by manual edits, external controllers, or failed applies.

Reconciler/agent (e.g., Argo CD application controller, Flux kustomize-controller): the component that pulls desired state and pushes it into the environment.

Source of truth: the Git repository (branch, path, commit SHA) plus any referenced artifacts (Helm charts, OCI images, Kustomize overlays) that define desired state.

Environment/promotion: a target (dev, staging, prod) whose desired state is a specific ref or overlay; promotion is changing which ref/overlay an environment tracks.

Health/sync status: sync status compares revision and resource state (Synced/OutOfSync); health status reports whether workloads are actually running (Healthy/Degraded/Progressing).

Prune and self-heal: prune deletes live resources no longer present in desired state; self-heal reverts manual drift back to the declared spec.

Declarative: the entire desired state is expressed declaratively, so the system can be reconstructed from the description alone without imperative steps.

Versioned and immutable: desired state is stored in a source that keeps full history (Git commits, tags, immutable image digests) so any past state is reproducible.

Pulled automatically: software agents pull desired state from the source rather than external systems push changes into the cluster.

Continuously reconciled: agents continuously observe actual state and act to converge it toward desired state, correcting drift without human intervention.

Single source of truth: exactly one canonical store defines desired state; all changes flow through it, not through direct cluster mutation.

Change via pull/merge request: modifications are proposed as commits, reviewed, and merged, giving an auditable approval trail and rollback by revert.

Git as the audit log: commit history, authors, and approvals provide provenance for every deployed change without a separate deployment database.

Reconciliation is idempotent and converging: repeating the loop on an already-converged system produces no changes, and partial failures are retried until convergence.

CI vs CD split: CI builds and tests artifacts and publishes immutable images; GitOps CD takes the published artifact reference and reconciles it into environments.

Infrastructure as Code: Terraform, Pulumi, or Crossplane declare infrastructure; GitOps can reconcile IaC outputs or use controllers that own cloud resources directly.

Progressive delivery: canary, blue/green, and feature flags control blast radius; GitOps handles the desired-state change while the delivery controller handles traffic shifting.

Policy as Code: OPA/Gatekeeper, Kyverno, or Conftest validate manifests in CI and admission control enforces constraints at reconcile time.

Secrets management: SOPS, Sealed Secrets, External Secrets Operator, or Vault inject secrets; plaintext secrets never belong in Git.

Observability and SLOs: metrics, logs, and traces verify that reconciled state is healthy; health checks feed back into sync/health status and rollback decisions.

Supply chain security: signed images (cosign/Sigstore), SBOMs, and admission verification ensure only trusted artifacts reach the cluster.

Environment promotion and release management: same artifact promoted across environments via PRs to overlay repos, with change freeze and approval gates encoded as policy.

Repo-per-environment vs repo-per-team: separate repos give isolation and access control; a monorepo with path-based overlays simplifies atomic cross-environment changes.

App-of-apps (Argo CD) / hierarchical composition (Flux): a root application points to a directory of child Applications or Kustomizations, enabling bootstrap and fan-out.

Environment branches vs directory overlays: branches isolate promotion but merge conflicts grow; directories with Kustomize overlays or Helm values files are the more common pattern.

Pull request promotion: change image tag or overlay in a PR, get review and policy checks, merge, and the reconciler deploys; revert is a Git revert.

Image automation (Flux image-reflector/image-automator) or Argo CD Image Updater: controllers commit updated tags or digests back to Git when new images appear.

Multi-cluster fleet management: a management cluster reconciles many target clusters; credentials and cluster registration are themselves declared as resources.

Disaster recovery / cluster rebuild: because desired state is fully declarative and versioned, a lost cluster is recreated by pointing a new reconciler at the same source.

Drift detection and self-heal modes: choose automated sync with prune/self-heal for prod convergence, or manual sync for gated approval; alert on OutOfSync as a signal.

Argo CD: Kubernetes-native GitOps controller with Application CRD, UI, sync waves/hooks, app-of-apps, and multi-cluster management; supports Helm, Kustomize, plain YAML, Jsonnet.

Flux (v2): GitOps toolkit of composable controllers - source-controller, kustomize-controller, helm-controller, notification-controller, image automation - driven by GitRepository and Kustomization CRs.

Kustomize: template-free overlay tool built into kubectl; bases plus overlays patch manifests per environment; native to Argo CD and Flux.

Helm: package manager using charts and values; GitOps tools render charts at reconcile time or you commit rendered manifests for full auditability.

Jenkins X, Tekton, GitHub Actions, GitLab CI: CI systems that build/test images and open promotion PRs; they do not own cluster reconciliation in a GitOps model.

OpenGitOps / CNCF: the OpenGitOps project publishes the four GitOps principles; Argo CD and Flux are CNCF projects commonly used as reference implementations.

Secrets tooling: SOPS with age/KMS, Sealed Secrets, External Secrets Operator, and Vault integrate with reconcilers to inject secrets without storing plaintext in Git.

Policy and validation: Kyverno, OPA Gatekeeper, and Conftest validate manifests in CI or at admission; Argo CD and Flux expose health/sync metrics for alerting.