Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: CRDs

Ziel: Wissen, wie Helm Custom Resource Definitions behandelt, warum CRDs im Ordner crds/ nie aktualisiert werden – und CRDs stattdessen in einem eigenen Chart versioniert und geschützt ausliefern. · Dauer: ca. 45 min · Voraussetzung: Tag 11

Briefing

  • Dateien in crds/ sind keine Templates. Helm legt sie vor allem anderen an – aber nur bei der Erstinstallation. upgrade ändert sie nie, uninstall löscht sie nie.
  • Der Grund: CRDs gelten clusterweit. Wer eine CRD löscht, löscht alle Objekte dieser Art in allen Namespaces.
  • Sauberer Weg für Updates: ein eigenes Chart nur mit CRDs in templates/, geschützt mit "helm.sh/resource-policy": keep.
 Chart mit crds/    install: CRD zuerst, dann Templates   upgrade: CRD bleibt alt
 Chart notes-crds   CRD in templates/ ── upgrade aktualisiert, uninstall: keep
 Chart notes        NoteBackup nur, wenn .Capabilities die CRD kennt

Drill 1: Eine CRD in crds/

Ein Wegwerf-Chart mit der CRD NoteBackup und einem Objekt dieser Art:

# auf prod
mkdir -p ~/helm/tag12 && cd ~/helm/tag12
mkdir -p backup/crds backup/templates
printf 'apiVersion: v2\nname: backup\nversion: 0.1.0\n' > backup/Chart.yaml
cat > backup/crds/notebackup.yaml <<'EOF'
# backup/crds/notebackup.yaml – Stand Tag 12
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: notebackups.lab.helm.example.com
spec:
  group: lab.helm.example.com
  scope: Namespaced
  names:
    kind: NoteBackup
    plural: notebackups
    singular: notebackup
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: [schedule]
              properties:
                schedule: {type: string}
                retention: {type: integer, minimum: 1}
      additionalPrinterColumns:
        - {name: Schedule, type: string, jsonPath: .spec.schedule}
EOF
cat > backup/templates/notebackup.yaml <<'EOF'
apiVersion: lab.helm.example.com/v1alpha1
kind: NoteBackup
metadata:
  name: {{ .Release.Name }}-nachts
spec:
  schedule: "0 2 * * *"
  retention: 7
EOF
helm template b ./backup | grep -E '^kind|^# Source'
helm template b ./backup --include-crds | grep -E '^kind|^# Source'
helm install b ./backup -n tag12 --create-namespace | grep STATUS
kubectl -n tag12 get notebackups
helm get manifest b -n tag12 | grep -E '^kind'

Erwartet:

# Source: backup/templates/notebackup.yaml
kind: NoteBackup
# Source: backup/crds/notebackup.yaml
kind: CustomResourceDefinition
# Source: backup/templates/notebackup.yaml
kind: NoteBackup
STATUS: deployed
NAME       SCHEDULE
b-nachts   0 2 * * *
kind: NoteBackup

helm template lässt crds/ weg, außer mit --include-crds. Bei install legt Helm die CRD zuerst an und wartet, bis die API sie kennt – darum darf dasselbe Chart sofort ein NoteBackup mitbringen. Im Manifest des Releases steht die CRD nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 2: upgrade lässt die CRD alt

Die CRD bekommt eine zweite Spalte, das Chart eine neue Version:

# auf prod
cat >> backup/crds/notebackup.yaml <<'EOF'
        - {name: Retention, type: integer, jsonPath: .spec.retention}
EOF
sed -i 's/^version: 0.1.0/version: 0.2.0/' backup/Chart.yaml
helm upgrade b ./backup -n tag12 | grep REVISION
kubectl -n tag12 get notebackups

Erwartet:

REVISION: 2
NAME       SCHEDULE
b-nachts   0 2 * * *

Keine neue Spalte, keine Warnung. Der Handweg aus vielen Anleitungen ist helm show crds | kubectl apply --server-side -f -. Unter Helm 4 scheitert er:

