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 VorschauKeycloakOIDCClientundKeycloakSAMLClient. - 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=300sErwartet:
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=300sErwartet:
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 .realmErwartet (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--optimizedund 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 realmErwartet:
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=600sErwartet:
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].imageErwartet (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}'; echoErwartet:
True
kubectl -n keycloak get statefulset kc -o jsonpath='{.status.readyReplicas}'; echoErwartet: zwei bereite Instanzen.
2
kc get realms --fields realm --format csv --noquotes | sortErwartet:
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, undstartOptimizedbleibt auftrue. - TLS:
spec.http.tlsSecretzeigt auf ein Secret mit Zertifikat, z. B. von cert-manager. Der Ingress spricht dannhttpszum 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.