PKR-Lab

f00b0 - Promotion-Kette ENTW → TECH → PROD

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/f-cicd-automatisierung/f00b0-promotion-chain.md

Promotion-Kette ENTW → TECH → PROD

promote-chain.yml bringt eine neue
Version (Image-Tag, Chart-Abhängigkeit) Schritt für Schritt in die produktiven
Cluster: zuerst läuft sie auf ENTW, und erst wenn sie dort 24 Stunden gesund war,
entsteht ein PR nach TECH. Ist sie danach 2 Stunden gesund auf TECH, entsteht der
PR nach PROD. Ein Mensch bestätigt den PROD-PR. Umgesetzt ist damit die
Kette aus 40080, Baustein 6.

Zwei Pipelines ergänzen sich, sie ersetzen sich nicht:

Pipeline Was sie überträgt Wann
ENTW → main (promote-entw.yml) Commits, die nicht nur argocd/apps/entw/ ändern (z. B. Doku, Skripte, Playbooks), per Cherry-Pick nach grüner CI auf entw
Promotion-Kette (promote-chain.yml) Versionsfelder der Apps unter argocd/apps/entw/, nach tech/ bzw. prod/ nach bestandenem Gesundheits-Gate

Ablauf

flowchart TD
    E["Version auf entw<br/>argocd/apps/entw/app"] --> G1{"Gate ENTW<br/>≥ 24 h gesund + ausgerollt<br/>+ Smoke-Checks"}
    G1 -->|nein| W1["blockiert, Grund im Job-Summary"]
    G1 -->|ja| P1["PR: argocd/apps/tech/app<br/>(oder direkt prod, falls die App nicht in TECH existiert)"]
    P1 -->|"Merge (optional Auto-Merge)"| T["TECH: ArgoCD synct die Version"]
    T --> G2{"Gate TECH<br/>≥ 2 h gesund + ausgerollt"}
    G2 -->|nein| W2["blockiert"]
    G2 -->|ja| P2["PR: argocd/apps/prod/app<br/>(nie Auto-Merge)"]
    P2 -->|"Merge = du prüfst"| PR["PROD: ArgoCD synct"]

Der Workflow läuft stündlich (17 * * * *) und auf Knopfdruck (Actions → Promote chain
→ Run workflow
, wahlweise nur eine Stufe oder nur planen). Jeder Lauf schreibt eine Tabelle in
die Job-Zusammenfassung: welche App, welche Stufe, welche Änderung, und bei „blockiert“ der genaue Grund.

Was übertragen wird — und was nicht

Es gibt bewusst nur Versionsfelder, nie den ganzen Ordner:

Datei Feld
values.yaml jedes tag unter einem Schlüssel image (image.tag, sealed-secrets.image.tag, server.image.tag, …)
Chart.yaml dependencies[*].version, sofern eine exakte Version (kein *, ^, ~, >=)

Hosts (*.dev.homeserver ↔ *.prod.homeserver), Replicas, Ressourcen, Secrets und Templates
unterscheiden sich je Cluster und wandern nie automatisch. Weitere Regeln:

Das Gate

Alle Bedingungen müssen stimmen, sonst ist die App „blockiert“ (Grund im Summary):

# Bedingung Quelle
1 Application ist Healthy und Synced ArgoCD-API (status.health, status.sync)
2 seit mindestens 24 h (ENTW) bzw. 2 h (TECH) gesund status.health.lastTransitionTime: springt bei jedem Rollout und jeder Störung zurück
3 Die neue Version liegt seit mindestens so lange in der Quell-Umgebung Commit-Zeit (git log -S, erster Elternpfad = Merge-Zeitpunkt)
4 Die neue Version ist ausgerollt: die von ArgoCD synchronisierte Revision enthält den Commit status.sync.revision, git merge-base --is-ancestor
5 Optionale Smoke-Checks bestehen (nur ENTW-Stufe konfiguriert) curl gegen die App, siehe unten

Bedingung 2 und 4 zusammen sind der Kern: „24 Stunden gesund“ heißt diese Version, nicht irgendeine.
Ist ArgoCD nicht erreichbar oder liefert keinen Status, ist alles blockiert (fail closed) und ein
Issue Promotion-Kette: ArgoCD nicht erreichbar (Label promotion-gate) meldet es einmal; es schließt sich,
sobald ArgoCD wieder antwortet.

Smoke-Checks

