2026/10/28 - Amazon OpenSearch Service - 6 new api methods
Changes This release adds APIs to simplify setting up a replication relationship between OpenSearch clusters. The APIs include new Switchover and Failover actions for planned switchovers and unplanned failovers to ensure high availability for OpenSearch in the event of disaster in a single region.
Starts replicating a domain to a peer domain in another AWS Region. A domain can have one peer. The domain you call becomes the primary and the peer becomes the secondary, which receives a copy of the primary's indexes and serves read requests.
Replication is established asynchronously. Use the DescribeDomainReplication operation to check whether the relationship has reached the ACTIVE state.
See also: AWS API Documentation
Request Syntax
client.add_replication_peer(
DomainName='string',
PeerDomainArn='string',
DryRun=True|False
)
string
[REQUIRED]
The name of an OpenSearch Service domain. Domain names are unique across the domains owned by an account within an Amazon Web Services Region.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the domain to replicate to. The peer must be in a different Region from the domain you are calling, and in the same AWS account.
boolean
When true, validates the request and reports whether replication could be established, without changing either domain.
dict
Response Syntax
{
'DomainArn': 'string',
'Status': 'PENDING_SETUP'|'ACTIVE'|'SWITCHING_OVER'|'FAILING_OVER'|'PENDING_REMOVAL'|'DETACHED'|'EJECTED'|'FAILED'
}
Response Structure
(dict) --
DomainArn (string) --
The Amazon Resource Name (ARN) of the domain that is now replicating to the peer.
Status (string) --
The state of the replication relationship. This is PENDING_SETUP immediately after the request is accepted.
Compares the metadata of two domains and reports where they differ. Use this operation to check that a secondary domain is configured consistently with its primary before you rely on it, because replication copies index data but does not copy domain metadata such as index templates, ingest pipelines, or security roles.
You choose which categories to compare. The response reports, for each category, how many items match, how many exist on only one domain, and which fields diverge.
See also: AWS API Documentation
Request Syntax
client.compare_domain_configuration(
SourceDomainArn='string',
TargetDomainArn='string',
Categories=[
'string',
]
)
string
[REQUIRED]
The Amazon Resource Name (ARN) of the domain to compare from.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the domain to compare against.
list
[REQUIRED]
The metadata categories to compare. At least one is required, and only the categories you name are read and returned.
aliases
alerting_monitors
cluster_settings
component_templates
ingest_pipelines
ism_policies — index state management policies
security_action_groups
security_internal_users
security_role_mappings
security_roles
templates — index templates
The set of categories grows over time, so this list is not fixed. A category the service does not recognise is rejected with the supported categories named in the error message.
(string) --
dict
Response Syntax
{
'SourceDomainArn': 'string',
'TargetDomainArn': 'string',
'Categories': {
'string': {
'Status': 'compared'|'error',
'InSync': 123,
'SourceOnly': 123,
'TargetOnly': 123,
'Diverged': 123,
'Items': {
'SourceOnly': [
'string',
],
'TargetOnly': [
'string',
],
'Diverged': [
{
'Name': 'string',
'Fields': [
{
'Path': 'string',
'SourceValue': 'string',
'TargetValue': 'string',
'Policy': 'redacted'
},
]
},
]
},
'Truncated': True|False
}
}
}
Response Structure
(dict) --
SourceDomainArn (string) --
The Amazon Resource Name (ARN) of the domain that was compared from.
TargetDomainArn (string) --
The Amazon Resource Name (ARN) of the domain that was compared against.
Categories (dict) --
The comparison result for each category you requested, keyed by category name.
(string) --
(dict) --
The result of comparing one metadata category between two domains.
Status (string) --
Whether the category was compared successfully. compared means the result is complete; error means the category could not be read.
InSync (integer) --
The number of items that are identical on both domains.
SourceOnly (integer) --
The number of items that exist only on the source domain.
TargetOnly (integer) --
The number of items that exist only on the target domain.
Diverged (integer) --
The number of items that exist on both domains but differ.
Items (dict) --
The names of the items that differ, and for diverging items, the fields that differ.
SourceOnly (list) --
The names of items that exist only on the source domain.
(string) --
TargetOnly (list) --
The names of items that exist only on the target domain.
(string) --
Diverged (list) --
The items that exist on both domains but differ, with the diverging fields.
(dict) --
An item that exists on both domains but whose contents differ.
Name (string) --
The name of the item.
Fields (list) --
The fields of the item that differ.
(dict) --
A single field that differs between the source and target copies of an item.
Path (string) --
The location of the field within the item.
SourceValue (string) --
The field's value on the source domain.
TargetValue (string) --
The field's value on the target domain.
Policy (string) --
How the comparison treats this field.
Truncated (boolean) --
Whether Items omits some differences because the category contained more than the response can carry. The counts remain complete when this is true.
Promotes a secondary domain to primary, coordinating with the current primary so that no writes are lost. Use this operation for planned role changes, such as testing your recovery procedure or moving write traffic to another Region.
Call this operation in the Region of the domain you want to promote. If the current primary is unreachable, use the FailoverReplication operation instead.
See also: AWS API Documentation
Request Syntax
client.switchover_replication(
DomainName='string',
PeerDomainArn='string'
)
string
[REQUIRED]
The name of an OpenSearch Service domain. Domain names are unique across the domains owned by an account within an Amazon Web Services Region.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the relationship's current primary. The request is rejected if this domain is no longer the peer of the domain you are calling.
dict
Response Syntax
{
'DomainArn': 'string',
'Status': 'PENDING_SETUP'|'ACTIVE'|'SWITCHING_OVER'|'FAILING_OVER'|'PENDING_REMOVAL'|'DETACHED'|'EJECTED'|'FAILED'
}
Response Structure
(dict) --
DomainArn (string) --
The Amazon Resource Name (ARN) of the domain being promoted.
Status (string) --
The state of the replication relationship. This is SWITCHING_OVER while the promotion is in progress.
Stops replicating a domain to its peer. Replication ends for both domains, and each domain keeps the data it holds at that point. Neither domain is deleted.
See also: AWS API Documentation
Request Syntax
client.remove_replication_peer(
DomainName='string',
PeerDomainArn='string'
)
string
[REQUIRED]
The name of an OpenSearch Service domain. Domain names are unique across the domains owned by an account within an Amazon Web Services Region.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the peer to stop replicating with. Both domains are named so that the request identifies exactly one replication relationship.
dict
Response Syntax
{
'DomainArn': 'string',
'Status': 'PENDING_SETUP'|'ACTIVE'|'SWITCHING_OVER'|'FAILING_OVER'|'PENDING_REMOVAL'|'DETACHED'|'EJECTED'|'FAILED'
}
Response Structure
(dict) --
DomainArn (string) --
The Amazon Resource Name (ARN) of the domain that is no longer replicating.
Status (string) --
The state of the replication relationship. This is PENDING_REMOVAL while replication is being stopped.
Promotes a secondary domain to primary without coordinating with the current primary. Use this operation when the primary is unreachable and you cannot wait for it to recover.
Writes that had not yet replicated when the primary became unreachable are lost. You must set AllowDataLoss to acknowledge this. To promote a domain without losing writes, use the SwitchoverReplication operation instead.
Call this operation in the Region of the domain you want to promote.
See also: AWS API Documentation
Request Syntax
client.failover_replication(
DomainName='string',
PeerDomainArn='string',
AllowDataLoss=True|False
)
string
[REQUIRED]
The name of an OpenSearch Service domain. Domain names are unique across the domains owned by an account within an Amazon Web Services Region.
string
[REQUIRED]
The Amazon Resource Name (ARN) of the relationship's current primary. The request is rejected if this domain is no longer the peer of the domain you are calling.
boolean
[REQUIRED]
Acknowledges that writes which had not yet replicated are lost. You must set this to true; the request is rejected otherwise.
dict
Response Syntax
{
'DomainArn': 'string',
'Status': 'PENDING_SETUP'|'ACTIVE'|'SWITCHING_OVER'|'FAILING_OVER'|'PENDING_REMOVAL'|'DETACHED'|'EJECTED'|'FAILED'
}
Response Structure
(dict) --
DomainArn (string) --
The Amazon Resource Name (ARN) of the domain being promoted.
Status (string) --
The state of the replication relationship. This is FAILING_OVER while the promotion is in progress.
Describes the replication arrangement that a domain participates in, including the domain's role and the state of its relationship with each peer.
A domain that is not replicating is returned with an empty Peers list and no Role. Returns ResourceNotFoundException if the domain does not exist.
See also: AWS API Documentation
Request Syntax
client.describe_domain_replication(
DomainName='string'
)
string
[REQUIRED]
The name of an OpenSearch Service domain. Domain names are unique across the domains owned by an account within an Amazon Web Services Region.
dict
Response Syntax
{
'DomainArn': 'string',
'Role': 'PRIMARY'|'SECONDARY',
'Peers': [
{
'PeerDomainArn': 'string',
'PeerRole': 'PRIMARY'|'SECONDARY',
'Status': 'PENDING_SETUP'|'ACTIVE'|'SWITCHING_OVER'|'FAILING_OVER'|'PENDING_REMOVAL'|'DETACHED'|'EJECTED'|'FAILED',
'StatusMessage': 'string'
},
]
}
Response Structure
(dict) --
DomainArn (string) --
The Amazon Resource Name (ARN) of the domain described.
Role (string) --
The domain's role in the arrangement, either PRIMARY or SECONDARY. Absent when the domain is not replicating.
Peers (list) --
The domains that this domain replicates with. Each entry carries the state of that one relationship. Empty when the domain is not replicating.
(dict) --
A domain that another domain replicates with, and the state of that relationship.
PeerDomainArn (string) --
The Amazon Resource Name (ARN) of the peer domain.
PeerRole (string) --
The peer's role in the relationship, either PRIMARY or SECONDARY.
Status (string) --
The state of the relationship:
PENDING_SETUP - replication is being established.
ACTIVE - replication is running.
SWITCHING_OVER - a planned promotion is in progress.
FAILING_OVER - an unplanned promotion is in progress.
PENDING_REMOVAL - replication is being stopped.
DETACHED - the relationship has ended.
EJECTED - a failover promoted the other domain. The former primary keeps the data it had when it was ejected and stays read-only until you remove the peer, or discard that data and pair again.
FAILED - setup or teardown could not complete. You can still remove the relationship.
A relationship that is removed successfully no longer appears in Peers.
StatusMessage (string) --
An explanation of why the relationship is in its current state, when more detail is available.