# auf prod
helm show crds ./backup | kubectl apply --server-side -f - 2>&1 | head -1
kubectl get crd notebackups.lab.helm.example.com --show-managed-fields -o json \
  | jq -c '.metadata.managedFields[] | {manager, operation}'

Erwartet:

error: Apply failed with 1 conflict: conflict with "helm": .spec.versions
{"manager":"helm","operation":"Apply"}
{"manager":"k3s","operation":"Update"}

Helm 4 legt die CRD per Server-Side Apply mit dem Field Manager helm an. Ein kubectl apply --server-side ist ein zweiter Manager, der dieselben Felder ändern will – Konflikt (mehr dazu in Tag 14). Wer im Namen von Helm aktualisiert, nennt sich auch so:

# auf prod
helm show crds ./backup | kubectl apply --server-side --field-manager=helm -f -
kubectl -n tag12 get notebackups

Erwartet:

customresourcedefinition.apiextensions.k8s.io/notebackups.lab.helm.example.com
serverside-applied
NAME       SCHEDULE    RETENTION
b-nachts   0 2 * * *   7

--force-conflicts wäre die zweite Möglichkeit; dann gehören die Felder danach kubectl. --field-manager=helm lässt die Zuständigkeit, wo sie war.

Fortschritt speichern? Kostenlos registrieren

Drill 3: uninstall lässt die CRD stehen

# auf prod
helm uninstall b -n tag12
kubectl get crd notebackups.lab.helm.example.com
kubectl -n tag12 get notebackups

Erwartet:

release "b" uninstalled
NAME                               SCOPE        VERSIONS            CREATED AT
notebackups.lab.helm.example.com   Namespaced   v1alpha1(storage)   2026-11-20T02:02:48Z
No resources found in tag12 namespace.

Das NoteBackup aus templates/ ist weg, die CRD bleibt. Gut so: Andere Releases oder Teams könnten Objekte dieser Art besitzen.

Achtung: kubectl delete crd … löscht alle Objekte dieser Art in allen Namespaces, ohne Rückfrage und ohne Papierkorb. Vorher immer kubectl get <plural> -A prüfen. Hier ist der Cluster ein Labor, und es gibt keine Objekte mehr.

# auf prod
kubectl get notebackups -A
kubectl delete crd notebackups.lab.helm.example.com
helm install b ./backup -n tag12 --skip-crds 2>&1 | tail -2

Erwartet:

No resources found
customresourcedefinition.apiextensions.k8s.io "notebackups.lab.helm.example.com" deleted
Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest:
resource mapping not found for name: "b-nachts" namespace: "" from "": no matches for
kind "NoteBackup" in version "lab.helm.example.com/v1alpha1"
ensure CRDs are installed first

--skip-crds ist für Umgebungen, in denen ein anderer Weg die CRDs pflegt. Fehlt die CRD, scheitert die Installation.

Fortschritt speichern? Kostenlos registrieren

Drill 4: CRD und Objekt in templates/

Naheliegende Idee: CRD einfach nach templates/ schieben, dann aktualisiert sie jedes Upgrade.

# auf prod
cp -r backup beides
sed -i 's/^name: backup/name: beides/' beides/Chart.yaml
mv beides/crds/notebackup.yaml beides/templates/crd.yaml && rmdir beides/crds
helm install c ./beides -n tag12 2>&1 | tail -2
kubectl get crd notebackups.lab.helm.example.com 2>&1 | tail -1

Erwartet:

Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest:
resource mapping not found for name: "c-nachts" namespace: "" from "": no matches for
kind "NoteBackup" in version "lab.helm.example.com/v1alpha1"
ensure CRDs are installed first
Error from server (NotFound): customresourcedefinitions.apiextensions.k8s.io
"notebackups.lab.helm.example.com" not found

Helm baut aus allen Templates Objekte, bevor es eines anlegt – NoteBackup ist der API zu diesem Zeitpunkt unbekannt. Es entsteht gar nichts, auch die CRD nicht. CRD und Objekte gehören darum in getrennte Charts.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Das CRD-Chart notes-crds

