Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: Ausliefern – Image, kustomize, Helm

Ziel: Den site-operator auslieferbar machen: Dockerfile statisch prüfen, mit ko ein Image ohne Docker bauen, mit kustomize ein Installations-Manifest rendern und mit dem Kubebuilder-Plugin helm/v2-alpha ein Helm-Chart erzeugen – installiert und geprüft in envtest · Dauer: ca. 120 min · Voraussetzung: Tag 11

Briefing

  • Ein Operator ist zwei Artefakte: ein Image (der Manager) und Manifeste (CRDs, RBAC, Deployment, Webhook-Konfiguration).
  • Kubebuilder liefert beides schon mit: Dockerfile (distroless, nonroot) und config/ (kustomize). make build-installer macht daraus eine Datei.
  • ko baut Go-Images ohne Docker-Daemon und ohne Dockerfile – ideal, wenn der Docker-Platz knapp ist.
  • Das Plugin helm/v2-alpha erzeugt aus derselben kustomize-Ausgabe ein Chart unter dist/chart.
  • envtest hat keine Nodes: Pods starten nie. Du prüfst, was installiert wird – nicht, ob es läuft. Dafür gibt es optional kind.
cmd/ + internal/ --docker build / ko build--> Image (distroless, UID 65532)
config/          --kustomize build---------> dist/install.yaml
dist/install.yaml --kubebuilder edit helm--> dist/chart/ --helm install--> envtest

Drill 1: Arbeitsstand und Werkzeuge

source ~/op-lab/env.sh
cp -r ~/op-lab/tag11-site-operator ~/op-lab/tag12-site-operator
cd ~/op-lab/tag12-site-operator

Heute brauchst du zwei zusätzliche Binaries: ko und helm. Beide kommen als einzelne Datei nach ~/op-lab/bin – nichts wird global installiert. (Die Makefile-Targets install-helm würden dagegen nach /usr/local/bin schreiben.)

KO=https://github.com/ko-build/ko/releases/download/v0.19.1
curl -sL $KO/ko_0.19.1_Darwin_arm64.tar.gz | tar xz -C ~/op-lab/bin ko
curl -sL https://get.helm.sh/helm-v4.3.0-darwin-arm64.tar.gz \
  | tar xz -C ~/op-lab/bin --strip-components=1 darwin-arm64/helm
ko version && helm version --short

Erwartet:

0.19.1
v4.3.0+gbec5b06

Auf einem Intel-Mac heißen die Archive …Darwin_x86_64 bzw. …darwin-amd64.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Das Dockerfile lesen und prüfen

grep -vE '^\s*#|^$' Dockerfile | cut -c1-80

Erwartet:

ARG BASE_IMAGE=golang:1.26
FROM ${BASE_IMAGE} AS builder
ARG TARGETOS
ARG TARGETARCH
WORKDIR /workspace
COPY go.mod go.mod
COPY go.sum go.sum
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o ma
FROM gcr.io/distroless/static:nonroot
WORKDIR /
COPY --from=builder /workspace/manager .
USER 65532:65532
ENTRYPOINT ["/manager"]

Zwei Stufen: Im golang-Image wird statisch gebaut – übrigens nur cmd/main.go plus importierte Pakete, deshalb lag der Readiness-Check an Tag 11 in internal/health (CGO_ENABLED=0), ins Laufzeit-Image kommt nur das Binary – keine Shell, kein Paketmanager, UID 65532. go mod download steht vor COPY . ., damit der Modul-Layer im Cache bleibt, solange go.mod sich nicht ändert.

Bauen musst du nicht, um Fehler zu finden. BuildKit hat einen Linter, der nur das Dockerfile auswertet:

docker build --check . 2>&1 | tail -1

Erwartet:

Check complete, no warnings found.

Jetzt eine kaputte Kopie mit zwei typischen Fehlern:

mkdir -p lab
sed -e 's/ AS builder/ as builder/' -e 's|^ENTRYPOINT .*|ENTRYPOINT /manager|' \
  Dockerfile > lab/Dockerfile.kaputt
docker build --check -f lab/Dockerfile.kaputt . 2>&1 | grep -A1 WARNING \
  | cut -c1-80

