CONCEPT Cited by 2 sources

Tenant header routing¶

Definition¶

Tenant header routing is the architectural pattern where a client's request carries an explicit tenant identifier in an HTTP header, and an L7 proxy uses that header alone to select the correct backend cluster — without needing to inspect the body or resolve the tenant from any other source.

Canonical articulation (Source: sources/2026-05-05-airbnb-monitoring-reliably-at-scale):

"Airbnb runs over 1,000 services, each mapped to its own tenant in a single, global user space. Our custom load-balancing tier makes this practical: we map each service name to a specific cluster backend, and every request must include a tenant header that informs routing."

Shape¶

┌──────────┐
│ client   │ (service X, tenant = X)
└────┬─────┘
     │
     │   HTTP request
     │   ▪ header: X-Tenant: service-X
     │   ▪ body: telemetry payload (opaque to proxy)
     ▼
┌─────────────────────┐
│ Envoy / L7 proxy    │
│ ─────────────────── │
│ header → backend    │
│   X-Tenant → VIP    │
│ mapping table       │
└────┬────────────────┘
     │
     ▼
┌─────────────────┐
│ backend cluster │
│  for tenant X   │
└─────────────────┘

Why it's a good primitive for telemetry ingestion¶

Clients don't know topology. Services emit metrics to one logical endpoint; the routing tier knows which backend cluster handles their tenant today. See concepts/vip-address-decoupling.
Body never needs to be parsed. The routing decision is made entirely on the header, avoiding the serialization tax of deserialising the payload.
Tenant topology can change without client redeploys. Moving a tenant to a new backend cluster is a config change on the proxy, not a change to every emitter.
Per-tenant policy enforcement. ACLs, rate limits, and per-tenant routing rules all key off the same header.

Simplification compared to content-based routing¶

A generic content-based router would need to:

Accept the request
Deserialise the payload (protobuf / JSON / OTLP)
Extract the identifying field
Route

Tenant header routing collapses this to a single lookup against a small in-memory map. The payload stays opaque and is forwarded byte-for-byte.

Enforcement: the header is mandatory¶

Airbnb's shape makes the header required, not optional: "every request must include a tenant header that informs routing." A request without the header is rejected. This shifts responsibility for tenancy identification to the emitter's instrumentation library (one place, controlled by the observability team), instead of leaving it as a proxy- side inference that can disagree with client intent.

concepts/tenant-isolation-in-routing-layer — why tenant isolation matters at the routing tier; Netflix's canonical framing. Tenant header routing is one mechanism for achieving this isolation.
concepts/vip-address-decoupling — clients address a logical use-case, not a VIP. Tenant header routing is a specific implementation of this decoupling.
patterns/separate-routing-from-model-selection — Netflix's sibling pattern at the ML-serving altitude; Lightbulb attaches routingKey + ObjectiveConfig, Envoy consumes the header to route. Same architectural shape; different tenancy vocabulary (routing-key-per-request vs tenant-per-service).
patterns/custom-l7-proxy-for-telemetry-over-service-mesh — the pattern that uses tenant header routing as its mechanism for handling many (~1,000) tenants.

Caveats¶

Header trust. If the header is client-set, an emitter can misroute by sending the wrong header. Airbnb's post does not discuss header signing or validation.
Per-service tenancy only at Airbnb's altitude. The granularity choice — one tenant per service — is service-scaled (~1,000 tenants). At very large orgs this granularity can become expensive; at very small orgs it's overkill.
Adding a new tenant is a config change. If the onboarding path is slow, new services can't emit until tenancy is registered.

Seen in¶

sources/2026-05-05-airbnb-monitoring-reliably-at-scale — canonical wiki instance at the telemetry-ingestion altitude. 1,000+ services, one tenant per service, single global user space, header-mandatory routing on a custom Envoy tier.
sources/2026-05-01-netflix-state-of-routing-in-model-serving — sibling pattern at the ML-serving altitude. Lightbulb attaches routingKey header, Envoy routes on the header, same architectural shape (header-based routing to avoid body inspection).