Anhang A: Spickzettel
Die wichtigsten Befehle und Muster aus Tag 0 bis 20, nach Thema
geordnet. Die Tage stehen in Klammern. Platzhalter in spitzen Klammern
ersetzt du. Werte wie lab-key-123 und
lab-zot-123 sind Laborwerte. Alle Befehle laufen auf
prod, die Registry ist zot unter
localhost:30500 (HTTP, deshalb
--plain-http).
Gelände und Umgebung (Tag 0)
# auf prod
export KUBECONFIG=$HOME/.kube/config
helm version --short
helm env | grep -E 'NAMESPACE|KUBECONTEXT'
helm list --short --kube-context helm-lab -n default- Ohne
-ngilt der Namespace des Kontexts – auch für Helm. - In Skripten immer
--kube-contextund-nsetzen.
Lebenszyklus (Tag 1, 13)
# auf prod
helm repo add zot https://zotregistry.dev/helm-charts && helm repo update
helm search repo zot/zot --versions | head -3
helm show values zot/zot --version 0.1.134 | grep -A3 '^service:'
helm pull zot/zot --version 0.1.134 --untar
helm install <rel> <chart> -n <ns> --create-namespace -f werte.yaml --wait
helm upgrade --install <rel> <chart> -n <ns> -f werte.yaml --wait --timeout 5m \
--rollback-on-failure --history-max 5 --description "Ticket LAB-1"
helm rollback <rel> [<rev>] -n <ns> --wait --description "zurück, Ticket LAB-2"
helm uninstall <rel> -n <ns> [--keep-history]Inspektion – die erste Minute (Tag 1, 13, 19)
# auf prod
helm list -A # Helm 4: jeder Status
helm list -A --failed --pending # nach aktueller Revision
helm status <rel> -n <ns> # inkl. Ressourcen und Pods
helm history <rel> -n <ns> --show-rollback-revision
helm get values <rel> -n <ns> [--all] [--revision N]
helm get manifest <rel> -n <ns> [--revision N]
helm get hooks <rel> -n <ns>
helm get notes <rel> -n <ns>
helm get metadata <rel> -n <ns> # APPLY_METHOD, Version
kubectl -n <ns> get events --field-selector reason=Failed \
-o custom-columns=MELDUNG:.message | tail -1Release-Secret lesen (Tag 13):
# auf prod
kubectl -n <ns> get secret -l owner=helm,name=<rel> \
--sort-by=.metadata.creationTimestamp
kubectl -n <ns> get secret sh.helm.release.v1.<rel>.v<N> -o jsonpath='{.data.release}' \
| base64 -d | base64 -d | gzip -d | jq -c '.config.global, .info.status'Werte und Vorrang (Tag 3)
values.yaml < -f a.yaml <
-f b.yaml < --set (rechts gewinnt).
# auf prod
helm install x ./notes --dry-run=client -o json --set a=1 | jq .config
--set-string env.NOTES_PAGE_SIZE=25 # String, Schema verlangt ihn
--set 'hosts={a.lab,b.lab}' # Liste
--set-json 'resources={"limits":{"memory":"64Mi"}}'
--set-file motd=motd.txt
--set key=null # Standard löschen| Upgrade mit | Standardwerte | eigene Werte |
|---|---|---|
| nichts | neue | der letzten deployed-Revision |
-f/--set |
neue | nur die angegebenen |
--reuse-values |
alte (berechnet) | alte + neue |
--reset-then-reuse-values |
neue | alte + neue |
--reset-values |
neue | nur die angegebenen |
Listen werden ersetzt, Maps gemischt – Umgebungsvariablen als Map anlegen.
Template-Muster (Tag 4–8)
{{/* rendern: helm template <rel> ./notes -s templates/<datei>.yaml */}}
metadata:
labels:
{{- include "notes.labels" . | nindent 4 }} # nindent, nie indent
spec:
replicas: {{ hasKey .Values "replicaCount" | ternary .Values.replicaCount 2 }}
template:
metadata:
annotations:
checksum/config: {{ include (print $.Template.BasePath "/config.yaml") .
| sha256sum }}
spec:
{{- with .Values.nodeSelector }}
nodeSelector:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- image: {{ printf "%s:%s" .Values.image.repository
(.Values.image.tag | default .Chart.AppVersion) | quote }}
env:
- name: NOTES_API_KEY
valueFrom:
secretKeyRef:
name: {{ required "apiKey.existingSecret fehlt"
.Values.apiKey.existingSecret }}
key: api-key{{- range .Values.ingress.hosts }}
- host: {{ tpl . $ | quote }} # $ = Wurzel im range
service: {{ include "notes.fullname" $ }}
{{- end }}
{{- if .Capabilities.APIVersions.Has "gateway.networking.k8s.io/v1" }} … {{- end }}
uid: {{ dig "metadata" "uid" "leer" (lookup "v1" "Namespace" "" "kube-system") }}
sekunden: {{ durationSeconds .Values.shutdownTimeout }} # neu in Helm 4.3
data:
{{- (.Files.Glob "config/*.conf").AsConfig | nindent 2 }}| Falle | Abhilfe | Tag |
|---|---|---|
default schluckt 0/false |
hasKey + ternary, kindIs |
5 |
{{- … -}} klebt Zeilen |
nur einseitig trimmen, rendern | 5 |
. im range/with |
$ für die Wurzel |
5 |
template … \| nindent |
include |
6 |
quote rettet 1.20 nicht |
in der Werte-Datei quoten | 4 |
lookup leer bei template, Argo CD |
Template muss leeren Fall können | 7, 18 |
randAlphaNum im Secret |
lookup + Wiederverwendung oder
existingSecret |
7 |
.Files liefert "" |
Pfad, .helmignore, nicht in
templates/ |
8 |
Schema (Tag 8, 9)
{"$schema": "http://json-schema.org/draft-07/schema#", "type": "object",
"additionalProperties": false, "required": ["apiKey"],
"properties": {"replicaCount": {"type": ["integer", "null"], "minimum": 0},
"postgres": {"type": "object"}, "global": {"type": "object"}}}Greift bei install, upgrade,
lint, template. Subchart-Schlüssel und
global erlauben, sonst „additional properties … not
allowed“.
Subcharts und Library Charts (Tag 9, 10)
# Chart.yaml
dependencies:
- name: postgres
version: "~0.1.0"
repository: oci://localhost:30500/charts
condition: postgres.enabled
- name: plattform
version: "~0.1.0"
repository: oci://localhost:30500/charts# auf prod
helm dependency update notes --plain-http # löst Bereich auf, schreibt Chart.lock
helm dependency build notes --plain-http # baut genau nach Chart.lock
helm dependency list notesWerte des Subcharts unter seinem Namen
(postgres.enabled), gemeinsame Werte unter
global. type: library ist nicht
installierbar.
Hooks und Tests (Tag 11)
metadata:
annotations:
"helm.sh/hook": post-install,pre-upgrade
"helm.sh/hook-weight": "0"
"helm.sh/hook-delete-policy": before-hook-creation# auf prod
helm test <rel> -n <ns> --logs
helm upgrade <rel> <chart> -n <ns> --no-hooksHooks gehören nicht zum Release (überleben uninstall),
pre-install läuft vor allen Objekten – auch vor Secrets und
Subcharts. Migration: post-install,pre-upgrade.
CRDs (Tag 12)
# auf prod
helm template x ./chart --include-crds
helm install x ./chart --skip-crds
helm show crds ./chart | kubectl apply --server-side --field-manager=helm -f -crds/: nur bei der Installation, nie aktualisiert, nie
gelöscht. Eigenes CRD-Chart mit
"helm.sh/resource-policy": keep.
Achtung: Eine gelöschte CRD löscht alle Objekte dieses Typs im Cluster.
Sicher ausrollen (Tag 13)
| Flag | Wirkung |
|---|---|
ohne --wait |
wartet nur auf Hooks (hookOnly) |
--wait / --wait=watcher |
wartet auf Bereitschaft (kstatus) |
--wait=legacy |
Verhalten von Helm 3 |
--wait-for-jobs |
Jobs abwarten (nur mit --wait) |
--rollback-on-failure |
Rollback bzw. Deinstallation bei Fehler, setzt
--wait |
--dry-run=server |
rendert mit Cluster und lookup, speichert nichts,
schickt die Objekte nicht zur API-Prüfung (Tag 4) |
--history-max N |
Revisionen behalten (Standard 10) |
Server-Side Apply und Helm 4 (Tag 14)
# auf prod
helm get metadata <rel> -n <ns> | grep APPLY_METHOD
helm upgrade <rel> <chart> -n <ns> --server-side=true # true|false|auto
helm upgrade <rel> <chart> -n <ns> --force-conflicts
kubectl -n <ns> get deploy <name> --show-managed-fields -o json \
| jq -r '.metadata.managedFields[]
| [.manager, .operation, .subresource // "-"] | @tsv'
helm diff upgrade <rel> <chart> -n <ns> --three-way-merge --detailed-exitcode| Helm 3 | Helm 4 |
|---|---|
--atomic |
--rollback-on-failure |
--force |
--force-replace (nicht mit SSA) |
helm list -a |
helm list (jeder Status), Filter
--deployed usw. |
--post-renderer ./skript |
--post-renderer <plugin> (Typ
postrenderer/v1) |
| Drei-Wege-Merge, Drift still überschrieben | SSA, Konflikt mit Field Manager |
OCI-Registry (Tag 15)
# auf prod
echo lab-zot-123 | helm registry login localhost:30500 -u lab-zot-user \
--password-stdin --plain-http # nur der Host
helm package notes
helm push notes-0.12.1.tgz oci://localhost:30500/charts --plain-http # stdout!
helm show chart oci://localhost:30500/charts/notes --version 0.12.1 --plain-http
helm install <rel> oci://localhost:30500/charts/notes@sha256:<digest> --plain-http
curl -s -u lab-zot-user:lab-zot-123 localhost:30500/v2/charts/notes/tags/list+ wird im Tag zu _, Tags sind
überschreibbar, der Digest nicht.
Signieren und Geheimnisse (Tag 16)
# auf prod
gpg --export-secret-keys '<Name>' > secring.gpg
helm package notes --sign --key '<Name>' --keyring secring.gpg
helm verify notes-0.12.1.tgz --keyring pubring.gpg
helm install <rel> ./notes-0.12.1.tgz --verify --keyring pubring.gpg
cosign signing-config create --out offline.json # ohne Rekor
cosign sign --key cosign.key -y --signing-config offline.json --allow-http-registry \
localhost:30500/charts/notes@<digest>
cosign verify --key cosign.pub --allow-http-registry --insecure-ignore-tlog \
localhost:30500/charts/notes:0.12.1
sops encrypt -i secrets.dev.yaml
helm upgrade <rel> ./notes -f secrets://secrets.dev.yamlWas als Wert in Helm landet, steht im Klartext im Release-Secret.
Besser: existingSecret und ein Secret von außen (ESO,
Sealed Secrets, CSI).
Prüfen ohne Cluster (Tag 17)
# auf prod
set -o pipefail
helm lint notes --strict --with-subcharts -f values/prod.yaml
for env in dev staging prod; do
helm template notes ./notes -f values/$env.yaml \
| kubeconform -strict -summary -kubernetes-version 1.37.0
done
helm template notes ./notes -f values/staging.yaml --skip-tests --no-hooks \
| kubectl apply --dry-run=server --server-side -n <staging> -f -
trivy config --severity HIGH,CRITICAL --exit-code 1 rendering.yaml
pluto detect rendering.yaml --target-versions k8s=<version>
pluto detect-helm
helm unittest notesCI und GitOps (Tag 18)
# auf prod
ct lint # liest ct.yaml, verlangt neue Version bei Änderung
ct install --namespace <ns> # installiert, helm test, deinstalliert
flux get sources oci -n <ns>
flux get helmreleases -n <ns>
kubectl kustomize --enable-helm .| Flux | Argo CD | Kustomize helmCharts |
|
|---|---|---|---|
helm list |
ja | leer | leer |
lookup |
Cluster | leer | leer |
| Hooks | Helm-Hooks | Sync-Hooks | normale Objekte |
Fehlersuche (Tag 19)
# auf prod
helm template <rel> ./chart -f werte.yaml --debug # Schicht Rendern
helm template <rel> ./chart | kubectl apply --dry-run=server -f - # Schicht API
helm rollback <rel> <letzte-deployed> -n <ns> --wait # pending-upgrade lösen
kubectl delete sts <name> --cascade=orphan # volumeClaimTemplates ändern
helm upgrade <rel> <chart> --take-ownership --force-conflictsNiemals ohne Nachdenken
kubectl delete secret -l owner=helm– löscht Helms Gedächtnis.--force-replace,--cascade=orphan,kubectl delete crd– vorher sichern.--reuse-valuesin Pipelines – verschluckt neue Standards.- Geheimnisse per
--set– stehen in jeder Revision im Klartext. - Upgrades ohne
--wait– kaputte Revisionen werden „letzte gute“. --force-conflictspauschal in Pipelines – versteckt Drift.- Installieren per Tag statt Digest, ohne Signaturprüfung.
Fehlerbilder
| Meldung | Ursache | Tag |
|---|---|---|
execution error at (notes/templates/deployment.yaml:20:20) |
required/fail im Template |
7, 19 |
YAML parse error … mapping values are not allowed |
Einrückung, indent/Minus |
5, 20 |
can't evaluate field Values in type string |
. statt $ im range |
5, 20 |
additional properties '…' not allowed |
Schema, Tippfehler, Subchart-Schlüssel | 8, 9, 20 |
library charts are not installable |
type: library |
10 |
no matches for kind |
CRD fehlt bzw. im selben Chart in templates/ |
12 |
another operation … is in progress |
verwaiste pending-*-Revision |
19, 20 |
release has no 0 version |
Rollback ohne gute Revision | 19 |
field is immutable |
Selektor, volumeClaimTemplates, Job |
6, 19, 20 |
invalid ownership metadata |
Objekt gehört keinem/anderem Release | 12, 19 |
conflict with "…" using … |
anderer Field Manager | 14, 19 |
cannot use server-side apply and force replace together |
--force-replace mit SSA |
19 |
unable to build kubernetes objects from current release manifest |
entfernte API im Release | 19 |
context deadline exceeded |
Image, Probe, Hook, PVC | 13, 19, 20 |
chart version not ok. Needs a version bump! |
ct lint ohne neue Version |
18 |
no signatures found |
Chart nicht signiert | 16, 20 |
sha256 sum does not match |
Paket nach dem Signieren verändert | 16 |
invalid registry |
registry login mit Pfad oder oci:// |
15 |
improper constraint |
_ statt + in --version |
15 |