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

簡単な説明

次のいずれかの方法で、Amazon ECS タスク内に環境変数を渡すことができます。

• 変数を Amazon Simple Storage Service (Amazon S3) バケット内に environmentFiles オブジェクトとして渡す。
• 変数を AWS Systems Manager Parameter Store に保存する。
• 変数を ECS のタスク定義に保存する。
• 変数を AWS Secrets Manager に保存する。

注: 機密データを環境変数として保存する場合、Parameter Store または Secrets Manager を使用するのがセキュリティ上のベストプラクティスです。上記の方法のいずれかで環境変数を渡すと、次のエラーが発生する可能性があります。

Parameter Store

「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 secrets from ssm: service call has been retried 5 time(s): RequestCanceled」

Secrets Manager

「ResourceInitializationError error」

-または-

「AccessDenied error on Amazon Elastic Compute Cloud (Amazon EC2)」

これらのエラーを解決するには、「Amazon ECS の AWS Secrets Manager シークレットに関連する問題のトラブルシューティングを行うにはどうすればよいですか?」を参照してください。

Amazon S3

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

Amazon ECS タスクに環境変数を渡すと、次の理由により問題が発生する可能性があります。

• EC2 タスク実行ロールに、必要な AWS Identity and Access Management (IAM) のアクセス許可がない。
• ネットワーク設定に問題がある。
• アプリケーションが環境変数を読み取れない。
• コンテナ定義の変数の形式が正しくない。
• 環境変数が自動的に更新されない。

Amazon ECS タスクの開始に失敗するエラーをトラブルシューティングするには、AWSSupport-TroubleshootECSTaskFailedToStart ランブックを使用します。その後、問題に該当するトラブルシューティングの手順を参照します。

解決策

重要:

• ECS クラスターのリソースが配置されているのと同じ AWS リージョンで、AWSSupport-TroubleshootECSTaskFailedToStart ランブックを使用してください。
• ランブックを使用する際は、最近失敗したタスクの ID を使用する必要があります。失敗したタスクが Amazon ECS サービスの一部である場合は、サービス内で最後に失敗したタスクを使用してください。失敗したタスクは、オートメーション中に ECS:DescribeTasks で確認できる必要があります。デフォルトで、停止した ECS タスクは停止状態になってから 1 時間以内であれば確認できます。最近失敗したタスク ID を使用すると、オートメーション中にタスク状態のクリーンアップにより分析が中断するのを防ぐことができます。

ランブックを開始する方法については、「AWSSupport-TroubleshootECSTaskFailedToStart」を参照してください。オートメーションの出力に基づいて、次の手動のトラブルシューティングステップのいずれかを実行してください。

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

Parameter Store または Secrets Manage 内で環境変数を使用している場合は、次の API 呼び出しのいずれかの AWS CloudTrail イベントを確認してください。

Parameter Store の場合、GetParameters

-または-

Secrets Manager の場合、GetSecretValue

CloudTrail イベントでタスク実行ロールの AccessDenied エラーに気付いた場合は、必要なアクセス許可をインラインポリシーとして ECS タスク実行 IAM ロールに手動で追加します。カスタマー管理ポリシーを作成して、そのポリシーを ECS タスク実行ロールに追加することもできます。

Secrets Manager を使用している場合、タスク実行ロールに次のアクセス許可を含めます。

{  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "kms:Decrypt"
      ],
      "Resource": [
        "arn:aws:secretsmanager:example-region:11112222333344445555:secret:example-secret",
        "arn:aws:kms:example-region:1111222233334444:key/example-key-id"
      ]
    }
  ]
}

Parameter Store を使用している場合、タスク実行ロールに次のアクセス許可を含めます。

{  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameters",
        "secretsmanager:GetSecretValue",
        "kms:Decrypt"
      ],
      "Resource": [
        "arn:aws:ssm:example-region:1111222233334444:parameter/example-parameter",
        "arn:aws:secretsmanager:example-region:1111222233334444:secret:example-secret",
        "arn:aws:kms:example-region:1111222233334444:key/example-key-id"
      ]
    }
  ]
}

