# Amazon ECS task scale-in protection 엔드포인트
<a name="task-scale-in-protection-endpoint"></a>

Amazon ECS 컨테이너 에이전트는 Amazon ECS 작업의 컨테이너에 `ECS_AGENT_URI` 환경 변수를 자동으로 주입하여 컨테이너 에이전트 API 엔드포인트와 상호 작용하는 방법을 제공합니다.

보호 필요성을 스스로 결정할 수 있는 작업에는 Amazon ECS 컨테이너 에이전트 엔드포인트를 사용하는 것이 좋습니다.

컨테이너가 작업 처리를 시작하면 컨테이너 내에서 Task scale-in protection 엔드포인트 경로 `$ECS_AGENT_URI/task-protection/v1/state`를 통해 `protectionEnabled` 속성을 설정할 수 있습니다.

컨테이너 내에서 이 URI에 대한 PUT 요청은 Task scale-in protection을 설정합니다. 이 URI에 대한 GET 요청은 작업의 현재 보호 상태를 반환합니다.

## Task scale-in protection 요청 파라미터
<a name="task-scale-in-protection-request"></a>

다음 요청 파라미터와 함께 `${ECS_AGENT_URI}/task-protection/v1/state` 엔드포인트를 사용하여 Task scale-in protection을 설정할 수 있습니다.

`ProtectionEnabled`  
작업을 보호 대상으로 표시하려면 `true`를 지정합니다. 보호를 제거하고 작업을 종료할 수 있도록 표시하려면 `false`를 지정합니다.  
유형: Boolean  
필수 여부: 예

`ExpiresInMinutes`  
작업이 보호되는 시간(분)입니다. 최소 1분에서 최대 2,880분(48시간)까지 지정할 수 있습니다. 이 기간 동안에는 서비스 Auto Scaling 또는 배포의 스케일 인 이벤트로 인해 작업이 종료되지 않습니다. 이 기간이 경과하면 `protectionEnabled` 파라미터가 `false`로 설정됩니다.  
시간을 지정하지 않으면 작업이 120분(2시간) 동안 자동으로 보호됩니다.  
유형: 정수  
필수 여부: 아니요

다음은 각기 다른 기간으로 작업 보호를 설정하는 예입니다.

**기본 기간에 작업을 보호하는 방법 예제**

이 예제에서는 기본 시간인 2시간으로 작업을 보호하는 방법을 보여줍니다.

```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true}'
```

**60분간 작업을 보호하는 방법 예제**

이 예제에서는 `expiresInMinutes` 파라미터를 사용하여 60분 동안 작업을 보호하는 방법을 보여줍니다.

```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":60}'      
```

**24시간 동안 작업을 보호하는 방법 예제**

이 예제에서는 `expiresInMinutes` 파라미터를 사용하여 24시간 동안 작업을 보호하는 방법을 보여줍니다.

```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":1440}'      
```

**Windows 컨테이너에 대한 예제**

Windows 컨테이너의 경우 curl 대신 PowerShell의 `Invoke-RestMethod` cmdlet을 사용할 수 있습니다. 다음 예제에서는 이전 curl 명령과 동일한 PowerShell을 보여줍니다.

**기본 기간에 Windows 컨테이너 태스크를 보호하는 방법 예제**

이 예제에서는 기본 2시간 동안 태스크를 보호하는 방법을 보여줍니다.

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true}' -ContentType 'application/json'
```

**60분간 Windows 컨테이너 태스크를 보호하는 방법 예제**

이 예제에서는 PowerShell에서 `expiresInMinutes` 파라미터를 사용하여 60분 동안 태스크를 보호하는 방법을 보여줍니다.

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true,"ExpiresInMinutes":60}' -ContentType 'application/json'
```

**24시간 동안 Windows 컨테이너 태스크를 보호하는 방법 예제**