Erwartet:

WARNING: FromAsCasing - https://docs.docker.com/go/dockerfile/rule/from-as-casin
'as' and 'FROM' keywords' casing do not match
--
WARNING: JSONArgsRecommended - https://docs.docker.com/go/dockerfile/rule/json-a
JSON arguments recommended for ENTRYPOINT to prevent unintended behavior related

Warum ist die zweite Warnung für einen Operator wichtig? In der Shell-Form startet /bin/sh -c /manager – das SIGTERM beim Pod-Stopp bekommt die Shell, nicht der Manager. Er beendet sich dann nicht sauber und gibt die Leader-Lease nicht frei (Tag 11). Im distroless-Image gibt es außerdem gar keine Shell: Der Container startet überhaupt nicht.

Tipp: docker build --check lädt nur Metadaten der Basis-Images, baut nichts und belegt keinen Platz in der Docker-VM. Wer hadolint installiert hat, bekommt mit hadolint Dockerfile weitere Regeln.

Fortschritt speichern? Kostenlos registrieren

Drill 3: ko – ein Image ohne Docker

ko ruft go build auf und legt das Binary als Layer auf ein Basis-Image. Eine kleine Konfiguration wählt dasselbe distroless-Image wie das Dockerfile:

cat > .ko.yaml <<'EOF'
defaultBaseImage: gcr.io/distroless/static:nonroot
builds:
  - id: manager
    main: ./cmd
    ldflags:
      - -s -w
EOF
export KO_DOCKER_REPO=registry.lab.example/site-operator
ko build ./cmd --push=false --bare --platform=linux/amd64 --sbom=none \
  --tarball=lab/manager.tar --image-refs=lab/image.txt 2>&1 | tail -2
cat lab/image.txt
ls -lh lab/manager.tar | awk '{print $5}'

Erwartet (Digest gekürzt):

2026/10/10 11:48:22 Saving lab/manager.tar
2026/10/10 11:48:28 Saved lab/manager.tar
registry.lab.example/site-operator@sha256:b4a31e6466a9...
20M

--push=false plus --tarball heißt: Image bauen, als Datei ablegen, nichts hochladen, Docker nicht anfassen. registry.lab.example ist ein Platzhalter. Was steckt drin?

cfg=$(tar -xOf lab/manager.tar manifest.json | jq -r '.[0].Config')
tar -xOf lab/manager.tar "$cfg" \
  | jq -c '{arch: .architecture, user: .config.User, ep: .config.Entrypoint}'

Erwartet:

{"arch":"amd64","user":"65532","ep":["/ko-app/cmd"]}

Gleicher Sicherheitsstand wie mit dem Dockerfile (nonroot, statisch), aber in Sekunden und ohne Docker-VM.

Achtung: ko benennt das Binary nach dem Paketverzeichnis (/ko-app/cmd). Das Kubebuilder-Deployment in config/manager/manager.yaml startet aber command: [/manager] – mit einem ko-Image gibt das CrashLoopBackOff. Entweder command im Manifest entfernen (dann gilt der Entrypoint) oder beim Dockerfile bleiben.

Fortschritt speichern? Kostenlos registrieren

Drill 4: kustomize – ein Manifest für alles

make build-installer setzt das Image in config/manager und rendert config/default in eine Datei:

make build-installer IMG=registry.lab.example/site-operator:0.1.0 >/dev/null
grep '^kind:' dist/install.yaml | sort | uniq -c
grep 'image:' dist/install.yaml

Erwartet:

   2 kind: Certificate
   6 kind: ClusterRole
   2 kind: ClusterRoleBinding
   1 kind: CustomResourceDefinition
   1 kind: Deployment
   1 kind: Issuer
   1 kind: MutatingWebhookConfiguration
   1 kind: Namespace
   1 kind: Role
   1 kind: RoleBinding
   2 kind: Service
   1 kind: ServiceAccount
   1 kind: ValidatingWebhookConfiguration
              image:
              image:
        image: registry.lab.example/site-operator:0.1.0

