멱등성 보장

변형 작업을 수행할 때 제한 시간이나 리소스 변형 후 서버 문제로 인해 예외가 발생할 수 있습니다. 이로 인해 변형이 발생했는지 여부를 판단하기 어려워지고 여러 번 재시도해야 할 수도 있습니다. 그러나 원래 작업과 후속 재시도에서 실제로 변형이 이루어진 경우 스택 변경 사항을 적용했거나 의도한 것보다 더 많은 리소스를 생성했을 수 있습니다. 멱등성은 작업에 의해 리소스가 한 번 이상 변형되지 않도록 합니다. 멱등성 요청을 사용하면 원래 요청이 성공적으로 변경된 경우 후속 재시도가 추가적인 변경 작업 없이 성공적으로 완료됩니다.

Amazon ECS의 멱등성

다음 API 작업은 필요에 따라 클라이언트 토큰을 사용하여 멱등성을 지원합니다. 해당하는 AWS CLI 명령 또한 클라이언트 토큰을 사용하여 멱등성을 지원합니다. 클라이언트 토큰은 대소문자를 구분하는 고유한 문자열입니다. 이러한 작업 중 하나를 사용하여 멱등적인 API 요청을 수행하려면 요청에 클라이언트 토큰을 지정하면 됩니다. 동일한 클라이언트 토큰을 다른 API 요청에 재사용해서는 안 됩니다. 동일한 클라이언트 토큰과 동일한 파라미터를 사용하여 성공적으로 완료된 요청을 재시도하면 추가 작업을 수행하지 않고 재시도가 성공합니다.

RunTask의 멱등성

RunTask API는 클라이언트 토큰을 사용하여 멱등성을 지원합니다. 클라이언트 토큰은 API 요청을 할 때 지정하는 고유 문자열입니다. 요청이 성공적으로 완료된 후 동일한 클라이언트 토큰과 동일한 요청 파라미터를 사용하여 API 요청을 다시 시도하면 원래 요청의 결과가 반환됩니다. 동일한 클라이언트 토큰을 사용하여 성공적인 요청을 재시도하는데, 리전 또는 가용 영역 외에 다른 파라미터 중 하나 이상이 다르면 ConflictException과 함께 재시도가 실패합니다. 고유 클라이언트 토큰을 지정하지 않으면 AWS SDK와 AWS Command Line Interface가 멱등성을 위해 요청에 대한 클라이언트 토큰을 자동으로 생성합니다. 클라이언트 토큰은 33~126(포함) 범위의 최대 64자의 ASCII 문자를 포함하는 모든 문자열일 수 있습니다.

RunTask 클라이언트 토큰의 유효 기간(TTL)은 24시간입니다. 서로 다른 요청에 동일한 클라이언트 토큰을 재사용해서는 안 됩니다. 클라이언트 토큰 최대 TTL은 다음 두 값 중 더 작은 값 동안 유효합니다.

RunTask 재시도 규칙 및 응답

5xx 예외가 발생하여 요청을 재시도하면 재시도된 성공 응답에는 일반적으로 원래 요청이 반환했을 모든 정보가 포함됩니다. 중단된 지 1시간 미만인 태스크에는 태스크 ARN, 최종 상태 및 원하는 상태만 포함됩니다.

다음은 실행 중인 태스크 1개, 중지된 태스크 1개, 시작에 실패한 태스크 1개가 있는 경우 재시도 시 반환되는 응답의 예제 스니펫입니다.

{
  "failures": [
    {
      "arn": "arn:aws:ecs:us-east-1:123456789012:container/4df26bb4-f057-467b-a079-961675296e64",
      "reason": "RESOURCE:MEMORY"
    }
  ],
  "tasks": [
    {
      "desiredStatus": "RUNNING",
      "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d816e7fb",
      ...
    },
    {
      "taskArn": "arn:aws:ecs:us-east-1:123456789012:task/default/fdf2c302-468c-4e55-b884-5331d819999",
      "lastStatus": "STOPPED",
      ...
     }
  ]
}

1시간이 지난 실패에는 실패한 태스크 수만 포함됩니다.

예제

AWS CLI 명령 예제

AWS CLI 명령을 멱등적으로 만들려면 --client-token 옵션을 추가합니다.

예제: create-service

다음 create-service 명령은 클라이언트 토큰을 포함하므로 멱등성을 사용합니다.

aws ecs create-service \
    --cluster MyCluster \
    --service MyService \
    --task-definition MyTaskDefinition:2 \
    --desired-count 2 \
    --launch-type FARGATE \
    --platform-version LATEST \
    --network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"],assignPublicIp="ENABLED"}" \
    --client-token 550e8400-e29b-41d4-a716-44665544

예: create-task-set

다음 create-task-set 명령은 클라이언트 토큰을 포함하므로 멱등성을 사용합니다.

aws ecs create-task-set \
    --cluster MyCluster \
    --service MyService \
    --task-definition MyTaskDefinition:2 \
    --network-configuration "awsvpcConfiguration={subnets=["subnet-12344321"],securityGroups=["sg-12344321"]}" \
    --client-token 550e8400-e29b-41d4-a716-44665544

예제: run-task

다음 run-task 명령은 클라이언트 토큰을 포함하므로 멱등성을 사용합니다.

aws ecs run-task \
    --cluster MyCluster \
    --task-definition MyTaskDefinition:2 \
    --client-token 550e8400-e29b-41d4-a716-446655440000

API 요청 예제

API 요청을 멱등적으로 만들려면 clientToken 파라미터를 추가합니다.

예: CreateService

다음 CreateService API 요청은 클라이언트 토큰을 포함하므로 멱등성을 사용합니다.

POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateService
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
  "serviceName": "MyService",
  "taskDefinition": "MyTaskDefinition:2",
  "desiredCount": 10,
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE",
         "weight": 1
      }
   ],
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE_SPOT",
         "weight": 1
      }
   ],
   "clientToken": "550e8400-e29b-41d4-a716-44665544"
}

예: CreateTaskSet

다음 CreateTaskSet API 요청은 클라이언트 토큰을 포함하므로 멱등성을 사용합니다.

POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 87
X-Amz-Target: AmazonEC2ContainerServiceV20141113.CreateTaskSet
X-Amz-Date: 20150429T170125Z
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
  "serviceName": "MyService",
  "taskDefinition": "mytask:1",
  "desiredCount": 1,
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE",
         "weight": 1
      }
   ],
   "capacityProviderStrategy": [ 
      { 
         "base": "number",
         "capacityProvider": "FARGATE_SPOT",
         "weight": 1
      }
   ],
    "clientToken": "550e8400-e29b-41d4-a716-44665544" 
}

예: RunTask

다음 RunTask API 요청은 클라이언트 토큰을 포함하므로 멱등성을 사용합니다.

POST / HTTP/1.1
Host: ecs.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 45
X-Amz-Target: AmazonEC2ContainerServiceV20141113.RunTask
X-Amz-Date: 20161121T215740Z
User-Agent: aws-cli/1.11.13 Python/2.7.12 Darwin/16.1.0 botocore/1.4.66
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS

{
  "count": 1,
  "taskDefinition": "mytask:1",
  "clientToken": "550e8400-e29b-41d4-a716-446655440000" 
}

멱등적인 요청에 대한 재시도 권장 사항

다음 테이블은 멱등성 API 요청에 대해 얻을 수 있는 몇 가지 일반적인 응답을 보여주고 재시도 권장 사항을 제공합니다.