Amazon ECS タスクに環境変数を渡す際の問題をトラブルシューティングする方法を教えてください。

簡単な説明

タスク内で環境変数または機密データを渡す際、設定に応じて、次のいずれかのエラーが表示される場合があります。

AWS Secrets Manager

ResourceInitializationError error または AccessDenied error on Amazon Elastic Compute Cloud (Amazon EC2)

これらの問題を解決するには、「Amazon ECS で発生する、AWS Secrets Manager のシークレットに関連する問題のトラブルシューティング方法を教えてください」を参照してください。

Amazon Elastic Block Store (Amazon EBS) ボリュームまたはサイドカー

ECS was unable to assume the configured ECS Infrastructure Role 'arn:aws:iam::111122223333:role/ecsInfrastructureRole'.Please verify that the role being passed has the proper trust relationship with Amazon ECS (ECS は、設定した ECS インフラストラクチャロールを引き受けられませんでした。渡すロールに Amazon ECS との正しい信頼関係があることを確認してください) または ECS timed out while configuring the EBS volume attachment to your Task (タスクに対して EBS ボリュームアタッチメントを設定中、ECS がタイムアウトしました)

これらの問題を解決するには、「Amazon ECS タスクに Amazon EBS ボリュームをアタッチする際の、ステータスに関する理由」を参照してください。

Amazon Simple Storage Service (Amazon S3)

ResourceInitializationError: failed to download env files: file download command: non empty error stream

この問題を解決するには、次の解決手順を実行します。

Parameter Store (AWS Systems Manager の機能)

Fetching secret data from SSM Parameter Store in region: AccessDeniedException: User: arn:aws:sts::123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 is not authorized to perform: ssm:GetParameters on resource: arn:aws:ssm:ap-south-1:12345678:parameter/status code: 400, request id: e46b40ee-0a38-46da-aedd-05f23a41e861または、ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed: unable to retrieve secret from asm: service call has been retried. (ResourceInitializationError: シークレットまたはレジストリ認証を取得できません: 実行リソースを取得できません: ssm からシークレットを取得できません: サービス呼び出しが 5 回再試行されました) RequestCanceled

これらの問題を解決するには、次の解決手順を実行します。

注: セキュリティ上、機密データは Secrets Manager のシークレットまたは Parameter Store のパラメータに保存することをおすすめします。

解決策

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI で発生したエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

問題の原因を特定する

Amazon ECS クラスターのリソースが配置されたリージョンと同じ AWS リージョンで、AWSSupport-TroubleshootECSTaskFailedToStart ランブックを使用します。なお、最後に失敗したタスクの ID を使用してください。失敗したタスクが Amazon ECS サービスに属している場合は、そのサービス内で最後に失敗したタスクを使用します。失敗したタスクは、オートメーション中に ECS:DescribeTasks で確認できる必要があります。デフォルトでは、停止した ECS タスクは Stopped 状態になってから 1 時間表示されます。

オートメーションの出力に応じて、次の手動トラブルシューティング手順のいずれかを実行します。

Amazon ECS タスク実行ロールに、必要な IAM アクセス許可がない

Parameter Store または Secrets Manage 内で環境変数を使用している場合は、次の 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 exec を使用するには、次の手順を実行します。

1. タスクが実行されているコンテナインスタンスに接続します。

2. 次の Docker コマンドを実行してコンテナ ID を特定します。

   docker container ps

3. コンテナを開くには、次の Docker コマンドを実行します。

   docker exec -it example-container-id bash

   注: example-container-id は、実際のコンテナ ID に置き換えます。さらに、お使いのコンテナのデフォルトシェルに応じてシェルを選択します。

4. コンテナで 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 は次の設定を使用します。

• コンテナ定義内の environment パラメータを使用する環境変数は、環境ファイル内の変数よりも優先されます。
• 複数の環境ファイルを指定しており、同じ変数を使用している場合は、ファイルは入力順に処理されます。Amazon ECS は変数の最初の値を使用し、重複する変数については、後続の値を無視します。一意の変数名を使用することをおすすめします。
• 環境ファイルをコンテナオーバーライドとして指定した場合、Amazon ECS はそのファイルを使用し、コンテナ定義内の他の環境ファイルを無視します。
• /proc/1/environ ファイルの環境変数は、コンテナ内の PID 1 プロセスに使用できます。コンテナが複数のプロセスまたは初期化プロセス (ラッパースクリプト、supervisord など) を実行する場合、PID 1 以外のプロセスでは環境変数を使用できません。

関連情報

Amazon ECS コンテナに機密データを渡す