Tag 2: SimpleSchema
Ziel: Eine API mit Typen, Pflichtfeldern, Defaults, Grenzen, Listen, Maps und eigenen Typen. Falsche Instanzen lehnt der API-Server ab, bevor kro sie überhaupt sieht. · Dauer: ca. 45 min · Voraussetzung: Tag 1
Briefing
- Das Schema einer RGD schreibst du in SimpleSchema:
feld: typ | marker. kro übersetzt das in ein OpenAPI-Schema für die CRD. - Grundtypen:
string,integer,boolean,float. Dazu[]typ(Liste),map[string]typ(Map), verschachtelte Objekte und eigene Typen untertypes. - Marker hinter dem
|:required=true,default=…,minimum=/maximum=,enum="a,b",pattern="…",minLength=/maxLength=,uniqueItems=true,maxItems=,immutable=true,description="…". - Die Prüfung übernimmt der API-Server. Eine falsche Instanz wird gar nicht erst gespeichert, und der Fehler landet direkt beim Team.
Drill 1: Ein Schema mit allem
Die neue API NotesSettings beschreibt Einstellungen für
ein Team. Heute zählt nur das Schema, die ConfigMap dahinter bleibt
klein.
mkdir -p ~/kro-lab/tag02
cd ~/kro-lab/tag02
cat > settings-rgd.yaml <<'EOF'
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
name: notes-settings
spec:
schema:
apiVersion: v1alpha1
kind: NotesSettings
group: lab.example.com
shortNames:
- nset
types:
Contact:
name: string | required=true
email: string | pattern="^[^@ ]+@[^@ ]+$"
spec:
team: string | required=true pattern="^[a-z][a-z0-9-]*$" description="Team, dem die Instanz gehört"
logLevel: string | enum="debug,info,warn,error" default="info"
maxNotes: integer | default=100 minimum=1 maximum=10000
readOnly: boolean | default=false
tags: "[]string | uniqueItems=true maxItems=3"
labels: "map[string]string"
owner: Contact
ticket: string | immutable=true
additionalPrinterColumns:
- name: Team
type: string
jsonPath: .spec.team
- name: Log
type: string
jsonPath: .spec.logLevel
- name: State
type: string
jsonPath: .status.state
resources:
- id: config
template:
apiVersion: v1
kind: ConfigMap
metadata:
name: ${schema.metadata.name}-settings
data:
team: ${schema.spec.team}
logLevel: ${schema.spec.logLevel}
EOFgroup: lab.example.comlegt eine eigene API-Gruppe fest. Die CRD heißt dannnotessettings.lab.example.com, und deine APIs mischen sich nicht mit denen von kro.shortNamesgibt der Art einen Kurznamen fürkubectl.typesdefiniert einen eigenen TypContact, denownerbenutzt.- Typen mit
[]odermap[stehen in Anführungszeichen, sonst liest YAML die Klammern als Liste. additionalPrinterColumnsbestimmt die Spalten vonkubectl get. Sobald du eigene Spalten angibst, fallen die StandardspaltenSTATEundREADYweg. Deshalb holt die dritte SpalteSTATEzurück.
kubectl apply -f settings-rgd.yaml
kubectl get rgd notes-settings
kubectl get crd | grep lab.example.comErwartet:
resourcegraphdefinition.kro.run/notes-settings created
NAME APIVERSION KIND STATE READY AGE
notes-settings v1alpha1 NotesSettings Active True 5s
notessettings.lab.example.com Namespaced v1alpha1(storage) 2026-11-11T17:31:12Z
Fortschritt speichern? Kostenlos registrieren
Drill 2: Das Schema lesen
kubectl explain nset.specErwartet (gekürzt):
GROUP: lab.example.com
KIND: NotesSettings
VERSION: v1alpha1
FIELD: spec <Object>
...
FIELDS:
labels <map[string]string>
logLevel <string>
enum: debug, info, warn, error
maxNotes <integer>
owner <Object>
readOnly <boolean>
tags <[]string>
team <string> -required-
Meldet kubectl stattdessen
the server doesn't have a resource type "nset", warte ein
paar Sekunden. kubectl merkt sich die Liste der Arten eine
Weile und kennt den Kurznamen dann noch nicht.
Was kro aus dem SimpleSchema gemacht hat, steht in der CRD:
kubectl get crd notessettings.lab.example.com -o yaml | grep -A12 ' maxNotes:'Erwartet:
maxNotes:
default: 100
maximum: 10000
minimum: 1
type: integer
owner:
properties:
email:
pattern: ^[^@ ]+@[^@ ]+$
type: string
name:
type: string
required:
Aus einer Zeile SimpleSchema werden fünf Zeilen OpenAPI. Für
ticket mit immutable=true erzeugt kro eine
CEL-Regel self == oldSelf, die der API-Server bei jeder
Änderung prüft.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Eine gültige Instanz
cat > blau.yaml <<'EOF'
apiVersion: lab.example.com/v1alpha1
kind: NotesSettings
metadata:
name: blau
namespace: app
spec:
team: team-blau
owner:
name: Ada
email: [email protected]
ticket: OPS-1
EOF
kubectl apply -f blau.yaml
kubectl -n app get nsetErwartet:
notessettings.lab.example.com/blau created
NAME TEAM LOG STATE
blau team-blau info ACTIVE
Die Spalten kommen aus additionalPrinterColumns. Die
Defaults stehen jetzt in der Instanz, obwohl du sie nicht geschrieben
hast:
kubectl -n app get nset blau -o yaml | grep -A10 '^spec:'Erwartet:
spec:
logLevel: info
maxNotes: 100
owner:
email: [email protected]
name: Ada
readOnly: false
team: team-blau
ticket: OPS-1
status:
Fortschritt speichern? Kostenlos registrieren
Drill 4: Eine falsche Instanz
cat > falsch.yaml <<'EOF'
apiVersion: lab.example.com/v1alpha1
kind: NotesSettings
metadata:
name: falsch
namespace: app
spec:
team: Team_Rot
logLevel: verbose
maxNotes: 0
tags: [a, a]
EOF
kubectl apply -f falsch.yamlErwartet:
The NotesSettings "falsch" is invalid:
* spec.team: Invalid value: "Team_Rot": spec.team in body should match '^[a-z][a-z0-9-]*$'
* spec.logLevel: Unsupported value: "verbose": supported values: "debug", "info",
"warn", "error"
* spec.maxNotes: Invalid value: 0: spec.maxNotes in body should be greater than or
equal to 1
* spec.tags[1]: Duplicate value: "a"
* <nil>: Invalid value: null: some validation rules were not checked because the
object was invalid; correct the existing errors to complete validation
Vier Fehler in einer Meldung, und kein Objekt wurde gespeichert. kro hat davon nichts mitbekommen, denn die Prüfung läuft im API-Server.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Unveränderliche Felder
kubectl -n app patch nset blau --type merge -p '{"spec":{"ticket":"OPS-2"}}'Erwartet:
The NotesSettings "blau" is invalid: spec.ticket: Invalid value: "OPS-2": field is
immutable
Andere Felder darfst du ändern:
kubectl -n app patch nset blau --type merge -p '{"spec":{"logLevel":"debug"}}'
kubectl -n app get configmap blau-settings -o jsonpath='{.data}{"\n"}'Erwartet:
notessettings.lab.example.com/blau patched
{"logLevel":"debug","team":"team-blau"}
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
kubectl get rgd notes-settingsErwartet: STATE Active, READY
True.
kubectl -n app get nsetErwartet:
NAME TEAM LOG STATE
blau team-blau debug ACTIVE
diff settings-rgd.yaml ~/kro-lab/code/loesung/tag02/settings-rgd.yamlErwartet: keine Ausgabe.
Challenge
Lege eine Instanz gelb an, deren Owner keinen Namen hat,
nur eine E-Mail-Adresse. Was meldet der API-Server, und warum ist
owner selbst trotzdem kein Pflichtfeld?
Hinweis: Sieh dir den Typ Contact
an.
Lösung
cat > gelb.yaml <<'EOF'
apiVersion: lab.example.com/v1alpha1
kind: NotesSettings
metadata:
name: gelb
namespace: app
spec:
team: team-gelb
owner:
email: [email protected]
EOF
kubectl apply -f gelb.yamlErwartet:
The NotesSettings "gelb" is invalid:
* spec.owner.name: Required value
* <nil>: Invalid value: null: some validation rules were not checked because the
object was invalid; correct the existing errors to complete validation
required=true gilt innerhalb von Contact.
Lässt du owner ganz weg, ist alles in Ordnung. Gibst du ihn
an, muss name dabei sein.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Eigene Gruppe: Nimm für deine Plattform-APIs eine
Gruppe unter einer Domain, die dir gehört, etwa
platform.firma.de. So gibt es keine Kollisionen mit anderen Werkzeugen. - Beschreibungen schreiben:
description="…"landet inkubectl explainund in jeder IDE mit Kubernetes-Unterstützung. Das ist die billigste Dokumentation, die es gibt. - Streng sein: Grenzen, Enums und Muster im Schema ersparen dir später Fehler, die erst beim Ausrollen auffallen. Was der API-Server ablehnt, kostet niemanden einen Rollout.