nik/homelab
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add cold-rebuild runbook reflecting closed GitOps gaps

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Nik Afiq 2026-07-23 18:22:31 +09:00
parent d44295f569
commit 992a00c2db
1 changed files with 35 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -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