# auf prod
cd ~/helm/charts && mkdir -p notes-crds/templates
cat > notes-crds/Chart.yaml <<'EOF'
# notes-crds/Chart.yaml – Stand Tag 12
apiVersion: v2
name: notes-crds
description: CRDs für notes – getrennt versioniert und vor dem Löschen geschützt
version: 0.1.0
EOF
cat > notes-crds/templates/notebackup.yaml <<'EOF'
{{/* notes-crds/templates/notebackup.yaml – Stand Tag 12 */}}
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: notebackups.lab.helm.example.com
  annotations:
    "helm.sh/resource-policy": keep
spec:
  group: lab.helm.example.com
  scope: Namespaced
  names:
    kind: NoteBackup
    plural: notebackups
    singular: notebackup
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: [schedule]
              properties:
                schedule: {type: string}
                retention: {type: integer, minimum: 1}
      additionalPrinterColumns:
        - {name: Schedule, type: string, jsonPath: .spec.schedule}
EOF
helm install notes-crds ./notes-crds -n notes | grep STATUS
cat >> notes-crds/templates/notebackup.yaml <<'EOF'
        - {name: Retention, type: integer, jsonPath: .spec.retention}
EOF
sed -i 's/^version: 0.1.0/version: 0.2.0/' notes-crds/Chart.yaml
helm upgrade notes-crds ./notes-crds -n notes | grep REVISION
kubectl get crd notebackups.lab.helm.example.com \
  -o jsonpath='{.spec.versions[0].additionalPrinterColumns[*].name}{"\n"}'

Erwartet:

STATUS: deployed
REVISION: 2
Schedule Retention

In templates/ ist die CRD ein normales Objekt: Das Upgrade aktualisiert sie. Und resource-policy: keep schützt sie vor helm uninstall:

# auf prod
helm uninstall notes-crds -n notes
kubectl get crd notebackups.lab.helm.example.com \
  -o jsonpath='{.metadata.annotations}{"\n"}'
helm install notes-crds ./notes-crds -n notes | grep STATUS
helm install fremd ./notes-crds -n tag12 2>&1 | tail -1

Erwartet:

These resources were kept due to the resource policy:
[CustomResourceDefinition] notebackups.lab.helm.example.com

release "notes-crds" uninstalled
{"helm.sh/resource-policy":"keep","meta.helm.sh/release-name":"notes-crds",
"meta.helm.sh/release-namespace":"notes"}
STATUS: deployed
Error: INSTALLATION FAILED: unable to continue with install: CustomResourceDefinition
"notebackups.lab.helm.example.com" in namespace "" exists and cannot be imported into
the current release: invalid ownership metadata; annotation validation error: key
"meta.helm.sh/release-name" must equal "fremd": current value is "notes-crds"; …

Die behaltene CRD trägt noch die Besitzer-Annotationen. Ein Release mit demselben Namen und Namespace übernimmt sie wieder, ein fremder Release nicht – invalid ownership metadata begegnet dir in Tag 19 wieder.

Fortschritt speichern? Kostenlos registrieren

Drill 6: notes legt ein NoteBackup an

Das App-Chart nutzt die CRD nur, wenn sie da ist:

# auf prod
cat > notes/templates/backup.yaml <<'EOF'
{{/* notes/templates/backup.yaml – Stand Tag 12 */}}
{{- $crd := "lab.helm.example.com/v1alpha1/NoteBackup" }}
{{- if and .Values.backup.enabled (.Capabilities.APIVersions.Has $crd) }}
apiVersion: lab.helm.example.com/v1alpha1
kind: NoteBackup
metadata:
  name: {{ include "notes.fullname" . }}
  labels:
    {{- include "notes.labels" . | nindent 4 }}
spec:
  schedule: {{ .Values.backup.schedule | quote }}
  retention: {{ .Values.backup.retention }}
{{- end }}
EOF
cat >> notes/values.yaml <<'EOF'