Ein Pod, der Running ist, beweist nicht, dass die App antwortet. Pro App und Umgebung lassen sich in
argocd/promotion.yaml HTTP-Prüfungen hinterlegen:

smoke:
  example-whoami:
    entw:
      - url: http://whoami.dev.homeserver/
        contains: "Hostname:"      # optional: Text im Body
        status: 200                # optional, Standard 200

Der Runner hat kein Heim-DNS, daher setzt die Engine curl --resolve auf die IP der Umgebung
(SMOKE_IP_ENTW, Standard 192.168.178.100; SMOKE_IP_TECH, Standard 192.168.178.94). Die beiden
Beispiele oben wurden gegen die laufende ENTW-VM geprüft (HTTP 200, erwarteter Inhalt).

Konfiguration: argocd/promotion.yaml

Schlüssel Bedeutung
gates.entw_hours Gesundheitsdauer auf ENTW (Standard 24)
gates.tech_hours Gesundheitsdauer auf TECH (Standard 2)
exclude Apps (Ordnernamen), die nie automatisch promotet werden
smoke HTTP-Prüfungen, siehe oben

Die Datei liegt außerhalb von argocd/apps/, kein ApplicationSet liest sie.

Die PRs

Ziel Branch Merge
TECH promote/tech-<app> von Hand; Auto-Merge nach grüner CI, wenn die Repo-Variable PROMOTE_AUTOMERGE_TECH auf true steht (Entscheidung aus 40080: TECH automatisch, PROD manuell; empfohlen erst nach einigen beobachteten Zyklen)
PROD promote/prod-<app> immer von Hand: der Merge rollt auf echte Nutzer aus

Pro App und Ziel gibt es einen rollenden Branch. Ändert sich die Übernahme, wird er per Force-Push
aktualisiert und der offene PR bleibt derselbe. Ein abgelehnter (geschlossener) PR wird für dieselbe Änderung
nicht erneut vorgeschlagen. Die PRs tragen die Labels promotion und promote-tech/promote-prod; der PR-Text
enthält die Tabelle der Änderungen und die Belege des Gates.


Netzweg und Zugriff

GitHub-Runner erreichen ArgoCD nur über Tailscale. Der Workflow tritt dem Tailnet bei (die Action nimmt
Subnet-Routen selbst an, ein Schritt prüft die Verbindung) und nutzt die Subnet-Route 192.168.178.0/24, die der Homeserver bereits ins
Tailnet bewirbt. Damit kommen beide ArgoCD-Instanzen über ihre LAN-Adresse, ohne Änderung an worker-1:

Ziel Adresse Zweck
Hub-ArgoCD (TECH + PROD) https://argocd.tech.homeserver (→ 192.168.178.94:443) Gate der TECH-Stufe; PROD-Applications heißen prod-<app>
ENTW-ArgoCD (entw-vm) https://argocd.dev.homeserver (→ 192.168.178.100:443) Gate der ENTW-Stufe
ENTW-Ingress 192.168.178.100:80 (Host-Header) Smoke-Checks

Der Runner hat kein Heim-DNS. Der Workflow trägt die beiden ArgoCD-Hosts in /etc/hosts ein und kopiert
pki/homeserver-root-ca.pem nach $RUNNER_TEMP/argocd-ca.pem; promote-chain.py prüft das Zertifikat
dagegen (Umgebungsvariable ARGOCD_CA_FILE). Die Zertifikatsprüfung ist nicht abschaltbar: Ist die CA nicht passend
oder das Zertifikat abgelaufen, gilt ArgoCD als nicht erreichbar und das Gate blockiert. Die Gründe der Umstellung
von http://…:30080: 60030.

Die Tailscale-ACL (grants) verbietet standardmäßig alles, was nicht erlaubt ist. Der Runner braucht einen
Grant. Empfehlung: ein eigenes Tag für den Runner, damit die Rechte nicht an einem Benutzer hängen:

"tagOwners": { "tag:ci": ["autogroup:admin"] },
"grants": [
  {
    "src": ["tag:ci"],
    "dst": ["192.168.178.94", "192.168.178.100"],
    "ip":  ["tcp:443", "tcp:80"]
  }
]

