GitOps principles — Git as the source of truth

GitOps is the practice of using Git as the source of truth for cluster configuration. This lesson walks the four principles, the benefits and trade-offs, and the operational discipline.

The GitOps model

flowchart LR
    A[Git repository] -->|desired state| B[GitOps controller]
    B -->|apply| C[Kubernetes cluster]
    C -->|actual state| B
    B -->|drift detected| A
    D[Developer commit] --> A

The GitOps model:

1. The desired cluster state is declared in YAML manifests in a Git repository.
2. A GitOps controller (Argo CD, Flux) watches the repository.
3. The controller applies the manifests to the cluster.
4. The controller continuously reconciles the actual state toward the desired state.

The cluster’s actual state is always derived from Git. Any drift (manual changes, drift) is detected and corrected.

The four principles

flowchart LR
    A[GitOps principles] --> B[Declarative]
    A --> C[Versioned]
    A --> D[Automatically pulled]
    A --> E[Continuously reconciled]

The four principles:

• Declarative. The desired state is declared in YAML manifests. Imperative commands (kubectl scale) are not GitOps.
• Versioned. The manifests are stored in Git, with full history. Every change is a commit; every commit can be reviewed.
• Automatically pulled. The controller pulls the manifests from Git (the GitOps pull model). The cluster does not push.
• Continuously reconciled. The controller continuously watches for drift and corrects it.

These principles distinguish GitOps from imperative cluster management (kubectl apply from a developer’s laptop) and from push-based CD (a CI pipeline that runs kubectl apply).

The benefits

flowchart LR
    A[GitOps benefits] --> B[Audit trail]
    A --> C[Rollback]
    A --> D[Drift detection]
    A --> E[Recovery from Git]
    A --> F[Review process]

The benefits:

• Audit trail. Every change to the cluster is a Git commit. git log shows the history.
• Rollback. A bad change can be reverted with git revert. The cluster returns to the previous state.
• Drift detection. The controller detects when the cluster’s actual state differs from Git’s desired state. Drift is reported and corrected.
• Recovery from Git. A cluster loss can be recovered by applying Git’s manifests to a fresh cluster. Git is the backup.
• Review process. Every change goes through a pull request with code review. Production changes are reviewed before they reach the cluster.

The trade-offs

flowchart LR
    A[GitOps trade-offs] --> B[Complexity]
    A --> C[Controller availability]
    A --> D[Manifest review]
    A --> E[Secrets in Git]

The trade-offs:

• Complexity. GitOps adds a controller, a Git repository, and a manifest review process. The operational surface is larger than imperative management.
• Controller availability. If the GitOps controller is down, manifests cannot be applied or reconciled. The controller is a critical component.
• Manifest review. Every change requires a pull request and review. This is good for production but can slow down development.
• Secrets in Git. Storing secrets in Git is a security risk. Use sealed-secrets, Vault, or External Secrets Operator instead.

Quiz

The operational discipline

GitOps in production rests on five non-negotiable elements:

• Git is the source of truth. The cluster’s actual state should match Git. Manual changes are drift.
• Manifests are reviewed. Every change goes through a pull request with code review.
• The controller is HA. The GitOps controller is critical; deploy it with HA.
• Secrets are external. Use sealed-secrets, Vault, or External Secrets Operator. Never plain Kubernetes Secrets in Git.
• Drift is detected and alerted. Alert on drift that the controller cannot auto-correct.

GitOps is the discipline that makes cluster configuration auditable, recoverable, and reviewable. The discipline is to treat Git as the source of truth and to enforce the principles consistently.