Fastly's Cache Key Design Beats Purge Precision in Multi-Tenant Edge
Fastly's edge platform rewards teams that treat cache key design as the main lever for multi-tenant performance. Surgical purge precision, the feature teams often reach for first, tends to create more coupling than it removes. This breakdown covers how cache keys actually work on Fastly, why purge fan-out scales badly across tenants, and which design moves hold up under real invalidation pressure.
Purge Precision Is a Comfortable Lie
Surrogate keys feel exact. You tag an object, you purge the tag, the object disappears. That mental model works fine on a single-tenant origin with a dozen cached URLs. It breaks the moment several tenants share a cache layer and a single deploy touches objects owned by different teams.
Purge fan-out grows with the number of tenants and the number of tags per object. A purge request that names a surrogate key must be evaluated against every cached variant that carries that key. On a busy edge POP, that evaluation cost lands during the exact minutes when traffic is highest and origin capacity is thinnest.
Precise invalidation also invites stale coupling. When a purge is the only mechanism keeping two objects consistent, every new object type becomes another place where a missed tag produces a stale response. Fastly's own documentation leans toward cache key design as the durable answer, with purging as a coarse corrective rather than a fine-grained tool.
What a Cache Key Actually Encodes
A Fastly cache key is built from request attributes: host, path, query string, selected headers, and cookies. Two requests with identical keys share a cached object. Two requests that differ in any keyed attribute get separate objects, even if the response bytes would be identical.
The Vary header reshapes the key rather than the object. Adding Vary: Accept-Encoding tells the edge to key on the encoding, so a gzip response and a brotli response occupy separate slots. Each dimension you add multiplies cardinality, and cardinality is the budget you are spending.
Tenant identity belongs in the key. If two tenants share a hostname and the tenant is resolved from a cookie or a header, that cookie or header must be part of the key. Otherwise one tenant's response can be served to another, which is a correctness failure, not a performance one.
Query string normalization is the cheapest win available. Reordering parameters before hashing collapses ?a=1&b=2 and ?b=2&a=1 into one cache entry. Without normalization, analytics trackers and ad parameters inflate cardinality until hit ratio collapses.
Fastly's VCL and Shielding Model
VCL runs at the edge, per request. It executes in a defined state machine, and the cache lookup happens after the key has been computed. That ordering matters: any logic you place before the lookup decides which object the request can hit.
Shielding adds a second cache tier behind the edge POP. A shield POP absorbs origin misses so that a hundred edge POPs missing the same object produce one origin fetch rather than a hundred. Fastly documents shielding as a way to raise hit ratio and reduce origin load, and the effect depends entirely on key consistency across POPs.
Cache hit ratio is a function of key cardinality. If the same logical resource produces many keys, shielding cannot help, because the shield sees the same fragmentation the edge does. Fastly's cache key and purging documentation treats key design and purge strategy as one topic for this reason.
Why Multi-Tenant Workloads Break Purge Logic
One tenant's deploy can touch shared objects. A layout template, a shared JavaScript bundle, or a common API response may be cached under a key that does not encode the tenant. A purge issued for tenant A then evicts or invalidates objects that tenant B depends on.
Surrogate keys leak across tenant boundaries when tags are global. If the tag homepage is used by every tenant, purging it purges everyone. Namespacing tags per tenant fixes the leak but multiplies the tag count, which pushes purge fan-out back up.
Purge storms look like cache stampedes. When a deploy purges a large key space, the next wave of requests all miss, and they all reach the shield at once. This is the classic dog-piling pattern described in cache stampede literature and in Memcached operational lore, and it hits origins hard.
The origin sees a spike that looks like an attack. Connection pools saturate, database queries queue, and the incident channel fills with speculation about traffic. The actual cause is a purge that was too broad relative to the key design.
Designing Keys That Survive Invalidation
Version prefixes replace surgical purges. Instead of purging an object, publish a new key: /v42/app.js instead of /app.js. The old key ages out on its own TTL, and no purge is needed. This is the single highest-leverage change for multi-tenant caches.
Immutable asset names with short TTLs do the same work for static content. Content-hashed filenames make the object permanently cacheable, and the HTML that references them carries the short TTL. Invalidation becomes a pointer swap rather than an eviction.
Key cardinality needs a budget per tenant. Decide how many distinct keys a tenant may produce, and treat query parameters, cookies, and headers as spending against that budget. A tenant that adds a tracking parameter to every URL should see that cost in its hit ratio, not in a shared incident.
Measure hit ratio before adding dimensions. Every new keyed attribute should be justified by a measured improvement, not by a theory about correctness. A related piece on edge teams trading on-call sleep makes a similar point about latency budgets: the number you can measure is the number you can defend.
Practical Moves for Edge Teams
Audit your Vary headers this week. List every header that appears in a Vary directive on your origin, and check whether each one actually changes the response body. Headers that do not change the body are pure cardinality cost.
Add tenant ID to every cache key, including shared assets. If a response can differ by tenant, the tenant must be in the key. If it cannot differ, cache it once under a tenant-neutral key and document why.
Replace purge precision with versioned keys where you can. Keep purging for emergencies and for content that genuinely cannot be versioned, such as a CMS page whose URL is fixed. For everything else, the version prefix is cheaper and safer.
Track hit ratio per tenant, not globally. A global number hides the tenant whose query parameters are fragmenting the cache. Per-tenant dashboards make the cost visible before it becomes an incident. A related piece on reading an SBOM the way the build pipeline writes it argues for the same discipline: measure the artifact the pipeline actually produces, not the one you wish it produced.
Document the key schema in the README. The next engineer to add a header to Vary should be able to see the cardinality budget and the tenant boundary rules without asking. This site has argued that maintainers of build tooling trade release cadence for hiring reach, and the same tradeoff applies to cache schemas: undocumented decisions get re-litigated.
The Cost of Getting It Wrong
When cache keys are too granular, hit ratio drops and origin load rises. When they are too coarse, tenants see each other's data. Both failures are expensive, but the second is a correctness bug that can end customer relationships. The safest default is to include tenant identity in every key that could possibly vary by tenant, and to accept the extra cardinality as insurance.
Teams that treat cache keys as an afterthought often end up with a fragile purge pipeline that requires constant maintenance. Those that version aggressively and keep keys minimal spend their time on features instead of cache fires. The difference shows up in incident reviews and in how quickly new engineers can reason about the system.
