Garantizar la idempotencia en las solicitudes de Amazon EC2 API

Cuando realizas una solicitud mutante, la API solicitud normalmente devuelve un resultado antes de que se completen los flujos de trabajo asíncronos de la operación. También es posible que se agote el tiempo de espera de las operaciones o que surjan otros problemas con el servidor antes de que finalicen, aunque la solicitud ya haya devuelto un resultado. Esto podría dificultar la determinación de si la solicitud se ha realizado correctamente o no, y podría dar lugar a múltiples reintentos para garantizar que la operación se completa correctamente. No obstante, si la solicitud original y los reintentos posteriores se realizan correctamente, la operación se completa varias veces. Esto significa que puede crear más recursos de los que pretendía.

La idempotencia garantiza que una API solicitud no se complete más de una vez. Con una solicitud idempotente, si la solicitud original se completa correctamente, cualquier reintento posterior también se completa correctamente sin realizar ninguna otra acción. Sin embargo, el resultado puede contener información actualizada, como el estado de creación actual.

Idempotencia en Amazon EC2

Las siguientes API acciones son idempotentes por defecto y no requieren configuración adicional. Los AWS CLI comandos correspondientes también admiten la idempotencia de forma predeterminada.

Idempotente por defecto

• AssociateAddress

• CreateVpnConnection

• DisassociateAddress

• ReplaceNetworkAclAssociation

• TerminateInstances

Las siguientes API acciones admiten opcionalmente la idempotencia mediante un token de cliente. Los AWS CLI comandos correspondientes también admiten la idempotencia mediante un token de cliente. Un token de cliente es una cadena única de hasta 64 caracteres que distingue entre mayúsculas y minúsculas. ASCII Para realizar una API solicitud idempotente mediante una de estas acciones, especifique un token de cliente en la solicitud. No debes reutilizar el mismo token de cliente para otras API solicitudes. Si reintentas una solicitud que se completó correctamente con el mismo token de cliente y los mismos parámetros, el reintento se realizará correctamente sin realizar ninguna otra acción. Si reintentas realizar una solicitud correctamente con el mismo token de cliente, pero uno o varios de los parámetros son diferentes, distintos de la región o la zona de disponibilidad, el reintento fallará y se producirá un error. IdempotentParameterMismatch

Idempotente con un token de cliente

• 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

Tipos de idempotencia

• Regional: las solicitudes son idempotentes en cada región. Sin embargo, puedes usar la misma solicitud, incluido el mismo token de cliente, en una región diferente.

• Zonal: las solicitudes son idempotentes en cada zona de disponibilidad de una región. Por ejemplo, si especificas el mismo token de cliente en dos llamadas a AllocateHosts la misma región, las llamadas se realizarán correctamente si especifican valores diferentes para el parámetro. AvailabilityZone

RunInstances idempotencia

La RunInstancesAPIacción utiliza la idempotencia regional y zonal.

El tipo de idempotencia que se utilice depende de cómo se especifique la zona de disponibilidad en la solicitud. RunInstances API La solicitud utiliza la idempotencia zonal en los siguientes casos:

• Si especifica explícitamente una zona de disponibilidad mediante el AvailabilityZoneparámetro del tipo de datos de ubicación

• Si especifica implícitamente una zona de disponibilidad mediante el parámetro SubnetId

Si no especifica una zona de disponibilidad de forma explícita o implícita, la solicitud utiliza la idempotencia regional.

Idempotencia zonal

La idempotencia zonal garantiza que una RunInstances API solicitud sea idempotente en cada zona de disponibilidad de una región. Esto garantiza que una solicitud con el mismo token de cliente solo se pueda completar una vez dentro de cada zona de disponibilidad de una región. Sin embargo, el mismo token de cliente se puede usar para lanzar instancias en otras zonas de disponibilidad de la región.

Por ejemplo, si envías una solicitud idempotente para lanzar una instancia en la zona de us-east-1a disponibilidad y, a continuación, utilizas el mismo token de cliente en una solicitud en la zona de us-east-1b disponibilidad, lanzamos instancias en cada una de esas zonas de disponibilidad. Si uno o más de los parámetros son diferentes, los reintentos posteriores con el mismo token de cliente en esas zonas de disponibilidad se devuelven correctamente sin realizar ninguna otra acción o se produce un error. IdempotentParameterMismatch

Idempotencia regional

