Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 14: Der Keycloak-Operator auf k3s

Ziel: Keycloak auf Kubernetes mit dem offiziellen Operator betreiben: zwei Instanzen hinter einem Ingress, ein Realm als Ressource, Selbstheilung und ein Upgrade, das der Operator selbst prüft. · Dauer: ca. 120 min · Voraussetzung: Tag 12

Briefing

  • Ein Operator ist ein Programm im Cluster, das eigene Ressourcen (Custom Resources) in Kubernetes-Objekte übersetzt und sie dauerhaft im Sollzustand hält.
  • Der Keycloak-Operator kennt vier Ressourcen: Keycloak (der Server), KeycloakRealmImport (einmaliger Import eines Realms) und seit 26.8 als Vorschau KeycloakOIDCClient und KeycloakSAMLClient.
  • Aus einer Keycloak-Ressource werden ein StatefulSet, Services und ein Ingress. Die Datenbank bringt der Operator nicht mit.
  • Bei einer Änderung entscheidet der Operator mit update-compatibility (Tag 12), ob er die Pods einzeln (rolling) oder alle zusammen neu startet.
 Browser ─► Traefik-Ingress kc.<K3S_IP>.sslip.io ─► Service kc-service
                                                     ├─► Pod kc-0 ─┐
 Operator ─überwacht─► Keycloak „kc"                 └─► Pod kc-1 ─┴─► postgres-0

Drill 1: Die VM k3s

Auf dem Laptop:

multipass launch 24.04 --name k3s --cpus 2 --memory 4G --disk 20G
multipass exec k3s -- bash -c "echo '$(cat ~/.ssh/id_ed25519.pub)' \
  >> ~/.ssh/authorized_keys"
multipass info k3s | grep IPv4

Melde dich per SSH an der neuen VM an. Alles Weitere in diesem Kapitel läuft dort:

sudo apt-get install -y jq git >/dev/null
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.36.5+k3s1 \
  sh -s - --write-kubeconfig-mode 644 2>&1 | tail -1
echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
until kubectl get nodes 2>/dev/null | grep -q ' Ready'; do sleep 3; done
kubectl get nodes
git clone -q https://github.com/thomaszachmann/keycloak-zum-anfassen.git \
  ~/kc-k8s/code
K3S_IP=$(hostname -I | awk '{print $1}'); echo "$K3S_IP"

Erwartet:

[INFO]  systemd: Starting k3s
NAME   STATUS   ROLES           AGE   VERSION
k3s    Ready    control-plane   5s    v1.36.5+k3s1
192.168.64.6

k3s bringt Traefik als Ingress-Controller und einen Storage-Provisioner für lokale Volumes mit – mehr braucht der Operator nicht.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der Operator

V=26.8.1
R=https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/$V/kubernetes
kubectl create namespace keycloak
for c in keycloaks keycloakrealmimports keycloakoidcclients keycloaksamlclients; do
  kubectl apply -f $R/$c.k8s.keycloak.org-v1.yml
done
kubectl -n keycloak apply -f $R/kubernetes.yml | grep -E 'deployment|serviceaccount'

Erwartet:

namespace/keycloak created
customresourcedefinition.apiextensions.k8s.io/keycloaks.k8s.keycloak.org created
customresourcedefinition.apiextensions.k8s.io/keycloakrealmimports.k8s.keycloak.org cr…
customresourcedefinition.apiextensions.k8s.io/keycloakoidcclients.k8s.keycloak.org cr…
customresourcedefinition.apiextensions.k8s.io/keycloaksamlclients.k8s.keycloak.org cr…
serviceaccount/keycloak-operator created
deployment.apps/keycloak-operator created

Fehlt eine der vier CRDs, stürzt der Operator beim Start ab („Informer startup error”). Auf einer kleinen VM mit zwei CPUs braucht er außerdem gut 35 Sekunden zum Start – so lange, wie seine Startup-Probe wartet. Wir geben ihm zwei Minuten:

P=/spec/template/spec/containers/0/startupProbe/failureThreshold
kubectl -n keycloak patch deploy keycloak-operator --type=json \
  -p "[{\"op\":\"replace\",\"path\":\"$P\",\"value\":12}]"
kubectl -n keycloak rollout status deploy/keycloak-operator --timeout=300s

Erwartet:

deployment.apps/keycloak-operator patched
…
deployment "keycloak-operator" successfully rolled out

Fortschritt speichern? Kostenlos registrieren

Drill 3: Eine Datenbank

grep -E '^kind|image:|storage:' ~/kc-k8s/code/k8s/postgres.yaml
kubectl apply -f ~/kc-k8s/code/k8s/postgres.yaml
kubectl -n keycloak rollout status statefulset/postgres --timeout=300s

Erwartet:

