Understanding Eureka Server's Three-Level Cache Architecture

This article introduces the three-level cache architecture used by the Eureka service registry server, which consists of a read‑only cache, a read‑write (Guava) cache, and a local registry cache implemented with ConcurrentHashMap. The design aims to improve performance by reducing direct access to the underlying data store.

The read‑only cache ( readOnlyCacheMap) is a simple ConcurrentHashMap that serves as a fast‑lookup store, analogous to a database. The read‑write cache also uses ConcurrentHashMap internally but is wrapped by Guava Cache, allowing both read and write operations, similar to a Redis master node. The local registry cache ( registry) is another ConcurrentHashMap that holds the raw registration data, comparable to a Redis slave node that only reads.

When a client requests registration information, Eureka first checks the read‑only cache. If the key is missing, it falls back to the read‑write cache; if still missing, it loads the data from the local registry cache.

The local registry cache stores registration entries via registry.putIfAbsent(app). The putIfAbsent method ensures that duplicate keys are not overwritten, inserting the value only when the key does not already exist.

The read‑write cache uses Guava Cache and defines two expiration strategies: timed expiration (e.g., expireAfterWrite(180s)) and real‑time expiration triggered by service instance registration, deregistration, or failure. The timed expiration is configured with a fixed interval, while real‑time expiration calls invalidateCache to remove stale entries.

The read‑only cache is refreshed periodically (default every 30 seconds) by a scheduled task that synchronizes data from the read‑write cache. Although called “read‑only,” it is updated internally to keep the cache consistent, similar to a master‑slave replication model where the slave is refreshed from the master.

Eureka provides configuration properties to control cache behavior, such as eureka.server.useReadOnlyResponseCache (whether to use the read‑only cache) and eureka.server.responseCacheUpdateIntervalMs (the interval for synchronizing the read‑only cache, default 30 seconds). The read‑write cache’s timed expiration interval can also be adjusted.

While the three‑level cache improves read performance, it introduces consistency challenges: the read‑only cache may serve stale data for up to the refresh interval, and in a clustered Eureka setup, different nodes can have divergent cache states, leading to AP (availability‑partition tolerance) behavior rather than strong consistency. Mitigation strategies include shortening the refresh interval or disabling the read‑only cache so clients read directly from the read‑write cache.

Every 30 seconds the read‑only cache is updated from the read‑write cache.

Clients first read from the read‑only cache; if missing, they read from the read‑write cache, then from the local registry.

The read‑write cache expires automatically every 180 seconds.

Service registration, deregistration, or failure triggers immediate expiration of the read‑write cache entry.

Multi‑level caching can cause data inconsistency across nodes.