Backstage cache with Redis or Valkey

When a Backstage cache must be shared, and how to configure it

Once you run two or more Backstage backend instances behind a load balancer, you need a shared cache store, because a per-process cache gives different answers depending on which instance serves the request. Backstage's architecture overview lists Redis, Memcache, Infinispan and in-memory caching as supported stores, and for a multi-instance deployment the choice narrows to a network store that every instance can reach. A cache holds short-lived data that plugins and the core backend reuse, such as responses fetched from external systems and intermediate results that are expensive to recompute. Because each instance reads and writes the same keys, a user who refreshes a catalog view should see the same data whichever backend handles the request.

A single instance with in-memory caching is enough when you run one backend process, have no rolling upgrades that overlap instances, and can accept losing cached data on restart. In that case the cache only costs memory in the backend process, and nothing needs to be operated. Once a second instance exists, even briefly during a rolling deployment, the in-memory cache stops being consistent across processes. Confirm your replica count and deployment strategy before you decide, since the cache choice is hard to change later without a planned cutover.

Between Redis and Valkey, the Backstage documentation does not prescribe one, so the decision rests on licensing, support and what your platform team already runs. Redis 8 and later are offered under RSALv2, SSPLv1 or AGPLv3 at your choice, while Valkey is BSD-3-Clause, so confirm the license terms with your legal team against the Redis licenses page. Whichever store you pick, test failover before go-live, because a cache outage should degrade Backstage gracefully rather than break sign-in or catalog reads. Ask your platform team who will size and patch the store and how they will monitor memory use and eviction.

Which cache store fits your Backstage deployment

This table compares in-memory, Memcache, Infinispan, Redis and Valkey against the deployment situations that usually decide the choice. Read each row against your instance count, your existing estate and your license requirements, then confirm the cache configuration keys in the Backstage docs for your version.

Option	Best fit	Licensing and trade-offs	Confirm before choosing
In-memory	One Backend instance where cache loss on restart is acceptable	No shared state, so each instance keeps its own cache and entries are not reused across replicas	Whether your Backstage version still defaults to in-memory for each plugin
Memcache	Existing Memcache estate that your operators already run and monitor	Supported by Backstage per the architecture overview, but Memcache has no built-in persistence or replication for cache data	Your Backstage version's cache store configuration keys and client settings
Infinispan	Existing Infinispan or JVM-centric estate with operators who already manage it	Supported by Backstage per the architecture overview, adds a Java-based component to operate beside Node.js services	Cluster sizing, eviction settings and the Backstage configuration keys for your version
Redis 7.2 and earlier	Shared cache across instances where a permissive license is required	BSD-3-Clause, so the license is permissive for these versions	Your distribution's version and whether your package source still ships this line
Redis 7.4 to 7.8	Shared cache where the team accepts the source-available license terms	Dual RSALv2 or SSPLv1, neither OSI-approved, so legal review is needed	Whether your legal team accepts RSALv2 or SSPLv1 terms for a hosted service
Redis 8.0 and later	Shared cache where you can pick AGPLv3 as the license	Choice of RSALv2, SSPLv1 or AGPLv3, effective from the Redis 8 general availability release	Which license you elect and whether any AGPLv3 obligations apply to your deployment
Valkey (BSD-3-Clause)	Shared cache where a permissively licensed store is required and Redis client libraries are in use	Forked from Redis before the source-available change, governed by LF Projects, LLC	Current stable line and the release your Backstage version tests against

Redis, Valkey or the licensing question behind the choice

The licensing question comes before the technical one. In March 2024, Redis moved from BSD-3-Clause to a dual license of the Redis Source Available License v2 (RSALv2) and the Server Side Public License v1 (SSPLv1), neither of which is OSI-approved. Procurement and legal teams need to know which license applies to the exact Redis version they plan to deploy. According to the Redis licenses page, Redis 8.0 and later can be used under RSALv2, SSPLv1 or the GNU AGPLv3, at the user's choice, while Redis 7.4.x through 7.8.x remain under the dual RSALv2 or SSPLv1 terms. Redis 7.2.x and earlier remain under BSD-3-Clause. Confirm with counsel whether AGPLv3 is acceptable for your use, including the network-service obligations that apply if you modify Redis code, and read the Redis licenses page before selecting a version.

