Zurück zum Hub

cargo.ayedo.cloud/ayedo/k8s/keycloak

Registry-Block

polycrate block pull cargo.ayedo.cloud/ayedo/k8s/keycloak:0.7.2

Keycloak

Dieser Block installiert Keycloak in Kubernetes.

Konfigurationsbeispiele: polycrate block examples keycloak (examples.poly).

Netzwerk (Ingress vs Gateway API)

Default bleibt Ingress-nginx. Gateway API ist opt-in wie Argo CD / Flux / GitLab.

Config Default Zweck
ingress.enabled false Ingress-nginx, Backend HTTPS :8443
gateway.enabled false Certificate + Gateway + HTTPRoute auf eg-shared (Envoy)

ingress.enabled und gateway.enabled sind mutually exclusive.

Bei Gateway terminiert Envoy TLS. Keycloak bekommt httpEnabled: true und proxy.headers: xforwarded; hostname ist die volle URL https://<host> (sonst wird der OIDC-Issuer http://). Die HTTPRoute zeigt auf keycloak-service:8080. gateway.host leer → ingress.host.

ingress:
  enabled: false
  host: id.example.com
  tls:
    issuer: letsencrypt-production
gateway:
  enabled: true
  create_gateway: true
  gateway_class_name: eg-shared
  host: id.example.com
  tls:
    issuer: letsencrypt-production
    secret_name: keycloak-gateway-tls

Upgrade 0.7.0 → 0.7.1 (Keycloak 26.7.2 → 26.7.3)

Security-Patch: 26.7.3 (LDAP hostname verify, OIDC assertion/auth-code, token-exchange, FGAP, path-traversal rest).

# workspace.poly: from: cargo.ayedo.cloud/ayedo/k8s/keycloak:0.7.1
polycrate run keycloak install
# keycloak-0 / operator: quay.io/keycloak/keycloak{,-operator}:26.7.3

Patch in 26.7.x: kurze Downtime bei 1 Replica. Rollback nur per CNPG-Restore.

Upgrade 0.7.1 → 0.7.2 (Keycloak 26.7.3 → 26.7.4)

Security-Patch: 26.7.4 (Locale-Cache DoS, PathMatcher %3B, impersonation, SAML zlib, MySQL replay gates). Quarkus 3.33.3.2.

Authorization Services: Matrix-Parameter inkl. %3B werden beim URI-Match gestrippt.

# workspace.poly: from: cargo.ayedo.cloud/ayedo/k8s/keycloak:0.7.2
polycrate run keycloak install
# keycloak-0 / operator: quay.io/keycloak/keycloak{,-operator}:26.7.4

Upgrade 0.6.x → 0.7.0 (Keycloak 26.6.0 → 26.7.2)

Security: CVE-2026-18963 (Kontoübernahme über Passwort-Reset) und weitere Fixes in 26.7.2.

Minor-Sprung: DB-Schema-Migration beim Start (startOptimized: false bleibt). Eine Replica → kurze Downtime. Kein Delete von Services/NetworkPolicy/Admin-Secret (das galt nur 0.5 → 0.6).

26.7.2 bringt zwei neue Operator-CRDs (KeycloakOIDCClient, KeycloakSAMLClient). install.yml wendet sie mit an — ohne sie crasht der Operator beim Informer-Start.

Neu in 0.7.0 außerdem: opt-in gateway.* und examples.poly. Workspaces mit Wildcard-DNS auf Envoy (eg-shared): ingress.enabled: false, gateway.enabled: true.

# workspace.poly: from: cargo.ayedo.cloud/ayedo/k8s/keycloak:0.7.0
polycrate run keycloak install
kubectl -n <namespace> get pods -w
# keycloak-0: quay.io/keycloak/keycloak:26.7.2

Vor dem Upgrade: Upgrading Guide 26.7.2. Rollback nach Schema-Migration nur per DB-Restore.

Upgrade 0.5.x → 0.6.0 (Keycloak 26.5.x → 26.6.0)

Breaking Change: Manuelle Schritte erforderlich vor dem Install.

Hintergrund

Block 0.6.0 führt folgende Änderungen ein:

  1. Explizites spec.image im Keycloak CR — pinnt das Keycloak-Server-Image auf block.app_version. Ohne dieses Feld bestimmt der Operator das Image selbst und rollt bestehende Pods bei einem Operator-Upgrade nicht automatisch.
  2. startOptimized: false — Keycloak 26.6.0 verweigert den Start mit --optimized bei einem Minor-Version-Upgrade (26.5 → 26.6), da eine DB-Schema-Migration erforderlich ist. Der Block setzt daher startOptimized: false, sodass Keycloak den Build-Step bei jedem Start ausführt.
  3. Konditionelles Provider-Volume — Das emptyDir-Volume für /opt/keycloak/providers wird nur noch gemountet wenn theme_downloader oder initcontainers aktiv sind. Ein leerer Mount auf dieses Verzeichnis bricht den --optimized-Modus in 26.6.0.
  4. Keycloak Operator 26.6.0 hat geänderte Resource-Definitionen (Services, NetworkPolicy, Admin-Secret). Die Server-Side-Apply Field Ownership kollidiert mit der alten 26.5.x Ownership, wodurch die Reconciliation scheitert und der Operator keine Pods aktualisiert.

Upgrade-Pfad

Schritt 1: Block-Version in workspace.poly auf 0.6.0 setzen.

