AWS Containers

Service Overview

開発者のニーズ	推奨サービス	キーCLI / CDK
最もシンプルなコンテナデプロイ（HTTPアプリ/API、新規顧客）	ECS Express Mode	aws ecs create-express-gateway-service
Webアプリ、ワーカー、バッチ、スケジュール済みタスク	ECS on Fargate	aws ecs create-service / CDK ecsPatterns.ApplicationLoadBalancedFargateService
GPUワークロード、16 vCPU超	ECS on EC2	CDK ecs.Ec2Service
コンテナイメージの保存	ECR	aws ecr create-repository
ロードバランサーの背後にあるWebアプリ	ECS Fargate + ALB	CDK ecsPatterns.ApplicationLoadBalancedFargateService
キューの深さに応じたSQSワーカースケーリング	ECS Fargate + SQS	CDK ecsPatterns.QueueProcessingFargateService
Cronジョブ/スケジュール済みタスク	ECS Fargate + EventBridge	CDK ecsPatterns.ScheduledFargateTask
サービスメッシュ/サービス間通信	ECS Service Connect	Cloud Map名前空間でECSサービスを設定
実行中のコンテナをデバッグ	ECS Exec	aws ecs execute-command --interactive --command "/bin/sh"

開発者が「コンテナをデプロイしたい」とサービス名を指定せずに言った場合：シンプルなHTTPアプリの場合はECS Express Modeを推奨（新規顧客向けにApp Runnerに代わります）。その他のすべての場合はECS Fargateを推奨します。Kubernetesを明示的に要求されない限り、EKSは推奨しません。

Overview

Amazon ECS、AWS Fargate、Amazon ECR、AWS App Runnerを使用して、コンテナ化されたワークロードの構築、デプロイ、および運用の専門知識を提供します。

推奨セットアップ： サンドボックス実行、監査ログ、エンタープライズ制御のためにAWS MCPサーバーをインストールしてください。参照：aws.amazon.com/mcp

AWS MCPなし： このスキルはAWS CLIアクセスを持つすべてのエージェントと連携します。すべてのコマンドは標準AWS CLI構文を使用します。

このスキルを使用しない場合：

• Kubernetes または EKS ワークロード → kubernetes スキルを使用
• コンテナデプロイメント用のCI/CDパイプセットアップ → deploy スキルを使用
• VPC サブネット設計とセキュリティグループアーキテクチャ → networking スキルを使用
• コンテナなしでコードを実行（Lambda、Step Functions） → serverless スキルを使用

コマンドを実行する前に：

• コマンドを実行する前に、AWS CLI v2がインストールされて設定されていることを確認する必要があります
• 必要なツール（AWS CLI、Docker、Session Manager plugin）が不足している場合は、ユーザーに通知する必要があります
• ユーザーがいつでも中止することを決めた場合は、その決定を尊重する必要があります

Gotchas

これらは毎回適用してください。各項目は、明示的な指示なしにエージェントが犯す間違いを正します。

1. Fargate CPU/メモリは有効な組み合わせでなければなりません。 任意の値は Invalid 'cpu' setting for task を引き起こします：

   • 256 (0.25 vCPU)：512 MiB、1 GB、2 GB
   • 512 (0.5 vCPU)：1～4 GB（1 GB単位）
   • 1024 (1 vCPU)：2～8 GB（1 GB単位）
   • 2048 (2 vCPU)：4～16 GB（1 GB単位）
   • 4096 (4 vCPU)：8～30 GB（1 GB単位）
   • 8192 (8 vCPU)：16～60 GB（4 GB単位）
   • 16384 (16 vCPU)：32～120 GB（8 GB単位）

   ユーザーが無効な組み合わせをリクエストした場合は、それを伝え、最も近い有効なオプションを推奨してください。無効なタスク定義を黙って作成してはいけません。

2. Fargate には awsvpc ネットワークモードが必須です。例外はありません。 エージェントは頻繁にFargateタスクに対して bridge または host モードを提案しますが、これはすぐに登録失敗を引き起こします。すべてのFargateタスク定義で networkMode を awsvpc に設定する必要があります。EC2では awsvpc が推奨されます。bridge はレガシーのみです。

3. 実行ロール対タスクロール。絶対に混同しないでください。 executionRoleArn：ECSエージェントが使用してイメージをプル、シークレットをフェッチ、ログを書き込みます。taskRoleArn：アプリケーションコードがAWS APIを呼び出すために使用します。ECS Execのパーミッション（ssmmessages:*）はタスクロールに配置します。ECRプルパーミッションは実行ロールに配置します。ecr:GetAuthorizationToken は Resource: "*" を使用する必要があります（レジストリレベルのアクション）。