Valkey is the main alternative with a permissive license. It is licensed under BSD-3-Clause, was forked from open-source Redis just before the license change, and is an open community project under LF Projects, LLC. Valkey is compatible with Redis OSS 7.2 and all earlier open-source Redis versions, so existing Redis client libraries connect without code changes, and a move from those versions is effectively an upgrade. Redis 7.4 and later produce data files that are not compatible with Valkey, so the migration method depends on the Redis version you run today. Check the running version before choosing between copying an RDB snapshot, replication, key-level migration or cluster replica promotion, and ask your Backstage team to confirm which method the Valkey migration guide covers for that version.

Before the decision, have legal review the Redis licenses page and the Valkey migration guide against your deployment model. Record the Redis or Valkey version, the license it ships under, whether you modify the server or only run unmodified artifacts, and whether the cache is exposed to any service users. Then choose the cache version with those facts in hand. Plan for the license to be reviewed again at each major upgrade, since the terms of a given Redis line can differ from the one you deployed earlier.

What Backstage plugins cache and what that means for sizing

Catalog and search results are usually the most read-heavy cache consumers in a Backstage instance. Catalog reads from the frontend and from other plugins repeat the same entity lookups, and list views and search queries generate result sets that can be cached briefly to avoid repeated database work. The volume here grows with the number of entities, the number of users browsing the portal, and how many distinct filter combinations people use. Entry size depends on the entity payload each plugin chooses to store, so a large catalog with rich annotations produces larger values than a small one.

Entity lookups: Individual entity reads by reference are typically the most frequent keys, with one key per entity or per query shape.
List and filter results: Each distinct filter or pagination combination can create its own key, so key count can rise faster than entity count.
Search results: Search caching stores query results for a limited time, and key count follows the variety of user queries.
Value size: Larger entities with many annotations and relations increase the bytes stored per key.
Sizing check: Ask the catalog and search plugin documentation for the exact cache keys and TTLs in your version, then measure key counts under realistic browsing.

Confirm with your plugin versions which catalog and search caches are active and what their expiry settings are before you set memory limits.

Setting up a shared Redis or Valkey cache for Backstage

This sequence takes a shared cache from version selection to a verified state where every Backstage backend replica reads and writes to one store. It also shows how to confirm that the cache keeps working when it restarts.

Confirm Backstage and Node.js versions
The platform engineering lead checks which Backstage release line the portal runs and confirms the Node.js version against the versioning policy, which currently supports two adjacent even-numbered Node.js releases. Record the Backstage version and the Node.js version in the change ticket, because cache client behavior is tied to the runtime the backend uses. This step is done when both versions are written down and the team has confirmed that the current Backstage release line supports them. Confirm the exact supported pairs with the versioning policy before you upgrade anything.
Choose the store and release line
Decide between Redis Open Source 8.x and Valkey 9.1, the current stable lines in the supplied release data. Check the license terms with your legal team, since Redis Open Source 8.0 and later are offered under a license you choose from several options, while Valkey is licensed under BSD-3-Clause. Confirm that your hosting platform, managed service offering and support contract cover the chosen product and version. This step is done when the team has a written decision that names the product, the release line and the license basis.
Deploy a standalone cache with authentication and TLS
The platform team deploys one standalone instance inside the same network zone as the Backstage backends, with password or ACL authentication and TLS enabled for client connections. Keep the cache off public networks and restrict access to the backend subnets or namespaces. Store the credentials in your secrets manager rather than in plain configuration files. This step is done when a test client can connect over TLS with credentials and is refused without them.
Point each backend cache configuration at the store
The Backstage owner updates the backend cache configuration in every replica so each one uses the same store, host, port, TLS setting and credentials, supplied through environment variables or secrets. Use the same configuration for every replica, including any backend split into separate deployments, so that cached entries are shared. Redeploy the backends in a rolling fashion and avoid mixing in-memory caching with the shared store. This step is done when every replica starts without cache errors in its logs.
Add Sentinel if failover is required
If the cache must fail over automatically, deploy Sentinel for Redis or Valkey, which applies only when you are not using Redis Cluster or Valkey Cluster. Run at least three Sentinel instances, as both project guides recommend, spread across failure domains. Configure Backstage to discover the primary through Sentinel rather than a fixed address, and confirm the client library in your build supports it. This step is done when a controlled failover promotes a replica and the backends reconnect without manual changes.
Verify connectivity from every replica
Run a connection check from each backend replica, either by reading the application logs for cache connection messages or by opening a test session from the pod or host. Confirm that every replica reports the same store endpoint and that none falls back to in-memory caching silently. Document the result per replica so that a single misconfigured instance is visible. This step is done when all replicas show successful connections to the same endpoint.
Confirm keys appear from catalog and auth activity
Sign in through the configured identity provider and browse a few catalog entities, then inspect the cache for new keys using the store's key listing command in a non-production copy or with a restricted account. Confirm that keys from catalog and authentication activity appear and expire as their time-to-live settings dictate. Watch memory usage for a short period, since the amount of cached data depends on your catalog size and plugins. This step is done when the team can show keys created by real activity and a stable memory trend.
Confirm behavior when the cache restarts
Restart the cache in a controlled window and observe the backends. Confirm that Backstage keeps serving requests, that cache misses lead to recomputation or fresh fetches, and that connections recover without a backend restart. Check whether the cache is configured to persist data, and confirm with your platform owner what data loss is acceptable after a restart. This step is done when the restart test produces a written result that matches the expected behavior.

