Skip to content
Hands-on IT IT Drills

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 under types.
  • 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}
EOF
  • group: lab.example.com sets your own API group. The CRD is then called notessettings.lab.example.com, and your APIs don’t mix with those of kro.
  • shortNames gives the kind a short name for kubectl.
  • types defines a custom type Contact, which owner uses.
  • Types with [] or map[ are in quotes; otherwise YAML reads the brackets as a list.
  • additionalPrinterColumns determines the columns of kubectl get. As soon as you specify your own columns, the default columns STATE and READY disappear. That’s why the third column brings STATE back.
kubectl apply -f settings-rgd.yaml
kubectl get rgd notes-settings
kubectl get crd | grep lab.example.com

Expected:

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

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

Expected:

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

Expected:

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

Expected: STATE Active, READY True.

kubectl -n app get nset

Expected:

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

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

Expected:

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