4. シークレットはタスク起動時のみインジェクトされます。ホットリロードはありません。 変更されたシークレットには aws ecs update-service --force-new-deployment が必要です。Secrets ManagerのJSONキーを参照するには：arn:aws:secretsmanager:region:account:secret:name-hash:json-key::。末尾のコロンは必須です（空のバージョンステージおよびバージョンIDフィールドを表します）。SSM Parameter Storeを使用して valueFrom でパラメータARNを指定することもできます。実行ロールには ssm:GetParameters パーミッションが必要です。

5. ALB登録解除遅延はデフォルトで300秒。30～60秒に減らしてください。 これは遅いデプロイメントの原因第1位です。ターゲットグループで設定してください。最長リクエスト期間を超える必要があります。

6. ALBの背後にあるすべてのECSサービスに healthCheckGracePeriodSeconds を設定してください。 設定しないと、ALBはタスクの準備ができる前にマーク不健康にし、サーキットブレーカーが失敗をカウントし、デプロイメントがロールバックします。JVM/Spring Bootアプリは60～120秒が必要です。

7. 常にデプロイメントサーキットブレーカーをロールバック付きで有効化してください。 無効にすると、不正なデプロイメントが30分以上「進行中」のままになります。CDKでは：circuitBreaker: { rollback: true }（プロパティを指定するとそれが暗黙的に有効化されます。enable はデフォルトで true です）。

8. プライベートサブネットFargateタスクはNATまたは4つすべてのVPCエンドポイントが必要です。 必要なエンドポイント：ecr.dkr（インターフェース）、ecr.api（インターフェース）、s3（ゲートウェイ。ECRはレイヤーをS3に保存）、logs（インターフェース。CloudWatch用）。S3ゲートウェイエンドポイントは最も見落とされます。ECS Execの場合は、ssmmessages も追加してください。

9. ECRライフサイクルポリシーは24時間以内に評価されます。すぐではありません。 マニフェストリストで参照されているマルチアーキテクチャイメージは、マニフェストリストが最初に削除されるまで有効期限切れできません。適用前にプレビューしてください：まず aws ecr start-lifecycle-policy-preview --repository-name $REPO、次に aws ecr get-lifecycle-policy-preview --repository-name $REPO --output json で影響を受けるイメージを確認してください。

10. ECS Execはタスクロールパーミッションが必要です。実行ロールではありません。 タスクロールには ssmmessages:CreateControlChannel、CreateDataChannel、OpenControlChannel、OpenDataChannel が必要です。enableExecuteCommand を有効にする前に起動されたタスクはECS Execをサポートしません。新しいデプロイメントを強制してください。コンテナイメージには --command で指定されたバイナリが含まれている必要があります（例：対話型セッション用の /bin/sh）。S3またはCloudWatch Logsへのコマンドログには、script と cat もインストールされている必要があります。Fargateプラットフォームバージョンは1.4.0以上である必要があります。

11. awslogs ログドライバーモード。アカウントのデフォルトを確認してください。 ECSドキュメントによると、ECSサービスはデフォルトで non-blocking モードです。バッファがいっぱいになるとログをドロップします。defaultLogDriverMode アカウント設定はアカウントごとにこれをオーバーライドできます。保証されたログ配信（監査/コンプライアンス）の場合、logConfiguration.options で明示的に "mode": "blocking" を設定してください。有効なデフォルトを確認：aws ecs list-account-settings --name defaultLogDriverMode --effective-settings --output json。

12. App Runner VPCコネクタはアプリケーションが開始したすべてのアウトバウンドトラフィックをVPCを通じてルーティングします。 （App Runnerはサンセット中です。新規顧客はECS Express Modeを使用すべきです。）NATゲートウェイがなければ、外部APIコールとアプリケーションコードからのAWSサービスコールが失敗します。App Runner独自の管理トラフィック（イメージプル、ログプッシュ、シークレット取得）はVPCを通じてルーティングされず、影響を受けません。スタートアップでのデータベース接続に対してはバックオフを伴う再試行ロジックを実装してください。

13. desiredCount=1 ゼロダウンタイムデプロイの場合：minimumHealthyPercent=100, maximumPercent=200。 これはデプロイメント中に2つのタスク用の容量を必要とします。ゼロダウンタイムが必要な場合は、minimumHealthyPercent=0 を設定してはいけません。