Sizing and availability decisions for the cache

The cache affects how Backstage behaves under load and during failures, so the choices below need to be made together. Each card covers one decision the team should settle before the shared store goes into production. Confirm the answers against your own measurements and your plugin configuration, not against defaults.

Size memory from measured key volume

Memory need depends on how many keys the plugins write and how large their values are, which varies with catalog size, search index use and the number of users. Measure key count and memory use in a staging environment that mirrors production traffic, then add headroom for peaks such as a catalog refresh. Ask your Redis or Valkey provider how memory use grows with replicas and persistence enabled, because both consume extra memory.

Choose an eviction policy deliberately

When memory is full, the server must either reject writes or evict keys. For a cache, eviction is usually the intended behavior, but the policy decides which keys go first. Confirm with each plugin's documentation whether any data it stores is not safe to lose, such as session or token state, and keep that data out of the evicting store or give it its own instance.

Decide between persistence and a pure cache

A pure cache keeps data only in memory, so a restart empties it and the plugins refill it from their sources. RDB snapshots or AOF logs keep data across restarts at the cost of disk I/O and recovery time. Most Backstage cache data can be rebuilt, but confirm this per plugin before turning persistence off, since some plugins may hold state that is slow to regenerate.

Pick Sentinel or Cluster for failover

Sentinel provides automatic failover for a primary and its replicas when you are not using a cluster, and both Redis and Valkey recommend at least three Sentinel instances for a robust setup. Cluster shards data across nodes and is a larger design. For most single Backstage deployments, the question is whether one dataset fits on one primary. Confirm that Backstage's cache client supports your topology before choosing.

Place replicas across failure domains

Sentinel and replicas only help if a single failure cannot take out the primary and all of its copies. Spread Sentinel instances and replicas across separate hosts, availability zones or racks, and check that the quorum survives the loss of one zone. Place the Sentinels on hosts that do not share the failure domain of the primary, and test a failover before go-live.

Decide whether a cache outage blocks Backstage

Ask what happens to each Backstage request when the cache is unreachable. Some plugins may fall back to their source, which slows responses, while others may fail the request. Test this by stopping the cache during a staging run and watching catalog pages, search and scaffolder actions. Set alerts on cache connection errors so the team learns of an outage before users report slow pages.

Securing the cache connection and its data

A cache looks like a disposable performance layer, but the entries it holds can include catalog and session data that reflect who uses the portal and what they can reach. The cards below cover the controls that protect the connection, the credentials and the data, along with the patching step that keeps the cache server current.

