Before choosing a design, you need a crisp picture of the problem you are solving.

Defining a tenant

A tenant is a customer, team, or organization that uses your system and expects its data to be treated as private and its experience to be consistent. In a company that sells software to other companies, each paying customer is usually a tenant. In an internal platform, each department or product team may be a tenant. Multi-tenancy simply means that one running system serves many tenants at the same time, instead of running a separate copy of the system for each one.

The word tenant is about a relationship, not a technology. A tenant might have three users or three million. It might store ten documents or ten billion. Any good design has to survive both extremes, because in real businesses the size of your customers follows a steep curve: a few giants and a very long tail of small ones.

Why do teams choose multi-tenancy at all?

The answer is almost always cost and operations. Running a dedicated search cluster per customer means paying for idle capacity many times over, patching many clusters, upgrading many clusters and watching many dashboards. Sharing infrastructure lets you pack many small workloads onto the same machines, keep hardware busy, and operate one fleet rather than thousands of tiny ones. The price you pay is complexity in isolation, security and fairness.

The three promises every tenant expects

Why Elasticsearch is a special case

In a traditional relational database, you can often add a tenant identifier column and lean on mature row-level security. Elasticsearch is different in several ways that matter for design. It is a distributed system built from many small pieces called shards, and every piece has a fixed overhead. Its cluster-wide metadata is held in memory on every node. Its search results are ranked using statistics that are computed across all documents in a shard, so tenants sharing a shard subtly influence each other’s relevance. And its most powerful isolation features, such as document-level security, belong to paid subscription tiers rather than the free core.

These traits mean that the obvious choices, one index per tenant or one big shared index, each have a cliff waiting at the end. The whole art of multi-tenancy in Elasticsearch is knowing where those cliffs are before you walk off them.

Every multi-tenancy decision is really a decision about these basic building blocks.

If you already know these terms, skim this chapter. If not, read it slowly, because every later chapter leans on it. We will define each idea in plain words, give an everyday comparison, and say why it matters for tenants.

Index, shard and replica in one picture

When you create an index you decide how many primary shards it has. That number is essentially fixed for the life of the index, because documents are placed into shards using a formula based on the document identifier or a routing value. You can later use special split or shrink operations to change it, but they are deliberate, heavy operations rather than casual settings.

Each primary shard can have replica copies. If a node dies, a replica is promoted, so no data is lost. Replicas also help read traffic, because a search can be answered by either a primary or a replica.

Why shards have a “tax”

Every shard, even an empty one, costs memory, file handles and cluster coordination effort. Elasticsearch keeps information about every shard in the cluster state, and every node holds a copy of that state. Two guardrails are worth remembering. First, there is a configurable limit on shards per node, which defaults to one thousand for regular data nodes. Second, a commonly quoted rule of thumb sizes shards between roughly ten and fifty gigabytes each, so that they are large enough to be efficient but small enough to move around and recover quickly. Always check the current official guidance for your version, since these recommendations have evolved.

This shard tax is the single most important fact in multi-tenant design. If you give every tenant its own index with the default shard settings, ten thousand tenants can quietly become tens of thousands of tiny shards, and your cluster will spend its life bookkeeping instead of searching.

Mappings and the field budget

A mapping lists the fields of your documents. By default, Elasticsearch will happily add new fields on the fly when it sees them, a behavior called dynamic mapping. There is also a default cap on the total number of fields in an index, which is one thousand. When tenants are allowed to send arbitrary fields, mappings can grow without bound. We will return to this danger in a later chapter under the name mapping explosion.

Multi-tenancy is not one design. It is a dial that runs from “nothing shared” to “everything shared”.

Architects who build software-as-a-service platforms usually describe three broad patterns. The names come from general cloud architecture, and they map neatly onto Elasticsearch.

flowchart LR
  A["Silo: cluster per tenant"] --> B["Bridge: index per tenant on shared cluster"]
  B --> C["Bridge: pooled small tenants plus dedicated large tenants"]
  C --> D["Pool: shared index with tenant field, routing and filtered alias"]
  A -. "Strongest isolation, highest cost" .-> A
  D -. "Lowest cost, most design effort" .-> D
        

How to choose: the four questions

Instead of asking “which model is best”, ask four questions about your situation. How many tenants will you have, and how skewed is their size? How strict are your compliance and contractual isolation requirements? How different are your tenants’ data shapes and search needs? And how much operational effort can your team afford?

The most intuitive design, and the easiest to explain to a security auditor.