14. ALBからの502 Bad Gateway。この順序でチェックしてください： (a) コンテナがターゲットグループ内のポートでリッスンしていない。(b) コンテナが応答前にクラッシュしている。(c) タスクセキュリティグループがコンテナポートでALBセキュリティグループからのインバウンドを許可していない。(d) ヘルスチェックパスが200以外を返している。(e) ヘルスチェックタイムアウトが応答時間を超えている。

15. Fargateプラットフォームバージョン：常に LATEST または 1.4.0 を使用してください。 バージョン1.3.0は2026年6月15日に廃止され、2026年6月30日に終了します。

16. SQSワーカースケーリング：カスタム一タスクあたりのバックログメトリクスを使用してください。 生の ApproximateNumberOfMessagesVisible とターゲット追跡では機能しません。タスクを追加してもキューの深さが比例して減少しないためです。カスタムメトリクス（ApproximateNumberOfMessagesVisible / RunningTaskCount）でターゲット追跡を使用するか、ステップスケーリングを使用してください。CDK QueueProcessingFargateService は scalingSteps を介してこれを自動的に処理します。ワーカーは stopTimeout 以内にSIGTERMを適切に処理する必要があります（デフォルト30秒、Fargateでの最大120秒）。

17. ブルー/グリーンデプロイメント：新しいサービスにはネイティブECSブルー/グリーン（2025年7月以降）を使用してください。 すべての一度に、カナリア、線形トラフィックシフト（カナリア/線形は2025年10月に追加）、さらにService Connect、ヘッドレスサービス、EBSボリューム、ライフサイクルフックをサポートしています。CodeDeployブルー/グリーンは現在レガシーです。ネイティブECSブルー/グリーンは完全な機能パリティを備えています。

18. コンテナ依存関係 HEALTHY 条件は依存関係コンテナにヘルスチェックが必要です。 設定されたヘルスチェックがない場合、依存するコンテナは起動しません。ECSはそれを次の状態に進める方法がありません。startTimeout が設定されている場合（最大120秒）、依存関係がタイムアウトしてタスクが失敗します。設定されていない場合、依存するコンテナは無限にブロックします。初期化コンテナの場合は、SUCCESS 条件を代わりに使用してください。

Quick-Start：CDK Fargate Webアプリ

import * as cdk from 'aws-cdk-lib';
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ecsPatterns from 'aws-cdk-lib/aws-ecs-patterns';

const service = new ecsPatterns.ApplicationLoadBalancedFargateService(this, 'WebApp', {
  taskImageOptions: {
    image: ecs.ContainerImage.fromEcrRepository(repo, 'latest'),
    containerPort: 8080,
    secrets: { DB_PASSWORD: ecs.Secret.fromSecretsManager(dbSecret) },
  },
  cpu: 512,
  memoryLimitMiB: 1024,
  desiredCount: 2,
  publicLoadBalancer: true,
  circuitBreaker: { rollback: true },
  minHealthyPercent: 100,
});

service.targetGroup.setAttribute('deregistration_delay.timeout_seconds', '30');

const scaling = service.service.autoScaleTaskCount({ minCapacity: 2, maxCapacity: 10 });
scaling.scaleOnCpuUtilization('CpuScaling', { targetUtilizationPercent: 70 });

CDK L3パターンはVPC、クラスタ、ALB、ターゲットグループ、セキュリティグループを自動作成します。本番環境では、これらを別途作成して渡してください。ApplicationLoadBalancedFargateService はデフォルトで assignPublicIp: false です。パブリックサブネット内のタスクはインターネットアクセスに assignPublicIp: true が必要です。または、NATを使用してプライベートサブネットを使用してください。

Quick-Start：ECS Exec

# 1. サービスで有効化（既存のタスクはサポートしません。新しいデプロイメントを強制してください）
aws ecs update-service --cluster $CLUSTER --service $SERVICE \
  --enable-execute-command --force-new-deployment --output json

# 2. 接続（タスクロールにはssmmessages:* パーミッションが必要です）
aws ecs execute-command --cluster $CLUSTER --task $TASK_ID \
  --container $CONTAINER --interactive --command "/bin/sh"

TargetNotConnectedException の場合：SSMエージェントの起動を30～60秒待機し、ssmmessages のNAT/VPCエンドポイントを確認し、タスクロール（実行ロールではない）にパーミッションがあることを確認してください。

Common Workflows

AWS操作に最適な利用可能なツール（MCPサーバー、AWS CLI、またはSDK）を使用してください。以下のコマンドはAWS CLIフォーム形式です。