backup:
  # -- NoteBackup anlegen (nur wenn die CRD aus notes-crds installiert ist)
  enabled: false
  schedule: "0 2 * * *"
  retention: 7
EOF
sed -i 's/Stand Tag 11/Stand Tag 12/' notes/values.yaml
jq '.title = "notes – Stand Tag 12" | .properties.backup = {"type": "object"}' \
  notes/values.schema.json > /tmp/s.json && mv /tmp/s.json notes/values.schema.json
sed -i 's/^version: .*/version: 0.11.0/; s/Tag 11/Tag 12/' notes/Chart.yaml
cat >> values/prod.yaml <<'EOF'
backup:
  enabled: true
EOF
sed -i 's/Stand Tag 09/Stand Tag 12/' values/prod.yaml
helm template notes ./notes -f values/prod.yaml -s templates/backup.yaml 2>&1 | head -1
helm template notes ./notes -f values/prod.yaml -s templates/backup.yaml \
  -a lab.helm.example.com/v1alpha1/NoteBackup | grep -A2 '^spec'
helm upgrade notes ./notes -n notes -f values/prod.yaml --wait | grep REVISION
kubectl -n notes get notebackups

Erwartet:

Error: could not find template templates/backup.yaml in chart
spec:
  schedule: "0 2 * * *"
  retention: 7
REVISION: 26
NAME    SCHEDULE    RETENTION
notes   0 2 * * *   7

helm template kennt den Cluster nicht und damit die CRD nicht – das Template rendert leer (Tag 4). Mit -a oder im Cluster entsteht das Objekt. Was passiert mit ihm, wenn jemand das CRD-Chart deinstalliert?

# auf prod
helm uninstall notes-crds -n notes | tail -1
kubectl -n notes get notebackups
helm install notes-crds ./notes-crds -n notes | grep STATUS

Erwartet:

release "notes-crds" uninstalled
NAME    SCHEDULE    RETENTION
notes   0 2 * * *   7
STATUS: deployed

Dank keep bleibt die CRD und damit das Objekt. Ohne die Annotation hätte ein helm uninstall notes-crds das Backup-Objekt jedes Teams im Cluster mitgenommen.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Liste alle CRDs der Gruppe lab.helm.example.com. Zeitziel: 15 s
  2. Welche Spalten zeigt kubectl get notebackups? Lies sie aus der CRD. Zeitziel: 30 s
  3. Welcher Release besitzt die CRD? Zeitziel: 20 s
  4. Rendere backup.yaml so, als gäbe es die CRD, nur die kind-Zeile. Zeitziel: 30 s

Lösung

# auf prod
cd ~/helm/charts
kubectl get crd | grep lab.helm
kubectl get crd notebackups.lab.helm.example.com \
  -o jsonpath='{.spec.versions[0].additionalPrinterColumns[*].name}{"\n"}'
kubectl get crd notebackups.lab.helm.example.com \
  -o jsonpath='{.metadata.annotations.meta\.helm\.sh/release-name}{"\n"}'
helm template notes ./notes -f values/prod.yaml -s templates/backup.yaml \
  -a lab.helm.example.com/v1alpha1/NoteBackup | grep kind

Erwartet:

notebackups.lab.helm.example.com   Namespaced   v1alpha1(storage)   2026-11-20T02:03:46Z
Schedule Retention
notes-crds
kind: NoteBackup

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

# auf prod
helm list -n notes

Erwartet: helper (Rev. 2), notes (Rev. 26, notes-0.11.0) und notes-crds (Rev. 1, notes-crds-0.2.0), alle deployed.

# auf prod
kubectl -n notes get notebackup notes

Erwartet: notes mit Schedule 0 2 * * * und Retention 7.

# auf prod
kubectl get crd notebackups.lab.helm.example.com \
  -o jsonpath='{.metadata.annotations.helm\.sh/resource-policy}{"\n"}'

Erwartet: keep

Challenge