How it works

In this model each tenant owns one or more indices whose names contain the tenant identifier. Your application routes each request to that tenant’s index, or to an alias that points to it. Because an index is a first-class object in Elasticsearch, everything you might want to control, such as settings, mappings, analyzers, shard counts, retention and access rules, can be set per tenant without touching anyone else.

What you gain

The small-tenant trap

The classic failure story goes like this. A team launches with fifty tenants and one index each, using the default settings. It works beautifully. Two years later there are eight thousand tenants, most of them tiny, and the cluster has crossed into tens of thousands of shards. Cluster state updates take seconds. Node restarts take an hour because shard recovery is a traffic jam. Heap usage is high even though the data volume is modest. Nothing is wrong with any single tenant. The design simply spent the shard budget on customers who did not need a full shard each.

Ways to stretch the model

The pooled design that scales to enormous tenant counts, at the price of more careful engineering.

How it works

In the pooled model, many tenants store their documents in the same index. Every document carries a tenant identifier field. Queries always restrict results to a single tenant. To make this efficient and safe, three Elasticsearch features are combined: a keyword field holding the tenant identifier, custom routing that sends each tenant’s documents to a predictable shard, and filtered aliases that bake the tenant restriction into a named entry point.

Custom routing: keeping a tenant in a few shards

Normally, Elasticsearch decides which shard a document goes to by hashing its identifier, which spreads documents evenly. A search then has to visit every shard of the index. With custom routing, you supply a routing value, typically the tenant identifier, and Elasticsearch hashes that instead. All of a tenant’s documents land on the same shard, and a search that supplies the same routing value visits only that shard. For a platform with fifty shards per index, that can be a fifty-fold reduction in work per query.

For very large tenants, one shard may not be enough, and it would become a hot spot. Elasticsearch offers a routing partition size setting that spreads each routing value across a small group of shards rather than a single one. This is a middle path: better balance for big tenants, still far fewer shards touched than a full scatter.

flowchart TD
  U["Tenant 42 user searches"] --> APP["Application layer"]
  APP --> AL["Filtered alias for tenant 42"]
  AL --> RT["Routing value: tenant 42"]
  RT --> S3["Shard 3 only"]
  S3 --> F["Tenant filter applied automatically"]
  F --> R["Results for tenant 42 only"]
  IDX["Shared index with many shards"] --- S3
        

Filtered aliases: safety by construction

An alias can be defined with a filter, and optionally with index and search routing values. When your application searches through the alias for tenant 42, Elasticsearch adds the tenant filter and the routing for you. The application does not have to remember anything. Combined with a role that only grants access to that alias, it becomes much harder to accidentally read another tenant’s data, because the caller simply has no name for the shared index.

Creating one alias per tenant is cheap compared with creating one index per tenant, though aliases are still stored in cluster state, so tens of thousands of them can add up. Plan for that number just as you would for indices.

Strengths and weaknesses

The silo: maximum separation, maximum responsibility.

How it works

In the silo model, each tenant receives its own Elasticsearch cluster or its own hosted deployment. Nothing is shared at the search layer: not the shards, not the heap, not the disks, not the master node. Whatever one tenant does, another tenant’s cluster cannot feel it.

When the silo is the right answer

The operational bill

The catch is that you now run a fleet. Every cluster needs monitoring, patching, backups, capacity planning and incident response. Without heavy automation, the human cost grows linearly with tenant count. Idle capacity also adds up: a cluster sized for peak load sits mostly unused most of the day, and you pay for that many times over.

Real platforms rarely stay pure. They graduate tenants between models as those tenants grow.

The most durable multi-tenant Elasticsearch platforms treat isolation as a service tier rather than a single decision. The pattern is simple to state: small tenants share, medium tenants get their own indices, and large or regulated tenants get dedicated infrastructure. Your platform then includes a small control layer that knows where each tenant currently lives and can move it.

flowchart TD
  T["Tenant request"] --> RG["Tenant registry: where does this tenant live?"]
  RG -->|"Free or small"| P["Pooled shared indices"]
  RG -->|"Growing"| I["Dedicated index on shared cluster"]
  RG -->|"Enterprise"| D["Dedicated nodes or dedicated cluster"]
  RG -->|"Regulated region"| R["Regional cluster with cross-cluster search"]
        

The tenant registry

