View a markdown version of this page

Upgrading a domain (CLI) - Amazon OpenSearch Service
In-place upgradeClone-based upgrade
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Upgrading a domain (CLI)

You can use the following operations to identify the correct version of OpenSearch or Elasticsearch for your domain, start an in-place or clone-based upgrade, perform the pre-upgrade check, and view progress:

  • get-compatible-versions (GetCompatibleVersions)

  • upgrade-domain (UpgradeDomain)

  • get-upgrade-status (GetUpgradeStatus)

  • get-upgrade-history (GetUpgradeHistory)

  • describe-domain-change-progress (DescribeDomainChangeProgress) – Monitors a clone-based upgrade.

  • update-clone (UpdateClone) – Shifts read traffic to the cloned cluster, cuts over, cancels, and manages the retention period for a clone-based upgrade.

In-place upgrade

To check whether your domain is eligible without starting an upgrade, use the --perform-check-only option:

aws opensearch upgrade-domain \
  --domain-name my-domain \
  --target-version OpenSearch_2.19 \
  --perform-check-only

To start the upgrade, run the same command without --perform-check-only:

aws opensearch upgrade-domain \
  --domain-name my-domain \
  --target-version OpenSearch_2.19

To view progress, use get-upgrade-status:

aws opensearch get-upgrade-status --domain-name my-domain

Clone-based upgrade

A clone-based upgrade has more steps than an in-place upgrade. For information about each step, see Validating, cutting over, and rolling back during a clone-based upgrade.

Start the upgrade

To start a clone-based upgrade, run upgrade-domain with DeploymentStrategy set to ClonedBlueGreen in --deployment-strategy-options. The retention period is optional. The maximum is 336 hours (14 days). To request a longer period, contact Amazon Support.

aws opensearch upgrade-domain \
  --domain-name my-domain \
  --target-version OpenSearch_3.1 \
  --deployment-strategy-options 'DeploymentStrategy=ClonedBlueGreen,ClonedBlueGreenOptions={RetentionOptions={RetentionInHours=48}}'

The response includes a ChangeId. Use it to monitor the upgrade:

aws opensearch describe-domain-change-progress \
  --domain-name my-domain \
  --change-id 9f1c2b7a-4d3e-4e21-9a5f-0c8b7d6e5f40

When the ConfigChangeStatus is PendingUserInput, the cloned cluster is ready for you to validate.

Shift read traffic to the cloned cluster

CloneReadTrafficPercent is the share of read requests that go to the cloned cluster, from 0 to 100. Writes always go to the primary cluster.

aws opensearch update-clone \
  --domain-name my-domain \
  --traffic-split-options Strategy=ShiftReadTrafficPercent,CloneReadTrafficPercent=10

Cut over to the cloned cluster

Set Target to ClonedCluster.

aws opensearch update-clone \
  --domain-name my-domain \
  --cutover-options Target=ClonedCluster

Cancel the upgrade before cutover

Set Target to PrimaryCluster. OpenSearch Service deletes the cloned cluster, and your domain stays as it was.

aws opensearch update-clone \
  --domain-name my-domain \
  --cutover-options Target=PrimaryCluster

Set or change the retention period

You can set or change the retention period before or after cutover.

aws opensearch update-clone \
  --domain-name my-domain \
  --retention-options RetentionInHours=24

End the retention period early

After cutover, you can roll back to the primary cluster, or delete the primary cluster now.

aws opensearch update-clone \
  --domain-name my-domain \
  --retention-options '{"RetentionAction":"RollbackToPrimaryCluster"}'
aws opensearch update-clone \
  --domain-name my-domain \
  --retention-options '{"RetentionAction":"DeletePrimaryCluster"}'

For more information, see the Amazon CLI command reference and Amazon OpenSearch Service API Reference.