Ensuring idempotency in Amazon EC2 API requests
When you make a mutating API request, the request typically returns a result before the operation's asynchronous workflows have completed. Operations might also time out or encounter other server issues before they complete, even though the request has already returned a result. This could make it difficult to determine whether the request succeeded or not, and could lead to multiple retries to ensure that the operation completes successfully. However, if the original request and the subsequent retries are successful, the operation is completed multiple times. This means that you might create more resources than you intended.
Idempotency ensures that an API request completes no more than one time. With an idempotent request, if the original request completes successfully, any subsequent retries complete successfully without performing any further actions. However, the result might contain updated information, such as the current creation status.
Contents
Idempotency in Amazon EC2
The following API actions are idempotent by default, and do not require additional configuration. The corresponding Amazon CLI commands also support idempotency by default.
Idempotent by default
AssociateAddress
CreateVpnConnection
DisassociateAddress
ReplaceNetworkAclAssociation
TerminateInstances
The following API actions optionally support idempotency using a client
token. The corresponding Amazon CLI commands also support idempotency
using a client token. A client token is a unique, case-sensitive string of up to 64
ASCII characters. To make an idempotent API request using one of these actions,
specify a client token in the request. You should not reuse the same client token
for other API requests. If you retry a request that completed successfully using the
same client token and the same parameters, the retry succeeds without performing any
further actions. If you retry a successful request using the same client token, but
one or more of the parameters are different, other than the Region or Availability
Zone, the retry fails with an IdempotentParameterMismatch
error.
Idempotent using a client token
AllocateHosts
AllocateIpamPoolCidr
AssociateClientVpnTargetNetwork
AssociateIpamResourceDiscovery
AttachVerifiedAccessTrustProvider
AuthorizeClientVpnIngress
CopyFpgaImage
CopyImage
CreateCapacityReservation
CreateCapacityReservationFleet
CreateClientVpnEndpoint
CreateClientVpnRoute
CreateEgressOnlyInternetGateway
CreateFleet
CreateFlowLogs
CreateFpgaImage
CreateInstanceConnectEndpoint
CreateIpam
CreateIpamPool
CreateIpamResourceDiscovery
CreateIpamScope
CreateLaunchTemplate
CreateLaunchTemplateVersion
CreateManagedPrefixList
CreateNatGateway
CreateNetworkAcl
CreateNetworkInsightsAccessScope
CreateNetworkInsightsPath
CreateNetworkInterface
CreateReplaceRootVolumeTask
CreateReservedInstancesListing
CreateRouteTable
CreateTrafficMirrorFilter
CreateTrafficMirrorFilterRule
CreateTrafficMirrorSession
CreateTrafficMirrorTarget
CreateVerifiedAccessEndpoint
CreateVerifiedAccessGroup
CreateVerifiedAccessInstance
CreateVerifiedAccessTrustProvider
CreateVolume
CreateVpcEndpoint
CreateVpcEndpointConnectionNotification
CreateVpcEndpointServiceConfiguration
DeleteVerifiedAccessEndpoint
DeleteVerifiedAccessGroup
DeleteVerifiedAccessInstance
DeleteVerifiedAccessTrustProvider
DetachVerifiedAccessTrustProvider
ExportImage
ImportImage
ImportSnapshot
ModifyInstanceCreditSpecification
ModifyLaunchTemplate
ModifyReservedInstances
ModifyVerifiedAccessEndpoint
ModifyVerifiedAccessEndpointPolicy
ModifyVerifiedAccessGroup
ModifyVerifiedAccessGroupPolicy
ModifyVerifiedAccessInstance
ModifyVerifiedAccessInstanceLoggingConfiguration
ModifyVerifiedAccessTrustProvider
ProvisionIpamPoolCidr
PurchaseHostReservation
RequestSpotFleet
RequestSpotInstances
RunInstances
StartNetworkInsightsAccessScopeAnalysis
StartNetworkInsightsAnalysis
Types of idempotency
-
Regional – Requests are idempotent in each Region. However, you can use the same request, including the same client token, in a different Region.
-
Zonal – Requests are idempotent in each Availability Zone in a Region. For example, if you specify the same client token in two calls to AllocateHosts in the same Region, the calls succeed if they specify different values for the AvailabilityZone parameter.
RunInstances idempotency
The RunInstances API action uses both Regional and zonal idempotency.
The type of idempotency that is used depends on how you specify the Availability Zone in your RunInstances API request. The request uses zonal idempotency in the following cases:
-
If you explicitly specify an Availability Zone using the AvailabilityZone parameter in the Placement data type
-
If you implicitly specify an Availability Zone using the SubnetId parameter
If you do not explicitly or implicitly specify an Availability Zone, the request uses Regional idempotency.
Zonal idempotency
Zonal idempotency ensures that a RunInstances API request is idempotent in each Availability Zone in a Region. This ensures that a request with the same client token can complete only once within each Availability Zone in a Region. However, the same client token can be used to launch instances in other Availability Zones in the Region.
For example, if you send an idempotent request to launch an instance in the
us-east-1a
Availability Zone, and then use the same client
token in a request in the us-east-1b
Availability Zone, we launch
instances in each of those Availability Zones. If one or more of the parameters
are different, subsequent retries with the same client token in those
Availability Zones either return successfully without performing any further
actions or fail with an IdempotentParameterMismatch
error.
Regional idempotency
Regional idempotency ensures that a RunInstances API request is idempotent in a Region. This ensures that a request with the same client token can complete only once within a Region. However, the exact same request, with the same client token, can be used to launch instances in a different Region.
For example, if you send an idempotent request to launch an instance in the
us-east-1
Region, and then use the same client token in a
request in the eu-west-1
Region, we launch instances in each of
those Regions. If one or more of the parameters are different, subsequent
retries with the same client token in those Regions either return successfully
without performing any further actions or fail with an
IdempotentParameterMismatch
error.
Tip
If one of the Availability Zones in the requested Region is not available, RunInstances requests that use regional idempotency could fail. To leverage the Availability Zone features offered by the Amazon infrastructure, we recommend that you use zonal idempotency when launching instances. RunInstances requests that use zonal idempotency and target an available Availability Zone succeed even if another Availability Zone in the requested Region is not available.
Examples
Amazon CLI command examples
To make an Amazon CLI command idempotent, add the --client-token
option.
Example 1: Idempotency
The following allocate-hosts command uses idempotency as it includes a client token.
aws ec2 allocate-hosts --instance-type
m5.large
--availability-zoneeu-west-1a
--auto-placementon
--quantity1
--client-token550e8400-e29b-41d4-a716-446655440000
Example 2: run-instances regional idempotency
The following run-instances command uses regional idempotency as it includes a client token but does not explicitly or implicitly specify an Availability Zone.
aws ec2 run-instances --image-id
ami-b232d0db
--count 1 --key-namemy-key-pair
--client-token550e8400-e29b-41d4-a716-446655440000
Example 3: run-instances zonal idempotency
The following run-instances command uses zonal idempotency as it includes a client token and an explicitly specified Availability Zone.
aws ec2 run-instances --placement "AvailabilityZone=
us-east-1a
" --image-idami-b232d0db
--count 1 --key-namemy-key-pair
--client-token550e8400-e29b-41d4-a716-446655440000
API request examples
To make an API request idempotent, add the ClientToken
parameter.
Example 1: Idempotency
The following AllocateHosts API request uses idempotency as it includes a client token.
https://ec2.amazonaws.com.cn/?Action=AllocateHosts &AvailabilityZone=
us-east-1b
&InstanceType=m5.large
&Quantity=1
&AutoPlacement=off
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS
Example 2: RunInstances regional idempotency
The following RunInstances API request uses regional idempotency as it includes a client token but does not explicitly or implicitly specify an Availability Zone.
https://ec2.amazonaws.com.cn/?Action=RunInstances &ImageId=
ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS
Example 3: RunInstances zonal idempotency
The following RunInstances API request uses zonal idempotency as it includes a client token and an explicitly specified Availability Zone.
https://ec2.amazonaws.com.cn/?Action=RunInstances &Placement.AvailabilityZone=
us-east-1d
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS
Retry recommendations for idempotent requests
The following table shows some common responses that you might get for idempotent API requests, and provides retry recommendations.
Response | Recommendation | Comments |
---|---|---|
200 (OK) |
Do not retry |
The original request completed successfully. Any subsequent retries return successfully. |
400-series response codes (client errors) |
Do not retry |
There is a problem with the request, from among the following:
If the request involves a resource that is in the process of changing states, retrying the request could possibly succeed. |
500-series response codes (server errors) |
Retry |
The error is caused by an Amazon server-side issue and is generally transient. Repeat the request with an appropriate backoff strategy. |