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:
- Gate-Schritt prüft per
git diffgegengithub.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 reinepacman-Änderung auchcarplay-apiund
n8nunnötig neu bauen. - Tag =
sha-<kurzer-commit-sha>(z. B.sha-a1b2c3d) — bewusst pro
Commit eindeutig statt eines wiederverwendeten Tags wie dem alten
v1/v2-Schema. - Build + Push via
docker/build-push-actionnach
ghcr.io/pkr-lab/<app>(bzw.n8n-customfür n8n), Auth über den
Standard-GITHUB_TOKEN(Job-Permissionpackages: write) — kein PAT,
kein Sealed-Secret nötig, anders als beim Kaniko-Weg. - Job-Summary listet den gepushten
repository:tag-String. - Bump-PR: bei Push auf
mainundworkflow_dispatchöffnet der Lauf einen PR, derimage.tagin der
values.yamlder App (argocd/apps/tech/<app>/values.yaml) auf den neuen Tag setzt (Branch
bump/<app>-image, Labelimage-bump, Werkzeugscripts/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,
ersatzweiseRENOVATE_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
- Kein Direkt-Commit.
image.tagwird nie aufmaingeschrieben, sondern nur über den
Bump-PR (oben); der Merge bleibt bei dir. - Kein Deploy. Erst der Merge des Bump-PR lässt ArgoCD den neuen Stand ausrollen,
siehe b0010-argocd.md. - Kein Rebuild bei reinen
values.yaml-Änderungen — die Pfad-Filter
greifen nur aufDockerfile/Source-Verzeichnisse, nicht auf
values.yamlselbst (sonst würde der manuelle Tag-Commit aus dem
vorigen Punkt einen neuen, unnötigen Build auslösen).
Ablauf nach einer Code-Änderung
- Dockerfile/Source unter
argocd/apps/tech/<app>/ändern, committen,
nachmainpushen. - GitHub → Actions → "Build Workload Images" abwarten (baut nur die App(s),
deren Pfad sich geändert hat), Job-Summary öffnen → gepushten Tag
kopieren. - Den automatisch geöffneten Bump-PR prüfen und mergen (er setzt
image.tagin
argocd/apps/tech/<app>/values.yaml; ohne PAT den Tag von Hand eintragen). - 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.