Skip to content

Keycloak

Keycloak provides identity and single sign-on for the Skatzi platform and the Kodexet portal.

At a glance
URL https://keycloak.prod.skatzi.com
Upstream version 26.4.7 (Quay)
Deployed image harbor.prod.skatzi.com/skatzi/keycloak-kodexet:<tag>
Operator Keycloak Operator (k8s.keycloak.org/v2alpha1)
Namespace keycloak
Database PostgreSQL (in-cluster StatefulSet in the same namespace)
Realms skatzi (internal admins) · kodexet (customers, Google OAuth)

Repository layout

components/keycloak/
├── Dockerfile                  # Bakes the kodexet theme into Keycloak
├── base/
│   ├── keycloak-instance.yaml  # The Keycloak CR consumed by the operator
│   ├── kodexet-realm.yaml      # Disaster-recovery snapshot — NOT live config
│   ├── skatzi-realm.yaml       # Disaster-recovery snapshot — NOT live config
│   ├── postgresql.yaml         # Keycloak's own PostgreSQL StatefulSet
│   ├── httproute.yaml          # Gateway API route for keycloak.prod.skatzi.com
│   └── ...
├── theme/kodexet/              # Custom login theme (CSS-only override)
└── secrets/                    # ExternalSecret definitions

Image composition

The deployed image is a thin wrapper around the upstream Keycloak image — it only adds the kodexet login theme:

FROM quay.io/keycloak/keycloak:26.4.7

COPY theme/kodexet /opt/keycloak/themes/kodexet

RUN /opt/keycloak/bin/kc.sh build

The kc.sh build step pre-compiles the theme so startup is fast. Because build-time options are baked into the image, the Keycloak CR sets startOptimized: false — that forces kc.sh build to re-run on pod boot whenever any build-time option (db, health-enabled, metrics-enabled, …) differs from the image. Without that flag the pod crash-loops after every option change.

Realm configuration — important

The KeycloakRealmImport CRDs in components/keycloak/base/*-realm.yaml are disaster-recovery snapshots only. The Keycloak Operator does not reconcile them against a running realm — it only applies them the first time the realm is created.

Live realm changes must be made manually in the admin console. Treat the YAML files as the target state to keep in sync by hand, so that a rebuild from scratch reproduces the configuration.

See the upgrade guide for the full workflow for changing the image, the theme, the Keycloak version, or realm settings.