Amazon ECS の「unable to pull secrets or registry auth」というエラーをトラブルシューティングする方法を教えてください。

所要時間3分

Amazon Elastic Container Service (Amazon ECS) タスクを起動すると、「unable to pull secrets or registry auth」というエラーメッセージが表示されます。

簡単な説明

Amazon ECS タスクを起動した際に、次のいずれかのエラーメッセージが表示される場合があります。

「ResourceInitializationError: unable to pull secrets or registry auth: pull command failed: : signal: killed」
「ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed: unable to retrieve secret from asm: service call has been retried.」

AWS Fargate プラットフォームバージョン 1.4.0 では、タスクの Elastic Network Interface を使用してイメージとシークレットを取得します。すべてのネットワークトラフィックは、Amazon Virtual Private Cloud (Amazon VPC) 内の Elastic Network Interface を経由します。このトラフィックは Amazon VPC フローログで確認できます。ただし、エラスティックネットワークインターフェイスは Amazon VPC 内に配置されるため、このタスクではユーザーのネットワーク設定が使用されます。

Amazon ECS コンテナエージェントは、AWS Identity and Access Management (IAM) のタスク実行ロールを使用して、以下のサービスから情報を取得します。

AWS Systems Manager Parameter Store
AWS Secrets Manager

カスタマーマネージド AWS Key Management Service (AWS KMS) キーを使用してデータを暗号化する場合は、タスク実行 IAM ロールに次の権限を付与します。

ssm:GetParameters
secretsmanager:GetSecretValue
kms:Decrypt

解決策

起動に失敗する Amazon ECS タスクをトラブルシューティングするには、AWSSupport-TroubleshootECSTaskFailedToStart ランブックを使用してください。ランブックの出力に推奨事項が記載されていない場合は、次のセクションの手動によるトラブルシューティング方法を使用してください。

重要:

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

TroubleshootECSTaskFailedToStart ランブックを使用する

AWSSupport-TroubleshootECSTaskFailedToStart ランブックを実行するには、次の手順に従います。

AWS Systems Manager コンソールを開きます。
ナビゲーションペインで、[変更管理] から [オートメーション] を選択します。
[オートメーションの実行] を選択します。
[Amazon が所有] タブを選択します。
[オートメーションドキュメント] で「TroubleshootECSTaskFailedToStart」を検索します。
AWSSupport-TroubleshootECSTaskFailedToStart カードを選択します。
**注:**ハイパーリンクされたオートメーション名ではなく、カード上のラジオボタンを選択します。
[次へ] を選択します。
**注:**実行後、分析結果が [グローバル出力] セクションに表示されます。ドキュメントのステータスが [成功] に変更されるまでお待ちください。また、[出力] セクションに例外がないかどうかも確認してください。
[オートメーションドキュメントを実行] で、[シンプルな実行] を選択します。
[入力パラメーター] セクションの [AutomationAssumeRole] に、Systems Manager Automation がアクションを実行できるようにするロールの ARN を入力します。
**注:**AutomationAssumeRole または IAM のユーザーもしくはロールのいずれかに、AWSSupport-TroubleshootECSTaskFailedToStart ランブックを実行するために必要な IAM 権限があることを確認してください。IAM ロールを指定しない場合、Systems Manager Automation ではランブックを実行する IAM ユーザーまたはロールのアクセス許可が使用されます。Systems Manager Automation の継承ロールの作成については、「タスク 1：自動化のサービスロールを作成する」を参照してください。
[ClusterName] には、タスクを開始できなかったクラスター名を入力します。
[TaskId] には、最近失敗したタスクの ID を入力します。
[実行] を選択します。

オートメーションの出力に基づいて、次の手動のトラブルシューティング手順のいずれかを実行してください。

サブネットからインターネットへのルートを確認する

パブリックサブネットに Fargate タスクがある場合は、そのタスクにパブリック IP アドレスが割り当てられていることを確認します。また、タスクにインターネットゲートウェイへのデフォルトルート (0.0.0.0/0) が設定されていることも確認します。新しいタスクを起動したり、新しいサービスを作成したりする際は、[自動割り当てパブリック] をオンにしてください。

以下の設定を使用する場合は、パブリックサブネットのインターネットゲートウェイを使用して Secrets Manager または Systems Manager にアクセスしないでください。

Secrets Manager または Systems Manager の VPC エンドポイントがパブリックサブネットにある。
Amazon VPC の DHCP 設定で AmazonProvidedDNS を有効にしている。

上記の場合は、Amazon VPC エンドポイントを使用してください。

**注:**既存のタスクに対して [自動割り当てパブリック] を有効にすることはできません。既存のサービスを再設定するには、AWS コマンドラインインターフェイス (AWS CLI) を使用します (AWS マネジメントコンソールは使用できません)。AWS CloudFormation スタックを使用して Amazon ECS サービスを作成した場合は、AWS::ECS::Service の NetworkConfiguration プロパティを変更してサービスを更新してください。

