AWS API Changes

2026/11/09 - Amazon OpenSearch Service - 1 new 2 updated api methods

Changes Adds cloned blue-green upgrades for Amazon OpenSearch Service domains. UpgradeDomain accepts DeploymentStrategyOptions to upgrade on a cloned cluster, the new UpdateClone API shifts search traffic, cuts over and sets retention, and DescribeDomainChangeProgress reports the upgrade details.

UpdateClone (new)

Link ¶

Manages a cloned blue/green upgrade that is in progress on a domain. Use it to shift a percentage of search traffic to the cloned cluster, to cut over to the cloned cluster or back to the primary cluster, or to change the retention period. Specify exactly one of TrafficSplitOptions, CutoverOptions, or RetentionOptions in each request.

See also: AWS API Documentation

Request Syntax

client.update_clone(
    DomainName='string',
    TrafficSplitOptions={
        'Strategy': 'ShiftReadTrafficPercent',
        'CloneReadTrafficPercent': 123
    },
    CutoverOptions={
        'Target': 'ClonedCluster'|'PrimaryCluster'
    },
    RetentionOptions={
        'RetentionInHours': 123,
        'RetentionAction': 'RollbackToPrimaryCluster'|'DeletePrimaryCluster'
    }
)

type DomainName:

string

param DomainName:

[REQUIRED]

The name of the domain that has a cloned blue/green upgrade in progress.

type TrafficSplitOptions:

dict

param TrafficSplitOptions:

Shifts a percentage of search traffic from the primary cluster to the cloned cluster.

Strategy (string) -- [REQUIRED]

The traffic shifting strategy. The only valid value is ShiftReadTrafficPercent.
CloneReadTrafficPercent (integer) -- [REQUIRED]

The percentage of search traffic, from 0 to 100, to send to the cloned cluster. The rest goes to the primary cluster.

type CutoverOptions:

dict

param CutoverOptions:

Cuts the domain over to the cloned cluster or back to the primary cluster.

Target (string) -- [REQUIRED]

The cluster to cut over to. ClonedCluster makes the cloned cluster serve the domain. PrimaryCluster keeps the primary cluster and ends the upgrade.

type RetentionOptions:

dict

param RetentionOptions:

Changes the retention period, or ends it after cutover completes.

RetentionInHours (integer) --

The number of hours to keep the cluster that you cut over from. The retention period starts when cutover completes. The minimum is 1 hour. In an UpdateClone response after cutover completes, this value is the number of hours remaining in the retention period, rounded up.
RetentionAction (string) --

Ends the retention period now. Valid only after cutover completes.

rtype:

dict

returns:

Response Syntax

{
    'DomainName': 'string',
    'ChangeId': 'string',
    'CutoverOptions': {
        'Target': 'ClonedCluster'|'PrimaryCluster',
        'Status': 'InProgress'|'Completed'|'Failed'
    },
    'TrafficSplitOptions': {
        'Current': {
            'PrimaryReadTrafficPercent': 123,
            'CloneReadTrafficPercent': 123
        },
        'Target': {
            'PrimaryReadTrafficPercent': 123,
            'CloneReadTrafficPercent': 123
        },
        'Status': 'InProgress'|'Completed'|'Failed'
    },
    'RetentionOptions': {
        'RetentionInHours': 123,
        'RetentionAction': 'RollbackToPrimaryCluster'|'DeletePrimaryCluster'
    }
}

Response Structure

(dict) --

Container for the response returned by the UpdateClone operation.
- DomainName (string) --
  
  The name of the domain.
- ChangeId (string) --
  
  The unique identifier of the configuration change. Use it with DescribeDomainChangeProgress to track the change.
- CutoverOptions (dict) --
  
  The requested cutover target and the status of the cutover.
  - Target (string) --
    
    The cluster that the domain is cutting over to.
  - Status (string) --
    
    The status of the cutover.
- TrafficSplitOptions (dict) --
  
  The current and requested traffic split, and the status of the traffic shift.
  - Current (dict) --
    
    The traffic split currently in effect.
    - PrimaryReadTrafficPercent (integer) --
      
      The percentage of search traffic sent to the primary cluster.
    - CloneReadTrafficPercent (integer) --
      
      The percentage of search traffic sent to the cloned cluster.
  - Target (dict) --
    
    The requested traffic split.
    - PrimaryReadTrafficPercent (integer) --
      
      The percentage of search traffic sent to the primary cluster.
    - CloneReadTrafficPercent (integer) --
      
      The percentage of search traffic sent to the cloned cluster.
  - Status (string) --
    
    The status of the traffic shift.