会話でより詳細な情報が必要な場合にのみ参照ファイルを読んでください。

• ユーザーがタスク定義を作成する、CPU/メモリを設定する、ネットワークモードを設定する、シークレットをインジェクトする、ボリュームをマウントする、またはコンテナ依存関係を設定する必要がある場合は、references/task-definition-authoring.md を読んでください。
• ユーザーがFargateサービスをALBの背後にデプロイする、ヘルスチェックを設定する、登録解除遅延を調整する、パスベースのルーティングを設定する、またはプライベートサブネットネットワークを処理する必要がある場合は、references/fargate-service-deployment.md を読んでください。
• ユーザーがECRライフサイクルポリシー、イメージスキャン、クロスアカウントイメージプル、またはイメージプルエラーのデバッグが必要な場合は、references/ecr-repository-management.md を読んでください。
• ユーザーがECS Execを設定する、TargetNotConnectedException をデバッグする、セッションログを設定する、またはECS Exec前提条件を検証する必要がある場合は、references/ecs-exec-debugging.md を読んでください。
• ユーザーが自動スケーリング、デプロイメント戦略（ローリング、ブルー/グリーン）、サーキットブレーカー設定、またはService Connectセットアップが必要な場合は、references/service-scaling-and-updates.md を読んでください。
• ユーザーが既存のApp Runnerサービスを持っている、App Runner接続をトラブルシューティングする、またはApp RunnerからECS Express Modeへの移行を希望する場合は、references/app-runner-guide.md を読んでください。
• ユーザーがFargateサービス、SQSワーカー、スケジュール済みタスク、EFSボリューム、ECS Exec、パスベースのルーティング、プライベートサブネット、またはFireLensのCDKまたはCloudFormationの例が必要な場合は、references/ecs-infrastructure-patterns.md を読んでください。
• ユーザーがawslogs設定、FireLens/Fluent Bitセットアップ、複数行ログ処理、または保証されたログ配信が必要な場合は、references/ecs-logging-and-firelens.md を読んでください。
• ユーザーがタスク配置失敗、OOMキル（終了コード137）、ヘルスチェック失敗、イメージプルエラー、またはプライベートサブネットのネットワークの問題をデバッグしている場合は、references/ecs-troubleshooting-guide.md を読んでください。
• ユーザーがFargate Spotの価格設定、キャパシティプロバイダー戦略、または中断処理について質問する場合は、references/fargate-spot.md を読んでください。

Decision Guide：ECS Express Mode対ECS Fargate

App Runner： 2026年4月30日にサンセット。新規顧客なし、新機能なし。既存顧客はECS Express Modeに移行すべきです。参照：App Runner Availability Change。

Factor	ECS Express Mode	ECS Fargate
セットアップの複雑性	最小（単一APIコール）	中程度。タスク定義、サービス、クラスタ、ALB
ネットワーク制御	管理（デフォルトVPCのALB）	完全。awsvpc、セキュリティグループ、サブネット
スケーリング	自動（CPU ベース）	設定可能なターゲット/ステップスケーリング
使用時期	新しいシンプルなHTTPアプリ/API、インフラ管理ゼロ	本番環境サービス。VPC、ALB、きめ細かいIAMが必要
制限	新しいサービス。進化する機能セット	最も多くのセットアップが必要

デフォルト推奨： 本番ワークロードにはECS Fargateを使用してください。最もシンプルなパス（新規顧客）にはECS Express Modeを使用してください。

Troubleshooting

CannotPullContainerError

原因： タスクがECRに到達できません。プライベートサブネットでは、タスクはNATゲートウェイまたはVPCエンドポイント（ecr.api、ecr.dkr、s3 ゲートウェイ、logs）が必要です。 修正： ルートテーブルがNATゲートウェイへのルートを持っているか、または必要なVPCエンドポイントを作成していることを確認してください。実行ロールに ecr:GetDownloadUrlForLayer、ecr:BatchGetImage、ecr:GetAuthorizationToken（リソース："*"）があることを確認してください。セキュリティグループがアウトバウンドHTTPS（443）を許可していることを確認してください。

タスクはELBヘルスチェックに失敗しました

原因： ヘルスチェックパスが200以外を返す、コンテナが設定されたポートでリッスンしていない、またはヘルスチェック猶予期間が短すぎる。 修正： コンテナがヘルスチェックパスとポートで応答することを確認してください。healthCheckGracePeriodSeconds を少なくとも60秒に設定してください（JVMアプリ用に長時間）。セキュリティグループがALBセキュリティグループからのトラフィックをコンテナポートで許可していることを確認してください。

