How CARTO uses Caches

Distinguish CARTO's two caching layers — the user-facing HTTP cache (Varnish) and the internal in-memory store (Valkey)

Two caches, two purposes

CARTO Self-Hosted has two distinct caching layers, and they are easy to confuse. When admins say "the cache," they usually mean the HTTP cache — the layer that shapes what end users experience. CARTO also runs an internal in-memory store, which is technically a cache too but serves a completely different purpose. Keep them separate:

Layer	Technology	What it does	User-facing?
HTTP cache	Varnish (http-cache)	CDN-style response caching in front of the APIs — serves repeated read-heavy responses (e.g. maps-api tiles/metadata) without re-computing them. The layer that directly shapes the end-user experience.	Yes
In-memory store	Valkey (valkey)	Internal acceleration: cached credentials/tokens, metadata, session/auth state, and rate-limit counters. Ephemeral; not served to end users.	No

The two sections below explain each one. When planning capacity, troubleshooting end-user latency, or configuring high availability, treat them separately.

HTTP cache (Varnish)

The HTTP cache is the layer most admins mean by "the cache." It sits in front of the CARTO APIs and serves repeated read-heavy responses — map tiles and metadata from maps-api, and some workspace-api responses — without re-computing them, CDN-style. It is therefore the layer that most directly shapes end-user experience and latency.

In CARTO Self-Hosted the HTTP cache ships as the bundled http-cache component (Varnish). In kubectl get pods it appears as carto-http-cache-* (prefixed by your Helm release name). It is part of the deployment and requires no external service. For how it fits into the request flow, see the Architecture overview.

The HTTP cache holds responses only — it is not where platform state lives. Cached content is purged automatically when the underlying data changes (via the cdn-invalidator-sub worker).

In-memory store (Valkey)

The in-memory store is an internal layer — not user-facing. CARTO uses Valkey to cache credentials and tokens, frequently-read metadata, session and authentication state, and rate-limit counters, accelerating work inside the platform. It is ephemeral and can be flushed without losing persistent data (which lives in the metadata database). A bundled Valkey instance is included in the deployment and is suitable for most production workloads; it runs as the valkey component, appearing as carto-valkey-* in kubectl get pods (prefixed by your Helm release name). For high availability, multi-replica scaling, or advanced operational controls, you can configure an external managed in-memory store (a Valkey- or Redis-compatible service) instead.

Valkey replaces Redis as of CARTO Self-Hosted 2026.04. Valkey is an open-source fork of Redis 7.2 and is fully wire-compatible: existing external Redis instances continue to work as a drop-in store without configuration changes. For versions earlier than 2026.04, see the legacy documentation.

The in-memory store sits in front of slower lookups: CARTO services check it first for cached credentials, metadata, and rate-limit state before falling back to the metadata database or re-establishing the value.

Common external in-memory store services:

Provider	Service name
Google Cloud	Memorystore for Redis
Amazon Web Services	ElastiCache for Redis
Microsoft Azure	Azure Cache for Redis
Self-managed	Valkey or Redis OSS (v6+)

What the in-memory store holds

Data type	Purpose
Connection credentials & OAuth tokens	Cached data-warehouse OAuth tokens (BigQuery, Snowflake, Databricks) and viewer credentials, so they don't have to be re-fetched on every request
Account, organization & source metadata	Frequently-read account/organization settings and map/named-source metadata
Session & authentication state	Login sessions, refresh tokens, and SSO/OAuth flow state
Rate-limit counters	Per-user and per-organization API rate-limit state

The in-memory store is not a persistent store; persistent data lives in the metadata database. It can be flushed without losing that data — cached credentials and metadata are simply re-fetched, though active sessions may need to re-authenticate.

Bundled vs. external in-memory store

	Bundled Valkey	External managed Valkey
Setup effort	None — included by default	Requires provisioning before deployment
Recommended for	Most production deployments	High-availability deployments
High availability	Not supported	Supported (Sentinel / Cluster)
Persistence across restarts	Lost on pod restart	Configurable
Scaling	Limited to pod resources	Independent scaling
Monitoring	Basic pod metrics	Cloud provider metrics and alerts

When to use an external in-memory store:

• High-availability configurations requiring Sentinel or Cluster

• When you need cloud provider-level monitoring, alerting, or SLA guarantees for the in-memory store

High availability considerations

For high-availability deployments, an external in-memory store is required. The supported topologies and how to configure them are covered in Configure an external in-memory cache and the Performance & HA section.

Valkey persistence (RDB/AOF) is not required for CARTO; the in-memory store is ephemeral by design. Do not enable persistence settings that may impact Valkey performance unless you have a specific operational reason.

Plan your deployment

When sizing your deployment and deciding between the bundled and an external in-memory store, see Plan Your Deployment.