PKR-Lab

f0060 - Build Workload Images — automatisierte Custom-Image-Builds

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/f-cicd-automatisierung/f0060-build-images.md

Build Workload Images — automatisierte Custom-Image-Builds

.github/workflows/build-images.yml
baut und pusht die drei selbst gebauten Workload-Images —
pacman, carplay-api, ticket-gate, isc-news-bot,
alert-caller (nur Dockerfile, das Skript kommt per ConfigMap) und n8n (dessen image/Dockerfile) —
automatisch nach GHCR, sobald der jeweilige Build-Kontext auf main
geändert wird. Vorher musste dafür manuell ein Kaniko-Build in Argo Workflows
angestoßen werden, das bei jeder Code-Änderung leicht vergessen wurde; dieser
Weg ist entfernt.


Was der Workflow tut

Trigger Bedingung
push auf main Pfad-Filter pro App (Dockerfile, Source-Verzeichnis, .dockerignore) — siehe on.push.paths im Workflow
pull_request gegen main Probebuild ohne Push: dieselben Pfad-Filter und dasselbe Gate pro App, aber push: false und kein GHCR-Login. Ein kaputtes Dockerfile oder ein Go-Fehler fällt so vor dem Merge auf. Kein Pflicht-Check (siehe f0090); die Go-Module prüft zusätzlich der Pflicht-Job go-check in f0070.
workflow_dispatch Manuell über GitHub → Actions → "Build Workload Images" → "Run workflow", App wählbar (all oder einzeln) — für einen Rebuild ohne Datei-Änderung, z. B. um ein neues Base-Image einzufangen

Ein Matrix-Job pro App:

  1. Gate-Schritt prüft per git diff gegen github.event.before, ob
    sich dieser App-Pfad im Push tatsächlich geändert hat — der
    on.push.paths-Filter oben entscheidet nur, ob der Workflow überhaupt
    läuft, nicht welche der drei Matrix-Apps betroffen ist. Ohne dieses
    Gate würde z. B. eine reine pacman-Änderung auch carplay-api und
    n8n unnötig neu bauen.
  2. Tag = sha-<kurzer-commit-sha> (z. B. sha-a1b2c3d) — bewusst pro
    Commit eindeutig statt eines wiederverwendeten Tags wie dem alten
    v1/v2-Schema.
  3. Build + Push via docker/build-push-action nach
    ghcr.io/pkr-lab/<app> (bzw. n8n-custom für n8n), Auth über den
    Standard-GITHUB_TOKEN (Job-Permission packages: write) — kein PAT,
    kein Sealed-Secret nötig, anders als beim Kaniko-Weg.
  4. Job-Summary listet den gepushten repository:tag-String.
  5. Bump-PR: bei Push auf main und workflow_dispatch öffnet der Lauf einen PR, der image.tag in der
    values.yaml der App (argocd/apps/tech/<app>/values.yaml) auf den neuen Tag setzt (Branch
    bump/<app>-image, Label image-bump, Werkzeug scripts/bump-image-tag.py:
    ändert nur die eine Zeile, Kommentare bleiben). Es ist ein PR, kein Commit: er läuft durch die Pflicht-Checks
    (f0090), der Merge ist der Rollout. Er braucht ein PAT (PROMOTE_TOKEN,
    ersatzweise RENOVATE_TOKEN), weil PRs mit dem Standard-Token keine CI auslösen; ohne PAT bleibt es beim
    Hinweis im Summary. Steht der Tag schon richtig, passiert nichts; ein offener PR wird aktualisiert.

Chronik: pacman-Build rot vom 2026-09-03 bis 2026-09-19

Ein Renovate-Merge (geoip2-golang v1 → v2) beschädigte am 2026-09-03 pacmans
go.mod (die v1-Zeile wurde überschrieben, der Code importiert weiter den v1-Pfad).
Der Push-Build lief drei Minuten später rot (no required module provides package github.com/oschwald/geoip2-golang), aber nach dem Merge und ohne Benachrichtigung;
das laufende Image v8 war nicht betroffen. Beim nächsten Lauf, der pacman baute
(2026-09-19), fiel es auf. Behoben durch Zurücksetzen auf geoip2-golang v1.13.0
und Entfernen der ungenutzten v2-Zeile; der Probebuild auf PRs und der Job go-check
verhindern eine Wiederholung. Am selben Tag waren Läufe zusätzlich rot, weil der
Layout-Umzug (workloads/ → tech/) die Pfade im Workflow überholt hatte
(path "argocd/apps/workloads/pacman" not found (alter Pfad, heute argocd/apps/tech/pacman)), behoben mit dem Umzug selbst.

Was der Workflow NICHT tut


Ablauf nach einer Code-Änderung

  1. Dockerfile/Source unter argocd/apps/tech/<app>/ ändern, committen,
    nach main pushen.
  2. GitHub → Actions → "Build Workload Images" abwarten (baut nur die App(s),
    deren Pfad sich geändert hat), Job-Summary öffnen → gepushten Tag
    kopieren.
  3. Den automatisch geöffneten Bump-PR prüfen und mergen (er setzt image.tag in
    argocd/apps/tech/<app>/values.yaml; ohne PAT den Tag von Hand eintragen).
  4. ArgoCD synct wie gewohnt (siehe b0010-argocd.md).

GHCR-Package-Sichtbarkeit

Frisch gepushte GHCR-Packages sind standardmäßig privat — ohne
imagePullSecrets scheitert der Pod dann mit ImagePullBackOff. Gleiche
Falle/Lösung wie früher beim Kaniko-Weg, siehe
pacman/README.md.

Verhältnis zu Kaniko

Das frühere Argo-WorkflowTemplate kaniko-build-push ist entfernt (2026-10-18). Für Ad-hoc-Builds anderer Images nutzt man docker build und docker push lokal oder ergänzt die Matrix in build-images.yml.


Fehlersuche

Logs: GitHub → Actions → „Build Workload Images“ → Job build <app>. Details zu allen Workflows: f00c0.

Symptom Ursache Lösung
Workflow läuft nach einer Änderung nicht Pfadfilter: die Änderung liegt außerhalb der gelisteten Pfade Pfade im Workflow prüfen, sonst manuell starten (Build Workload Images, App wählen)
Build schlägt bei go build/npm ci fehl Quellcode oder Abhängigkeiten lokal nachstellen (Nutzung: Lokale Prüfungen)
Push nach ghcr.io/pkr-lab scheitert (denied) Paketrechte, GITHUB_TOKEN ohne packages: write Berechtigungen des Workflows und Paket-Sichtbarkeit prüfen
Bump-PR wird nicht erstellt RENOVATE_TOKEN fehlt oder abgelaufen (PRs mit GITHUB_TOKEN lösen keine CI aus) Secret prüfen (Token-Register)
bump-image-tag.py: erwartet genau ein image.tag values.yaml hat keinen oder mehrere image.tag Chart anpassen
unveraendert im Log Tag stimmt schon (Exit 3) kein Fehler
Pod bleibt auf dem alten Image Bump-PR nicht gemergt oder ArgoCD noch nicht synchron PR prüfen, ArgoCD
Pod ImagePullBackOff nach dem Bump Tag existiert nicht (Build noch nicht fertig) oder Image privat Tag in der Registry prüfen

Allgemeine Fehlersuche: zentrale Fehlersuche.