이 예제에서는 PowerShell에서 `expiresInMinutes` 파라미터를 사용하여 24시간 동안 태스크를 보호하는 방법을 보여줍니다.

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true,"ExpiresInMinutes":1440}' -ContentType 'application/json'
```

PUT 요청은 다음과 같은 응답을 반환합니다.

```
{
  "protection": {
    "ExpirationDate": "2023-12-20T21:57:44.837Z",
    "ProtectionEnabled": true,
    "TaskArn": "arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
  }
}
```

## Task scale-in protection 응답 파라미터
<a name="task-scale-in-protection-response"></a>

다음 정보가 Task scale-in protection 엔드포인트(`${ECS_AGENT_URI}/task-protection/v1/state`)에서 JSON 응답으로 반환됩니다.

`ExpirationDate`  
작업에 대한 보호가 만료되는 Epoch 시간입니다. 작업이 보호되지 않는 경우 이 값은 null입니다.

`ProtectionEnabled`  
작업의 보호 상태입니다. 작업에 대해 축소 보호가 활성화되면 값은 `true`이고, 그렇지 않으면 `false`입니다.

`TaskArn`  
컨테이너가 속한 태스크의 전체 Amazon 리소스 이름(ARN)

다음 예제에서는 보호된 작업에 대해 반환된 세부 정보를 보여줍니다.

```
curl --request GET ${ECS_AGENT_URI}/task-protection/v1/state
```

Windows 컨테이너의 경우 다음 PowerShell 명령을 사용하여 보호 상태를 가져옵니다.

```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Get
```

```
{
    "protection":{
        "ExpirationDate":"2023-12-20T21:57:44Z",
        "ProtectionEnabled":true,
        "TaskArn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
    }
}
```

결함이 발생하면 다음 정보가 반환됩니다.

`Arn`  
작업의 전체 Amazon 리소스 이름(ARN)입니다.

`Detail`  
실패와 관련된 세부 정보입니다.

`Reason`  
실패 이유

다음 예제에서는 보호되지 않는 작업에 대해 반환된 세부 정보를 보여줍니다.

```
{
    "failure":{
        "Arn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0",
        "Detail":null,
        "Reason":"TASK_NOT_VALID"
    }
}
```

예외가 발생하면 다음 정보가 반환됩니다.

`requestID`  
예외를 발생시키는 Amazon ECS API 호출에 대한 AWS 요청 ID입니다.

`Arn`  
작업 또는 서비스의 전체 Amazon 리소스 이름(ARN)입니다.

`Code`  
오류 코드입니다.

`Message`  
오류 메시지입니다.  
`RequestError` 또는 `RequestTimeout` 오류가 표시되면 이는 네트워킹 문제일 수 있습니다. Amazon ECS에 VPC 엔드포인트를 사용해 보세요.

다음 예제에서는 오류 발생 시 반환되는 세부 정보를 보여줍니다.

```
{
    "requestID":"12345-abc-6789-0123-abc",
    "error":{
        "Arn":"arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
        "Code":"AccessDeniedException",
        "Message":"User: arn:aws:sts::444455556666:assumed-role/my-ecs-task-role/1234567890abcdef0 is not authorized to perform: ecs:GetTaskProtection on resource: arn:aws:ecs:us-west-2:555555555555:task/test/1234567890abcdef0 because no identity-based policy allows the ecs:GetTaskProtection action"
    }    
}
```

네트워크 문제 또는 Amazon ECS 컨트롤 플레인 중단과 같은 이유로 Amazon ECS 에이전트가 Amazon ECS 엔드포인트에서 응답을 받을 수 없는 경우 다음 오류가 표시됩니다.

```
{
  "error": {
    "Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
    "Code": "RequestCanceled",
    "Message": "Timed out calling Amazon ECS Task Protection API"
  }
}
```

Amazon ECS 에이전트가 Amazon ECS에서 제한 예외를 받으면 다음 오류가 표시됩니다.

```
{
  "requestID": "12345-abc-6789-0123-abc",
  "error": {
    "Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
    "Code": "ThrottlingException",
    "Message": "Rate exceeded"
  }
}
```