Ensuring idempotency in Amazon EC2 API requests

Cuando realiza una solicitud de API de mutación, la solicitud suele devolver un resultado antes de que se hayan completado 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 podría crear más recursos de los previstos.

La idempotencia garantiza que una solicitud a la API 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 podría contener información actualizada, como el estado de creación actual.

Idempotencia en Amazon EC2

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

Las siguientes acciones de la API admiten opcionalmente idempotencia mediante un token de cliente. Los comandos AWS CLI correspondientes también admiten idempotencia usando un token de cliente. Un token de cliente es una cadena única que distingue entre mayúsculas y minúsculas de hasta 64 caracteres ASCII. Para realizar una solicitud de API idempotente mediante una de estas acciones, especifique un token de cliente en la solicitud. No debe reutilizar el mismo token de cliente para diferentes solicitudes de API. Si reintenta 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 vuelve a intentar una solicitud correcta usando el mismo token de cliente, pero uno o más de los parámetros son diferentes, excepto la región o la zona de disponibilidad, el reintento falla y se produce un error IdempotentParameterMismatch.

Idempotencia de RunInstances

La acción de la API RunInstances utiliza idempotencia regional y zonal.

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

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

Idempotencia zonal

La idempotencia zonal garantiza que una solicitud de la API RunInstances 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 en 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ía una solicitud idempotente para lanzar una instancia en la zona de disponibilidad us-east-1a y, a continuación, utiliza el mismo token de cliente en una solicitud en la zona de disponibilidad us-east-1b, 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 solicitud de la API RunInstances sea idempotente en una región. Esto garantiza que una solicitud con el mismo token de cliente solo se pueda completar una vez en 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ía una solicitud idempotente para lanzar una instancia en la región us-east-1 y, a continuación, utiliza el mismo token de cliente en una solicitud en la región eu-west-1, 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 se produce un error IdempotentParameterMismatch.

Ejemplos

Ejemplos de comando de AWS CLI

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

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 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 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

Ejemplos de solicitud de la API

Para hacer que una solicitud de la API sea idempotente, agrega el parámetro ClientToken.

Ejemplo 1: idempotencia

La siguiente API AllocateHosts utiliza 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 de RunInstances

La siguiente API RunInstances usa 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 de RunInstances

La siguiente API RunInstances usa idempotencia zonal, ya que incluye un token de cliente y una zona de disponibilidad especificada explícitamente.

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 solicitudes idempotentes

En la siguiente tabla se muestran algunas respuestas comunes que puede obtener para solicitudes de API idempotentes y se ofrecen recomendaciones de reintento.