kind: Secret
kind: StatefulSet
          image: postgres:18.6-alpine
          requests: {storage: 2Gi}
kind: Service
secret/keycloak-db created
statefulset.apps/postgres created
service/postgres created
…
partitioned roll out complete: 1 new pods have been updated...

Fürs Labor reicht ein einzelner Postgres-Pod. In Produktion nimmst du eine verwaltete Datenbank oder einen eigenen Operator wie CloudNativePG.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Keycloak als Ressource

sed -n '/^spec:/,$p' ~/kc-k8s/code/k8s/keycloak.yaml
sed "s/K3S_IP/$K3S_IP/" ~/kc-k8s/code/k8s/keycloak.yaml | kubectl apply -f -
kubectl -n keycloak wait keycloak/kc --for=condition=Ready --timeout=900s
kubectl -n keycloak get pods -l app=keycloak
kubectl -n keycloak get ingress
curl -s http://kc.$K3S_IP.sslip.io/realms/master | jq -r .realm

Erwartet (nach etwa fünf Minuten):

spec:
  instances: 2
  image: quay.io/keycloak/keycloak:26.8.0
  startOptimized: false                 # Standard-Image, kein eigener Build
  db:
    vendor: postgres
    host: postgres
    database: keycloak
    usernameSecret: {name: keycloak-db, key: username}
    passwordSecret: {name: keycloak-db, key: password}
  http:
    httpEnabled: true                   # Labor: TLS endet nicht hier
  hostname:
    hostname: http://kc.K3S_IP.sslip.io
  proxy:
    headers: xforwarded
  ingress:
    enabled: true
    className: traefik
  resources:
    requests: {cpu: 200m, memory: 600Mi}
    limits: {memory: 1Gi}
  update:
    strategy: Auto                      # Operator prüft: rolling oder recreate
keycloak.k8s.keycloak.org/kc created
keycloak.k8s.keycloak.org/kc condition met
NAME   READY   STATUS    RESTARTS   AGE
kc-0   1/1     Running   0          4m
kc-1   1/1     Running   0          2m
NAME         CLASS     HOSTS                      ADDRESS        PORTS   AGE
kc-ingress   traefik   kc.192.168.64.6.sslip.io   192.168.64.6   80      5m
master
  • Mit Absicht steht hier 26.8.0 – das Upgrade kommt in Drill 7.
  • startOptimized: false: Der Operator startet Keycloak sonst mit --optimized und erwartet ein vorab gebautes Image. Mit dem Standard-Image bricht der Start dann ab.
  • Die Felder entsprechen den Optionen aus Tag 1 und 12: db → KC_DB_*, hostname → KC_HOSTNAME, proxy.headers → KC_PROXY_HEADERS.
  • Der Operator startet die Pods nacheinander. Der zweite tritt dem Cluster des ersten bei.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Der erste Admin

Der Operator legt einen temporären Admin an und legt sein Passwort in ein Secret:

kubectl -n keycloak get secret kc-initial-admin -o jsonpath='{.data.username}' \
  | base64 -d; echo
PW=$(kubectl -n keycloak get secret kc-initial-admin -o jsonpath='{.data.password}' \
  | base64 -d)
kc() { kubectl -n keycloak exec kc-0 -- /opt/keycloak/bin/kcadm.sh "$@"; }
kc config credentials --server http://localhost:8080 --realm master \
  --user temp-admin --password "$PW"
kc get realms --fields realm

Erwartet:

temp-admin
Logging into http://localhost:8080 as user temp-admin of realm master
[ {
  "realm" : "master"
} ]

Wie in Tag 1 gilt: Der temporäre Admin ist nur für den Anfang. Leg einen echten Admin an und lösch ihn danach – oder verwalte alles per Terraform aus Tag 13.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Ein Realm als Ressource

sed -n '/^spec:/,/clients:/p' ~/kc-k8s/code/k8s/realm-k8s.yaml
kubectl apply -f ~/kc-k8s/code/k8s/realm-k8s.yaml
kubectl -n keycloak wait keycloakrealmimport/realm-k8s --for=condition=Done \
  --timeout=600s
kubectl -n keycloak get pods -l app=keycloak-realm-import
curl -s -d grant_type=password -d client_id=notes-cli \
  -d client_secret=lab-client-secret-123 -d username=kira -d password=lab-user-pw-kira \
  http://kc.$K3S_IP.sslip.io/realms/k8s/protocol/openid-connect/token \
  | jq -r .access_token | jq -R -c 'split(".")[1] | gsub("-";"+") | gsub("_";"/")
  | @base64d | fromjson | {iss, roles: .realm_access.roles}'

Erwartet:

spec:
  keycloakCRName: kc
  realm:
    realm: k8s
    enabled: true
    displayName: notes auf Kubernetes
    roles:
      realm:
        - name: notes-lesen
    clients:
