Module 03 · Platform foundation · 40 min · You are: Platform team

Hand the fleet over to Git

Terraform built the clusters and installed Argo CD. From here on, Terraform only runs when clusters change; everything that runs on the clusters comes from Git through Argo CD. The root Application is the handover point: one object that points at a folder of ApplicationSets.

Open this module in the interactive course to track progress and switch tracks.

Change journey practised: Requested → Proposed → Validated → Previewed → Approved → Merged → Reconciled → Healthy

Concepts

Root Application

root-app.yaml points Argo CD at applicationsets/ in your repo. Everything else is reached from there ("app of apps").

ApplicationSet

A template plus a generator. The git files generator reads clusters/*.yaml and creates one Application per cluster: dev-platform-namespaces, prod-platform-namespaces.

AppProject

fleet-platform is the project for platform-owned Applications.

Reconcile and self-heal

Argo CD compares live state with Git every few minutes and fixes differences. A manual change survives only until the next comparison.

Files to know

Open them in your editor or on GitHub; the bullets say what to look at.

• root-app.yaml (reference, your repo): The handover point. Twenty lines.
  1. Argo CD reads the applicationsets/ folder of your repo L8–11
  2. Fully automatic: Git deletions delete, manual changes get reverted L15–18
• applicationsets/platform-namespaces-appset.yaml (reference, your repo): The simplest ApplicationSet. Read it top to bottom once.
  1. One parameter set per inventory file... L7–12
  2. ...becomes one Application per cluster L15
  3. Each cluster gets the overlay of its environment L21
• applicationsets/fleet-platform-project.yaml (reference, your repo): The fence around platform-owned Applications.
  1. Created before anything uses it L7
  2. The only repositories platform Applications may read L12–21
• addons/namespaces/overlays/dev/kustomization.yaml (reference, your repo): A Kustomize overlay: shared base plus dev labels.
  1. Start from the shared base L1–2
  2. ...and add environment labels L4–7

Steps

1. Propose the root app and the first ApplicationSet

set-repo-url.sh (no arguments) points every copied manifest at your origin. The plan comment on the pull request lists the two Applications this will create.

cd ~/work/fleet-gitops && git switch main && git pull -q
git switch -c root-app

Copy the root app, a project, the first ApplicationSet and the namespaces it deploys:

git checkout reference/main -- root-app.yaml applicationsets/fleet-platform-project.yaml \
  applicationsets/platform-namespaces-appset.yaml addons/namespaces

Point the copied files at your repo instead of the reference:

scripts/set-repo-url.sh

Check it worked. Find the repoURL line: it should be https://github.com/YOUR_GITHUB_USER/fleet-gitops.git, your repo.

git diff root-app.yaml

Run the checks. Expect them to pass:

scripts/validate.sh

git add -A && git commit -m "Root app: hand the fleet to Argo CD"
git push -u origin HEAD

Open the pull request ↗

2. Merge, then let Terraform finish the chain

Terraform now finds root-app.yaml and creates exactly one more thing: the root Application.

cd ~/work/fleet-gitops && git switch main && git pull -q

Apply. Read the plan before you type yes: it should say Plan: 1 to add, the root Application, and nothing else.

cd infrastructure/kind && terraform apply

cd ~/work/fleet-gitops && git switch main && git pull -q

kubectl --context kind-platform apply -f root-app.yaml

3. Watch Git become the fleet

The root Application reads applicationsets/, the ApplicationSets create Applications, and the Applications deploy to the clusters. You watch the chain build itself.

Within a minute you should see root, then dev-platform-namespaces and prod-platform-namespaces appear. Wait until all of them show Synced and Healthy, then press Ctrl-C.

kubectl --context kind-platform -n argocd get applications -w

4. Check a spoke

Argo CD ran on the hub, but its work happened on dev. Look at dev directly.

The namespaces Argo CD created on dev. Expect a short list, all labelled environment=dev:

kubectl --context kind-dev get namespaces -l environment=dev

One of them in detail. Expect labels such as the environment and the owner: the platform put them there, not you.

kubectl --context kind-dev get namespace observability -o jsonpath='{.metadata.labels}'; echo

Break it on purpose: Delete something Git owns

Someone "cleans up" a namespace on dev that looks unused, with kubectl.

You practise: finding which Application owns a resource, and making a per-environment change with a Kustomize overlay instead of by hand.

1. Break it

Delete the namespace on dev:

kubectl --context kind-dev delete namespace platform-system

Watch it. Press Ctrl-C after a minute.

kubectl --context kind-dev get namespace platform-system -w

2. What you see

The namespace is deleted, and a few seconds later it is back: Active, with a new age. Nobody ran anything. Expected (by whoever cleaned up): gone for good.

3. Fix it yourself

Dev really does not need platform-system. Remove it from dev only, keep it in prod, and do not touch base/. Prove the dev overlay renders without it before you push. Once it is gone from dev, put it back with a revert: the reference keeps it.

cd ~/work/fleet-gitops && git switch main && git pull -q
git switch -c dev-without-platform-system

patches:
  - patch: |-
      $patch: delete
      apiVersion: v1
      kind: Namespace
      metadata:
        name: platform-system

kubectl kustomize addons/namespaces/overlays/dev | grep -c platform-system

kubectl kustomize addons/namespaces/overlays/prod | grep -c platform-system

git add -A && git commit -m "dev: no platform-system namespace"
git push -u origin HEAD

kubectl --context kind-dev get namespace platform-system

kubectl --context kind-prod get namespace platform-system

git switch main && git pull -q
git switch -c restore-platform-system && git revert --no-edit HEAD && git push -u origin HEAD

Quiz

1. What does root-app.yaml point at?
   • applicationsets/
   • clusters/, the inventory, so that root creates one Application per cluster file
   • infrastructure/, the add-on charts, so that root installs them directly on the hub
2. You delete a namespace that Git declares. What happens?
   • It stays deleted, because Argo CD only creates objects and never restores them afterwards
   • Argo CD recreates it (self-heal)
   • Terraform recreates it the next time someone runs terraform apply on the hub
3. When does Terraform run after this module?
   • On every merge, as the last job of the pipeline, so the cluster always matches Git
   • Never again, because Argo CD takes over and Terraform is deleted from the repository
   • Only when clusters or the hub bootstrap change

Field note

Keep the root app boring. I have seen teams put logic in it; every one of them regretted it the first time they rebuilt a hub.

Report a problem with this module