ADR-049: Horizontal scaling via multiple operator deployments (realm sharding)

Category: architecture Provenance: human

Decision

Horizontal scaling of operator capacity is achieved by deploying multiple operator instances, each managing a different subset of realms. This mimics classic sharding but at the operator deployment level. HA replicas (ADR 45) are for availability only, not capacity scaling.

Rationale

When operator reaches reconciliation capacity limits, deploy additional operators rather than adding more replicas to a single deployment. Each operator manages a different set of realms - effectively sharding by realm. This is simpler than implementing proper work distribution/sharding within a single operator deployment, and achieves the same result. Users configure CRs to reference specific operators. Known limitation - all operators still monitor all CRs cluster-wide, but only reconcile CRs that reference them. If monitoring overhead becomes an issue (unlikely for 99% of users - would require enormous clusters), there is no solution within this architecture. Keycloak API is almost certainly the bottleneck before operator capacity becomes an issue.

Agent Instructions

Horizontal scaling uses multiple operator deployments, each managing different realm subsets. Do not use HA replicas for capacity scaling.

Rejected Alternatives

Use HA replicas for capacity scaling

Active-standby HA (ADR 45) does not increase capacity - only one replica is active. Would require complex active-active work distribution.

Implement proper sharding within single operator

Much more complex to implement. Would still shard by realm, resulting in essentially the same architecture but requiring more configuration in CRs.

Namespace-scoped operators to reduce monitoring overhead

Loses ability to watch cross-namespace resources. Monitoring overhead is negligible compared to reconciliation work.