Elasticsearch upgrades: a practical guide for developers

Introduction

Upgrading Elasticsearch is one of those tasks that makes even experienced engineers pause. You've got data in flight, queries running, and the pressure to minimize downtime. Elasticsearch upgrades: a practical guide for developers walks you through the process without the theatre—we'll cover how to read breaking changes, snapshot your cluster, perform rolling upgrades node by node, and update clients afterwards. The key is preparation, not speed.

Read Breaking Changes Before You Touch Anything

Every Elasticsearch minor and major version introduces breaking changes. Ignoring them is the fastest way to learn them the hard way—during production upgrades when you've already stopped half your infrastructure. Before you even think about upgrading, spend an hour with the official migration guide for your target version.

Breaking changes typically fall into a few categories:

• API removals: endpoints that no longer exist or behave differently.
• Mapping changes: field types that are deprecated or default behaviours that shift.
• Query DSL changes: operators or syntax that move or disappear.
• Node configuration: settings that are no longer valid and must be removed before startup.

For example, if you're upgrading from 7.x to 8.x, you need to know that default mappings were removed entirely. Every index must have an explicit mapping. If your application relies on dynamic field creation without a template, you'll face index creation failures during upgrade.

Create a checklist from the migration guide specific to your version jump. Test it against a staging cluster that mirrors production. Don't assume your team knows these changes—document them in a shared space and review them in a pre-upgrade meeting. This single step prevents the majority of upgrade disasters.

Snapshot Before Upgrading

A snapshot is your insurance policy. If anything goes sideways, you can restore to a known good state. This is not optional.

Set up your snapshot repository before you even schedule the upgrade. If you're running on AWS, use S3. On-premises? Use shared storage or a dedicated NFS mount. The key is that your repository must be accessible to all nodes in your cluster, both before and after the upgrade.

Here's how to create a repository and take a snapshot:

PUT /_snapshot/my_backup
{
  "type": "s3",
  "settings": {
    "bucket": "my-es-backups",
    "region": "us-east-1",
    "base_path": "prod-cluster",
    "compress": true
  }
}

Once the repository is registered, create a full cluster snapshot:

PUT /_snapshot/my_backup/pre_upgrade_snapshot
{
  "indices": "*",
  "include_global_state": true
}

Include global state so that cluster settings, templates, and ILM policies are backed up too. Wait for the snapshot to complete—check status with:

GET /_snapshot/my_backup/pre_upgrade_snapshot

You're looking for "state": "SUCCESS" and all shards accounted for. Only after you see this should you proceed with the upgrade. In production, we've waited hours for snapshots to complete rather than upgrade without a safety net. It's always worth the time.

Rolling Upgrades: Node by Node

A rolling upgrade removes nodes one at a time from your cluster, upgrades the node's Elasticsearch binary and configuration, then brings it back online. This keeps your cluster operational throughout the process. It's the standard approach for most teams.

The process follows this pattern for each node:

1. Disable shard allocation. Prevents Elasticsearch from rebalancing shards while the node is down.
2. Flush the translog. Ensures all in-flight operations are persisted to disk.
3. Stop the node. Gracefully shut down the Elasticsearch process.
4. Upgrade the binary and update config. Replace the Elasticsearch files and adjust settings for the new version.
5. Start the node. Bring Elasticsearch back up; it rejoins the cluster.
6. Wait for recovery. Shards rebalance and the node becomes fully operational again.
7. Repeat for the next node.

Here's the practical workflow. First, disable shard allocation cluster-wide:

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "none"
  }
}

Then flush the translog on each node before stopping it:

POST /_flush/synced

Now stop the first node. In Docker:

docker stop my-elasticsearch-node-1

On a systemd host:

sudo systemctl stop elasticsearch

Upgrade the binaries. If you're using containers, pull the new image. If bare metal, download and extract the new version. Update your configuration file to remove any deprecated settings that the migration guide flagged. This is critical—starting a node with invalid settings will fail.

Start the node and wait for it to rejoin the cluster. Check the logs—you should see messages about cluster discovery and state recovery. Once the node is green and responding to requests, re-enable shard allocation:

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "all"
  }
}

Wait for the cluster to finish rebalancing before moving to the next node. You can monitor this with:

GET /_cluster/health

Watch for "status": "green" and "relocating_shards": 0. Once you see this, that node is ready and you can proceed to the next one. This methodical approach keeps your cluster operational and gives you a natural checkpoint to catch problems early.

Upgrade Clients After the Cluster

Once your cluster is fully upgraded and stable, upgrade your client libraries. This is often overlooked—teams rush to upgrade the cluster, then forget that their Python or Node.js clients might be running an older version that doesn't understand new APIs or response formats.

Client upgrades are simpler than cluster upgrades because you control the rollout. Update your application dependencies and test in staging first. For example, if you're using the official Elasticsearch Python client:

pip install --upgrade elasticsearch==8.5.0

Then update your connection code to use any new client features or required settings. In Elasticsearch 8.x, SSL/TLS is on by default and API key authentication is preferred:

from elasticsearch import Elasticsearch

es = Elasticsearch(
    ["https://localhost:9200"],
    api_key=("api_key_id", "api_key_secret"),
    verify_certs=True,
    ca_certs="/path/to/ca.crt"
)

Run your integration tests against the upgraded cluster. Look for deprecation warnings in the response headers—Elasticsearch still communicates deprecated usage patterns this way. Fix them before you deploy to production. This prevents technical debt from accumulating and keeps your codebase compatible with future versions.

Common Mistakes

• Upgrading multiple nodes simultaneously: Your cluster can't handle full rebalancing and remains red for hours. Always upgrade one at a time.
• Forgetting to disable shard allocation: Elasticsearch wastes resources moving shards around unnecessarily, extending upgrade time and increasing failure risk.
• Removing deprecation warnings before testing: Deprecations exist for a reason. Clearing them without understanding the impact leads to subtle bugs after upgrade.
• Skipping the snapshot: We've all been tempted to skip this for a "quick" upgrade. It's never quick when something breaks and you don't have a backup.
• Upgrading clients and cluster at the same time: If something fails, you don't know whether it's the cluster or the client. Always isolate variables.

Key Takeaways

• Read the migration guide for your target version and create a checklist specific to your changes.
• Always snapshot your cluster to a stable repository and verify completion before upgrade.
• Perform rolling upgrades node by node, waiting for the cluster to stabilize and shards to rebalance between each node.
• Disable shard allocation during the upgrade to prevent unnecessary rebalancing.
• Update clients after the cluster is stable, test against staging, and fix any deprecation warnings.
• Build time into your upgrade window for the unexpected—snapshots take longer than you think, and cluster recovery isn't always linear.