T

Stéphane Tailland a97399c2bf Import the realm on every start, so the file is the source of truth

configmap-realm.yaml was a first-install seed: `start --import-realm`
skips a realm that already exists and logs "Import skipped", so editing
the file changed nothing on a restart and the truth drifted into the
database. It already had — four scope grants existed only in the running
realm.

There is no option to make the startup import overwrite. The --override
flag exists only on the standalone `import` command, and the Keycloak
documentation is explicit that re-creating realms means running that
command before starting the server. So the import moves into an init
container that runs `import --dir ... --override true`, and --import-realm
comes off the main container's args.

The init container empties JAVA_OPTS_APPEND for itself. It inherits the
main container's env, which loads the OpenTelemetry agent from a volume
the other init container downloads into and this one does not mount;
inherited verbatim, the JVM fails before the import runs.

What this costs, deliberately: the realm is replaced at every start, so
anything created at runtime and not written back to this file is lost, and
active sessions are dropped. Checked before enabling it — the five users
in the realm are the five declared here, and the only live sessions were
two LibreChat ones. Nothing is to be created through the admin console
expecting it to last.

Verified after the switch: the import logs "Strategy: OVERWRITE_EXISTING",
the realm still has its 21 clients with no optionalClientScopes
divergence, and the full identity chain still returns 200 — pm-user token,
exchanged by the Catalogue agent, accepted by catalog-mcp.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-28 09:37:35 +02:00

compose

first commit

2026-05-07 21:08:39 +02:00

k8s

Import the realm on every start, so the file is the source of truth

2026-08-28 09:37:35 +02:00

.DS_Store

first commit

2026-05-07 21:08:39 +02:00

.gitignore

Stop versioning the real secret.yaml

2026-08-25 07:30:20 +02:00

OIDC.md

first commit

2026-05-07 21:08:39 +02:00

README.md

first commit

2026-05-07 21:08:39 +02:00

README.md

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.