Keycloak Memory and Heap Sizing Calculator

How this estimate is calculated

The model is deliberately simple, and every constant it uses is listed below so you can replace one with a figure from your own deployment. It is an estimate for planning, not a measurement of any particular installation, and it is only as good as the per-session size you feed it.

Two of the inputs below are documented Keycloak figures. The rest are assumptions, and they are marked as such.

• Session footprint (assumption). The cluster-wide cache figure is your session count times the per-session size you selected times the number of in-memory copies. The 4.5 KB default is an estimate, not a Keycloak figure: the selectable sizes are planning assumptions for leaner or larger session data. They are not token-size measurements or documented per-session memory costs.
• Base memory (documented). Keycloak's sizing guidance states that "the base memory usage for a Pod including caches of Realm data and 10,000 cached sessions is 1250 MB of RAM". That figure is total instance memory, not heap, so the baseline used here is 1250 MB minus the documented 300 MB non-heap allowance, or 950 MB of heap. Each realm past the first adds a further 100 MB, which is an assumption rather than a documented figure, on the basis that a realm carries its own configuration, keys and client set in the realm cache.
• Working headroom (assumption). The per-node heap is the session share plus the base, multiplied by 1.2 to leave room for request-time allocation and garbage collection slack. There is no documented multiplier for this; 20 percent is a planning convention.
• Node count (assumption). Nodes are added so that no single node holds more than 3 GB of session cache, with a floor of two nodes so that a rolling restart is possible. Real node count is usually decided by CPU rather than by memory: the sizing guide allocates 1 vCPU per 15 password logins per second and 1 vCPU per 120 refresh requests per second, and that arithmetic is worked through in the sizing article rather than here.
• Container limit (documented). The container image sets the heap as a percentage of the container limit, not the reverse, using -XX:MaxRAMPercentage=70, and the sizing guide budgets approximately 300 MB of non-heap memory per instance. The documented rule is (total instance memory - 300 MB non-heap) / 0.7, and because the heap is exactly that subtraction, the limit above is heap / 0.7. The 300 MB of non-heap memory is already covered by the remaining 30 percent of the limit, so it is not added again.
• Cache owners on current releases. The caching documentation states that session data is "stored in the database by default and loaded on-demand", and that the internal user and client session caches "run with only a single owner for each cache entry". On such a release the 2-owner and 3-owner settings model an older or externally-replicated topology and will overstate memory. Select the lowest option that matches your deployment.

Read how the Infinispan cache and heap figures are derived for the documented sizing model, cache limits, and CPU calculations that complement this estimate.

Related guides

• Keycloak memory usage and heap sizing — the documented sizing model, cache tuning and what to monitor.
• Realms, clients and token design fundamentals — why token size and realm count drive these numbers.
• Keycloak hostname and proxy errors — get the deployment answering correctly before you size it.
• Keycloak vs authentik vs Authelia — if the estimate looks heavier than the requirement justifies.