Keycloak Tenant Isolation on Kubernetes: Realms vs Dedicated Releases
Keycloak realms provide logical separation inside one Keycloak deployment. A dedicated Kubernetes release per customer adds a different boundary: separate runtime, database ownership, credentials, domain, network policy, capacity, maintenance, and failure blast radius. For managed identity and white-label authentication products, the right model depends on the isolation promise—not on Helm versus Operator alone.
Direct answer
Use shared Keycloak realms when customers can safely share runtime operations and upgrade timing. Use dedicated releases when customers require independent domains, database and secret boundaries, custom extensions, regulated change control, or predictable blast-radius containment. OpenTenant can orchestrate those per-customer releases around a reviewed Keycloak deployment template.
What Keycloak provides on Kubernetes
Keycloak's Operator exposes first-class Kubernetes configuration for resources, scheduling, TLS Secret references, trusted certificates, and NetworkPolicy rules. Its advanced configuration documentation also warns that NetworkPolicy enforcement depends on a compatible cluster network plugin.
For production, Keycloak stores users, clients, realm configuration, credentials, and signing
material in a relational database. The database guide states that the default
dev-file database is for development and must be replaced for production.
These capabilities configure a Keycloak installation. They do not choose the tenancy model for the service built around it.
Realms and releases solve different problems
A realm is an application-level administration boundary. It can separate users, clients, roles, identity providers, and authentication flows while sharing the same Keycloak runtime and operational lifecycle.
A dedicated release gives a customer its own Kubernetes workload and a separately governed data and change boundary. That can include:
- a dedicated database or database-level scope and credentials;
- customer-specific TLS, hostname, themes, and identity providers;
- isolated extension and provider configuration;
- independent compute limits, topology, and maintenance windows;
- tenant-specific backup, restore, export, and deletion procedures;
- network rules that expose only required database, monitoring, and ingress paths.
The trade-off is cost and operational surface area. More releases mean more upgrades, health checks, database connections, certificates, backups, and failure modes to manage.
Reference architecture
customer identity profile
→ choose realm or dedicated-release policy
→ validate domain, database, extension, and network requirements
→ resolve tenant-scoped TLS and database secrets
→ create namespace and deploy Keycloak template
→ verify database, route, readiness, and admin boundary
→ record revision for upgrade and rollback
OpenTenant's role is to make that lifecycle repeatable. It does not change Keycloak's realm semantics, token behavior, database security, or upstream upgrade requirements.
Illustrative tenant declaration
tenant: acme
userspace:
namespace: tenant-acme-identity
domain: login.acme.example
deployment:
engine: helm
template: keycloak-production
release: keycloak-acme
config:
realmImport: acme-v3
replicas: 3
secretScope: tenants/acme/keycloak
Treat this as an architecture sketch. A production declaration should reference versioned templates and Secret objects rather than embedding database passwords, bootstrap credentials, realm signing keys, or TLS private keys.
Database ownership is the critical decision
A dedicated Keycloak pod set with shared database credentials is not a complete tenant boundary. Decide whether each customer receives a database instance, database, or schema and document the restore and deletion semantics for that choice.
Database TLS and encryption at rest remain responsibilities of the selected database platform and configuration. OpenTenant can distribute references and coordinate releases, but it should not claim to provide guarantees that belong to Keycloak or the database service.
Network and administrative boundaries
Start with denied-by-default tenant networking, then allow the paths the deployment requires: DNS, the tenant database, monitoring, and ingress or Gateway traffic. Confirm that the cluster's network plugin enforces NetworkPolicy.
Separate customer login traffic from operator administration where practical. A custom login hostname does not automatically secure the admin surface. Keep bootstrap and operator credentials in scoped secret storage, restrict admin routes, and record configuration changes in the tenant audit trail.
Upgrade and restore strategy
Keycloak upgrades can involve database migration. Test the target version against the deployment template and extensions, back up the tenant database, and promote through controlled cohorts. A Kubernetes rollback cannot reverse an incompatible database migration by itself.
Restore testing should prove that the database, realm configuration, external identity-provider secrets, TLS route, and signing behavior return together. A backup that restores only the pods is not a Keycloak recovery plan.
When realms are the better choice
Shared realms are the narrow concession: they are efficient when customers have similar availability and upgrade needs, custom code is limited, and logical administration boundaries satisfy the risk model. They reduce infrastructure cost and operational repetition.
Choose dedicated releases when the product promise requires independent runtime and change ownership. If a customer must be upgraded, restored, suspended, or exported without involving every other customer, release-level isolation is easier to reason about.
Evaluation checklist
- Is the promised isolation logical, operational, or infrastructure-level?
- Can one customer's extension or load affect another customer's login path?
- Are database credentials and restore procedures tenant-scoped?
- Are admin routes separated from public authentication routes?
- Does the cluster enforce the intended NetworkPolicy rules?
- Can a database migration be tested, backed up, and rolled back safely?
- Does offboarding remove routes and credentials before retained identity data?
OpenTenant coordinates these release boundaries while Keycloak remains the identity system and source of truth for its own security model.