Eine Datei, die ein Kunde mit kubectl apply -f einspielen kann – CRD, Namespace, RBAC, Deployment, Metrik-Service, Webhook-Konfigurationen und cert-manager-Objekte. Achte auf den Nebeneffekt: kustomize edit set image hat config/manager/kustomization.yaml geändert. Das gehört in Git – oder du setzt es vor dem Commit zurück.

Nimmt der API-Server das alles an? envtest ist zum Wegwerfen da. Terminal 1: Control Plane ohne CRDs starten (die bringt das Manifest mit):

source ~/op-lab/env.sh
envtest-up

Terminal 2:

kubectl apply --server-side -f dist/install.yaml > lab/apply.log 2>&1
grep -c serverside-applied lab/apply.log
grep -o 'no matches for kind "[A-Za-z]*"' lab/apply.log | sort | uniq -c

Erwartet:

18
   2 no matches for kind "Certificate"
   1 no matches for kind "Issuer"

18 Objekte kommen an – alles bis auf Certificate und Issuer. Seit Tag 8 hat der Operator Webhooks, und deren TLS-Zertifikat stellt cert-manager aus. Ohne cert-manager im Cluster ist install.yaml nicht installierbar; das gehört als Voraussetzung in jede Installationsanleitung.

Für die Helm-Drills brauchst du wieder ein leeres envtest: Terminal 1 mit Ctrl+C stoppen und envtest-up neu starten. (Löschen hilft nicht: envtest hat keinen Namespace-Controller, site-operator-system bliebe für immer Terminating.)

Fortschritt speichern? Kostenlos registrieren

Drill 5: Ein Overlay für Produktion

config/default ist die Basis. Kundenspezifisches gehört in ein Overlay, nicht in die Basis – sonst überschreibt der nächste kubebuilder-Lauf deine Änderungen:

mkdir -p config/overlays/prod
cat > config/overlays/prod/kustomization.yaml <<'EOF'
resources:
- ../../default
images:
- name: controller
  newName: registry.lab.example/site-operator
  newTag: 0.1.0
patches:
- target:
    kind: Deployment
    name: controller-manager
  patch: |-
    - op: replace
      path: /spec/replicas
      value: 2
    - op: add
      path: /spec/template/spec/containers/0/args/-
      value: --zap-encoder=json
    - op: replace
      path: /spec/template/spec/containers/0/resources/limits/memory
      value: 256Mi
EOF
bin/kustomize build config/overlays/prod \
  | grep -E '^  replicas|zap-encoder|memory: 256|image: registry'

Erwartet:

  replicas: 2
        - --zap-encoder=json
        image: registry.lab.example/site-operator:0.1.0
            memory: 256Mi

Zwei Replicas sind nur mit --leader-elect sinnvoll – das setzt config/manager/manager.yaml schon. Das Patch-Ziel controller-manager ist der Name aus der Basis ohne Präfix – kustomize findet Ressourcen auch unter ihrem ursprünglichen Namen.

Tipp: Flags im Overlay prüft niemand beim Rendern. Ein Tippfehler fällt erst beim Start auf (flag provided but not defined) – im Cluster als CrashLoop. Deshalb bin/manager --help | grep <flag> vor dem Release.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Helm-Chart mit dem Kubebuilder-Plugin

Kubebuilder v4.16 bringt das Plugin helm/v2-alpha mit (das ältere helm/v1-alpha taucht in kubebuilder help nicht mehr auf). Es liest dist/install.yaml und baut daraus ein Chart:

kubebuilder edit --plugins=helm/v2-alpha 2>&1 | grep -o 'added Helm.*' | cut -c1-80
ls dist/chart dist/chart/templates

Erwartet:

added Helm deployment targets to Makefile targets=helm-deploy, helm-uninstall, h
dist/chart:
Chart.yaml
templates
values.yaml

dist/chart/templates:
_helpers.tpl
cert-manager
crd
manager
metrics
network-policy
NOTES.txt
prometheus
rbac
webhook

Die Unterordner spiegeln config/. Die Makefile-Targets (helm-deploy …) installieren Helm bei Bedarf global – im Lab nutzt du helm direkt. Die Werte sind übersichtlich:

grep -vE '^\s*#|^\s*$' dist/chart/values.yaml | head -8
grep -E '^[a-zA-Z]+:' dist/chart/values.yaml | tr -d ':' | xargs

Erwartet:

manager:
  enabled: true
  replicas: 1
  image:
    repository: controller
    pullPolicy: IfNotPresent
  args:
    - --leader-elect
manager rbac serviceAccount crd metrics certManager webhook prometheus networkPolicy

Achtung: Das Plugin ruft intern noch einmal make build-installer ohne IMG auf. Danach steht in values.yaml repository: controller und in config/manager/kustomization.yaml wieder controller:latest. Das Image setzt du deshalb beim Installieren (--set) oder in einer eigenen Values-Datei – nie im generierten Chart.

Chart.yaml überschreibt das Plugin nie, alles andere mit --force. Workflow bei API-Änderungen: make manifests build-installer, dann kubebuilder edit --plugins=helm/v2-alpha.

helm lint dist/chart
helm template site-operator dist/chart -n site-operator-system \
  --set manager.image.repository=registry.lab.example/site-operator \
  | grep '^kind:' | sort | uniq -c

Erwartet:

==> Linting dist/chart
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed
   2 kind: Certificate
   3 kind: ClusterRole
   2 kind: ClusterRoleBinding
   1 kind: CustomResourceDefinition
   1 kind: Deployment
   1 kind: Issuer
   1 kind: MutatingWebhookConfiguration
   1 kind: Role
   1 kind: RoleBinding
   2 kind: Service
   1 kind: ServiceAccount
   1 kind: ValidatingWebhookConfiguration

Fortschritt speichern? Kostenlos registrieren

Drill 7: Helm-Install in envtest

envtest hat keine Nodes – aber CRD, RBAC und Deployment nimmt der API-Server an, und Helm verwaltet das Release wie in einem echten Cluster. Das frisch gestartete envtest aus Drill 4 ist leer. Ohne cert-manager scheitert das Chart wie install.yaml – für den Lab-Test schaltest du die Zertifikate ab:

helm install site-operator dist/chart -n site-operator-system --create-namespace \
  --set manager.image.repository=registry.lab.example/site-operator \
  --set manager.image.tag=0.1.0 --set certManager.enabled=false | head -4
helm list -n site-operator-system -o json \
  | jq -r '.[] | "\(.name) \(.status) \(.chart)"'
kubectl get deploy -n site-operator-system \
  -o jsonpath='{.items[0].spec.template.spec.containers[0].image}{"\n"}'

Erwartet:

NAME: site-operator
LAST DEPLOYED: Sat Oct 10 11:50:08 2026
NAMESPACE: site-operator-system
STATUS: deployed
site-operator deployed site-operator-0.1.0
registry.lab.example/site-operator:0.1.0

Achtung: Jetzt zeigen Webhook-Konfigurationen und die Conversion der CRD (Tag 9) auf einen Service ohne Pods. Anfragen, die einen Webhook brauchen, laufen in den Timeout (… webhook … context deadline exceeded) – das Bild „Webhook down” aus Tag 15. Im echten Cluster startet der Pod, in envtest nie.

Ein Upgrade mit zwei Replicas, dann Deinstallation:

helm upgrade site-operator dist/chart -n site-operator-system --reuse-values \
  --set manager.replicas=2 >/dev/null
kubectl get deploy -n site-operator-system -o jsonpath='{.items[0].spec.replicas}{"\n"}'
helm uninstall site-operator -n site-operator-system
kubectl get crd
kubectl apply -f lab/site.yaml
kubectl get staticsites.v1alpha1.web.lab.example 2>&1 | cut -c1-80

Erwartet:

2
These resources were kept due to the resource policy:
[CustomResourceDefinition] staticsites.web.lab.example

release "site-operator" uninstalled
NAME                          SCOPE        VERSIONS               CREATED AT
staticsites.web.lab.example   Namespaced   v1(storage),v1alpha1   2026-10-10T09:49:28Z
staticsite.web.lab.example/demo created
Warning: v1alpha1 ist veraltet, nutze v1
Error from server (StorageReadError): failed to read one or more staticsites.web

