aws-containers

AWS Containers

Service Overview

開發者需求	建議方案	主要 CLI / CDK
最簡單的容器部署（HTTP 應用程式/API，新客戶）	ECS Express Mode	aws ecs create-express-gateway-service
Web 應用程式、Worker、批次處理、排程任務	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 Worker	ECS Fargate + SQS	CDK ecsPatterns.QueueProcessingFargateService
Cron Job / 排程任務	ECS Fargate + EventBridge	CDK ecsPatterns.ScheduledFargateTask
Service Mesh / 服務間通訊	ECS Service Connect	在 ECS 服務上搭配 Cloud Map 命名空間設定
針對運行中的容器進行除錯	ECS Exec	aws ecs execute-command --interactive --command "/bin/sh"

當開發者未指定特定服務而直接要求「部署我的容器」時：針對簡單的 HTTP 應用程式，優先推薦 ECS Express Mode（已取代 App Runner 成為新客戶的首選方案）。其餘情境則建議使用 ECS Fargate。除非使用者明確要求使用 Kubernetes，否則切勿主動推薦 EKS。

Overview

本 Skill 提供使用 Amazon ECS、AWS Fargate、Amazon ECR 與 AWS App Runner 建置、部署及維運容器化工作負載的專業指引。

建議設定： 安裝 AWS MCP Server 以獲得沙盒化執行環境、稽核日誌與企業級安全控管。詳情請參閱：aws.amazon.com/mcp

未使用 AWS MCP 時： 本 Skill 可搭配任何具備 AWS CLI 存取權限的 Agent 使用。所有命令皆採用標準 AWS CLI 語法。

何時不應使用此 Skill：

• Kubernetes 或 EKS 工作負載 → 請使用 kubernetes Skill
• 容器部署的 CI/CD 管道建置 → 請使用 deploy Skill
• VPC 子網路設計與 Security Group 架構規劃 → 請使用 networking Skill
• 無容器的程式碼執行環境（Lambda、Step Functions） → 請使用 serverless Skill

執行任何命令前：

• 執行命令前，您必須確認 AWS CLI v2 已正確安裝與設定
• 若缺少必要工具（AWS CLI、Docker、Session Manager 外掛程式），您必須主動告知使用者
• 您必須完全尊重使用者在任何階段決定中斷執行的權利

Gotchas

請在每次操作時遵循以下原則。每條規則皆旨在修正 Agent 在缺乏明確指引時容易犯的錯誤：

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 為遞增單位）

   若使用者提出無效的配置要求，請主動說明並推薦最接近的有效選項。絕對不能默許或產生無效的 Task Definition。

2. Fargate 強制要求使用 awsvpc 網路模式——絕無例外。 Agent 常會誤建議 Fargate 任務使用 bridge 或 host 模式，這會直接導致 Task 註冊失敗。在設定所有 Fargate Task Definition 時，您必須將 networkMode 指定為 awsvpc。在 EC2 上同樣建議使用 awsvpc；bridge 模式僅供舊版相容使用。

3. 切勿混淆執行角色（Execution Role）與任務角色（Task Role）。 executionRoleArn：由 ECS Agent 用於拉取映像檔、讀取機密資訊及寫入日誌。taskRoleArn：由應用程式程式碼用於呼叫 AWS API。ECS Exec 權限（ssmmessages:*）應設定於 Task Role；ECR 拉取權限則應設定於 Execution Role。ecr:GetAuthorizationToken 必須使用 Resource: "*"（此為 Registry 層級的操作）。

4. 機密資訊僅在 Task 啟動時注入——不支援熱重載（Hot-reload）。 若修改了機密資訊，必須執行 aws ecs update-service --force-new-deployment 才能生效。若要引用 Secrets Manager 中的特定 JSON Key，格式為：arn:aws:secretsmanager:region:account:secret:name-hash:json-key::——末尾的分號為必填項（代表空白的 version-stage 與 version-id 欄位）。您也可以搭配 SSM Parameter Store 使用，將 valueFrom 指向 Parameter ARN——此時 Execution Role 需具備 ssm:GetParameters 權限。

5. ALB 的反註冊延遲（Deregistration Delay）預設為 300 秒——建議調降至 30–60 秒。 這是導致部署緩慢的首要原因。請在 Target Group 上進行設定，且設定值應稍微大於最長的請求處理時間。

6. 請為所有位於 ALB 後方的 ECS 服務設定 healthCheckGracePeriodSeconds。 若未設定，ALB 會在 Task 尚未完成初始化前就將其判定為 Unhealthy，進而引發 Circuit Breaker 的失敗計數並觸發部署回滾。JVM/Spring Boot 應用程式通常需要設定 60–120 秒。

7. 務必啟用支援自動回滾的 Deployment Circuit Breaker。 若未啟用，異常部署將會持續停留在「進行中（In Progress）」狀態長達 30 分鐘以上。在 CDK 中可設定：circuitBreaker: { rollback: true }（指定此屬性即代表預設啟用，enable 預設為 true）。

8. 位於私有子網路的 Fargate Task 需要 NAT 閘道或完整的 4 個 VPC Endpoint。 必備的 Endpoint 包括：ecr.dkr（Interface）、ecr.api（Interface）、s3（Gateway——ECR 映像檔層儲存於 S3）、logs（Interface——供 CloudWatch 使用）。其中 S3 Gateway Endpoint 最常被漏設。若需使用 ECS Exec，還需額外新增 ssmmessages。

