# How to Upgrade Elasticsearch: Strategies for Zero-Downtime Migration and Data Integrity

> Upgrade Elasticsearch seamlessly with zero downtime. Learn strategies for rolling restarts, shard allocation management, and ensuring data integrity during your Elasticsearch upgrade.

- Repository: [elastic/elasticsearch](https://github.com/elastic/elasticsearch)
- Tags: migration-guide
- Published: 2026-02-21

---

**Upgrade Elasticsearch using a rolling restart strategy that disables shard allocation, upgrades nodes one at a time, and re-enables allocation to maintain data integrity and achieve zero downtime.**

Upgrading the `elastic/elasticsearch` cluster requires careful orchestration to prevent data loss and service interruption. Whether you are moving between minor versions or performing a major version jump, the upgrade Elasticsearch workflow involves pre-flight checks, strategic node replacement, and post-upgrade validation. This guide covers the official rolling restart procedure, common failure modes, and specific source file references that define the upgrade behavior.

## Pre-Upgrade Preparation for a Safe Elasticsearch Upgrade

Before touching any binaries, you must prepare the cluster to withstand the transition. The following steps are documented in the Elasticsearch reference manuals and are enforced by the upgrade logic in the source tree.

### Create a Snapshot Backup

Snapshots protect against accidental data loss and provide a rollback point. According to [`docs/reference/elasticsearch/rest-apis/reindex-data-stream.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/reindex-data-stream.md), you should execute a snapshot before any upgrade activity:

```bash
curl -XPUT "http://localhost:9200/_snapshot/my_repo/snapshot_1?wait_for_completion=true"

```

### Run the Upgrade Assistant

The **Upgrade Assistant** scans deprecation logs, identifies breaking changes, and suggests automatic fixes. As documented in [`docs/reference/elasticsearch/rest-apis/compatibility.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/compatibility.md), you can access this via Kibana (Management → Upgrade Assistant) or through the dedicated API.

### Validate Plugin Compatibility

Nodes will refuse to start if plugins do not match the target version exactly. The [`docs/reference/elasticsearch-plugins/cloud/ec-plugins-guide.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch-plugins/cloud/ec-plugins-guide.md) file specifies that you must verify plugin versions and rebuild custom plugins for the target version before beginning the upgrade.

### Upgrade the Keystore Format

The on-disk keystore format can change between major releases. According to [`docs/reference/elasticsearch/command-line-tools/elasticsearch-keystore.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/command-line-tools/elasticsearch-keystore.md), run the upgrade command on each node before restarting:

```bash
bin/elasticsearch-keystore upgrade

```

### Check Remote Cluster Settings

Remote clusters used for cross-cluster search must run a compatible version. The [`docs/reference/elasticsearch/configuration-reference/remote-clusters.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/configuration-reference/remote-clusters.md) documentation recommends ensuring `skip_unavailable` is set appropriately to handle temporary disconnections during the upgrade.

## Upgrade Elasticsearch Strategies

Elasticsearch supports multiple upgrade paths depending on your availability requirements and version gap.

### Rolling Upgrade (Recommended)

The **rolling upgrade** strategy allows you to upgrade nodes one at a time while maintaining cluster availability. This procedure is detailed in [`docs/reference/elasticsearch/index-settings/path.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/index-settings/path.md).

**Step 1:** Disable shard allocation to prevent unnecessary rebalancing during the upgrade:

```bash
curl -XPUT "http://localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
  "transient": {
    "cluster.routing.allocation.enable": "none"
  }
}'

```

**Step 2:** Stop the Elasticsearch process on a single node, replace the binaries with the new version, and start the node. Wait for the node to rejoin the cluster and reach a `green` health status.

**Step 3:** Repeat Step 2 for every node in the cluster.

**Step 4:** Re-enable allocation after the last node is upgraded:

```bash
curl -XPUT "http://localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
  "transient": {
    "cluster.routing.allocation.enable": "all"
  }
}'

```

### Full Cluster Restart

Use a **full cluster restart** when you need a clean restart after changing settings that require a full stop, or when performing a major version upgrade that does not support rolling upgrades. Shut down **all** nodes, upgrade the binaries, then start them together. This incurs full downtime and is usually only acceptable for small, non-critical clusters.

### Reindex During Upgrade

If an index mapping or analysis component (e.g., ICU or percolator queries) is no longer compatible, you must **reindex** the data. The [`docs/reference/elasticsearch/rest-apis/reindex-indices.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/reindex-indices.md) file describes the classic reindex API, while [`docs/reference/elasticsearch/rest-apis/reindex-data-stream.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/reindex-data-stream.md) covers data streams.

```bash
curl -XPOST "http://old-cluster:9200/_reindex?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "source": {
    "index": "my_old_index"
  },
  "dest": {
    "index": "my_new_index"
  }
}'

```

### Machine Learning Upgrade Mode

ML jobs have a special **upgrade mode** that prepares their hidden indices for a version change. Activate it via the ML upgrade-mode API documented in [`docs/reference/elasticsearch/rest-apis/index.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/index.md):

```bash
curl -XPOST "http://localhost:9200/_ml/set_upgrade_mode?enabled=true"

```

Disable it after the cluster is upgraded.

## Common Pitfalls When You Upgrade Elasticsearch

Avoid these documented failure modes that can corrupt data or prevent cluster formation.

### Incompatible Plugins and Extensions

Nodes will fail to start if plugins do not match the target Elasticsearch version exactly. As documented in [`docs/reference/elasticsearch-plugins/cloud/ec-plugins-guide.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch-plugins/cloud/ec-plugins-guide.md), you must verify plugin versions against the compatibility matrix and rebuild custom plugins for the target version before beginning the upgrade.

### Custom Index Metadata and Mappings

Old mappings or percolator queries may become unreadable after an upgrade. The [`docs/reference/elasticsearch/rest-apis/reindex-data-stream.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/reindex-data-stream.md) and [`docs/reference/elasticsearch/rest-apis/reindex-indices.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/reindex-indices.md) files describe how to use the Reindex API to migrate data to new indices with compatible mappings.

### Remote Cluster Version Mismatch

Cross-cluster search fails during rolling upgrades if remote clusters run incompatible versions. According to [`docs/reference/elasticsearch/configuration-reference/remote-clusters.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/configuration-reference/remote-clusters.md), you should upgrade remote clusters first or configure `skip_unavailable` to handle temporary disconnections.

### Keystore Format Changes

Startup aborts with "Failed to read keystore" if the on-disk format changed between major releases. As specified in [`docs/reference/elasticsearch/command-line-tools/elasticsearch-keystore.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/command-line-tools/elasticsearch-keystore.md), run `bin/elasticsearch-keystore upgrade` on each node before restarting.

### Multiple Data Paths

A node that changes its data path configuration during an upgrade may lose data. According to [`docs/reference/elasticsearch/index-settings/path.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/index-settings/path.md), consolidate to a single data path before the upgrade following the rolling-restart procedure.

### Version Gap Violations

Elasticsearch only supports a **one major version gap** between running nodes. You cannot jump directly from 7.x to 9.x; you must upgrade sequentially through 8.x first.

## Post-Upgrade Validation Steps

After the last node rejoins the cluster, verify the upgrade succeeded before exposing the cluster to production traffic.

1. **Check cluster health** – Verify `status: green`:
   ```bash
   curl -XGET "http://localhost:9200/_cluster/health?pretty"
   ```

2. **Verify all plugins** – Confirm plugin versions match:
   ```bash
   curl -XGET "http://localhost:9200/_cat/plugins?v"
   ```

3. **Check index versions** – Ensure no index remains on the old major version:
   ```bash
   curl -XGET "http://localhost:9200/_cat/indices?v&s=index"
   ```

4. **Monitor deprecation logs** – Keep the Upgrade Assistant open for several days to catch any lingering issues.

## Summary

- **Always create a snapshot** before you upgrade Elasticsearch to provide a rollback point.
- **Use the rolling upgrade strategy** for production environments to maintain availability while upgrading nodes one by one.
- **Run the Upgrade Assistant** to identify breaking changes and deprecated settings before starting the migration.
- **Upgrade the keystore** and verify plugin compatibility to prevent node startup failures.
- **Never skip major versions**; Elasticsearch only supports a one-version gap between nodes during the upgrade process.

## Frequently Asked Questions

### Can I upgrade Elasticsearch without downtime?

Yes, the **rolling upgrade** strategy allows you to upgrade nodes individually while the cluster remains available to clients. According to [`docs/reference/elasticsearch/index-settings/path.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/index-settings/path.md), you must disable shard allocation before stopping each node and re-enable it after the node rejoins to prevent unnecessary rebalancing during the upgrade process.

### What happens if I skip a major version during an upgrade?

Elasticsearch enforces a **one major version gap** rule between running nodes, and the cluster will refuse to form if you attempt to jump versions (for example, from 7.x directly to 9.x). You must upgrade sequentially through each major version, allowing the cluster to fully stabilize before proceeding to the next version.

### How do I handle incompatible plugins during an upgrade?

Nodes will fail to start if plugins do not match the target Elasticsearch version exactly. As documented in [`docs/reference/elasticsearch-plugins/cloud/ec-plugins-guide.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch-plugins/cloud/ec-plugins-guide.md), you must verify plugin versions against the compatibility matrix and rebuild custom plugins for the target version before beginning the upgrade.

### Do I need to reindex all data when upgrading Elasticsearch?

Not necessarily, but you must reindex if your data uses **incompatible mappings**, **percolator queries**, or **deprecated analysis components** that are removed in the target version. The [`docs/reference/elasticsearch/rest-apis/reindex-indices.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/reindex-indices.md) and [`docs/reference/elasticsearch/rest-apis/reindex-data-stream.md`](https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/rest-apis/reindex-data-stream.md) files describe how to use the Reindex API to migrate data to new indices with compatible mappings.