Keycloak on Kubernetes with the Keycloak Operator

The database is the one part of a Keycloak deployment that holds state you cannot rebuild, so the first decision is choosing a supported engine. Keycloak's database guide lists MariaDB, Microsoft SQL Server, MySQL, Oracle Database, PostgreSQL 14 to 18, EnterpriseDB Advanced, Amazon Aurora PostgreSQL and Azure SQL as supported production databases. Confirm the exact version your platform team plans to run against that guide before you commit, because the supported range is the baseline you test against. The default dev-file database stores data on the local filesystem of a single instance. It suits local experiments only. It cannot be shared across replicas, it cannot support the high availability designs Keycloak documents, and it ties users, clients and configuration to one pod's disk.

With the Keycloak Operator, the database connection is declared in the Keycloak custom resource, and the operator turns that declaration into server configuration. Confirm the field names and the vendor value for your engine in the operator reference, since they can change between releases. Credentials belong in Kubernetes Secrets that the custom resource references by name, with one Secret for the database user and one for the password. Keep those manifests out of Git, manage the Secrets through your existing secret tooling, and restrict who can read them with RBAC. Rotating a database password then means updating the Secret and restarting the pods, which your change process should rehearse before the first rotation is due.

Keycloak migrates its database schema automatically at startup by default. For a small or non-production instance, this is the simplest path: a new pod applies pending changes before it serves traffic. For a large deployment, the upgrading guide suggests manual migration instead. Administrators generate the SQL for the target version, review it with the database team, and apply it on a schedule outside the rollout. This separates the schema change from the pod restart, lets a DBA check locking and run time against production data volumes, and gives you a script to work from if you need to roll back. The cost is process. Someone must own the SQL, and the operator update and the schema change must be sequenced so the running version always matches the schema it expects.

Before the first production start, check three things against the Keycloak database guide. First, the network policy must allow traffic from the Keycloak pods to the database port, and nothing else should reach it. Second, certificate trust must be in place so Keycloak verifies the database certificate against a CA bundle you mount into the pods. Third, the database version must fall within the supported range. Test all three in a staging namespace that uses the same network policies as production. If you plan a high availability design, confirm that the database is synchronously replicated, because the high availability documentation requires this for the supported designs. Record the test results in the change record so that auditors and operators can see the connection was verified before go-live.

Declare each OIDC or SAML client as a KeycloakOIDCClient or KeycloakSAMLClient resource and keep those manifests in the same Git repository and review process as the application that uses them. The point of this approach is that a client's redirect URIs, protocol settings and scopes change through a pull request that someone other than the author approves, and the cluster state can be traced back to a commit. The operator reconciles the Keycloak realm to match the manifest, so the manifest, not the admin console, becomes the record of what the client should look like. Client secrets should never appear in these manifests. Reference a Kubernetes Secret from the client resource and populate that Secret through your normal secret management path, such as an external secrets controller, sealed secrets or a vault integration. Confirm in your operator version's documentation exactly which secret reference fields are supported and which key names the operator expects, because the field names have changed between releases. Check also whether the operator reads the secret value into Keycloak on every reconcile, since that determines how a rotation propagates.

Drift happens when someone edits a client in the admin console during an incident or a quick fix. Decide before go-live whether the operator should revert such changes on its next reconcile or whether you accept a manual override and then fold it back into Git. Either way, run a periodic comparison between the live realm export and the manifests so unexpected edits are visible. Restrict admin console write access to a small group, and record administrative events so the change can be traced to a person and a time. Client review belongs to the team that owns the application, with the identity team as a required second reviewer for anything that changes redirect URIs, scopes, token lifetimes or authentication flows. Tie client changes to application releases: a new redirect URI should land in the same release that deploys the page that uses it, and a rollback of the application should carry its client configuration with it. Agree on this ownership model in writing before the first client is migrated.

Not every client setting necessarily maps one-to-one to a field in the custom resource. Some attributes, advanced protocol mappers or newer features may be absent from the resource schema, or may only be set through the admin console or the Administration REST API. Before you commit to a GitOps model, compare the settings your clients use against the schema of the operator version you have installed, and list any gaps. For each gap, decide whether to accept a documented workaround, extend the configuration through a realm import, or keep the setting out of scope for the operator. Record the operator version alongside the client manifests and re-run this comparison before each operator update, because field coverage can change between releases. Ask the operator's maintainers or your Red Hat support contact, if you use the Red Hat build, which fields are supported in the version you run. Test one representative client end to end in a non-production realm before relying on the resource for production.

The operating model for a Keycloak Operator deployment is set by three things: what you watch, what you back up, and how a change moves from review to production. Keycloak exposes Prometheus-format metrics at /metrics on its management interface, but only when it is started with --metrics-enabled=true. Confirm that the Keycloak custom resource sets this flag, that the management port is reachable only from your monitoring namespace, and that the scrape target is listed in your Prometheus configuration. Health endpoints on the same management interface serve liveness and readiness probes, so the kubelet can restart or drain pods without operator intervention. Your on-call team should know which signals page them, such as failed logins, latency and cache health, and which only open a ticket.

Backups need to cover three separate things. The database holds users, clients, sessions and configuration, so it needs point-in-time recovery and a restore test, not just a nightly dump. Realm exports, taken through the admin tooling on a schedule and before each change, give you a human-readable copy of realm configuration that you can diff and reload into a lower environment. The resource manifests for the Keycloak, KeycloakRealmImport, KeycloakOIDCClient and KeycloakSAMLClient objects belong in version control, because the cluster state alone does not tell you what was intended. Confirm with your database team who owns restore rights and how long a restore takes in your own environment before you rely on the plan.

Upgrades should follow one path every time. First, read the upgrade notes for every minor release between your current version and the target, since behavior changes are documented there. For the 26.8 line, these include enforced SMTP StartTLS without plaintext fallback, mandatory signature validation of backchannel logout tokens from external providers, login failures persisted to the database by default, and a recommendation to move from the deprecated multi-site feature to the stateless feature. Second, apply the upgrade in a lower environment restored from a recent database backup, and run your sign-in, token refresh and logout tests against it. Third, approve the operator update. The Keycloak Operator documentation strongly recommends manual approval mode so that no upgrade starts without a named approver.

Schema migration deserves its own decision. Keycloak migrates its database schema automatically at startup by default. For large deployments, the upgrading guide suggests manual migration, where your DBA reviews and applies the SQL before the new pods start. Choose the mode in the lower environment first, measure how long the migration takes on a production-sized copy, and record the rollback path. Note that a schema change generally cannot be reversed by redeploying an older image, so the database restore point is your real rollback.