- RetentionOptions (dict) --
  
  The retention settings for the upgrade.
  Note
  
  This is a Tagged Union structure. Only one of the following top level keys will be set: RetentionInHours, RetentionAction. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
```
'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
```
  - RetentionInHours (integer) --
    
    The number of hours to keep the cluster that you cut over from. The retention period starts when cutover completes. The minimum is 1 hour. In an UpdateClone response after cutover completes, this value is the number of hours remaining in the retention period, rounded up.
  - RetentionAction (string) --
    
    Ends the retention period now. Valid only after cutover completes.

DescribeDomainChangeProgress (updated)

Link ¶
Changes (response)

{'ChangeProgressStatus': {'ClonedBlueGreenUpgradeDetails': {'RetentionInHours': 'integer',
                                                            'ScheduledAction': {'Action': 'AutomaticCutoverToPrimaryCluster '
                                                                                          '| '
                                                                                          'DeletePrimaryCluster',
                                                                                'ScheduledTime': 'timestamp'},
                                                            'TrafficSplit': {'CloneReadTrafficPercent': 'integer',
                                                                             'PrimaryReadTrafficPercent': 'integer'}}}}

Returns information about the current blue/green deployment happening on an Amazon OpenSearch Service domain. For more information, see Making configuration changes in Amazon OpenSearch Service.

See also: AWS API Documentation

Request Syntax

client.describe_domain_change_progress(
    DomainName='string',
    ChangeId='string'
)

type DomainName:

string

param DomainName:

[REQUIRED]

The name of the domain to get progress information for.

type ChangeId:

string

param ChangeId:

The specific change ID for which you want to get progress information. If omitted, the request returns information about the most recent configuration change.

rtype:

dict

returns:

Response Syntax

{
    'ChangeProgressStatus': {
        'ChangeId': 'string',
        'StartTime': datetime(2015, 1, 1),
        'Status': 'PENDING'|'PROCESSING'|'COMPLETED'|'FAILED',
        'PendingProperties': [
            'string',
        ],
        'CompletedProperties': [
            'string',
        ],
        'TotalNumberOfStages': 123,
        'ChangeProgressStages': [
            {
                'Name': 'string',
                'Status': 'string',
                'Description': 'string',
                'LastUpdated': datetime(2015, 1, 1)
            },
        ],
        'LastUpdatedTime': datetime(2015, 1, 1),
        'ConfigChangeStatus': 'Pending'|'Initializing'|'Validating'|'ValidationFailed'|'ApplyingChanges'|'Completed'|'PendingUserInput'|'Cancelled',
        'InitiatedBy': 'CUSTOMER'|'SERVICE',
        'ClonedBlueGreenUpgradeDetails': {
            'TrafficSplit': {
                'PrimaryReadTrafficPercent': 123,
                'CloneReadTrafficPercent': 123
            },
            'ScheduledAction': {
                'Action': 'AutomaticCutoverToPrimaryCluster'|'DeletePrimaryCluster',
                'ScheduledTime': datetime(2015, 1, 1)
            },
            'RetentionInHours': 123
        },
        'ValidationFailures': [
            {
                'Code': 'string',
                'Message': 'string',
                'Severity': 'Critical'|'Warning'
            },
        ],
        'AcceptedWarnings': [
            'string',
        ]
    }
}

Response Structure

(dict) --