keycloakrealmimport.k8s.keycloak.org/realm-k8s created
keycloakrealmimport.k8s.keycloak.org/realm-k8s condition met
NAME              READY   STATUS      RESTARTS   AGE
realm-k8s-…       0/1     Completed   0          2m
{"iss":"http://kc.192.168.64.6.sslip.io/realms/k8s","roles":["notes-lesen"]}

Der Import läuft als Job mit einem eigenen Keycloak-Prozess. Er legt den Realm einmal an – spätere Änderungen an der Ressource übernimmt er nicht. Für die Pflege bleibt Terraform (Tag 13); KeycloakOIDCClient ist ein erster Schritt in diese Richtung.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Selbstheilung und Upgrade

kubectl -n keycloak delete pod kc-1
kubectl -n keycloak wait pod/kc-1 --for=condition=Ready --timeout=600s

Erwartet:

pod "kc-1" deleted from keycloak namespace
pod/kc-1 condition met

Das StatefulSet startet den Pod neu, der Operator wacht über das StatefulSet. Jetzt das Upgrade auf 26.8.1:

kubectl -n keycloak patch keycloak kc --type=merge \
  -p '{"spec":{"image":"quay.io/keycloak/keycloak:26.8.1"}}'
until kubectl -n keycloak get job kc-update-job 2>/dev/null | grep -q Complete; do
  sleep 10; done
kubectl -n keycloak get job kc-update-job
kubectl -n keycloak rollout status statefulset/kc --timeout=900s
kubectl -n keycloak get keycloak kc \
  -o jsonpath='{.status.conditions[?(@.type=="RecreateUpdateUsed")].message}'; echo
kubectl -n keycloak get pods -l app=keycloak \
  -o custom-columns=NAME:.metadata.name,IMAGE:.spec.containers[0].image

Erwartet (nach fünf bis zehn Minuten):

keycloak.k8s.keycloak.org/kc patched
NAME            STATUS     COMPLETIONS   DURATION   AGE
kc-update-job   Complete   1/1           2m         2m
…
partitioned roll out complete: 2 new pods have been updated...
Compatible changes detected.
NAME   IMAGE
kc-0   quay.io/keycloak/keycloak:26.8.1
kc-1   quay.io/keycloak/keycloak:26.8.1

Der Operator hat erst den Update-Job laufen lassen. Er vergleicht die alte und die neue Version wie update-compatibility in Tag 12. Ergebnis: verträglich, also tauscht er die Pods einzeln – Keycloak bleibt die ganze Zeit erreichbar.

Die neuen Pods kennen die Anmeldung von kcadm aus Drill 5 nicht mehr:

kc config credentials --server http://localhost:8080 --realm master \
  --user temp-admin --password "$PW"

Erwartet:

Logging into http://localhost:8080 as user temp-admin of realm master

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl -n keycloak get keycloak kc \
  -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'; echo

Erwartet:

True
kubectl -n keycloak get statefulset kc -o jsonpath='{.status.readyReplicas}'; echo

Erwartet: zwei bereite Instanzen.

2
kc get realms --fields realm --format csv --noquotes | sort

Erwartet:

k8s
master

Challenge

Wo landet spec.hostname aus der Keycloak-Ressource? Zeig den Wert, den der Operator dem Keycloak-Container mitgibt.

Hinweis: Der Operator schreibt ein StatefulSet. Optionen werden zu Umgebungsvariablen mit dem Präfix KC_.

Lösung

kubectl -n keycloak get statefulset kc -o json \
  | jq -r '.spec.template.spec.containers[0].env[]
    | select(.name=="KC_HOSTNAME") | .value'

Erwartet:

http://kc.192.168.64.6.sslip.io

Ändere das StatefulSet nie direkt: Der Operator setzt es beim nächsten Abgleich wieder auf das, was in der Keycloak-Ressource steht.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Optimiertes Image: In Produktion baut man ein eigenes Image mit kc.sh build (Datenbank, Features, Provider, Themes fest eingebaut). Dann startet Keycloak deutlich schneller, und startOptimized bleibt auf true.
  • TLS: spec.http.tlsSecret zeigt auf ein Secret mit Zertifikat, z. B. von cert-manager. Der Ingress spricht dann https zum Pod.
  • Ressourcen: Keycloak braucht je Pod eher 1–2 GiB Speicher. Die Werte hier sind für eine 4-GB-VM gerade so ausreichend.
  • Mehrere Namespaces: Der Operator überwacht standardmäßig nur seinen Namespace. Für mehrere Keycloak-Instanzen gibt es die Cluster-weite Installation.
  • Helm-Charts von Dritten gibt es auch. Der Operator ist der offizielle Weg und kennt Keycloaks Upgrade-Regeln.