Service software updates in Amazon OpenSearch Service
For descriptions of the changes and additions made in each major service software release, see the release notes.
Amazon OpenSearch Service regularly releases service software updates that add features or otherwise improve
your domains. The Notifications panel in the console is the easiest way to
see if an update is available or to check the status of an update. Each notification includes
details about the service software update. The notification severity is
Informational
if the update is optional and High
if it's
required.
Service software updates differ from OpenSearch version upgrades. For information about upgrading to a later version of OpenSearch, see Upgrading Amazon OpenSearch Service domains.
Domain update considerations
Consider the following when deciding whether to update your domain:
-
When you initiate a service software update, OpenSearch Service sends a notification when the update starts and when it completes.
-
If you take no action on available updates, OpenSearch Service eventually updates your domain for you. If an update is optional, OpenSearch Service updates your domain the next time you make a change that causes a blue/green deployment. If the update is required, OpenSearch Service initiates a blue/green deployment after a certain timeframe (typically two weeks) if the domain hasn't already been updated. You receive notifications when the update starts and when it completes.
-
Software updates use blue/green deployments to minimize downtime. Updates can temporarily strain a cluster's dedicated master nodes, so make sure to maintain sufficient capacity to handle the associated overhead.
Manually updating your domain lets you take advantage of new features more quickly. When you choose Update, OpenSearch Service places the request in a queue and begins the update when it has time. Updates typically complete within minutes, but can also take several hours or even days if your system is experiencing heavy load. Consider updating your domain at a low traffic time to avoid long update periods.
Patch releases
Service software versions that end in "-P" and a number, such as
R20211203-P4
, are patch releases. Patches are likely to include
performance improvements, minor bug fixes, and security fixes or posture improvements. Patch
releases do not include new features or breaking changes, and they generally do not have a
direct or noticeable impact on users.
Request a service software update (console)
To request a service software update (console)
-
Go to https://aws.amazon.com
and choose Sign In to the Console. -
Under Analytics, choose Amazon OpenSearch Service.
-
In the navigation pane, under Domains, choose the domain name to open its settings.
-
Choose Actions, Update and confirm the update.
Request a service software update (AWS CLI)
Send the following AWS CLI command to request a service software update:
aws opensearch start-service-software-update --domain-name
my-domain
For more information, see start-service-software-update in the AWS CLI command reference and StartServiceSoftwareUpdate in the configuration API reference.
After requesting an update, you might have a narrow window of time in which you can cancel
it. The duration of this PENDING_UPDATE
state can vary greatly and depends on
your AWS Region and the number of concurrent updates OpenSearch Service is performing. To cancel, use the
console or cancel-service-software-update
(CancelServiceSoftwareUpdate
) command.
Request a service software update (SDK)
This sample Python script uses the describe_domaindomain_name
.
import boto3 from botocore.config import Config import time # Build the client using the default credential configuration. # You can use the CLI and run 'aws configure' to set access key, secret # key, and default region. my_config = Config( # Optionally lets you specify a Region other than your default. region_name='us-east-1' ) domain_name = '' # The name of the domain to check and update client = boto3.client('opensearch', config=my_config) def getUpdateStatus(client): """Determines whether the domain is eligible for an update""" response = client.describe_domain( DomainName=domain_name ) sso = response['DomainStatus']['ServiceSoftwareOptions'] if sso['UpdateStatus'] == 'ELIGIBLE': print('Domain [' + domain_name + '] is eligible for a service software update from version ' + sso['CurrentVersion'] + ' to version ' + sso['NewVersion']) updateDomain(client) else: print('Domain is not eligible for an update at this time.') def updateDomain(client): """Starts a service software update for the eligible domain""" response = client.start_service_software_update( DomainName=domain_name ) print('Updating domain [' + domain_name + '] to version ' + response['ServiceSoftwareOptions']['NewVersion'] + '...') waitForUpdate(client) def waitForUpdate(client): """Waits for the domain to finish updating""" response = client.describe_domain( DomainName=domain_name ) status = response['DomainStatus']['ServiceSoftwareOptions']['UpdateStatus'] if status == 'PENDING_UPDATE' or status == 'IN_PROGRESS': time.sleep(30) waitForUpdate(client) elif status == 'COMPLETED': print('Domain [' + domain_name + '] successfully updated to the latest software version') else: print('Domain is not currently being updated.') def main(): getUpdateStatus(client)
Monitoring service software update events
OpenSearch Service sends a notification when a service software update is available, required, started, completed, or failed. You can view these notifications on the Notifications panel of the OpenSearch Service console. It also sends these notifications to Amazon EventBridge. You can use EventBridge to configure rules that send an email or perform a specific action when an event is received. For an example walkthrough, see Tutorial: Sending Amazon SNS alerts for available software updates.
To see the format of each service software event sent to Amazon EventBridge, see Service software update events.
When domains are ineligible for an update
Your domain is ineligible for a service software update if it's in any of the following states:
State | Description |
---|---|
Domain in processing |
The domain is in the middle of a configuration change. Check update eligibility after the operation completes. |
Red cluster status |
One or more indexes in the cluster is red. For troubleshooting steps, see Red cluster status. |
High error rate |
The OpenSearch cluster is returning a large number of 5xx errors when attempting to process requests. This problem is usually the result of too many simultaneous read or write requests. Consider reducing traffic to the cluster or scaling your domain. |
Split brain |
Split brain means your OpenSearch cluster has
more than one master node and has split into two clusters that never will rejoin on
their own. You can avoid split brain by using the recommended number of dedicated master nodes. For
help recovering from split brain, contact AWS Support |
Amazon Cognito integration issue |
Your domain uses authentication for OpenSearch Dashboards, and OpenSearch Service can't find one or more Amazon Cognito resources. This problem usually occurs if the Amazon Cognito user pool is missing. To correct the issue, recreate the missing resource and configure the OpenSearch Service domain to use it. |
Other OpenSearch Service service issue |
Issues with OpenSearch Service itself might cause your domain to display as ineligible for an
update. If none of the previous conditions apply to your domain and the problem
persists for more than a day, contact AWS Support |