CONCEPT Cited by 1 source

Elasticsearch compatibility mode

Definition

Elasticsearch compatibility mode is a mechanism Elastic ships in its 7.17 High Level REST Client (HLRC) that lets the old client talk to the new cluster during a major-version upgrade. The mechanism is a conventional MIME-type suffix on the Accept + Content-Type headers:

Accept:       application/vnd.elasticsearch+json;compatible-with=7
Content-Type: application/vnd.elasticsearch+json;compatible-with=7

The 8.x cluster sees compatible-with=7, preserves 7.x response shapes where breaking changes would otherwise apply (e.g. retains _type in responses, tolerates range-query numeric bounds, etc.), and serves the request.

Why it exists

Major-version upgrades of a stateful datastore are two upgrades entangled:

1. The cluster binaries and storage format (operators-owned).
2. The client library embedded in application code (developers-owned).

If those two must move in lockstep, the operations org can't upgrade the cluster without application teams finishing their code changes first — a classic coupling that delays security patches and feature access.

Compatibility mode decouples the two: cluster upgrades first, applications continue running the old client (with the compat header), and application teams migrate to the new client gradually.

The transition strategies Elastic documents

From Elastic's migration guide:

1. Compatibility mode alone — run 7.17 HLRC against 8.x cluster indefinitely (until client is eventually migrated).
2. Side-by-side — new client added alongside old; code migrated call-site by call-site.
3. Full rewrite — all calls migrated at once.

Compatibility mode is a prerequisite for (2) — it provides the window during which both clients need to work.

Seen in

• sources/2023-11-19-zalando-migrating-from-elasticsearch-7-to-8 — Canonical wiki instance. Zalando's Origami application (443k LOC, 846 files of Scala) used compatibility mode to run the 7.17 HLRC against the freshly-upgraded ES 8.x clusters, decoupling the cluster-wide reindex-based Blue/Green migration from the application-side client migration to the Elasticsearch Java API Client. Without compatibility mode, the 443k-LOC rewrite would have been a blocker for the cluster upgrade, not a parallel track. The article says: "this way we would be able to upgrade the Elasticsearch cluster first, and then upgrade the client gradually. With this approach, we would avoid rewriting too much code at once."

Related pattern

• patterns/compatibility-mode-client-transition — the generalisation of this primitive: any datastore with a versioned REST API and a compat-header can follow this two-phase sequence.

Generalisation

The primitive — a client-injected header that instructs the server to preserve old response semantics — generalises beyond Elasticsearch. It is a specific form of backward compatibility at the REST API boundary. Siblings:

• Stripe's API versioning via Stripe-Version header.
• GitHub's REST API versioning via Accept header suffix.
• Kubernetes API-version negotiation via the API group / version in the URL and apiVersion in the body.

What makes the Elasticsearch case distinctive is that it was retrofitted specifically to unblock a breaking major-version upgrade, not designed as a general API-evolution contract.