Zum Inhalt springen
Trainingslager IT-Trainingslager

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 unter types.
  • 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}
EOF
  • group: lab.example.com legt eine eigene API-Gruppe fest. Die CRD heißt dann notessettings.lab.example.com, und deine APIs mischen sich nicht mit denen von kro.
  • shortNames gibt der Art einen Kurznamen für kubectl.
  • types definiert einen eigenen Typ Contact, den owner benutzt.
  • Typen mit [] oder map[ stehen in Anführungszeichen, sonst liest YAML die Klammern als Liste.
  • additionalPrinterColumns bestimmt die Spalten von kubectl get. Sobald du eigene Spalten angibst, fallen die Standardspalten STATE und READY weg. Deshalb holt die dritte Spalte STATE zurück.
kubectl apply -f settings-rgd.yaml
kubectl get rgd notes-settings
kubectl get crd | grep lab.example.com

Erwartet:

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.spec

Erwartet (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 nset

Erwartet:

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

Erwartet:

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

Erwartet: STATE Active, READY True.

kubectl -n app get nset

Erwartet:

NAME   TEAM        LOG     STATE
blau   team-blau   debug   ACTIVE
diff settings-rgd.yaml ~/kro-lab/code/loesung/tag02/settings-rgd.yaml

Erwartet: 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.yaml

Erwartet:

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 in kubectl explain und 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.