Platform Engineering Fundamentals · Module 07 of 12

GitOps and declarative delivery

Use version-controlled desired state and reconciliation to make platform delivery observable, reviewable and recoverable, while separating build pipelines from deployment authority.

Learning objectives

By the end of this module, you should be able to:

Explain desired state, reconciliation and drift in GitOps.
Design a build-to-promotion handoff using immutable artifact references.
Differentiate a Git change from proof that runtime reached the intended state.

GitOps is a reconciliation model

Desired state is declared in version control and an automated reconciler continuously compares and applies that desired state to the target environment. The important idea is convergence and auditability, not simply “YAML in Git.”

Build once, promote by identity

The build system should produce an immutable artifact; environment changes should promote that artifact identity rather than rebuilding different binaries for each environment.

The build platform is also a product surface

CI runners, build permissions, caches, artifact registries and provenance are platform capabilities with their own ownership and reliability boundaries. A platform team should define who owns runner images, isolation, credentials, capacity and failure recovery instead of treating CI as an invisible upstream service.

Runner ownership and isolation
Immutable artifact identity
SBOM and provenance hand-off
Registry and retention policy
Build failure diagnostics

Supply-chain evidence crosses the build/deploy boundary

The DevSecOps course teaches SBOMs, signing and provenance in depth. Here the platform concern is integration: the golden path should carry artifact digest, SBOM/provenance references and policy results into promotion so deployment consumes evidence produced by the build rather than rebuilding or trusting mutable tags.

Sync status is evidence, not the whole outcome

A reconciler can report desired/live differences and sync/health states, but application readiness, SLOs and business checks still matter.

Worked example

Promotion contract

build → artifact digest → desired-state change → review → reconciler → runtime health evidence

The artifact identity remains constant through promotion.
The runtime is verified after reconciliation rather than assuming the Git merge equals successful deployment.

Core lab · account-free

Lab 07 — Detect desired/live drift

Goal: Compare synthetic desired and live state and decide whether reconciliation is needed.

Before you start

No cloud account required.
Core lab uses bash/Python 3 and local files only.

STEP 1

Create desired/live

cat > /tmp/desired.json <<'EOF'
{"image":"registry/orders@sha256:abc123","replicas":3}
EOF
cat > /tmp/live.json <<'EOF'
{"image":"registry/orders@sha256:old999","replicas":3}
EOF

STEP 2

Detect drift

python3 - <<'PY2'
import json
d=json.load(open('/tmp/desired.json')); l=json.load(open('/tmp/live.json'))
diff={k:(l.get(k),v) for k,v in d.items() if l.get(k)!=v}
print(diff)
assert 'image' in diff and 'replicas' not in diff
PY2

STEP 3

Define post-sync proof

Name one workload health check and one observability signal required after reconciliation.

Verify

Only image drift is detected.
A runtime verification step is defined separately from sync.

Expected outcome

A clear desired/live drift report.

Diagnose / troubleshoot

If desired state is correct but runtime is unhealthy, investigate application/runtime evidence instead of repeatedly forcing sync.
If the pipeline rewrites mutable tags, switch to immutable artifact identity.

Real-world connection

GitOps gives platform teams a repeatable delivery interface while preserving reviewable state and drift detection.

Real-tool practicum · optional but recommended

Real-tool practicum — watch Argo CD reconcile drift on kind

Install a pinned Argo CD release into the disposable kind cluster, create the official guestbook Application, then observe desired/live reconciliation instead of only modelling drift in Python.

Prerequisites

Run ./ops/setup-platform-kind-lab.sh first.
kubectl with access to context kind-gnu-platform-lab.
Internet access for the tagged Argo CD manifest and example Git repository.
The commands are for a disposable local lab only; never point them at production.

Cost / risk

Core learning is account-free. Optional external/sandbox tools may consume local CPU/RAM; do not use production credentials or billable cloud resources.

Warnings

Do not point training automation at production clusters, repositories or cloud accounts.
A successful command is not proof of a good platform interface; validate the developer outcome and guardrails.

TOOL 1

./ops/setup-platform-kind-lab.sh

TOOL 2

ARGOCD_VERSION=${ARGOCD_VERSION:-v3.2.0}; kubectl --context kind-gnu-platform-lab create namespace argocd --dry-run=client -o yaml | kubectl --context kind-gnu-platform-lab apply -f -

TOOL 3

ARGOCD_VERSION=${ARGOCD_VERSION:-v3.2.0}; kubectl --context kind-gnu-platform-lab apply -n argocd --server-side --force-conflicts -f "https://raw.githubusercontent.com/argoproj/argo-cd/${ARGOCD_VERSION}/manifests/install.yaml"

TOOL 4

kubectl --context kind-gnu-platform-lab -n argocd wait --for=condition=Available deployment/argocd-server --timeout=240s

TOOL 5

cat <<'EOF' | kubectl --context kind-gnu-platform-lab apply -f -
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
EOF

TOOL 6

kubectl --context kind-gnu-platform-lab -n argocd get application guestbook -o wide

TOOL 7

for i in {1..36}; do kubectl --context kind-gnu-platform-lab -n default get deployment guestbook-ui >/dev/null 2>&1 && break; sleep 5; done; kubectl --context kind-gnu-platform-lab -n default scale deployment guestbook-ui --replicas=3; sleep 20; kubectl --context kind-gnu-platform-lab -n default get deployment guestbook-ui -o jsonpath="{.spec.replicas}{\n}"

Avoid these traps

Common mistakes

Treating Git as proof that deployment succeeded.
Rebuilding artifacts per environment.
Giving the CI runner broad cluster-admin access when a reconciler can own deployment authority.

Knowledge check

Can you connect the developer need to a platform contract?

Three concept checks plus one scenario check.

1What is reconciliation?

Repeatedly comparing desired and actual state and acting to converge actual state toward the declaration.

2Why promote immutable digests?

The exact artifact identity remains provable across environments.

3What is drift?

A difference between declared desired state and actual/live state.

4Scenario: Argo CD reports Synced but the service has 40% errors. Is the release healthy?

No. Sync proves desired/live configuration convergence, not application health or SLO compliance.

My Learning

Record your progress for this module.

Progress is saved in this browser immediately. When you sign in to My Learning, it can also sync across devices.

Not started

Core lab attemptedRecord this after meaningfully completing or attempting the module's core lab.Knowledge checks attemptedThis is marked automatically after you open every answer in the module; you can also record it manually.

Attempt the core lab and knowledge checks before marking the module complete.