Day 2: SimpleSchema
Goal: An API with types, required fields, defaults, limits, lists, maps and custom types. The API server rejects wrong instances before kro even sees them. · Duration: approx. 45 min · Prerequisite: Day 1
Briefing
- You write the schema of an RGD in SimpleSchema:
feld: typ | marker. kro translates that into an OpenAPI schema for the CRD. - Basic types:
string,integer,boolean,float. Plus[]typ(list),map[string]typ(map), nested objects and custom types undertypes. - Markers after the
|:required=true,default=…,minimum=/maximum=,enum="a,b",pattern="…",minLength=/maxLength=,uniqueItems=true,maxItems=,immutable=true,description="…". - The API server does the validation. A wrong instance is never stored in the first place, and the error goes straight to the team.
Drill 1: A Schema with Everything
The new API NotesSettings describes settings for a team.
Today only the schema matters; the ConfigMap behind it stays small.
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.comsets your own API group. The CRD is then callednotessettings.lab.example.com, and your APIs don’t mix with those of kro.shortNamesgives the kind a short name forkubectl.typesdefines a custom typeContact, whichowneruses.- Types with
[]ormap[are in quotes; otherwise YAML reads the brackets as a list. additionalPrinterColumnsdetermines the columns ofkubectl get. As soon as you specify your own columns, the default columnsSTATEandREADYdisappear. That’s why the third column bringsSTATEback.
kubectl apply -f settings-rgd.yaml
kubectl get rgd notes-settings
kubectl get crd | grep lab.example.comExpected:
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
Save your progress? Sign up for free
Drill 2: Reading the Schema
kubectl explain nset.specExpected (shortened):
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-
If kubectl reports
the server doesn't have a resource type "nset" instead,
wait a few seconds. kubectl caches the list of kinds for a
while and doesn’t know the short name yet.
What kro made of the SimpleSchema is in the CRD:
kubectl get crd notessettings.lab.example.com -o yaml | grep -A12 ' maxNotes:'Expected:
maxNotes:
default: 100
maximum: 10000
minimum: 1
type: integer
owner:
properties:
email:
pattern: ^[^@ ]+@[^@ ]+$
type: string
name:
type: string
required:
One line of SimpleSchema becomes five lines of OpenAPI. For
ticket with immutable=true, kro generates a
CEL rule self == oldSelf, which the API server checks on
every change.
Save your progress? Sign up for free
Drill 3: A Valid Instance
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 nsetExpected:
notessettings.lab.example.com/blau created
NAME TEAM LOG STATE
blau team-blau info ACTIVE
The columns come from additionalPrinterColumns. The
defaults are now in the instance, even though you didn’t write them:
kubectl -n app get nset blau -o yaml | grep -A10 '^spec:'Expected:
spec:
logLevel: info
maxNotes: 100
owner:
email: [email protected]
name: Ada
readOnly: false
team: team-blau
ticket: OPS-1
status:
Save your progress? Sign up for free
Drill 4: A Wrong Instance
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.yamlExpected:
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
Four errors in one message, and no object was stored. kro noticed none of it, because the validation runs in the API server.
Save your progress? Sign up for free
Drill 5: Immutable Fields
kubectl -n app patch nset blau --type merge -p '{"spec":{"ticket":"OPS-2"}}'Expected:
The NotesSettings "blau" is invalid: spec.ticket: Invalid value: "OPS-2": field is
immutable
You may change other fields:
kubectl -n app patch nset blau --type merge -p '{"spec":{"logLevel":"debug"}}'
kubectl -n app get configmap blau-settings -o jsonpath='{.data}{"\n"}'Expected:
notessettings.lab.example.com/blau patched
{"logLevel":"debug","team":"team-blau"}
Save your progress? Sign up for free
Checkpoint
kubectl get rgd notes-settingsExpected: STATE Active, READY
True.
kubectl -n app get nsetExpected:
NAME TEAM LOG STATE
blau team-blau debug ACTIVE
diff settings-rgd.yaml ~/kro-lab/code/loesung/tag02/settings-rgd.yamlExpected: no output.
Challenge
Create an instance gelb whose owner has no name, only an
email address. What does the API server report, and why is
owner itself still not a required field?
Note: Look at the type Contact.
Solution
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.yamlExpected:
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 applies within Contact. If
you leave out owner entirely, everything is fine. If you
specify it, name must be included.
Save your progress? Sign up for free
Enterprise Note
- Your own group: For your platform APIs, use a group
under a domain you own, such as
platform.firma.de. That way there are no collisions with other tools. - Write descriptions:
description="…"ends up inkubectl explainand in every IDE with Kubernetes support. It’s the cheapest documentation there is. - Be strict: Limits, enums and patterns in the schema save you errors later that only show up during rollout. What the API server rejects costs nobody a rollout.