Service software updates in Amazon OpenSearch Service

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. All service software updates use blue/green deployments to minimize downtime.

Service software updates differ from OpenSearch Service version upgrades. For information about upgrading to a later version of OpenSearch Service, see Upgrading Amazon OpenSearch Service domains.

OpenSearch Service requires you to apply required service software updates within 30 days of their availability. These updates are critical for maintaining security compliance.

If you don't apply required updates within the 30-day period, you'll receive reminder notifications every 15 days for 30 days. After this period without compliance, your domain will be isolated with the following effects:

During isolation, you'll continue receiving reminder notifications every 15 days for 60 days. If you don't apply the required updates within this period, your OpenSearch Service domain and all associated data will be permanently deleted. For more information, see Troubleshooting validation errors.

Optional versus required updates

OpenSearch Service has two broad categories of service software updates:

Optional updates

Optional service software updates generally include enhancements and support for new features or functionality. Optional updates aren't enforced on your domains, and there's no hard deadline to install them. The availability of the update is communicated through email and a console notification. You can choose to apply the update immediately or reschedule it for a more appropriate date and time. You can also schedule it during the domain's off-peak window. The majority of software updates are optional.

Regardless of whether or not you schedule an update, if you make a change on the domain that causes a blue/green deployment, OpenSearch Service automatically updates your service software for you.

You can configure your domain to automatically apply optional updates during off-peak hours. When this option is turned on, OpenSearch Service waits at least 13 days from when an optional update is available and then schedules the update after seven days. You receive a console notification when the update is scheduled and you can choose to reschedule it for a later date.

To turn on automatic software updates, select Enable automatic software update when you create or update your domain. To configure the same setting using the AWS CLI, set --software-update-options to true when you create or update your domain.

Required updates

Required service software updates generally include critical security fixes or other mandatory updates to ensure the continued integrity and functionality of your domain. Examples of required updates are Log4j Common Vulnerabilities and Exposures (CVEs) and enforcement of Instance Metadata Service Version 2 (IMDSv2). The number of mandatory updates in a year is usually less than three.

OpenSearch Service automatically schedules these updates and notifies you seven days before the scheduled update through email and a console notification. You can choose to apply the update immediately or reschedule it for a more appropriate date and time within the allowed timeframe. You can also schedule it during the domain's next off-peak window. If you take no action on a required update and you don't make any domain changes that cause a blue/green deployment, OpenSearch Service can initiate the update at any time beyond the specified deadline (typically 14 days from availability), within the domain's off-peak window.

Regardless of when the update is scheduled for, if you make a change on the domain that causes a blue/green deployment, OpenSearch Service automatically updates your domain for you.

Patch updates

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 don't have a direct or noticeable impact on users. The service software notification tells you if a patch release is optional or mandatory.

Considerations

Consider the following when deciding whether to update your domain:

Starting a service software update

You can request a service software update through the OpenSearch Service console, the AWS CLI, or one of the SDKs.

aws opensearch start-service-software-update \
  --domain-name my-domain \
  --schedule-at "NOW"

{
    "ServiceSoftwareOptions": {
        "CurrentVersion": "R20220928-P1",
        "NewVersion": "R20220928-P2",
        "UpdateAvailable": true,
        "Cancellable": true,
        "UpdateStatus": "PENDING_UPDATE",
        "Description": "",
        "AutomatedUpdateDate": "1969-12-31T16:00:00-08:00",
        "OptionalDeployment": true
    }
}

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)

Scheduling software updates during off-peak windows

Each OpenSearch Service domain created after February 16, 2023 has a daily 10-hour window between 10:00 P.M. and 8:00 A.M. local time that we consider the off-peak window. OpenSearch Service uses this window to schedule service software updates for the domain. Off-peak updates help to minimize strain on a cluster's dedicated master nodes during higher traffic periods. OpenSearch Service can't initiate updates outside of this 10-hour window without your consent.

For each domain, you can choose to override the default 10:00 P.M. start time with a custom time. For instructions, see Configuring a custom off-peak window.

aws opensearch start-service-software-update \
  --domain-name my-domain \
  --schedule-at "OFF_PEAK_WINDOW"

Monitoring service software updates

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. The notification severity is Informational if the update is optional and High if it's required.

OpenSearch Service also sends service software events 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 walk through, 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:

Rolling back a service software update

Amazon OpenSearch Service supports rolling back service software updates. You can initiate a rollback using the OpenSearch Service console, the AWS CLI, or one of the AWS SDKs. Software updates are rolled back using a blue/green deployment.

Rollback eligibility and considerations

Your domain must meet all of the following conditions for a rollback to be available:

Rollback time windows

The rollback window depends on the type of software update that was applied.

After the rollback window expires, self-service rollback is no longer available. Contact Support if you are experiencing a critical issue after the window has closed.

How to request a rollback

You can request a rollback using the RollbackServiceSoftwareUpdate API.

Request

POST /2021-01-01/opensearch/serviceSoftwareUpdate/rollback

Request body:

{
    "DomainName": "your-domain-name"
}

Response

The API returns an HTTP 200 response in all non-error cases. The RollbackAvailable field in the response body indicates whether the rollback was initiated.

{
    "RollbackServiceSoftwareOptions": {
        "CurrentVersion": "string",
        "NewVersion": "string",
        "RollbackAvailable": boolean,
        "Description": "string"
    }
}

Response fields:

Error responses

Example responses

Rollback initiated successfully:

{
    "RollbackServiceSoftwareOptions": {
        "CurrentVersion": "OpenSearch_2_11_R20240115",
        "NewVersion": "OpenSearch_2_11_R20231023",
        "RollbackAvailable": true,
        "Description": "Rollback initiated successfully. The domain will be rolled back from OpenSearch_2_11_R20240115 to OpenSearch_2_11_R20231023."
    }
}

Rollback unavailable, outside the time window:

{
    "RollbackServiceSoftwareOptions": {
        "CurrentVersion": "OpenSearch_2_11_R20240115",
        "NewVersion": null,
        "RollbackAvailable": false,
        "Description": "Rollback is not available. The 15-day rollback window has expired. Please contact AWS Support for assistance."
    }
}

Rollback unavailable, mandatory update auto-applied by service:

{
    "RollbackServiceSoftwareOptions": {
        "CurrentVersion": "OpenSearch_2_11_R20240215",
        "NewVersion": null,
        "RollbackAvailable": false,
        "Description": "Rollback is not available. The current version was applied through a mandatory service update. Please contact AWS Support for assistance."
    }
}

Rollback unavailable, engine version upgrade:

{
    "RollbackServiceSoftwareOptions": {
        "CurrentVersion": "OpenSearch_2_11_R20240215",
        "NewVersion": null,
        "RollbackAvailable": false,
        "Description": "Rollback is not available. Engine version upgrades are irreversible. Please contact AWS Support for assistance."
    }
}

Rollback unavailable, domain already in rolled-back state:

{
    "RollbackServiceSoftwareOptions": {
        "CurrentVersion": "OpenSearch_2_11_R20231023",
        "NewVersion": null,
        "RollbackAvailable": false,
        "Description": "Domain is already in a rolled-back state."
    }
}