Upgrade Aiven for OpenSearch®

Aiven for OpenSearch® allows you to choose the version that best fits your needs and upgrade when ready.

Multi-version: how it works

Aiven for OpenSearch supports the two latest upstream OpenSearch major versions.
When Aiven releases a new minor version within a major version, it decommissions the previous minor version after six months, giving you time to test and migrate.
Patch version upgrades are automatic. For example, Aiven upgrades 3.3.1 to 3.3.2.

Default version

When creating an Aiven for OpenSearch service, you can select the starting version. See all available versions in Versions of Aiven-managed services and tools.

Voluntary manual upgrades

Except for a few specific cases, upgrades are voluntary and require your action.

Upgrading between minor versions of the same major version: upgrade directly to the target version.
Upgrading between minor versions of two different major versions:
1. Upgrade to the latest major version.
2. Upgrade to a minor version of the latest major version.

Mandatory automatic upgrades

Although mandatory upgrades don't require your action, you can still run them yourself as soon as they become available. Otherwise, they are applied automatically during the maintenance window.

Version patches: major.minor.patch1 > major.minor.patch2, for example, 2.19.1 > 2.19.2
- Scheduled and applied during your maintenance window
- Possible after any voluntary manual minor version upgrade to ensure the patch version consistency between the cluster nodes
Cluster node version upgrades after node replacements in disaster recovery scenarios to ensure the version consistency between the cluster nodes
Upgrades due to versions reaching end-of-life on the Aiven Platform

Before you start

Available or upcoming upgrades

Track upgrades for your service via:

Aiven Console: Service Overview page > the Maintenance section > List of available mandatory and optional upgrades
Email: notifications for automated upgrades

Downgrade restriction

Downgrades are not supported: You cannot revert to a previous version or change to a lower

k-NN field requirements

If your indices use k-NN fields, Aiven for OpenSearch checks them during specific upgrades and blocks the upgrade (403 Forbidden) if a check fails. The error response lists the affected index names.

OpenSearch 1.x to 2.x: Fails if any index has the legacy index.knn: true setting. Reindex the affected indices with an explicit knn_vector field mapping before upgrading.
OpenSearch 1.x to 2.x: Fails if any knn_vector field name contains a space or one of " * \ < | , > / ?. Rename the field or reindex the affected indices with valid field names before upgrading.
OpenSearch 2.19 to 3.x: Fails if any knn_vector field uses the deprecated nmslib engine. To resolve this, see Migrate off the nmslib engine.

Prerequisites for upgrade

To upgrade your service version, check that:

Your Aiven for OpenSearch service is running.
Target version to upgrade to is available for manual upgrade.
You can use one of the following tools to upgrade:

Upgrade your service

Console
CLI
API
Terraform
Kubernetes

In the Aiven Console, go to your service.
On the Overview page, go to the Maintenance section.
Click Actions > Upgrade version.
Select a version to upgrade to, and click Upgrade.

Optional: Check available service versions using the avn service versions command.
Upgrade the service version using the avn service update command. Replace placeholders PROJECT_NAME, SERVICE_NAME, and NEW_VERSION as needed.
```
avn service update --project PROJECT_NAME SERVICE_NAME -c service_version=NEW_VERSION
```

Call the ServiceUpdate endpoint to set service_version. Replace placeholders PROJECT_NAME, SERVICE_NAME, API_TOKEN, and NEW_VERSION as needed.

curl --request PUT \
     --url "https://api.aiven.io/v1/project/PROJECT_NAME/service/SERVICE_NAME" \
     --header "Authorization: Bearer API_TOKEN" \
     --header "Content-Type: application/json" \
     --data '{
       "user_config": {
         "service_version": "NEW_VERSION"
       }
     }'

Use the aiven_opensearch resource to set opensearch_version.

Use the OpenSearch resource to set opensearch_version.

Multi-version: how it works​

Default version​

Voluntary manual upgrades​

Mandatory automatic upgrades​

Before you start​

Available or upcoming upgrades​

Downgrade restriction​

k-NN field requirements​

Prerequisites for upgrade​

Upgrade your service​