From 992a00c2dbac95973b399b6103fd81fb708882d7 Mon Sep 17 00:00:00 2001 From: Nik Afiq Date: Thu, 23 Jul 2026 18:22:31 +0900 Subject: [PATCH] docs: add cold-rebuild runbook reflecting closed GitOps gaps Stage 8 of REFACTOR_PLAN.md. The documented bootstrap sequence never mentioned installing Authentik or the cert-manager ClusterIssuers -- both required for the rest of the stack to work, per the original audit's Critical findings #1/#2. Now that cert-manager-config and authentik-config are real Argo CD Applications (previous commit), the runbook reflects what's actually automatic vs. still-manual (Authentik's Helm chart install remains a one-time manual step pending a chart-version decision -- see argocd/apps/authentik.yaml). Co-Authored-By: Claude Sonnet 5 --- README.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3c6a9b1..6642fd0 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ Install workstation tools: ```bash pip install ansible -ansible-galaxy collection install community.general ansible.posix +ansible-galaxy collection install -r ansible/requirements.yml ``` Also install `kubectl`, `helm`, and `kubeseal`. The inventory expects SSH @@ -88,6 +88,7 @@ ansible-playbook -i ansible/inventory.yaml ansible/playbooks/bootstrap-minisforu ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-k3s.yaml -K ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-nfs-debian.yaml -K ansible-playbook -i ansible/inventory.yaml ansible/playbooks/join-debian-agent.yaml -K +ansible-playbook -i ansible/inventory.yaml ansible/playbooks/setup-gpu-node.yaml -K ``` Install Argo CD once, then hand control to the app-of-apps: @@ -103,7 +104,39 @@ helm upgrade --install argocd argo/argo-cd \ kubectl apply -f manifests/argocd/app-of-apps.yaml ``` -After that, normal changes should flow through Git and Argo CD. +The app-of-apps now brings up cert-manager's `ClusterIssuer`s (via +`cert-manager-config`) and Authentik's ingress/proxy-outpost/middleware (via +`authentik-config`) automatically — these used to require untracked manual +`kubectl apply` steps that weren't documented anywhere. **Authentik's Helm +chart itself is still a one-time manual install**, since its Argo CD +Application (`argocd/apps/authentik.yaml`) is deliberately left on manual sync +with a `targetRevision` placeholder pending a chart-version decision: + +```bash +helm repo add authentik https://charts.goauthentik.io +helm repo update +helm upgrade --install authentik authentik/authentik \ + -f values/authentik.yaml -n authentik --create-namespace +``` + +Populate secrets (see "Secrets" below) before Authentik, Gitea, Grafana, or +the other services that depend on them will come up healthy. After that, +normal changes should flow through Git and Argo CD. + +### Cold-rebuild order + +Rebuilding from nothing, the dependency order that actually matters is: + +1. Ansible playbooks above (hosts, K3s, NFS). +2. `helm install argocd` + `kubectl apply -f manifests/argocd/app-of-apps.yaml` + — this alone now brings up cert-manager, sealed-secrets, and their + `ClusterIssuer`s/CA cert via sync-wave ordering. +3. Runtime secret scripts and Sealed Secret regeneration (see "Secrets") — + several Applications (Gitea, Grafana, home-services, Authentik) will sit + degraded/crash-looping until their secrets exist. +4. Manual Authentik Helm install (above) — every OAuth-gated service + (Grafana, Gitea, Argo CD SSO, Traefik dashboard) depends on it. +5. Everything else reconciles from Git on its own from here. ## Daily Operations