The registry is a small, highly reliable lookup, often kept in a relational database or a configuration store, that maps a tenant identifier to its current home: which cluster, which index or alias, which routing value, and which quota limits. Every request begins by consulting it. Because the application never hard-codes where a tenant lives, you can move tenants without changing any callers.

Using node roles and data tiers

Elasticsearch lets you label nodes with attributes and tell indices which nodes they may live on. You can therefore dedicate a group of nodes to premium tenants inside a shared cluster. This gives you a stronger performance boundary than pure logical sharing, because heavy tenants literally run on different machines, while still keeping one cluster to operate. Separately, the built-in hot, warm, cold and frozen data tiers let older tenant data migrate onto cheaper hardware as it ages.

To predict noisy neighbors, you must understand where tenants actually collide.

The life of a search

When a search arrives at any node, that node acts as the coordinating node for the request. It figures out which shards must be consulted, sends the query to one copy of each of those shards, waits for their partial results, merges them into a final ranked list, and then fetches the actual documents for the winners. This two-phase approach is often called query then fetch.

sequenceDiagram
  participant C as Client
  participant N as Coordinating node
  participant S1 as Shard copy A
  participant S2 as Shard copy B
  C->>N: Search for one tenant
  N->>N: Resolve alias, filter and routing
  N->>S1: Query phase
  N->>S2: Query phase
  S1-->>N: Top matches
  S2-->>N: Top matches
  N->>N: Merge and rank
  N->>S1: Fetch phase for winners
  S1-->>N: Documents
  N-->>C: Final results
        

The four collision points

Why shards behave like tiny search engines

Each shard is a full Lucene index. Data is written into small immutable segments, and searches read across all segments of a shard. Deletions do not remove data immediately. They mark documents as deleted, and the space is only reclaimed when segments merge. This is the reason tenant deletion inside a shared index is slow: you are marking potentially millions of documents and then waiting for merging to physically remove them.

Where routing helps and where it does not

Routing reduces the number of shards touched by a query, which lowers cost and speeds up small tenants. But it also concentrates a tenant on a few shards. If that tenant is popular, those shards become hot, and the replica copies serving them share the load. Routing therefore improves efficiency for the average tenant and can worsen imbalance for the biggest one, which is why the partition size setting and dedicated indices for giants exist.

The quietest scaling limit is not data volume. It is metadata.

What the cluster state contains

The cluster state is the master copy of the cluster’s structure: which indices exist, their settings and mappings, where every shard lives, which aliases exist, and more. One elected master node changes it, and every change is sent to all other nodes. Every node keeps the whole thing in memory. When the state is small, changes are quick. When it holds tens of thousands of indices with rich mappings, each change can take noticeable time, and the master becomes a bottleneck for anything structural, such as creating a tenant.

Mapping explosion

Mapping explosion happens when an index accumulates a huge number of distinct fields. It typically starts innocently. A platform lets tenants send custom attributes, dynamic mapping creates a field for each new attribute name, and after a few thousand tenants you have hundreds of thousands of field names in one shared index. Memory use climbs, the cluster state balloons, and updates slow down. Elasticsearch protects you with a total fields limit, but hitting it means new documents are rejected, which is an outage for the tenant who happened to send the last field.

Controls that keep metadata healthy

One tenant’s bad afternoon should never become everyone’s outage.

A noisy neighbor is a tenant whose behavior consumes a disproportionate share of shared resources. It is rarely malicious. It is usually a legitimate customer running a huge report, launching a marketing campaign, or importing a decade of history on a Monday morning. Elasticsearch has no built-in per-tenant quota system in the way some databases do, so you assemble fairness from several layers.

Layer 1: limit at the edge

The cheapest and most effective controls live in your own application or API gateway, before requests reach Elasticsearch. Apply per-tenant rate limits, cap the size of result pages, restrict the depth of pagination, and forbid the most expensive query shapes for tenants on lower tiers. Because your gateway knows who the tenant is, it can apply different budgets to different plans.

Layer 2: limit inside Elasticsearch

Layer 3: separate the heavy from the light

When logical controls are not enough, use physical separation inside the same cluster. Allocation filtering and node attributes let you pin an index to specific nodes, so a demanding tenant lives on machines that other tenants do not use. Dedicated coordinating nodes for expensive aggregations, and separate ingest capacity for bulk loading, also keep different kinds of work apart.

Protecting the write path

Search is not the only culprit. A tenant that indexes massive volumes causes segment creation, merging and refresh pressure. Two habits help. First, insist on bulk requests of sensible size rather than a storm of single-document writes. Second, queue tenant writes through a message buffer, so bursts are smoothed and a slow cluster applies back pressure to producers rather than dropping data or collapsing.

