Stéphane Tailland
1b613768e7
This file is a bootstrap seed, not the live realm. Keycloak starts with
--import-realm under IGNORE_EXISTING and logs "Realm 'classic-models'
already exists. Import skipped", so editing it changes nothing on a
restart and the truth lives in Keycloak's database.
That divergence had already opened, in the direction that hurts: four
authorisations existed only in the running realm, granted through the
admin API while working out which audiences the gateway actually needs.
classic-models-agent-catalogue +catalog-api-audience
+sales-api-audience
+kong-token-exchange-broker-audience
librechat +classic-models-agent-catalogue-audience
Rebuilding the realm from this file would have left the Catalogue agent
with two of its five scopes and no indication why it stopped working.
Compared object by object against the live realm: the inventories already
matched — 21 clients, 38 client scopes, none missing either way — so the
drift was in contents, not in the lists. optionalClientScopes are now
copied back for every client that differed, and a re-comparison reports no
remaining gap.
This closes today's drift; it does not fix the mechanism that allows it.
Keeping a seed honest by hand is the same arrangement the Flux entrypoints
had before they were made self-reconciling, and it will drift again.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pm-keycloak
Keycloak deployment with declarative realm configuration via keycloak-config-cli.
Stack
- Keycloak 26.5.4 — identity and access management
- PostgreSQL 16 — persistent storage
- keycloak-config-cli 6.5.0 — declarative realm configuration
Installation
Prerequisites
- Docker and Docker Compose
Setup
cd compose
cp .env.example .env
Edit .env with your credentials:
COMPOSE_PROJECT_NAME=pm-keycloak
KC_DB_PASSWORD=<your-db-password>
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=<your-admin-password>
Start
docker compose up -d
Keycloak is available at http://localhost:8080.
keycloak-config-cli runs once at startup, applies all realm configuration files, then exits. This is expected behavior.
Configuration
Realm configuration files live in compose/keycloak-config/. Each .yaml file maps to one realm.
Apply configuration changes
After editing a realm file:
docker compose run --rm keycloak-config-cli
File structure
compose/keycloak-config/
├── master-realm.yaml # minimal patch of the master realm
└── demo-realm.yaml # example realm with roles and clients
Managed mode
IMPORT_MANAGED_REALM: full is set, meaning keycloak-config-cli is the source of truth for each realm it manages. Anything not declared in a YAML file will be removed from Keycloak on the next apply.