Scaling Guide
Scaling the RealmSSO server pods is the easy part. Realm count — one per customer account — is the variable to actually watch.
Horizontal autoscaling
The Helm chart ships autoscaling off by default (autoscaling.enabled: false). The Deployment runs replicaCount: 1 until an operator opts in. Flip autoscaling.enabled: true to create a HorizontalPodAutoscaler that scales between minReplicas: 1 and maxReplicas: 10 on CPU (target 70%) and memory (target 80%) utilization. The single-replica default is deliberate (server #181): an HPA with a higher minReplicas floor would override replicaCount and re-create multi-replica state the chart intentionally left off until singleton work (webhook outbox lease, etc.) is settled. See Helm Chart Reference for the full values list, including the resources requests/limits those percentages are computed against.
| Key | Default |
|---|---|
| replicaCount | 1 |
| autoscaling.enabled | false |
| autoscaling.minReplicas / maxReplicas | 1 / 10 |
| autoscaling.targetCPUUtilizationPercentage | 70 |
| autoscaling.targetMemoryUtilizationPercentage | 80 |
Postgres and Redis are external dependencies (postgresql.enabled / redis.enabled both default to false), so scaling those — read replicas, a Redis cluster — is outside this chart's scope and is your managed provider's responsibility.
Rate limiting
Every request is capped by RATE_LIMIT_MAX requests per RATE_LIMIT_WINDOW_MS milliseconds (defaults in src/common/config/env.ts: 100 requests / 60000ms; the Helm chart sets 200 / 60000 — 200 requests per 60-second window — by default). Both are plain Helm config.* values, so raise them per-deployment if legitimate traffic from a single client (e.g. a customer's directory sync hitting SCIM in bursts) needs more headroom.
The scaling question that matters more: realm count
Under the realm-per-account model (see Accounts (Tenants), ADR 0001), every customer account gets its own dedicated Keycloak realm — a real isolation boundary, not a naming convention. The direct consequence is that the number of Keycloak realms scales 1:1 with the number of customer accounts, which is a fundamentally different scaling axis than adding RealmSSO server replicas.
Realm count, not API replicas, is the real capacity question
Each realm carries its own signing keys, caches, login pages, and admin surface. Keycloak handles dozens of realms comfortably, but ADR 0001 flags high realm counts as an open scaling question to validate before promising very large tenant counts — it hasn't been load-tested yet in this codebase. Sizing your Keycloak deployment for your target account count is a separate exercise from autoscaling the API pods above, and has no chart value to tune.