9. ECR 生命週期策略（Lifecycle Policy）的評估週期為 24 小時內——非即時生效。 由 Manifest List 引用的多架構映像檔（Multi-architecture images），必須先刪除 Manifest List 才能使子映像檔過期。在套用策略前建議先預覽：先執行 aws ecr start-lifecycle-policy-preview --repository-name $REPO，再執行 aws ecr get-lifecycle-policy-preview --repository-name $REPO --output json 查看將受影響的映像檔。

10. ECS Exec 需要 Task Role 權限，而不是 Execution Role。 Task Role 需要具備 ssmmessages:CreateControlChannel、CreateDataChannel、OpenControlChannel、OpenDataChannel 權限。在啟用 enableExecuteCommand 前就已啟動的 Task 無法支援 ECS Exec——請強制執行重新部署。容器映像檔中必須包含 --command 指定的執行檔（例如用於互動式 Session 的 /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 Connector 會將所有由應用程式發起的對外流量導向 VPC。（App Runner 即將停用——新客戶請改用 ECS Express Mode。）若缺乏 NAT 閘道，應用程式存取外部 API 或呼叫 AWS 服務的請求將會中斷。App Runner 本身託管的流量（如拉取映像檔、推送日誌、擷取密碼）則不會經過 VPC，不受此影響。請在應用程式啟動時為資料庫連線實作帶有退避機制的重試邏輯（Retry Logic with Backoff）。

13. 當 desiredCount=1 且需實現零停機部署（Zero-downtime Deploys）時：請設定 minimumHealthyPercent=100, maximumPercent=200。 這代表部署期間系統需具備容納 2 個 Task 的容量。若有零停機需求，絕對不能將 minimumHealthyPercent 設定為 0。

14. ALB 回傳 502 Bad Gateway 錯誤——請依以下順序排查： (a) 容器未在 Target Group 指定的 Port 上進行監聽。(b) 容器在回應請求前就已崩潰 (Crash)。(c) Task 的 Security Group 未放行來自 ALB Security Group 對容器 Port 的 inbound 流量。(d) 健康檢查路徑回傳非 200 狀態碼。(e) 健康檢查逾時時間設定短於應用程式回應時間。

15. Fargate 平台版本（Platform Version）：請一律使用 LATEST 或 1.4.0。 1.3.0 版本將於 2026 年 6 月 15 日廢棄，並於 2026 年 6 月 30 日正式終止服務。

16. SQS Worker 擴展：請使用自訂的單一 Task 積壓指標（Backlog-per-task metric）。 直接對原始 ApproximateNumberOfMessagesVisible 套用 Target Tracking 是行不通的，因為新增 Task 並不會按比例直接減少佇列深度。請使用自訂指標（ApproximateNumberOfMessagesVisible / RunningTaskCount）搭配 Target Tracking，或採用 Step Scaling。CDK 的 QueueProcessingFargateService 已透過 scalingSteps 自動處理此邏輯。Worker 在收到 SIGTERM 時，必須能在 stopTimeout（預設為 30 秒，Fargate 上上限為 120 秒）內完成平滑關機（Graceful Shutdown）。

17. 藍綠部署（Blue/green deployments）：新服務請優先使用 ECS 原生藍綠部署（2025 年 7 月起支援）。 支援全量切換（All-at-once）、金絲雀部署（Canary）與線性流量切換（Linear shifting，金絲雀/線性功能於 2025 年 10 月新增），並支援 Service Connect、Headless Service、EBS 磁碟區以及生命週期 Hook。CodeDeploy 藍綠部署現已被視為舊版技術——ECS 原生藍綠部署已具備完整的對等功能。

18. 容器依賴項設定 HEALTHY 條件時，該依賴容器必須配置健康檢查（Health Check）。 若未配置健康檢查，依賴容器將永遠無法啟動——ECS 將無法推進其至下一個狀態。若設定了 startTimeout（最高 120 秒），依賴將會逾時並導致 Task 失敗；若未設定，依賴容器將會無限期阻塞。對於 Init 容器，請改用 SUCCESS 條件。

Quick-Start: CDK Fargate Web App

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 Pattern 會自動建立 VPC、Cluster、ALB、Target Group 以及 Security Group。若在生產環境使用，建議分開建立這些元件再傳入。ApplicationLoadBalancedFargateService 預設設定為 assignPublicIp: false——部署在公有子網路的 Task 需要將其設定為 assignPublicIp: true 才能存取網際網路，或是改為使用搭配 NAT 的私有子網路。

Quick-Start: ECS Exec

# 1. 在服務上啟用此功能（現有的 Task 不支援——需強制重新部署）
aws ecs update-service --cluster $CLUSTER --service $SERVICE \
  --enable-execute-command --force-new-deployment --output json

# 2. 建立連線（Task Role 必須具備 ssmmessages:* 權限）
aws ecs execute-command --cluster $CLUSTER --task $TASK_ID \
  --container $CONTAINER --interactive --command "/bin/sh"

若遇到 TargetNotConnectedException：請等待 30–60 秒讓 SSM Agent 完成啟動，檢查 NAT/VPC Endpoint 是否已設定 ssmmessages，並確認 Task Role（非 Execution Role）已授予正確權限。

Common Workflows

請選擇最適用的工具來執行 AWS 操作（MCP Server、AWS CLI 或 SDK）。下列命令展示了 AWS CLI 的寫法。

僅在對話需要更深層細節時才讀取參考文件。

• 若使用者需要更深入的細節，請閱讀 references/task-definition-authoring.md