Die CRD bleibt: Das Chart setzt helm.sh/resource-policy: keep (crd.keep: true). Würde Helm die CRD löschen, wären mit ihr alle StaticSites aller Kunden weg – der teuerste Tippfehler im Operator-Betrieb. Die Kehrseite zeigen die letzten beiden Zeilen: Die verbliebene CRD verweist weiter auf den Conversion-Webhook des gelöschten Operators (spec.conversion.strategy: Webhook). v1 geht noch (Storage-Version, keine Konvertierung), jeder Client, der v1alpha1 liest, scheitert – bis der Operator zurück ist. Einen Operator mit Conversion deinstalliert man nie „mal eben”.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Ausblick – E2E in kind (optional)

Kubebuilder hat unter test/e2e/ schon einen End-to-End-Test: Er baut das Image, lädt es in einen kind-Cluster, macht make deploy und prüft, ob der Manager-Pod läuft und Metriken liefert. Das kostet etwa 2–3 GB in der Docker-VM. Erst prüfen:

colima ssh -- df -h / | tail -1

Erwartet (Beispiel):

/dev/root        19G   16G  2.6G  86% /

Unter 2 GB frei: Diesen Drill nur lesen. Sonst – und nur mit einem eigenen, frisch angelegten Cluster:

export KUBECONFIG=~/op-lab/kind-e2e.kubeconfig   # nicht envtest überschreiben
export KIND_CLUSTER=site-e2e
make test-e2e
kind delete cluster --name site-e2e
docker image rm example.com/site-operator:v0.0.1
rm ~/op-lab/kind-e2e.kubeconfig
export KUBECONFIG=~/op-lab/envtest.kubeconfig

Erwartet (gekürzt, kann je nach Version abweichen):

Creating cluster "site-e2e" ...
Running Suite: e2e suite
  Manager should run successfully
  Manager should ensure the metrics endpoint is serving metrics
Ran 2 of 2 Specs in 96.412 s
SUCCESS! -- 2 Passed | 0 Failed | 0 Pending | 0 Skipped
Deleting cluster "site-e2e" ...

make test-e2e legt den Cluster selbst an (setup-test-e2e), installiert cert-manager (überspringbar mit CERT_MANAGER_INSTALL_SKIP=true) und räumt ihn danach mit cleanup-test-e2e wieder ab; das kind delete ist das Sicherheitsnetz, falls der Test abbricht. Den Cluster eines anderen Projekts (bei dir z. B. seclab) fasst das nicht an – prüfe trotzdem vorher mit kind get clusters, dass site-e2e noch nicht existiert.

Achtung: kind schreibt den neuen Cluster in die Datei aus KUBECONFIG und macht ihn zum aktuellen Kontext. Ohne die erste Zeile landete er in envtest.kubeconfig – oder, ohne env.sh, in ~/.kube/config neben deinen echten Clustern.

Fortschritt speichern? Kostenlos registrieren

Drill 9: OLM und Operator SDK in fünf Minuten

Der Operator Lifecycle Manager (OLM) installiert und aktualisiert Operatoren aus Katalogen; OpenShift bringt ihn mit (OperatorHub). Dafür braucht es ein Bundle: CRDs, RBAC, Deployment und eine ClusterServiceVersion (CSV) mit Beschreibung, Icon und Upgrade-Pfad.

Werkzeug Aufgabe Stand Oktober 2026
Operator SDK Kubebuilder-Plugins + Bundle-Werkzeuge v1.42.x
OLM v0 Subscription, CatalogSource, CSV v0.46.x
OLM v1 (operator-controller) ClusterExtension, ClusterCatalog v1.12.x

Der Weg mit dem Operator SDK sieht so aus (nur lesen, nicht im Lab ausgeführt):

operator-sdk generate kustomize manifests -q   # Basis-CSV unter config/manifests
make bundle IMG=registry.lab.example/site-operator:0.1.0 VERSION=0.1.0
operator-sdk bundle validate ./bundle --select-optional suite=operatorframework
BUNDLE_IMG=registry.lab.example/site-operator-bundle:v0.1.0
make bundle-build bundle-push BUNDLE_IMG=$BUNDLE_IMG
operator-sdk run bundle $BUNDLE_IMG