S3 バケットを使用して、環境変数を .env ファイルとして保存できます。ただし、次のアクセス許可をインラインポリシーとしてタスク実行ロールに手動で追加する必要があります。

{  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::example-bucket/example-folder/example-env-file"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::example-bucket"
      ]
    }
  ]
}

ネットワーク設定に問題がある

ECS タスクがプライベートサブネットにある場合は、次の点を確認してください。

• タスクまたはサービスのセキュリティグループが、ポート 443 での送信トラフィックを許可していること。
• VPC エンドポイントを使用する場合は、ネットワークのアクセスコントロールリスト (ACL) がポート 443 での送信トラフィックを許可していること。
• Systems Manager/Secrets Manager と Amazon S3 エンドポイントへの接続。これを行うには、telnet コマンドを使用します。
• NAT ゲートウェイを使用する場合、タスクに NAT ゲートウェイへのデフォルトルートがあること。
• タスクの VPC エンドポイントを定義すること。Secrets Manager/Systems Manager Parameter Store と Amazon S3 に必要な VPC エンドポイントがあること。

VPC エンドポイントを使用する場合は、次の点を確認してください。

• VPC エンドポイントのセキュリティグループがポート 443 でのタスクまたはサービスからの送信トラフィックを許可していること。
• VPC エンドポイントを正しい VPC に関連付けること。
• VPC 属性 enableDnsHostnames および enableDnsSupport を有効にすること。

ECS タスクがパブリックサブネットにある場合は、次の点を確認してください。

• タスクのパブリック IP アドレスを有効にすること。
• VPC のセキュリティグループで、ポート 443 でインターネットへのアウトバウンドアクセスが許可されていること。
• ネットワーク ACL の設定で、すべてのトラフィックのサブネットへの出入りおよびインターネットへのアクセスが許可されていること。

アプリケーションが環境変数を読み取れない

タスクコンテナ内に正しい環境変数が入力されているかどうかを確認するには、次を実行します。

1. コンテナ内で公開されているすべての環境変数をリストアップします。
2. このリストに、タスク定義または S3の .env ファイルで定義した環境変数が含まれていることを確認します。

Amazon EC2 または AWS Fargate の起動タイプを使用している場合は、ECS Exec 機能を使用するのがベストプラクティスです。この機能を使用して、Amazon EC2 インスタンスまたは Fargate で実行されているコンテナでコマンドを実行したり、シェルを取得できます。この機能を有効にしたら、次のコマンドを実行してコンテナを操作します。

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

Amazon EC2 起動タイプを使用する場合は、Docker exec コマンドを使用してコンテナを操作することもできます。その場合は、次のステップを実行してください。 タスクが実行されているコンテナインスタンスに接続します。その後、次の Docker コマンドを実行して、タスクコンテナのコンテナ ID を確認します。

docker container ps

コンテナを操作するには、次を実行します

docker exec -it example-container-id bash

注: コンテナのデフォルトシェルに従ってシェルを選択してください。

コンテナとの接続を確立したら、コンテナで env コマンドを実行して、環境変数の完全なリストを取得します。このリストをレビューして、タスク定義または **.env ** ファイルで定義した環境変数が存在することを確認します。

コンテナ定義の変数の形式が正しくない

コンテナ定義内で環境変数を定義する場合、環境変数を KeyValuePair オブジェクトとして定義します。

"environment": [{    "name": "foo",
    "value": "bar"
}]

.env ファイルで環境変数を定義する際も、必ずこの形式を使用してください。

環境変数が自動的に更新されない

.env ファイルの環境変数を更新しても、実行中のコンテナでは、変数は自動的に更新されません。
更新された環境変数の値をタスクに挿入するには、次のコマンドを実行してサービスを更新します。

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

コンテナ定義で環境変数を使用する場合は、新しいタスク定義を作成して、更新された環境変数を更新する必要があります。この新しいタスク定義を使用して、新しいタスクを作成したり ECS サービスを更新できます。

`aws ecs update-service --cluster example-cluster --service example-service --task-definition <family:revision>`;

注: 環境変数をタスクに渡す際は、次の点に注意してください。

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

関連情報

コンテナへの環境変数の受け渡し