Isolation you cannot prove is isolation you do not have.

The security building blocks

Elasticsearch security is built from a few ideas. Authentication proves who a caller is, through usernames, API keys, tokens or single sign-on. Authorization decides what that identity may do, using roles that grant privileges on indices, aliases, clusters and fields. Encryption protects data in transit between nodes and clients, and can protect it at rest on disk. Audit logging records who did what, which is essential evidence when a customer or regulator asks.

Security by model

The trusted-proxy pattern

A common and sturdy design keeps Elasticsearch completely hidden from end users. Only your backend talks to it, using service credentials scoped to a tenant. The backend authenticates the end user, looks up the tenant, and uses that tenant’s alias or credentials. This means a bug in the browser or a stolen end-user token cannot reach the search layer directly. The important discipline is that the tenant identity must come from the authenticated session, never from a value the client can freely send.

Testing isolation

Treat cross-tenant access as a class of bug that deserves its own automated tests. Create two test tenants with overlapping content, then verify that every search path, count, suggestion, export and administrative function returns only the caller’s data. Run these tests in your continuous delivery pipeline, and repeat them whenever you upgrade Elasticsearch or change a role.

Search quality is a tenant-visible feature, and sharing changes it in ways people rarely expect.

How relevance is scored

Elasticsearch ranks documents using a scoring formula called BM25 by default. In simple terms, a word that is rare across the collection is treated as more meaningful than a word that appears everywhere. The statistics that decide how rare a word is are gathered per shard, not across the whole index.

What this means for a shared index

In a pooled design, the term statistics on a shard mix content from many tenants. A tenant in the legal industry sharing a shard with a tenant in the cooking industry will have its rare-word signals distorted by the other’s vocabulary. The results remain sensible for most uses, but ranking can shift as other tenants come and go, and small tenants can see surprising behavior. There is also a subtle privacy angle: scores computed from a shared distribution encode a little information about the shared data.

There are three responses. You can accept the small distortion, which is fine for many products. You can use a search type that gathers global statistics first, at the cost of an extra round trip. Or you can separate tenants whose ranking quality matters most into their own indices, where statistics are purely theirs.

Analyzers, synonyms and languages

Analysis is the process of breaking text into searchable pieces, including lowercasing, splitting words, removing endings and applying synonyms. Different tenants often want different behavior: different languages, different synonyms for their own jargon, different handling of product codes. Index-per-tenant handles this gracefully because analyzers are index settings. In a shared index, the analyzer is fixed for a field, so per-tenant variations require workarounds such as separate fields per language or a query-time synonym approach managed centrally.

Every tenant eventually changes plans, shrinks, leaves or asks you to erase their data.

Lifecycle management basics

Elasticsearch includes index lifecycle management, which moves indices through phases as they age. A hot phase handles active writing and searching, a warm phase keeps data searchable on cheaper hardware, a cold phase uses even cheaper storage, and a delete phase removes data at a set age. For time-based data such as logs, events and metrics, data streams combine with rollover so that new backing indices are created automatically when one grows too large or too old.

Retention per tenant

Different plans often promise different retention: seven days for a free tier, ninety days for a standard tier, several years for enterprise. The model you chose decides how hard this is.

A neat compromise for pooled designs is to create separate shared index families by retention class, for example a short-retention pool and a long-retention pool. Each family has one lifecycle policy, and moving a tenant between plans becomes a data move rather than a per-document cleanup.

Offboarding and the right to erasure

When a tenant leaves, or when privacy law obliges you to delete someone’s data, you need a clear, verifiable procedure. In an index-per-tenant design, you delete the indices and remove aliases and roles, and the files are gone. In a shared index, you run delete-by-query, which marks documents as deleted and depends on background merging to reclaim space, and you must think about snapshots too, because backups may still contain the deleted data.

Tenants never stay the size they started. Your design must let them move.

Sizing with skew in mind

Tenant sizes in a real platform follow a long-tail pattern. A handful of tenants may account for most of your data and traffic, while thousands account for very little. Capacity planning based on the average tenant is therefore misleading. Plan around percentiles: what do the top one percent look like, what does a typical tenant look like, and how quickly are tenants moving between those groups?

Tools for changing shape