Die Targets bundle, bundle-build und bundle-push gibt es nur in Projekten, die mit operator-sdk init angelegt wurden; ein reines Kubebuilder-Projekt ergänzt sie per Hand oder nutzt das Helm-Chart. Für OpenShift-Kunden mit zertifizierten Katalogen führt kein Weg am Bundle vorbei – für alle anderen reicht meist Helm oder install.yaml.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

envtest (Terminal 1) läuft, das Release ist deinstalliert:

cat > lab/check.sh <<'EOF'
ok()  { echo "✔ $1"; }
nok() { echo "✘ $1"; }
docker build --check . >/dev/null 2>&1 && ok "Dockerfile-Check" || nok "Dockerfile"
[ -s lab/manager.tar ] && ok "ko-Image als Tarball" || nok "ko-Tarball fehlt"
grep -q 'kind: CustomResourceDefinition' dist/install.yaml \
  && ok "install.yaml mit CRD" || nok "install.yaml"
bin/kustomize build config/overlays/prod | grep -q 'replicas: 2' \
  && ok "Prod-Overlay" || nok "Overlay"
helm lint dist/chart >/dev/null 2>&1 && ok "helm lint" || nok "helm lint"
helm template t dist/chart | grep -q 'resource-policy": keep' \
  && ok "CRD bleibt bei uninstall" || nok "CRD-Policy"
kubectl get crd staticsites.web.lab.example >/dev/null 2>&1 \
  && ok "CRD nach uninstall vorhanden" || nok "CRD gelöscht"
EOF
bash lab/check.sh

Erwartet:

✔ Dockerfile-Check
✔ ko-Image als Tarball
✔ install.yaml mit CRD
✔ Prod-Overlay
✔ helm lint
✔ CRD bleibt bei uninstall
✔ CRD nach uninstall vorhanden

Challenge

Schreibe lab/values-prod.yaml für das Chart: Image registry.lab.example/site-operator:0.1.0, zwei Replicas, JSON-Logs. Prüfe mit helm template, dass der Manager danach noch mit --leader-elect startet.

Hinweis: Helm ersetzt Listen aus values.yaml komplett, statt sie zu ergänzen.

Lösung

cat > lab/values-prod.yaml <<'EOF'
manager:
  replicas: 2
  image:
    repository: registry.lab.example/site-operator
    tag: 0.1.0
  args:
    - --leader-elect
    - --zap-encoder=json
EOF
helm template site-operator dist/chart -f lab/values-prod.yaml \
  | grep -E '^  replicas:|--leader-elect|--zap-encoder|image: '

Erwartet:

  replicas: 2
        - --leader-elect
        - --zap-encoder=json
        image: "registry.lab.example/site-operator:0.1.0"

Ohne --leader-elect in der Liste liefen zwei Replicas als zwei aktive Controller – genau der Fall, den Tag 11 verhindert. Der Code-Stand in code/tag12-site-operator enthält die Challenge nicht.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Images per Digest ausliefern (image@sha256:…), signieren (cosign/Sigstore) und mit SBOM versehen; ko erzeugt SBOMs nativ (--sbom=spdx), für das Dockerfile übernimmt das docker buildx build --sbom=true.
  • Air-gapped Kunden: Image und Chart als OCI-Artefakte spiegeln (helm push dist/chart-0.1.0.tgz oci://…, crane copy); Basis-Images (distroless, golang) über die eigene Registry beziehen (BASE_IMAGE-Argument im Dockerfile).
  • OpenShift: Die Restricted-SCC vergibt eine zufällige UID – das distroless-Image läuft damit, weil es nichts ins Dateisystem schreibt. runAsUser: 65532 nicht hart im Deployment setzen.
  • CRDs getrennt vom Operator verwalten (eigenes Chart oder crd.enabled: false und separates Release): CRD-Upgrades sind Cluster-Änderungen mit eigener Freigabe, Operator-Upgrades nicht.
  • Für OperatorHub/zertifizierte OpenShift-Kataloge braucht es ein OLM-Bundle (Drill 9); für alle anderen Kunden sind Helm-Chart plus install.yaml der kleinste gemeinsame Nenner.