La idempotencia regional garantiza que una RunInstances API solicitud sea idempotente en una región. Esto garantiza que una solicitud con el mismo token de cliente solo se pueda completar una vez dentro de una región. Sin embargo, se puede usar exactamente la misma solicitud, con el mismo token de cliente, para lanzar instancias en una región diferente.

Por ejemplo, si envías una solicitud idempotente para lanzar una instancia en la us-east-1 región y, a continuación, utilizas el mismo token de cliente en una solicitud en la eu-west-1 región, lanzamos instancias en cada una de esas regiones. Si uno o más de los parámetros son diferentes, los reintentos posteriores con el mismo token de cliente en esas regiones se devuelven correctamente sin realizar ninguna otra acción o fallan y se produce un error. IdempotentParameterMismatch

sugerencia

Si una de las zonas de disponibilidad de la región solicitada no está disponible, RunInstances las solicitudes que utilizan la idempotencia regional podrían fallar. Para aprovechar las funciones de las zonas de disponibilidad que ofrece la AWS infraestructura, le recomendamos que utilice la idempotencia zonal al lanzar las instancias. RunInstances las solicitudes que utilizan la idempotencia zonal y se dirigen a una zona de disponibilidad disponible se aceptan aunque no haya otra zona de disponibilidad disponible en la región solicitada.

Ejemplos

AWS CLI ejemplos de comandos

Para hacer que un AWS CLI comando sea idempotente, añada la --client-token opción.

Ejemplo 1: Idempotencia

El siguiente comando allocate-hosts utiliza la idempotencia, ya que incluye un token de cliente.

aws ec2 allocate-hosts  --instance-type m5.large  --availability-zone eu-west-1a  --auto-placement on  --quantity 1 --client-token 550e8400-e29b-41d4-a716-446655440000

Ejemplo 2: idempotencia regional de run-instances

El siguiente comando run-instances usa la idempotencia regional, ya que incluye un token de cliente, pero no especifica explícita o implícitamente una zona de disponibilidad.

aws ec2 run-instances --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

Ejemplo 3: idempotencia zonal de run-instances

El siguiente comando run-instances usa la idempotencia zonal, ya que incluye un token de cliente y una zona de disponibilidad especificada explícitamente.

aws ec2 run-instances  --placement "AvailabilityZone=us-east-1a" --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

APIejemplos de solicitudes

Para hacer que una API solicitud sea idempotente, añada el ClientToken parámetro.

Ejemplo 1: Idempotencia

La siguiente AllocateHostsAPIsolicitud utiliza la idempotencia, ya que incluye un token de cliente.

https://ec2.amazonaws.com/?Action=AllocateHosts
&AvailabilityZone=us-east-1b
&InstanceType=m5.large
&Quantity=1
&AutoPlacement=off
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Ejemplo 2: idempotencia regional RunInstances

La siguiente RunInstancesAPIsolicitud utiliza la idempotencia regional, ya que incluye un token de cliente, pero no especifica explícita o implícitamente una zona de disponibilidad.

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Ejemplo 3: idempotencia zonal RunInstances

La siguiente RunInstancesAPIsolicitud utiliza la idempotencia zonal, ya que incluye un token de cliente y una zona de disponibilidad especificada de forma explícita.

https://ec2.amazonaws.com/?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

Vuelva a intentar las recomendaciones para las solicitudes idempotentes

En la siguiente tabla se muestran algunas de las respuestas habituales que se pueden obtener para las API solicitudes idempotentes y se proporcionan recomendaciones para volver a intentarlo.

Respuesta	Recomendación	Comentarios
200 (OK)	No reintentar	La solicitud original se ha completado correctamente. Cualquier reintento posterior se devuelve correctamente.
Códigos de respuesta de la serie 400 (errores del cliente)	No reintentar	Hay un problema con la solicitud, uno de los siguientes: Incluye un parámetro o una combinación de parámetros que no es válida. Utiliza una acción o un recurso para el que no tiene permisos. Utiliza un recurso que está en proceso de cambiar de estado. Si la solicitud implica un recurso que está en proceso de cambiar de estado, el reintento de la solicitud podría realizarse correctamente.
Códigos de respuesta de la serie 500 (errores del servidor)	Reintentar	El error se debe a un problema AWS del servidor y, por lo general, es transitorio. Repita la solicitud con una estrategia de retardo adecuada.