sequenceDiagram
  participant Reg as Tenant registry
  participant Pool as Shared index
  participant Ded as Dedicated index
  participant App as Application
  App->>Reg: Read tenant location
  Reg-->>App: Pool
  Note over Reg,Ded: Tenant crosses size threshold
  Reg->>Ded: Create dedicated index from template
  Pool->>Ded: Reindex tenant documents
  App->>Ded: Dual write during catch-up
  Reg->>Reg: Switch location to Dedicated
  App->>Ded: Reads and writes now go here
  Pool->>Pool: Delete tenant documents after safety period
        

The golden rules of migration

First, never move a tenant without a way back. Keep the source data intact until the new location has been verified. Second, handle writes that arrive during the copy, either by writing to both places temporarily or by replaying a change log. Third, switch traffic through the registry so the change is atomic from the application’s point of view. Fourth, verify counts and sample documents rather than trusting that the copy job reported success.

You cannot be fair to tenants you cannot measure.

Two kinds of monitoring

Platform monitoring watches the health of the cluster: heap use, garbage collection, CPU, disk, thread pool queues, shard counts, cluster state size and recovery activity. Tenant monitoring watches how each customer uses the platform: request rate, latency, error rate, indexing volume, storage and expensive query counts. Most teams do the first well and the second poorly, which is why noisy neighbors take so long to find.

Tagging everything at the edge

The most reliable technique is to make your API gateway or search service the measurement point. Every request passes through it with a verified tenant identity, so it can attach the tenant to logs, metrics and traces. Elasticsearch can also record an opaque identifier header on requests, which appears in slow logs and task listings, making it possible to trace a slow operation back to a tenant.

Metering and billing

If you charge by usage, measure with the same care as a utility company. Use documents stored, bytes stored, queries served and indexing volume, and keep those counters in a durable place that is not the same cluster being measured. In pooled designs, storage attribution is approximate unless you maintain counters, so design your billing promises around what you can honestly measure.

Governance: who is allowed to change what

A short catalogue of what works, and what quietly hurts.

Patterns worth adopting

Anti-patterns to avoid

Best practices at a glance

Four common situations, and how the ideas in this guide apply to each.

A decision walk-through

No. The best model depends on tenant count, size skew, compliance needs and team capacity. Most mature platforms end up with a tiered mixture rather than one pure model.

It depends on hardware, version and mappings. What is certain is that every index and shard consumes memory and cluster coordination effort, so count them, set alerts, and treat the per-node shard limit as a warning sign rather than a target.

Not on its own. A filter depends on every code path remembering to add it. Use tenant-scoped aliases, roles, and where available document-level security, so the platform enforces the boundary.

No. Routing is a performance optimization that sends a tenant’s data to fewer shards. It does not stop a query without the right filter from reading other tenants’ documents.

In a shared index it can create hot shards. Options include a routing partition size to spread the tenant, or moving it to a dedicated index or dedicated nodes, ideally through a planned migration process.

Easily with index per tenant, because analyzers are index settings. In a shared index you need workarounds such as per-language fields or centrally managed synonym sets.

Deletions mark documents as removed, and physical cleanup happens later during segment merging. Dedicated indices avoid this, because dropping the whole index removes its files directly.

Spaces separate saved objects like dashboards and visualizations for different teams. Data access still has to be controlled by roles on indices and aliases.

Layer your defenses: rate limits at the gateway, timeouts and limits inside Elasticsearch, per-tenant monitoring, and physical separation of heavy tenants onto dedicated nodes or clusters.

Yes, if you plan for it. A tenant registry, alias-based access and rehearsed reindexing procedures let you move tenants between models with little disruption.

The core concepts, shards, routing, aliases and cluster state costs, are shared by the two projects, but security features, defaults and terminology differ, so verify each capability in the documentation of the product and version you use.

For thousands of small tenants, usually yes. For a modest number of large or regulated tenants, it is often the right and even the cheapest choice once you count the risk and the engineering effort of complex isolation.

Multi-tenancy in Elasticsearch is the craft of letting many customers share one search platform while each feels alone in it. There is no free lunch. Index-per-tenant gives clean isolation and flexible settings but spends your shard and metadata budget quickly. Shared indices with routing and filtered aliases scale to enormous tenant counts but demand careful security, schema discipline and fairness controls. Dedicated clusters give the strongest boundaries at the highest operational cost. The wisest platforms mix these, use a registry to know where every tenant lives, enforce isolation with roles rather than good intentions, measure usage per tenant, and rehearse moving tenants as they grow. Build the walls, the meters and the moving trucks before you need them.