AWS re:Post Knowledge Center Feedback Survey

Help us improve the AWS re:Post Knowledge Center by sharing your feedback in a brief survey. Your input can influence how we create and update our content to better support your AWS journey.

如何針對將環境變數傳遞到 Amazon ECS 任務時出現的問題進行疑難排解？

3 分的閱讀內容

我想要針對將環境變數傳遞到 Amazon Elastic Container Service (Amazon ECS) 任務時出現的問題進行疑難排解。

簡短說明

當您在任務中傳遞環境變數或敏感資料時，根據您的組態，您可能會收到下列其中一個錯誤。

AWS Secrets Manager

「ResourceInitializationError 錯誤」或「Amazon Elastic Compute Cloud (Amazon EC2) 上的 AccessDenied 錯誤」。

若要解決這些問題，請參閱如何對 Amazon ECS 中的 AWS Secrets Manager 祕密相關問題進行疑難排解？

Amazon Elastic Block Store (Amazon EBS) 磁碟區或 Sidecar

「ECS 無法擔任設定的 ECS 基礎架構角色 'arn:aws:iam::111122223333:role/ecsInfrastructureRole'。請確認正在傳遞的角色與 Amazon ECS 是否具有正確的信任關係」或「在將 EBS 磁碟區附件設定到任務時，ECS 逾時」。

若要解決這些問題，請參閱 Amazon EBS 磁碟區附加到 Amazon ECS 任務的狀態原因。

Amazon Simple Storage Service (Amazon S3)

「ResourceInitializationError：無法下載 env 檔案：檔案下載命令：非空白錯誤串流」。

若要解決此問題，請完成以下解決步驟。

Parameter Store，AWS Systems Manager 的一項功能

「從區域中的 SSM Parameter Store 中擷取祕密資料： AccessDeniedException: 使用者：arn:aws:sts::123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 未被授權對資源：arn:aws:ssm:ap-south-1:12345678:parameter/status code:400 執行：ssm:GetParameters，請求 ID：e46b40ee-0a38-46da-aedd-05f23a41e861」。或者，「ResourceInitializationError：無法提取祕密或登錄檔驗證：執行資源檢索失敗：無法從 ssm 檢索祕密：服務呼叫已重試 5 次： RequestCanceled」。

若要解決這些問題，請完成以下解決步驟。

注意： 安全最佳做法是將敏感資料儲存在 Secrets Manager 祕密或 Parameter Store 參數中。

解決方法

注意： 如果您在執行 AWS Command Line Interface (AWS CLI) 命令時收到錯誤訊息，則請參閱對 AWS CLI 進行錯誤疑難排解。此外，請確定您使用的是最新的 AWS CLI 版本。

確定問題的原因

在 Amazon ECS 叢集資源所在的相同 AWS 區域中使用 AWSSupport-TroubleshootECSTaskFailedToStart 執行手冊。另外，請使用最近失敗的任務 ID。如果失敗的任務屬於 Amazon ECS 服務，請在服務中使用最近失敗的任務。失敗的任務必須在 ECS:DescribeTasks 自動化過程中顯示。預設情況下，已停止的 ECS 任務在進入已停止狀態後會在 1 小時內顯示。

根據自動化的輸出，使用下列其中一個手動進行疑難排解步驟。

您的 Amazon ECS 任務執行角色沒有 IAM 所需的權限

如果您在 Parameter Store 或 Secrets Manager 中使用環境變數，請查看以下 API 呼叫的 AWS CloudTrail 事件：

適用於 Parameter Store 的 GetParameters
適用於 Secrets Manager 的 GetSecretValue

如果您收到任務執行角色的 AccessDenied 錯誤，則必須手動將所需的權限作為內嵌政策新增至該角色。您也可以建立新增至 Amazon ECS 任務執行角色的自訂受管政策。

如果您使用 S3 儲存貯體將環境變數儲存為 .env 檔案，請將 Amazon S3 所需的權限新增至任務執行角色。

您的網路組態有問題

如果您的任務位於私有子網路中，請確認下列組態：

任務或服務的安全群組允許連接埠 443 上的傳出流量。
如果您使用 NAT 閘道，則您的任務必須具有到 NAT 閘道的預設路由。
您的任務使用 Secrets Manager 、 Parameter Store 或 Amazon S3 所需的虛擬私有雲端 (VPC) 端點。