Isolate the cache on a private network

Place the Redis or Valkey endpoint on a private subnet that only the Backstage backend pods or processes can reach, and block it from developer workstations and other application tiers. Confirm that no public load balancer, NodePort or security group rule exposes the cache port. If you run Redis Sentinel or Valkey Sentinel, apply the same restriction to the Sentinel ports and to replication traffic between nodes.

Require authentication and TLS

Enable password or ACL authentication on every node and configure the Backstage cache client to use TLS if your cache server and client libraries support it in your environment. Check the server's TLS and ACL settings against the version you deploy, because the options differ between releases. Confirm that plaintext connections are rejected on the production endpoint.

Keep the cache password out of images and source

Store the cache credential in your secret manager or a Kubernetes Secret with encryption at rest, and inject it at runtime as an environment variable or mounted file. Keep the cache host and password references out of app-config.production.yaml committed to source control, and confirm that the production image build does not copy the value into any layer. Rotate the credential on a schedule you set and test that Backstage reconnects after the change.

Treat cached data as sensitive

Cached entries can include catalog entity data, user identity references and session-related values, depending on which plugins write to the cache. Ask each plugin owner which keys they store, how long they live and whether any value contains tokens or personal data. Set expirations so stale identity data does not persist, and confirm that the cache is included in your data classification and access review.

Patch the cache server on security releases

Track security releases for the Redis or Valkey line you run, and plan a rollout for each one. Recent examples include Redis security releases 8.10.2, 8.8.3, 8.6.7, 8.4.7 and 8.2.10, shipped together on September 17, 2026, and Valkey 9.1.2, published on September 1, 2026. Confirm your own patch window, approval path and testing steps with your security and platform teams before you need them.

Common questions about Backstage caching

Is in-memory caching enough for Backstage?

In-memory caching can be enough for a single Backstage backend instance, such as a development or small pilot environment. Once you run more than one backend instance, each process holds its own cache, so a catalog or search result cached on one replica may be missing or stale on another. A shared store such as Redis or Valkey gives every instance the same cache view. Confirm your replica count and which plugins you run before deciding, because the answer depends on your deployment shape rather than on team size.

What drives the cost and effort of a Backstage cache setup?

Most of the cost is in-house staff time and the infrastructure you run the cache on. Effort rises with the number of backend instances, the choice between a managed service and a self-operated server, how many plugins rely on caching, and the availability target you set. Recurring costs include the cache hosting, monitoring, patching and licensing review, while the design and initial configuration are one-time work. Ask any partner for a quote that lists each of these components separately and states what is one-time and what recurs.

How long does it take to configure a Backstage cache?

The configuration change in Backstage itself is small, but the surrounding work determines the duration. Teams usually spend more time choosing the store, provisioning a highly available topology, agreeing on network and secret handling, and testing failover than editing the app configuration. A single-instance test can move quickly, while a multi-instance production rollout that includes Sentinel or a managed service takes longer. Ask for a timeline in the written scope that lists these phases separately, since no fixed duration is supplied here.

What do you need from us to set up the cache?

Expect to provide access to the environment where Backstage runs, including the Kubernetes cluster or hosts, the network paths between backend instances and the cache, and the secret store used for connection credentials. You also need the current Backstage version, the list of enabled plugins and their cache usage, the expected number of backend replicas, and the availability target from your operations team. A plugin inventory is especially useful because it shows which caches are actually used. Confirm these items during scoping so the quote reflects your real environment.

Can our own team set up the Backstage cache without a partner?

Yes, if your team already operates a cache service and has Backstage experience. The core task is a configuration change, a reliable shared store and a tested failover path. The areas that need the most care are high availability design, sizing, secret handling and verifying that each plugin behaves correctly with the chosen store. Teams without that operational background often bring in outside help for the design and the verification, then run the result internally. Your team can decide the split based on its skills and staffing.

Does Redis or Valkey licensing change which cache we should choose?

