Let’s establish clear definitions before exploring the decision-making involved.

In Keycloak, the open-source Identity and Access Management (IAM) server built by Red Hat, a realm is the top-level container for a set of users, clients, roles, and configuration — essentially a self-contained security domain. Realm sizing refers to understanding and planning for how much data (users, sessions, clients) a single realm can comfortably hold while continuing to perform well and remain operable. Sharding refers to the strategy of deliberately splitting what could have been one enormous realm’s worth of data across multiple realms (or, more broadly, multiple Keycloak deployments) to keep each individual piece manageable.

It’s important to understand that Keycloak doesn’t have a single, universal “maximum realm size” number that applies to every deployment — the practical ceiling depends heavily on factors like the underlying database’s performance, the caching and clustering configuration, the number of concurrent active sessions, and the hardware resources allocated to the deployment. Realm sizing is therefore less about memorizing a fixed limit and more about understanding which factors actually constrain a realm’s growth, so an organization can plan proactively rather than discovering the limit painfully in production.

Let’s examine exactly which pressures cause a growing realm to strain.

As a realm accumulates more users, more active sessions, and more clients, several distinct subsystems inside Keycloak come under increasing pressure, and they don’t all strain at the same rate or for the same reason.

None of these pressures appear suddenly at some universal threshold — they build gradually, and different organizations will notice strain at very different scales depending on their specific database technology, hardware, caching configuration, and usage patterns (a realm with a modest user count but extremely high login frequency can strain differently than a realm with many users who rarely log in). This is precisely why realm sizing requires ongoing measurement and planning rather than a one-time decision made at initial setup.

Let’s map out which parts of Keycloak’s architecture are most directly shaped by realm sizing decisions.

When an organization decides that sharding is the right strategy, it typically chooses one or more dimensions along which to split its identity data into separate realms. Common sharding dimensions include splitting by business unit, by geographic region, by product line, or by customer/tenant (particularly relevant for B2B SaaS providers, where the Organizations feature and realm sharding can sometimes be complementary strategies at different scales).

graph TD
    A[Single Massive Realm] -->|Sharding Decision| B[Realm: Region - EU]
    A -->|Sharding Decision| C[Realm: Region - APAC]
    A -->|Sharding Decision| D[Realm: Region - Americas]
    B --> E[Own DB Load, Own Cache, Own Blast Radius]
    C --> F[Own DB Load, Own Cache, Own Blast Radius]
    D --> G[Own DB Load, Own Cache, Own Blast Radius]
        

Let’s walk through the process a team typically follows to decide whether and how to shard.

sequenceDiagram
    participant Team as Platform Team
    participant KC as Keycloak
    participant DB as Database
    Team->>KC: Measure user count, sessions, latency
    Team->>DB: Analyze query performance trends
    Team->>Team: Project growth, identify binding constraint
    Team->>Team: Evaluate vertical scaling feasibility
    alt Vertical scaling sufficient
        Team->>KC: Increase capacity, monitor
    else Sharding needed
        Team->>Team: Choose sharding dimension
        Team->>KC: Plan and execute realm split/migration
        Team->>KC: Monitor new realms post-migration
    end
        

Let’s dig into the specific technical mechanisms that determine practical realm capacity.

Keycloak stores nearly all persistent realm data — users, credentials, roles, clients, and configuration — in a relational database. The performance characteristics of that database, including how well its tables are indexed and how efficiently common queries (like searching for a user by username or email) execute as row counts grow, is one of the most fundamental factors shaping practical realm size.

Beyond the database, Keycloak’s distributed caching layer (which manages active sessions, authentication session state, and various runtime caches) has its own capacity considerations, primarily driven by available memory across the cluster. A realm with an extremely high number of concurrently active sessions needs proportionally more cache capacity, independent of how many total (not concurrently active) user accounts exist in that realm.

Let’s trace what actually happens to data during a realm-splitting migration.

These two strategies address the same underlying pressure in fundamentally different ways.

A useful mental model is that vertical scaling buys time and simplicity, while sharding buys long-term structural headroom and reduced blast radius at the cost of ongoing operational complexity. Many organizations reasonably choose to scale vertically for as long as it remains sufficient, reserving sharding for the point where either technical limits or organizational/compliance reasons make a genuinely compelling case for it.

Sharding is a powerful tool, but every tool has costs worth weighing honestly.

The right balance point depends heavily on organizational context. A company already structured into clearly separate divisions or regions may find sharding along those lines relatively natural and low-friction. A company with a single, unified user base and no compelling organizational boundary to split along may find that investing in strong vertical scaling and careful database tuning delivers most of the benefit with far less operational overhead.

Sizing and sharding decisions carry security implications that deserve deliberate attention.

Good sizing decisions depend entirely on good measurement — let’s cover what to track.

A handful of recurring patterns show up across teams that have navigated realm growth successfully.

A concise checklist for teams planning ahead for realm growth.

Realm sizing and sharding decisions show up across a wide range of organizations that grow into needing them.

Across these examples, successful sharding decisions tend to follow organizational logic that already exists, rather than being purely reactive technical fixes — reinforcing that the best sharding strategy is usually the one that makes sense on a whiteboard even before performance metrics are considered.

Common questions teams ask when first thinking about realm sizing and sharding.

There is no single universal number — practical capacity depends on the underlying database, hardware, caching configuration, and usage patterns. Sizing should be based on measuring your specific deployment’s behavior rather than assuming a fixed industry-wide limit.

No. Many organizations run a single, well-tuned, appropriately-scaled realm indefinitely without ever needing to shard. Sharding is a response to specific, measured pressure points or organizational needs, not an inevitable milestone every deployment must reach.

Not entirely — they solve related but distinct problems at different scales. Organizations helps manage many B2B tenants cleanly within one realm; realm sharding addresses situations where a realm itself (regardless of how tenants are organized within it) has grown too large for a single deployment to handle comfortably.

Data integrity issues — particularly around credentials, role mappings, and federated identity links — pose the greatest risk, since errors here directly and immediately affect real users’ ability to authenticate correctly.

Yes. Total user count primarily affects database size and search/administrative performance, while concurrent session count primarily affects the distributed cache layer’s memory usage. A realm can have very high numbers on one metric and comfortable numbers on the other.

Ideally, well before any specific metric approaches a known limit — establishing regular monitoring and periodic capacity reviews from early in a deployment’s life gives the team enough lead time to plan a calm, well-tested response rather than a rushed one.

Realm Sizing and Sharding Strategy is fundamentally about recognizing that a Keycloak realm’s practical capacity is shaped by several distinct, independently measurable pressures — database performance, concurrent session volume, administrative usability, and incident blast radius — rather than one fixed limit. Organizations facing genuine growth-driven strain have two broad responses available: scaling the existing realm’s infrastructure vertically, or deliberately sharding identity data across multiple realms along a natural organizational boundary. Neither choice is universally correct; the right answer depends on measured data, projected growth, and how well a given sharding dimension aligns with the organization’s existing structure.