The result of a DescribeDomainChangeProgress request. Contains progress information for the requested domain change.
- ChangeProgressStatus (dict) --
  
  Container for information about the stages of a configuration change happening on a domain.
  - ChangeId (string) --
    
    The unique change identifier associated with a specific domain configuration change.
  - StartTime (datetime) --
    
    The time at which the configuration change is made on the domain.
  - Status (string) --
    
    The overall status of the domain configuration change.
  - PendingProperties (list) --
    
    The list of properties in the domain configuration change that are still pending.
    - (string) --
  - CompletedProperties (list) --
    
    The list of properties in the domain configuration change that have completed.
    - (string) --
  - TotalNumberOfStages (integer) --
    
    The total number of stages required for the configuration change.
  - ChangeProgressStages (list) --
    
    The specific stages that the domain is going through to perform the configuration change.
    - (dict) --
      
      Progress details for each stage of a domain update.
      - Name (string) --
        
        The name of the stage.
      - Status (string) --
        
        The status of the stage.
      - Description (string) --
        
        The description of the stage.
      - LastUpdated (datetime) --
        
        The most recent updated timestamp of the stage.
  - LastUpdatedTime (datetime) --
    
    The last time that the status of the configuration change was updated.
  - ConfigChangeStatus (string) --
    
    The current status of the configuration change.
  - InitiatedBy (string) --
    
    The IAM principal who initiated the configuration change.
  - ClonedBlueGreenUpgradeDetails (dict) --
    
    Details about a cloned blue/green upgrade, when the change is one.
    - TrafficSplit (dict) --
      
      The current split of search traffic between the primary and cloned clusters.
      - PrimaryReadTrafficPercent (integer) --
        
        The percentage of search traffic sent to the primary cluster.
      - CloneReadTrafficPercent (integer) --
        
        The percentage of search traffic sent to the cloned cluster.
    - ScheduledAction (dict) --
      
      The action that the service takes automatically if you don't act before the scheduled time.
      - Action (string) --
        
        The action that the service takes.
      - ScheduledTime (datetime) --
        
        The time at which the service takes the action.
    - RetentionInHours (integer) --
      
      The retention period, in hours, for the cluster that you cut over from.
  - ValidationFailures (list) --
    
    The validation failures that occurred as a result of the configuration change.
    - (dict) --
      
      A validation failure that occurred as the result of a pre-update validation check (verbose dry run) on a domain.
      - Code (string) --
        
        The error code of the failure.
      - Message (string) --
        
        A message corresponding to the failure.
      - Severity (string) --
        
        The severity of the validation failure.
  - AcceptedWarnings (list) --
    
    The list of advisory warning codes that were accepted for the configuration change.
    - (string) --

UpgradeDomain (updated)

Link ¶
Changes (both)

{'DeploymentStrategyOptions': {'ClonedBlueGreenOptions': {'RetentionOptions': {'RetentionAction': 'RollbackToPrimaryCluster '
                                                                                                  '| '
                                                                                                  'DeletePrimaryCluster',
                                                                               'RetentionInHours': 'integer'}},
                               'DeploymentStrategy': 'ClonedBlueGreen'}}

Allows you to either upgrade your Amazon OpenSearch Service domain or perform an upgrade eligibility check to a compatible version of OpenSearch or Elasticsearch.

See also: AWS API Documentation

Request Syntax

client.upgrade_domain(
    DomainName='string',
    TargetVersion='string',
    PerformCheckOnly=True|False,
    AdvancedOptions={
        'string': 'string'
    },
    DeploymentStrategyOptions={
        'DeploymentStrategy': 'ClonedBlueGreen',
        'ClonedBlueGreenOptions': {
            'RetentionOptions': {
                'RetentionInHours': 123,
                'RetentionAction': 'RollbackToPrimaryCluster'|'DeletePrimaryCluster'
            }
        }
    }
)

type DomainName:

string

param DomainName:

[REQUIRED]

Name of the OpenSearch Service domain that you want to upgrade.

type TargetVersion:

string

param TargetVersion:

[REQUIRED]

OpenSearch or Elasticsearch version to which you want to upgrade, in the format Opensearch_X.Y or Elasticsearch_X.Y.

type PerformCheckOnly:

boolean

param PerformCheckOnly:

When true, indicates that an upgrade eligibility check needs to be performed. Does not actually perform the upgrade.

type AdvancedOptions:

dict

param AdvancedOptions:

Only supports the override_main_response_version parameter and not other advanced options. You can only include this option when upgrading to an OpenSearch version. Specifies whether the domain reports its version as 7.10 so that it continues to work with Elasticsearch OSS clients and plugins.

(string) --
- (string) --

type DeploymentStrategyOptions:

dict

param DeploymentStrategyOptions:

Overrides the deployment strategy for this upgrade. To run a cloned blue/green upgrade, set DeploymentStrategy to ClonedBlueGreen.

DeploymentStrategy (string) -- [REQUIRED]