OutOfMemoryError / 終了コード137

原因： コンテナがメモリハード制限を超過しました（SIGKILL）。Fargateでは、タスクレベルのメモリはハード制限です。 修正： タスクレベルのメモリを増やしてください。JVMアプリの場合、固定の -Xmx の代わりに -XX:MaxRAMPercentage=75 を使用してください。これはコンテナのメモリ割り当てに自動的に適応します。コンテナレベルの memory（ハード制限）対 memoryReservation（ソフト制限）を確認してください。

コンテナからのAWS API呼び出しに対するAccessDeniedException

原因： パーミッションが実行ロールではなく、タスクロールに配置されているか、タスクロールが不足しています。 修正： タスク定義に taskRoleArn が設定されていることを確認してください（ただし executionRoleArn のみではありません）。タスクロールに必要なパーミッションを追加してください。

サービスがデプロイに固まる / タスクが再起動を続ける

原因： デプロイメントサーキットブレーカーが有効になっていない、またはヘルスチェックが新しいタスクで失敗しています。 修正： ロールバック付きのサーキットブレーカーを有効化してください。サービスイベントを確認：aws ecs describe-services --cluster $CLUSTER --services $SERVICE --output json。停止されたタスクの理由を確認：aws ecs describe-tasks --cluster $CLUSTER --tasks $TASK_ID --output json。

ECS Exec TargetNotConnectedException

原因： SSMエージェントが実行していない、タスクロールのパーミッションが不足している、またはVPCエンドポイントが不足しています。 修正： enableExecuteCommand がサービスで真であることを確認してください。タスクロールにSSMパーミッションがあることを確認してください。プライベートサブネットの場合、ssmmessages VPCエンドポイントを作成してください。aws ecs describe-tasks で ExecuteCommandAgent ステータスが RUNNING であることを確認してください。

エラー再試行分類

再試行	再試行しません
ThrottlingException	InvalidParameterException
ServiceUnavailableException	ClientException
ServerException	AccessDeniedException

Security Considerations

• IAMロール（実行ロール＋タスクロール）を使用する必要があります。コンテナイメージまたは環境変数に認証情報を埋め込まないでください
• Secrets ManagerまたはSSM Parameter Storeを機密設定に使用し、タスク定義の secrets フィールドを介してインジェクトする必要があります
• プッシュ時にECRイメージスキャンを有効化して、脆弱性検出を行う必要があります
• 本番環境ワークロードの場合、プライベートサブネットとNATゲートウェイまたはVPCエンドポイントを使用する必要があります
• ECS API監査ログ用にCloudTrailを有効化する必要があります
• 監視用にCloudWatch Container Insightsを設定する必要があります
• コンテナ定義で可能な限り readonlyRootFilesystem: true を使用する必要があります（注意：ECS Execと互換性がありません）
• タスクロールのパーミッションを特定のリソースにスコープする必要があります。* ワイルドカードと *FullAccess ポリシーを避けてください
• 破壊的な操作を実行する前にユーザーに確認する必要があります：--force-new-deployment（すべての実行中のタスクを置き換え）、delete-service、deregister-task-definition。ECSは --dry-run をサポートしていません。plan-validate-executeパターンを使用：何が起こるかを説明し、確認を得て、実行してください
• ECS サービスの前にあるALBsでACM証明書を使用してHTTPSリスナーを設定する必要があります。ECS ネットワークセキュリティベストプラクティス によると：「AWS Certificate Manager（ACM）を使用してロードバランサーの証明書をプロビジョニングしてください」
• コンテナstdout/stderrで機密データ（シークレット、PII、トークン）のログを避ける必要があります。これらはawslogs ドライバーを介してCloudWatch Logsに流れます。機密データがログに表示される可能性がある場合、KMSキーでCloudWatch Logsの暗号化を有効化してください
• インターネット対応のALBにAWS WAF WebACLをアタッチして、一般的なWebエクスプロイトに対する多層防御を行う必要があります
• クロスアカウントアクセス時に、confused deputy 攻撃を防ぐため、ECRリポジトリポリシーに aws:SourceArn および aws:SourceAccount 条件キーを含める必要があります

Additional Resources

• Amazon ECS Developer Guide
• Amazon ECS API Reference
• Amazon ECS Best Practices Guide
• Amazon ECR User Guide
• AWS Fargate Documentation
• ECS Express Mode Getting Started
• ECS Security Best Practices
• App Runner Developer Guide（既存顧客）
• App Runner Availability Change (Sunset)