Elasticsearch rolling upgrade (8.x minor or 8.19 → 9.x)

Not an installation: moves a running Elasticsearch cluster to a new version without downtime by upgrading the nodes one at a time (a minor upgrade within 8.x, or the 8.19 → 9.x major upgrade). The steps cover pre-checks (version, health, deprecation API, system feature migration), a pre-upgrade snapshot, limiting shard allocation to primaries and flushing, the version upgrade and plugins on each node, re-enabling allocation and waiting for health, the Kibana upgrade and, if needed, a fallback from the snapshot. At the end all nodes and Kibana are on the target version and the cluster is green. To go to 9.x from an 8.x older than 8.19, first apply this guide to reach 8.19 with the 'within the same major version' option; if there is no snapshot repository, open the snapshot guide first.

Topology: Existing cluster with 3+ nodes (+ Kibana)

Scenarios

• Within the same major version (e.g. 8.18 → 8.19, 9.1 → 9.2) — Within the same major version (8.18 → 8.19, 9.1 → 9.2): the repository does not change; the deprecation check is still done. Skipping intermediate minor versions is supported.
• Major version: 8.19.x → 9.x — The source cluster must first be upgraded to 8.19.x (latest patch). The pre-checks include the Upgrade Assistant / deprecation API and system feature migration steps.

Before you start

• All nodes are on the same version: …. …To move to 9.x the source version must be 8.19.x (except 8.18 → 9.0); otherwise first apply this guide with the "Within the same major version" option to reach 8.19.…The target version … must be newer than the current version; skipping intermediate minor versions (8.17 → 8.19) is supported.…
• Cluster is green; no relocating/initializing shards; disk usage below 75% on all nodes (shards are rebuilt during the upgrade).
• Application clients, Logstash, Beats/Elastic Agent and APM are compatible with the target version. …9.x requires the 9.x client libraries (or 8.x with compatibility headers); read the breaking changes in the release notes.…
• Snapshot repository … is registered and verified and has enough free space for the snapshot. An upgraded node cannot be taken back to the old version; this snapshot is the only way back.
• The servers can reach artifacts.elastic.co (or an internal mirror) and … is available in the repository.
• The maintenance window is approved; write load is reduced during the upgrade if possible (not required). …All critical warnings in Kibana under Stack Management → Upgrade Assistant have been resolved.…

Phases of the guide

• Preparation — Create a temporary credentials file for API access · Back up the configuration · List the installed plugins
• Pre-checks — Check versions and roles · Check cluster health · Run the deprecation check (Upgrade Assistant API) · Run the system feature migration · List the installable target versions
• Switch the repository to 9.x — Define the Elastic 9.x repository · Define the Elastic 9.x repository · Check the target version
• Fallback point: snapshot — Take a pre-upgrade snapshot · Enable ML upgrade mode
• Verification — Verify that all nodes are on the target version · Check that the allocation setting has been cleared permanently · Disable ML upgrade mode · Check the logs for errors
• Upgrade Kibana — Stop Kibana · Upgrade Kibana to … · Start Kibana and check its status
• Post-installation — Take a post-upgrade snapshot · Delete the temporary credentials file
• Fallback (only if the upgrade fails) — Stop the service on all nodes · Install the old version · Move the data directory aside and create an empty one · Write the initial_master_nodes setting for the new cluster · Start the services · Set a temporary elastic password …