The deployment strategy to use for this operation. The only valid value is ClonedBlueGreen, which creates a cloned cluster on the target version next to the primary cluster so that you can validate it and shift traffic to it before you cut over.
ClonedBlueGreenOptions (dict) --

Options that apply when DeploymentStrategy is ClonedBlueGreen.
- RetentionOptions (dict) --
  
  How long to keep the cluster that you cut over from after cutover completes. When you start the upgrade, only RetentionInHours is accepted.
  
  Note
  
  This is a Tagged Union structure. Only one of the following top level keys can be set: RetentionInHours, RetentionAction.
  - RetentionInHours (integer) --
    
    The number of hours to keep the cluster that you cut over from. The retention period starts when cutover completes. The minimum is 1 hour. In an UpdateClone response after cutover completes, this value is the number of hours remaining in the retention period, rounded up.
  - RetentionAction (string) --
    
    Ends the retention period now. Valid only after cutover completes.

rtype:

dict

returns:

Response Syntax

{
    'UpgradeId': 'string',
    'DomainName': 'string',
    'TargetVersion': 'string',
    'PerformCheckOnly': True|False,
    'AdvancedOptions': {
        'string': 'string'
    },
    'DeploymentStrategyOptions': {
        'DeploymentStrategy': 'ClonedBlueGreen',
        'ClonedBlueGreenOptions': {
            'RetentionOptions': {
                'RetentionInHours': 123,
                'RetentionAction': 'RollbackToPrimaryCluster'|'DeletePrimaryCluster'
            }
        }
    },
    'ChangeProgressDetails': {
        'ChangeId': 'string',
        'Message': 'string',
        'ConfigChangeStatus': 'Pending'|'Initializing'|'Validating'|'ValidationFailed'|'ApplyingChanges'|'Completed'|'PendingUserInput'|'Cancelled',
        'InitiatedBy': 'CUSTOMER'|'SERVICE',
        'StartTime': datetime(2015, 1, 1),
        'LastUpdatedTime': datetime(2015, 1, 1)
    }
}

Response Structure

(dict) --

Container for the response returned by UpgradeDomain operation.
- UpgradeId (string) --
  
  The unique identifier of the domain upgrade.
- DomainName (string) --
  
  The name of the domain that was upgraded.
- TargetVersion (string) --
  
  OpenSearch or Elasticsearch version that the domain was upgraded to.
- PerformCheckOnly (boolean) --
  
  When true, indicates that an upgrade eligibility check was performed.
- AdvancedOptions (dict) --
  
  The advanced options configuration for the domain.
  - (string) --
    - (string) --
- DeploymentStrategyOptions (dict) --
  
  The deployment strategy override used for the upgrade.
  - DeploymentStrategy (string) --
    
    The deployment strategy to use for this operation. The only valid value is ClonedBlueGreen, which creates a cloned cluster on the target version next to the primary cluster so that you can validate it and shift traffic to it before you cut over.
  - ClonedBlueGreenOptions (dict) --
    
    Options that apply when DeploymentStrategy is ClonedBlueGreen.
    - RetentionOptions (dict) --
      
      How long to keep the cluster that you cut over from after cutover completes. When you start the upgrade, only RetentionInHours is accepted.
      Note
      
      This is a Tagged Union structure. Only one of the following top level keys will be set: RetentionInHours, RetentionAction. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - RetentionInHours (integer) --
        
        The number of hours to keep the cluster that you cut over from. The retention period starts when cutover completes. The minimum is 1 hour. In an UpdateClone response after cutover completes, this value is the number of hours remaining in the retention period, rounded up.
      - RetentionAction (string) --
        
        Ends the retention period now. Valid only after cutover completes.
- ChangeProgressDetails (dict) --
  
  Container for information about a configuration change happening on a domain.
  - ChangeId (string) --
    
    The ID of the configuration change.
  - Message (string) --
    
    A message corresponding to the status of the configuration change.
  - ConfigChangeStatus (string) --
    
    The current status of the configuration change.
  - InitiatedBy (string) --
    
    The IAM principal who initiated the configuration change.
  - StartTime (datetime) --
    
    The time that the configuration change was initiated, in Universal Coordinated Time (UTC).
  - LastUpdatedTime (datetime) --
    
    The last time that the configuration change was updated.