使用 telnet 命令確認與 Systems Manager、Secrets Manager 或 Amazon S3 端點的連線。

另外，請確認以下 VPC 端點組態：

VPC 端點的安全群組允許來自連接埠 443 上的任務或服務的傳出流量。
網路存取控制清單 (網路 ACL) 允許連接埠 443 上的傳出流量。
您將 VPC 端點與正確的 VPC 關聯。
您啟動了 DNS 主機名稱和 DNS 解析 VPC 屬性。

如果您的 Amazon ECS 任務位於公有子網路中，請確認以下組態：

您為該任務啟動了公有 IP 位址。
您的 VPC 的安全群組允許透過連接埠 443 傳出存取網際網路。
網路 ACL 允許子網路和網際網路之間的所有傳入和傳出流量。

您的應用程式無法讀取環境變數

若要檢查任務容器中是否填入了正確的環境變數，請使用 ECS Exec 列出容器中的所有環境變數。啟動 ECS Exec，然後執行以下命令來與容器互動：

aws ecs execute-command --cluster cluster-name \
    --task task-id \
    --container container-name \
    --interactive \
    --command "/bin/sh"

注意： 將 cluster-name 替換為您的叢集名稱，將 task-id 替換為您的任務 ID，將 container-name 替換為您的容器執行個體名稱。

輸出範例：

The Session Manager plugin was installed successfully. Use the AWS CLI to start a session.


Starting session with SessionId: ecs-execute-command-hlei32fctyur2bn63rhe2uraaq
sh-5.2#

然後，執行 env 命令以列出所有環境變數：

sh-5.2# env

輸出範例：

sh-5.2# env
AWS_EXECUTION_ENV=AWS_ECS_FARGATE
AWS_DEFAULT_REGION=us-east-1
AWS_REGION=us-east-1
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
_=/usr/bin/env

如果您使用 Amazon EC2 啟動類型，那麼也可以使用 Docker exec 命令來與容器互動。若要使用 Docker 執行程式，請完成下列步驟：

連線到執行任務的容器執行個體。
執行以下 Docker 命令來尋找容器 ID：
```
docker container ps
```
若要開啟容器，請執行以下 Docker 命令：
```
docker exec -it example-container-id bash
```
注意： 將 example-container-id 替換為您的容器 ID。另外，根據容器的預設 shell 選擇 shell。
在容器上執行 env 命令以列出所有環境變數。

確保您在任務定義或 .env 檔案中定義的環境變數位於變數清單中。

容器定義中的變數格式不正確

在容器定義中定義環境變數時，必須將環境變數定義為鍵值組物件：

"environment": [
    {
        "name": "variable",    
        "value": "value"
    }
]

在 .env 檔案中定義環境變數時，也必須使用此格式。

任務不會自動重新整理環境變數

此任務不會自動重新整理您在 .env 檔案或祕密中更新的執行容器中的環境變數。

若要將更新的環境變數新增至容器執行個體，請執行下列 update-service 命令：

aws ecs update-service --cluster example-cluster --service example-service --force-new-deployment

**注意：**將 example-cluster 替換為您的叢集名稱，將 example-service 替換為您的服務名稱。

如果您在容器定義中使用環境變數，則必須建立新的任務定義來更新環境變數。然後，執行以下 update-service 命令，以使用新任務定義建立新任務或更新您的 Amazon ECS 服務：

aws ecs update-service --cluster example-cluster --service example-service --task-definition family:revision

**注意：**將 example-cluster 替換為您的叢集名稱，將 example-service 替換為您的服務名稱，將 family:revision 替換為您的新任務定義。

當您將環境變數傳遞給任務時，Amazon ECS 會使用以下組態：

在容器定義中使用環境參數的環境變數，其優先順序會高於環境文件中的變數。
如果您指定多個環境檔案，且這些檔案使用相同的變數，則檔案將按照項目的順序進行處理。Amazon ECS 會使用變數的第一個值，並忽略重複變數的後續值。最佳做法是使用唯一的變數名稱。
如果您指定環境檔案作為容器覆寫，則 Amazon ECS 將使用該檔案，並忽略容器定義中的其他環境檔案。
容器中的 PID 1 程序可以從 /proc/1/environ 檔案取得環境變數。如果容器執行多個程序或 init 程序 (例如包裝函式指令碼或 supervisord)，則環境變數無法供非 PID 1 程序使用。