Zum Inhalt springen
Trainingslager IT-Trainingslager

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 -n gilt der Namespace des Kontexts – auch für Helm.
  • In Skripten immer --kube-context und -n setzen.

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 -1

Release-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 notes

Werte 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-hooks

Hooks 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.yaml

Was 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 notes

CI 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-conflicts

Niemals ohne Nachdenken

  • kubectl delete secret -l owner=helm – löscht Helms Gedächtnis.
  • --force-replace, --cascade=orphan, kubectl delete crd – vorher sichern.
  • --reuse-values in Pipelines – verschluckt neue Standards.
  • Geheimnisse per --set – stehen in jeder Revision im Klartext.
  • Upgrades ohne --wait – kaputte Revisionen werden „letzte gute“.
  • --force-conflicts pauschal 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