Amazon ECS 任務擴展保護端點

Amazon ECS 容器代理程式會自動將ECS_AGENT_URI環境變數注入 Amazon ECS 任務的容器中，以提供與容器代理程式API端點互動的方法。

我們建議使用 Amazon ECS 容器代理程式端點來執行可自行判斷是否需要受保護的任務。

當容器開始處理工作時，您可以使用容器內的工作縮放保護端點路徑$ECS_AGENT_URI/task-protection/v1/state來設定protectionEnabled屬性。

使用容器內的PUT要求URI來設定工作擴充保護。這個GET要求會URI傳回工作目前的防護狀態。

工作擴充保護要求參數

您可以使用具有下列請求參數的 ${ECS_AGENT_URI}/task-protection/v1/state 端點來設定任務縮減保護。

ProtectionEnabled

指定true此選項可將工作標示為要保護。指定false移除保護，並使工作有資格終止。

類型：布林值

必要：是

ExpiresInMinutes

工作受到保護的分鐘數。您可以指定最短 1 分鐘到最長 2,880 分鐘 (48 小時)。在此期間，您的任務不會因 Service 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}'      

該PUT請求返回以下響應。

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

工作縮放保護回應參數

下列資訊會從回應中的工作擴充保護端點${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

{
    "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 請求識別碼。

Arn

任務或服務的完整 Amazon 資源名稱 (ARN)。

Code

錯誤代碼。

Message

錯誤訊息。

注意

如果出現 RequestError 或 RequestTimeout 錯誤，則可能是聯網問題。嘗試使用 Amazon 的VPC端點ECS。

以下範例顯示了發生錯誤時傳回的詳細資訊。

{
    "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"
  }
}