Rolling Upgrades & Patching

Keeping Keycloak current is one of the hardest parts of self-hosting — and one of the biggest reasons to be managed. We handle it with zero-downtime rolling deploys and a gated database migration step.

Why upgrades are safe here

Sessions survive restarts

persistent-user-sessions (KC 26) keeps sessions in Aurora, so restarting or replacing a task doesn’t drop logged-in users — Infinispan is just a near-cache.

Stateless tokens

Access tokens are validated in your app, so rolling tasks never invalidate issued tokens.

Clustered across AZs

Tasks are drained and replaced a few at a time behind the ALB — capacity never drops to zero.

Minor version / patch — rolling deploy

1. Pull the new Keycloak image (pinned, digest-addressed) into the cell’s task definition.
2. ALB connection draining on the old tasks; new tasks start and pass health checks.
3. Replace tasks N at a time across AZs, watching login success + p95 latency.
4. Auto-roll-back on health-check or error-rate regression.

Database migrations — always gated

Never let Keycloak auto-migrate in production

Keycloak’s startup can auto-apply Liquibase migrations. Those are DDL-heavy and non-transactional — a mid-migration failure can leave a partially-migrated schema. On distributed SQL (YugabyteDB) some DDL is unsupported/slow (startup ~138s vs ~35s on Postgres). So we disable auto-migration and run a single, gated migration-runner job with CI validation per Keycloak version before any task rolls.

1. Validate the target version’s migration against a copy of the schema in CI (Postgres and, for multi-cloud cells, YugabyteDB).
2. Snapshot the database (point-in-time restore available).
3. Run the one migration-runner job to completion (tasks stay on the old version).
4. Roll the Fargate tasks onto the new version once the schema is ready.
5. On failure, restore from snapshot — no half-migrated state in production.

Major versions — blue/green

For breaking upgrades we stand up a parallel (green) cell on the new version, replay config, validate, and shift traffic via the registry/DNS — with instant rollback by shifting back. Dedicated/silo tenants can be scheduled individually.

Patch cadence

Security patches

Applied on an expedited track when Keycloak or base-image CVEs warrant it.

Regular upgrades

Minor versions on a rolling cadence after CI validation; you don’t schedule them.

Version pinning

Images are digest-pinned; enterprise/silo tenants can pin a version and upgrade on a coordinated window.

Tip

Because migrations are gated and sessions persist, a Keycloak upgrade is a non-event for your users — no forced logout, no maintenance page. That’s the managed-upgrade promise.