Schritt 2: Bestehende Operator-verwaltete Resources löschen (werden vom Operator neu erstellt):

kubectl -n <namespace> delete svc keycloak-service keycloak-discovery
kubectl -n <namespace> delete networkpolicy keycloak-network-policy
kubectl -n <namespace> delete secret keycloak-initial-admin

Hinweis: Das keycloak-initial-admin Secret wird mit einem neuen Passwort regeneriert. Das betrifft nur den temporären Admin-Account. Permanente Admin-Accounts in Keycloak sind nicht betroffen.

Schritt 3: Block installieren:

poly run keycloak install

Schritt 4: Operator-Restart, falls die Reconciliation nicht automatisch anläuft (Retries exhausted):

kubectl -n <namespace> rollout restart deployment keycloak-operator

Schritt 5: Verifizieren:

kubectl -n <namespace> get pods -w
# keycloak-0 sollte neu starten mit Image quay.io/keycloak/keycloak:26.6.0

Keycloak 26.6.0 Upgrading Guide

Vor dem Upgrade die Keycloak Upgrading Guide prüfen.

Beim Upgrade von 0.2.4 auf eine 0.3.0 wurde das Bitnami Helm Chart durch den Keycloak Operator ersetzt. Der Operator installiert keine Datenbank! Siehe https://www.keycloak.org/operator/basic-deployment

Migration vorhandener installationen und beibehalten der Bitnami Postgres DB:

  • Um Installationen von 0.2.4 auf 0.3.0 umzustellen, muss das DB Passwort und der Hostname (Service) im Block hinterlegt werden. block.config.postgresql.host und block.config.postgresql.password
  • Das vorhandene Keycloak Statefulset muss gelöscht werden.
  • Der neue Block wird installiert.

Beim Upgrade von 0.0.2 auf eine höhere Version muss ein Backup der PostgreSQL durchgeführt werden.

Folgende Befehle dienen lediglich als Hilfestellung und müssen ggf. angepasst werden.

kubectl scale --replicas=0 -n keycloak statefulset/keycloak

kubectl exec -n keycloak -it keycloak-postgres -- pg_dump -U postgres -d bitnami_keycloak -cC > /bitnami/postgresql/postgres_16_YYYMMDD.sql
## Optional Backup auf localen host
kubectl cp -n keycloak -it keycloak-postgres /bitnami/postgresql/postgres_16_YYYMMDD.sql postgres_16_YYYMMDD.sql 

## Leeren des Verzechnisses und setzen der Replica auf 0. Muss direkt nacheinander durchgeführt werden.
kubectl exec -n keycloak -it keycloak-postgres -- rm -rf /bitnami/postgresql/data
kubectl scale --replicas=0 -n keycloak statefulset/keycloak-postgresql

poly run keycloak install

kubectl scale --replicas=0 -n keycloak statefulset/keycloak
kubectl exec -n keycloak -it keycloak-postgres -- /bin/bash
psql -d bitnami_keycloak -U postgres
# \c postgres
# drop DATABASE bitnami_keycloak;
# create DATABASE bitnami_keycloak;
# \q
cat ./postgres_16_YYYMMDD.sql | psql -d bitnami_keycloak -U postgres
exit
kubectl scale --replicas=1 -n keycloak statefulset/keycloak

Changelog

  • Moved to CHANGELOG.poly
  • 0.1.4: chore: docs
  • 0.1.3: chore: added block.kind stanza
  • 0.1.2: Fix:
  • uninstall action.
  • Ein benutzerdefiniertes Zertifikat kann unter ingress.secrets abgelegt werden.
  • certmanager annotations können deaktiviert werden .tls.certmanager.annotation:.disabled
  • 0.1.1: Fix:
  • Vorherige Version war ein Feat wurde aber mit 0.0.4 gepusht. Daher auf 0.1.x aktualisiert.
  • Fehlende einträge in der block.poly hinzugefügt (external.user, external.database)
  • Helm Chart auf oci umgestellt.
  • 0.0.4: Feat: Added theme downloader
  • 0.0.3: Fix: BREAKING CHANGE: Bump Chart to 24.4.6 (Manuelle Postgres Migration erforderlich)
  • 0.0.2: Fix: Ingress PathType
  • 0.0.1: Keycloak

actions

install

Beispiel für migration von Bitnami Chart

Vorhandene Postgres instanz wird genutzt

blocks:
  - name: keycloak
    from: cargo.ayedo.cloud/ayedo/k8s/keycloak
    kubeconfig:
      from: k8s
    config:
      ingress:
        enabled: true
        host: keycloak.example.com
        tls:
          enabled: true
          issuer: "letsencrypt-production"
      postgresql:
        host: "keycloak-postgresql.keycloak.svc.cluster.local."
        password: "sEcBEz"

Beispiel für default installation

Postgresql muss seperat installiert werden

blocks:
  - name: keycloak
    from: cargo.ayedo.cloud/ayedo/k8s/keycloak
    kubeconfig:
      from: k8s
    config:
      ingress:
        enabled: true
        host: keycloak.example.com
        tls:
          enabled: true
          issuer: "letsencrypt-production"
      postgresql:
        host: "postgres.postgres.svc.cluster.local"
        port: 5432
        user: bn_keycloak
        database: keycloak
        password: "sEcBEz"

uninstall

poly run keycloak uninstall