Der Workflow meldet sich per Workload Identity Federation (Federated Identity) an: Der Runner holt von GitHub ein kurzlebiges OIDC-Token (Berechtigung id-token: write
im Job) und tauscht es bei Tailscale gegen den Zugang. Es gibt kein dauerhaftes Secret. In GitHub liegen nur TS_OAUTH_CLIENT_ID (Client ID) und TS_AUDIENCE (Audience), beide sind
keine Geheimnisse. Der Runner tritt mit dem Tag tag:ci bei, die Action erzeugt dabei pro Lauf einen frischen, kurzlebigen Key: nichts läuft ab, nichts wird verbraucht. Der Runner ist
ein getaggtes, kurzlebiges Gerät und sieht nichts außer den ACL-Zielen.

Die Federated Identity entsteht im Tailscale-Admin-Panel unter Settings → Trust credentials → Credential → OpenID Connect
(console.tailscale.com/admin/settings/trust-credentials):

Feld Wert
Issuer GitHub
Subject repo:pkr-lab/capulus-core:ref:refs/heads/main (nur dieses Repo, nur der Branch main; dort laufen schedule und workflow_dispatch der Kette)
Scope nur auth_keys mit Write, ohne weitere Scopes
Tags nur tag:ci

Danach Generate credential und die Werte Client ID und Audience kopieren. Damit kann nur ein Lauf von main im eigenen Repo Geräte mit dem Tag tag:ci erzeugen; ein Lauf von einem
anderen Branch oder Fork bekommt das Token nicht, und die ID und die Audience allein sind wertlos. Gelegentlich im Admin-Panel die Spalte „Last used“ prüfen und die Credential bei einem unbekannten
Zeitpunkt widerrufen. Der Tailscale-Client im Runner ist in den Workflows fest gepinnt (version: 1.104.1) und wird von Renovate aktualisiert, siehe
600a0. Die Subnet-Route des
Homeservers muss im Admin-Panel freigegeben sein (sie ist es: der Homeserver zeigt PrimaryRoutes: 192.168.178.0/24).

Einrichtung

Reihenfolge (nach dem Merge der Änderungen, die diese Pipeline einführen):

  1. CI-Pflicht-Check erweitern: scripts/setup-main-ruleset.sh erneut ausführen (kommt der Check docs links dazu).
  2. ArgoCD-Konto ci ausrollen (Nur-Lese-Rolle, nur API-Token): Ansible-Rolle argocd, Schalter
    argocd_ci_account_enabled (Standard true).
    • Hub: make argocd
    • ENTW: ansible-playbook -i inventory/hosts.yml entw.yml --tags argocd --vault-password-file ~/.vault_pass
  3. Tokens erzeugen und als Secret hinterlegen (nichts wird ausgegeben):
    scripts/create-argocd-ci-token.sh hub und scripts/create-argocd-ci-token.sh entw
    → Secrets ARGOCD_HUB_TOKEN, ARGOCD_ENTW_TOKEN (365 Tage gültig).
  4. Tailscale: ACL-Grant (oben) speichern, Federated Identity wie oben anlegen und Client ID und Audience als TS_OAUTH_CLIENT_ID und TS_AUDIENCE ablegen
    (gh secret set TS_OAUTH_CLIENT_ID, gh secret set TS_AUDIENCE). Ein Auth-Key als Secret taugt nicht (einmalig oder nach
    höchstens 90 Tagen abgelaufen): der Beitritt scheitert dann dauerhaft mit BackendState=NeedsLogin.
    Fehlen die beiden Secrets, läuft die Kette als „inaktiv“ (Hinweis statt Fehler).
  5. PoC ausführen (Actions → Tailscale Runner PoC): muss OK melden.
  6. Trockenlauf: Promote chain → Run workflow, plan_only aktivieren, Summary prüfen.
  7. Beobachten: einige echte Zyklen begleiten. Danach optional Repo-Variable PROMOTE_AUTOMERGE_TECH=true.
  8. Renovate für die Pilot-Apps in TECH/PROD abschalten, damit es genau einen Update-Weg gibt
    (argocd/apps/entw/ → Kette). Diese Regel bewusst erst jetzt in renovate.json ergänzen,
    sonst fehlte solange die Kette nicht läuft die Update-Quelle:
{
  "description": "Pilot-Apps: Updates laufen ueber ENTW und die Promotion-Kette.",
  "matchBaseBranches": ["main"],
  "matchFileNames": [
    "argocd/apps/tech/sealed-secrets/**", "argocd/apps/prod/sealed-secrets/**",
    "argocd/apps/prod/demo-app/**", "argocd/apps/prod/example-whoami/**"
  ],
  "enabled": false
}

