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-alphaein 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) undconfig/(kustomize).make build-installermacht daraus eine Datei. kobaut Go-Images ohne Docker-Daemon und ohne Dockerfile – ideal, wenn der Docker-Platz knapp ist.- Das Plugin
helm/v2-alphaerzeugt aus derselben kustomize-Ausgabe ein Chart unterdist/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-operatorHeute 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 --shortErwartet:
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-80Erwartet:
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 -1Erwartet:
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-80Erwartet:
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 --checklädt nur Metadaten der Basis-Images, baut nichts und belegt keinen Platz in der Docker-VM. Werhadolintinstalliert hat, bekommt mithadolint Dockerfileweitere 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 inconfig/manager/manager.yamlstartet abercommand: [/manager]– mit einem ko-Image gibt dasCrashLoopBackOff. Entwedercommandim 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.yamlErwartet:
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-upTerminal 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 -cErwartet:
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. Deshalbbin/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/templatesErwartet:
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 ':' | xargsErwartet:
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-installerohneIMGauf. Danach steht invalues.yamlrepository: controllerund inconfig/manager/kustomization.yamlwiedercontroller: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 -cErwartet:
==> 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-80Erwartet:
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 -1Erwartet (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.kubeconfigErwartet (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
KUBECONFIGund macht ihn zum aktuellen Kontext. Ohne die erste Zeile landete er inenvtest.kubeconfig– oder, ohneenv.sh, in~/.kube/configneben 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_IMGDie 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.shErwartet:
✔ 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;koerzeugt SBOMs nativ (--sbom=spdx), für das Dockerfile übernimmt dasdocker 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: 65532nicht hart im Deployment setzen. - CRDs getrennt vom Operator verwalten (eigenes Chart oder
crd.enabled: falseund 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.yamlder kleinste gemeinsame Nenner.