Rüste die CRD in einer Kopie von notes-crds (Version 0.3.0) auf: retention bekommt den Standard 7, schedule ein Muster, das nur Cron-Zeichen erlaubt. Rolle sie aus, ohne notes anzufassen, und weise beides mit einem Objekt nach, das du per kubectl in tag12 anlegst.

Hinweis: OpenAPI-Schemas in CRDs kennen default und pattern; der API-Server setzt Standardwerte beim Anlegen.

Lösung

# auf prod
cd ~/helm/tag12 && rm -rf notes-crds && cp -r ~/helm/charts/notes-crds .
sed -i 's/^version: 0.2.0/version: 0.3.0/' notes-crds/Chart.yaml
sed -i 's/minimum: 1}/minimum: 1, default: 7}/' notes-crds/templates/notebackup.yaml
P='schedule: {type: string, pattern: "^[0-9*,/ -]+$"}'
sed -i "s|schedule: {type: string}|$P|" notes-crds/templates/notebackup.yaml
helm upgrade notes-crds ./notes-crds -n notes | grep REVISION
cat > cr.yaml <<'EOF'
apiVersion: lab.helm.example.com/v1alpha1
kind: NoteBackup
metadata:
  name: ohne-retention
spec:
  schedule: "30 3 * * *"
EOF
kubectl -n tag12 apply -f cr.yaml
kubectl -n tag12 get notebackups
sed -i 's/30 3 \* \* \*/jeden Tag/' cr.yaml
kubectl -n tag12 apply -f cr.yaml 2>&1 | tail -1

Erwartet:

REVISION: 2
notebackup.lab.helm.example.com/ohne-retention created
NAME             SCHEDULE     RETENTION
ohne-retention   30 3 * * *   7
The NoteBackup "ohne-retention" is invalid: spec.schedule: Invalid value: "jeden Tag":
spec.schedule in body should match '^[0-9*,/ -]+$'

Eine CRD-Änderung wirkt sofort auf alle Objekte im Cluster – auch auf die anderer Teams. Darum hat sie ein eigenes Chart mit eigener Version und eigenem Freigabeweg.

Fortschritt speichern? Kostenlos registrieren

Aufräumen

Zurück auf den Stand des Repos, Wegwerf-Namespace weg:

# auf prod
kubectl -n tag12 delete notebackup ohne-retention
cd ~/helm/charts
helm upgrade notes-crds ./notes-crds -n notes | grep REVISION
kubectl delete namespace tag12
git add -A
git commit -qm "Tag 12: notes-crds mit resource-policy keep, NoteBackup, notes 0.11.0"

Erwartet:

notebackup.lab.helm.example.com "ohne-retention" deleted from tag12 namespace
REVISION: 3
namespace "tag12" deleted

Interview-Notiz

  • Warum aktualisiert Helm CRDs in crds/ nicht? CRDs gelten clusterweit; eine Änderung oder Löschung trifft alle Custom Resources aller Teams. Helm installiert sie darum nur einmal und überlässt Updates einem bewussten Schritt.
  • Wie lieferst du CRDs dann aus? In einem eigenen Chart unter templates/ mit helm.sh/resource-policy: keep, getrennt versioniert, vor dem App-Chart installiert.
  • Warum nicht CRD und Objekte im selben Chart unter templates/? Helm baut alle Objekte vor dem Anlegen; die Art ist noch unbekannt → no matches for kind.

Enterprise-Notiz

  • Viele Projekte (cert-manager, Prometheus-Operator) bieten CRDs als eigenes Chart oder als Schalter installCRDs/crds.enabled – im Plattform-Team zentral verwalten, nicht pro App-Team.
  • CRD-Updates gehören in einen eigenen Freigabeprozess: erst Testcluster, Konvertierung zwischen Versionen prüfen, dann Produktion.
  • GitOps-Werkzeuge haben eigene Optionen für CRDs (Flux crds: CreateReplace, Argo CD Server-Side Apply) – Tag 18.
  • Kein Werkzeug schützt vor kubectl delete crd. RBAC sollte das Löschen von CRDs auf wenige Personen beschränken.