Solange ARGOCD_ENTW_TOKEN, ARGOCD_HUB_TOKEN oder das PAT fehlen, läuft der Workflow durch, meldet
„Promotion-Kette inaktiv“ und tut nichts.

Bedienung

Ziel Wie
Sofort prüfen Actions → Promote chain → Run workflow (plan_only = nur planen)
App ausschließen Ordnername unter exclude: in argocd/promotion.yaml
Gate anpassen gates.entw_hours / gates.tech_hours
Warum wird nichts promotet? Job-Summary des letzten Laufs: pro App steht der Grund
Lokal planen python3 scripts/promote-chain.py --plan-only --status entw=entw.json --status hub=hub.json mit kubectl -n argocd get applications -o json als Eingabe (auf der ENTW-VM per ssh [email protected] 'sudo k3s kubectl …')
Token erneuern scripts/create-argocd-ci-token.sh … erneut; alte Token laufen nach 365 Tagen ab

Bewusst nicht enthalten

Was getestet wurde

Vollständig lokal getestet: ein synthetisches Repo (bare origin, Branches main/entw, datierte Commits,
Status-JSON) deckt ab: Gate bestanden (PR-Branch mit genau der einen Tag-Zeile, Kommentare erhalten), Progressing,
zu junge Version, kein Downgrade, vendorisierter Chart, Direktziel PROD, Stufe TECH → PROD, Idempotenz (zweiter Lauf
pusht nichts). Die Engine lief außerdem live gegen die echten ArgoCD-APIs (ENTW: 3 Apps, Hub: 48 Apps, falscher Token
und nicht erreichbarer Server enden sauber in „blockiert“) und plant gegen das echte Repo: aktuell sind alle Versionen
gleich, es ist nichts zu übertragen. Dabei fiel auf, dass die ArgoCD-API status.sync nur liefert, wenn die
Unterfelder einzeln in fields= genannt werden; das ist berücksichtigt.

Noch nicht getestet: der Lauf auf GitHub selbst (Tailscale-Verbindung des Runners, gh pr create, Auto-Merge),
die Token-Erzeugung per API (das Konto ci existiert erst nach dem Rollout) und der Netzweg des Runners. Der erste
Lauf sollte per Run workflow mit plan_only beobachtet werden.


Fehlersuche

Skripte, Meldungen und Umgebungsvariablen: f00c0: Promotion.

gh workflow run promote-chain.yml -R pkr-lab/capulus-core -f plan_only=true     # nur planen
gh run view --log -R pkr-lab/capulus-core $(gh run list -R pkr-lab/capulus-core --workflow promote-chain.yml -L1 --json databaseId -q '.[0].databaseId')

Die Zusammenfassung des Laufs (GITHUB_STEP_SUMMARY) zeigt je App, ob das Gate erfüllt ist, welche Felder übernommen würden und warum etwas wartet.

Symptom Ursache Lösung
Kein PR trotz neuer Version auf ENTW Gate nicht erfüllt: weniger als gates.entw_hours gesund, neue Version noch nicht ausgerollt, Smoke-Check rot Zusammenfassung des Laufs lesen, ArgoCD auf ENTW prüfen (b0050)
ARGOCD_ENTW_TOKEN fehlt / ARGOCD_HUB_TOKEN fehlt Secret nicht gesetzt scripts/create-argocd-ci-token.sh hub\|entw
ArgoCD <url>: … (Verbindungsfehler) ArgoCD im Tailnet nicht erreichbar, CA, Token abgelaufen Tailscale-Verbindung des Runners (f00a0), ARGOCD_CA_FILE, Token erneuern
Ziel wird nicht überschrieben Ziel ist jünger als die Quelle (kein Downgrade) gewollt
Nur Versionsfelder wandern, andere Änderungen nicht Absicht: übertragen werden nur image.tag und exakte Chart-Versionen Rest von Hand per PR
PROD-PR wird nie automatisch gemergt Absicht (TECH optional per AUTOMERGE_TECH) PR prüfen und mergen
kubectl-Smoke-Check gegen SMOKE_IP_* schlägt fehl Adresse falsch oder Dienst nicht erreichbar SMOKE_IP_ENTW und SMOKE_IP_TECH prüfen
Doppelte oder veraltete PRs Läufe stündlich, PR-Branch wird aktualisiert offene PRs der Promotion ansehen, überholte schließen

Mit cubi lassen sich ArgoCD-Zustand und Branch-Stände ansehen. Allgemeine Fehlersuche: zentrale Fehlersuche.