Licensing matters because it affects how you can use and distribute the software. Redis Open Source 8.0 and later can be used under a license of your choice among RSALv2, SSPLv1 and AGPLv3, while Redis 7.4.x to 7.8.x use RSALv2 or SSPLv1, neither of which is OSI-approved. Redis 7.2.x and earlier use BSD-3-Clause. Valkey is licensed under BSD-3-Clause and is an open community project under LF Projects. Have your legal and procurement teams review the exact version you plan to deploy before you choose.

How do we keep the Backstage cache available during failures?

For a non-clustered setup, Redis Sentinel or Valkey Sentinel can provide automatic failover that promotes a replica to master. Both projects document running at least three Sentinel instances for a robust deployment. Clustered setups use a different topology. Test the failover path in a non-production environment, confirm how Backstage behaves while the cache is unavailable, and record the result so operations staff know what to expect during an incident.

Does DeployOpen cover the cache work in an engagement?

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so cache design, configuration and verification can be part of a fixed-scope engagement. The written scope defines which plugins, environments and failover tests are included. Ongoing operation, upgrades and testing can be covered by a retainer. Pricing follows from that written scope, so ask for a quote based on your specific environment.

Limits to confirm in your environment

The cache choice depends on details that change between Backstage releases, client libraries and cloud offerings. The cards below list the points to verify against your own versions and environment before you write the configuration or sign a managed service contract.

Supported cache store types

Confirm which cache stores your Backstage version supports with the Redis or Valkey backend in its configuration reference, since the architecture overview names Redis, Memcache, Infinispan and in-memory options. Check whether your version handles a Valkey endpoint the same way it handles Redis, because the configuration keys and connection behavior may differ. Record the exact release you run, not the latest one.

Client library and Node.js compatibility

Backstage's Redis client library must work with the Node.js versions your Backstage release supports. Confirm the client version pinned in your dependency tree, then test connection, reconnect and TLS behavior against the exact Redis or Valkey server version you plan to run. Treat a client upgrade as a change that needs its own test cycle.

Plugin behavior when the cache is down

Each plugin that reads the cache must be tested with the cache unavailable. Some plugins may fall back to fresh requests, which raises load on upstream systems such as source control or Kubernetes, while others may return errors to users. Ask each plugin owner or review its source to learn which behavior applies, and set alerts for the fallback path.

Memory and eviction under load

Measure how much memory cached entries use under your catalog size and plugin mix, then decide on a maximum memory limit and eviction policy. An eviction policy that removes keys unexpectedly can cause cache misses across all instances at once. Load test with realistic catalog and search traffic before setting the limit, and watch hit rates after go-live.

Managed service residency and licensing

Managed Redis or Valkey services from cloud providers may differ in the engine version they offer, the region where data is stored, and the license terms attached to the product. Confirm with the provider which engine version and region apply, and check whether your data residency rules allow the chosen region. Redis licensing terms differ by version, so review the Redis licenses page against your legal team's requirements.

How DeployOpen scopes and delivers Backstage cache work

DeployOpen approaches Configuring the Backstage cache with Redis or Valkey as a written, fixed-scope piece of work inside your own infrastructure. We agree the cache store, the plugins that use it, and the availability design before any configuration changes, then test and document the result so your team can operate it after handover.

How we scope

Confirm how many Backstage instances share the cache and which plugins are expected to use it.
Agree the choice between Redis, Valkey, Memcache, Infinispan or in-memory caching for each environment.
Record the license, support and hosting constraints that affect the cache choice in the written scope.

How we build

Configure the cache store and connection settings in your Backstage app configuration for each environment.
Set up high availability with Sentinel or your chosen topology, with at least three Sentinel instances where that model applies.
Test failover, cache loss and restart behavior against your Backstage instances before sign-off.

How we hand over

Deliver the configuration files, deployment manifests and a runbook covering sizing, eviction and failover steps.
Walk your platform and security engineers through the cache design and the reasons behind each decision.
Document the upgrade path for the cache engine and the Backstage version it must stay compatible with.

How we support

Offer ongoing support, upgrades and continuous testing for the cache layer as a retainer, if you want it.
Review cache metrics and engine release notes with your team when security or maintenance releases ship.
Plan engine migrations, such as moving between Redis and Valkey, as a separately scoped piece of work.