プライベートサブネットに Fargate タスクがある場合は、そのタスクにインターネット接続ソースへのデフォルトルート (0.0.0.0/0) があることを確認してください。

インターネット接続ソースには、NAT ゲートウェイ、AWS PrivateLink、またはその他のソースを使用できます。

NAT ゲートウェイを使用する場合は、パブリックサブネットに配置します。詳細については、インターネットゲートウェイと NAT ゲートウェイを備えたアーキテクチャを参照してください。
PrivateLink を使用する場合は、Fargate インフラストラクチャが Amazon VPC エンドポイントのセキュリティグループを使用できることを確認してください。
カスタムネームドメインサーバーを使用する場合は、DNS クエリの設定を確認してください。クエリは、UDP プロトコルと TCP プロトコルを使用してポート 53 でアウトバウンドアクセスする必要があります。また、ポート 443 で HTTPS アクセスできる必要もあります。

ネットワーク ACL とセキュリティグループの設定を確認する

ネットワークアクセスコントロールリスト (ネットワーク ACL) とセキュリティグループが、サブネットからのポート 443 へのアウトバウンドアクセスをブロックしていないことを確認します。詳細については、「セキュリティグループを使用して AWS リソースへのトラフィックを制御する」を参照してください。

**注:**送信トラフィックを許可し、Amazon ECS エンドポイントにアクセスするには、Fargate タスクにポート 443 へのアウトバウンドアクセス権が必要です。

Amazon VPC エンドポイントを確認する

PrivateLink を使用する場合は、必要なエンドポイントを作成する必要があります。Fargate プラットフォームバージョン 1.4.0 以降には、次のエンドポイントが必要です。

com.amazonaws.region.ecr.dkr
com.amazonaws.region.ecr.api
S3 ゲートウェイエンドポイント
com.amazonaws.region.logs

詳細については、「Considerations for Amazon Elastic Container Registry (Amazon ECR) VPC endpoints」を参照してください。

**注:**タスク定義で Secrets Manager、Systems Manager のパラメータ、または Amazon CloudWatch Logs を使用している場合は、エンドポイントの定義が必要になることがあります。詳細については、次のドキュメントを参照してください。

PrivateLink については、Amazon VPC のセキュリティグループが TCP ポート 443 の Fargate タスクセキュリティグループまたは Fargate タスク VPC CIDR 範囲からのトラフィックを許可していることを確認します。

Fargate インフラストラクチャにサービスアクセスがあることを確認するには、「VPC endpoint policies」と「endpoint policies for Amazon Simple Storage Service (Amazon S3)」を確認してください。

IAM ロールと権限を確認する

タスク実行ロールは、Amazon ECS コンテナと Fargate エージェントにタスクの API 呼び出しを行うために必要な権限を付与します。Fargate では、次のアクションを実行するときにこのロールが必要になります。

Amazon ECR からコンテナイメージを取得する。
awslogs ログドライバーを使用する。
プライベートレジストリ認証を使用する。
機密データを参照するには、Secrets Manager シークレットまたは Systems Manager Parameter Store パラメータを使用します。

ユースケースに前述のシナリオのいずれかが含まれる場合は、タスク実行ロールで必要な権限を定義します。必要な権限の詳細なリストについては、「Amazon ECS タスク実行 IAM ロール」を参照してください。

Amazon ECS タスク定義で参照されている機密情報を確認する

**注:**AWS CLI のコマンドの実行時にエラーが発生する場合は、「AWS CLI エラーのトラブルシューティング」を参照してください。また、必ずAWS CLI の最新バージョンを使用してください。

シークレット名とパラメータ名が Amazon ECS タスク定義の参照名と一致していることを確認します。次に、コンテナ定義の値が Amazon ECS タスク定義の値と一致していることを確認します。詳細については、「Amazon ECS タスク内のコンテナに秘密または機密情報を安全に渡すにはどうすればよいですか? 」を参照してください。

Systems Manager Parameter Store パラメータとタスクが同じリージョンにある場合は、完全な ARN またはシークレットの名前を使用してください。パラメータが別のリージョンに存在する場合は、完全な ARN を指定する必要があります。

Systems Manager のパラメータ名と ARN を確認するには、次の手順を実行してください。

AWS Systems Manager コンソールを開きます。
ナビゲーションペインで [パラメータストア] を選択し、パラメータストア名を確認します。
パラメータの ARN を取得するには、AWS CLI を使用して次のコマンドを実行します。name_of_parameter_store_secret は、パラメータストアのシークレット名に置き換えます。
```
$ aws ssm get-parameter —name <name_of_parameter_store_secret> —with-decryption
```
**注:**Secrets Manager シークレットを参照するパラメータでは、パラメータストアのバージョニングや履歴の機能を使用できません。詳細については、「制限事項」を参照してください。