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,uninstalllö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 notebackupsErwartet:
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 notebackupsErwartet:
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 notebackupsErwartet:
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 immerkubectl get <plural> -Aprü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 -2Erwartet:
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 -1Erwartet:
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 -1Erwartet:
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 notebackupsErwartet:
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 STATUSErwartet:
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
- Liste alle CRDs der Gruppe
lab.helm.example.com. Zeitziel: 15 s - Welche Spalten zeigt
kubectl get notebackups? Lies sie aus der CRD. Zeitziel: 30 s - Welcher Release besitzt die CRD? Zeitziel: 20 s
- Rendere
backup.yamlso, als gäbe es die CRD, nur diekind-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 kindErwartet:
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 notesErwartet: 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 notesErwartet: 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 -1Erwartet:
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/mithelm.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.