AWS ECS・Fargateでコンテナアプリを本番運用するための設計手順｜タスク定義・ALB連携・マルチAZ配置の構成パターン入門

この記事のポイント

・FargateはサーバーレスでEC2管理が不要。本番用途では最初の選択肢になる
・タスク定義でCPU・メモリ・コンテナ定義・ログ設定を一元管理する
・ECSサービス＋ALBでマルチAZに分散配置してヘルスチェックを自動化する
・maximumPercent=200／minimumHealthyPercent=100でゼロダウンタイムデプロイを実現する
・Auto ScalingはCPU使用率70%をトリガーにするターゲットトラッキングが基本
・実行ロール（起動権限）とタスクロール（アプリ権限）を分離して最小権限を実現する
・デプロイ失敗時はcircuit breakerで自動ロールバックしサービス停止を防ぐ
・タスク定義JSONをファイル管理してGitで変更履歴を残すと構成ドリフトを防げる

# ECSクラスターを作成する（Container Insights有効化）
aws ecs create-cluster   --cluster-name myapp-cluster   --settings "name=containerInsights,value=enabled"   --region ap-northeast-1

# 既存クラスターにContainer Insightsを後から有効化する
aws ecs update-cluster-settings   --cluster myapp-cluster   --settings "name=containerInsights,value=enabled"   --region ap-northeast-1

# タスク定義のJSON（コンテナ定義部分の抜粋）
{
  "family": "myapp-task",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "containerDefinitions": [
    {
      "name": "myapp",
      "image": "123456789012.dkr.ecr.ap-northeast-1.amazonaws.com/myapp:latest",
      "portMappings": [
        {
          "containerPort": 8080,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {"name": "APP_ENV", "value": "production"},
        {"name": "LOG_LEVEL", "value": "info"}
      ],
      "secrets": [
        {
          "name": "DB_PASSWORD",
          "valueFrom": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:myapp/db-password"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/myapp",
          "awslogs-region": "ap-northeast-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

# CloudWatch Logsのロググループを作成する
aws logs create-log-group   --log-group-name /ecs/myapp   --region ap-northeast-1

# ロググループの保持期間を30日に設定する（必ず設定すること）
aws logs put-retention-policy   --log-group-name /ecs/myapp   --retention-in-days 30

# タスク定義のコンテナヘルスチェック設定（JSON抜粋）
{
  "healthCheck": {
    "command": [
      "CMD-SHELL",
      "curl -f http://localhost:8080/health || exit 1"
    ],
    "interval": 30,
    "timeout": 5,
    "retries": 3,
    "startPeriod": 60
  }
}

# startPeriodは起動直後のヘルスチェック猶予時間（秒）
# アプリの起動に時間がかかる場合は大きめに設定する
# 例: Javaアプリで起動に45秒かかるなら startPeriod を 60～90 に設定する

# 既存のタスク定義をJSONファイルとして書き出す（初回）
aws ecs describe-task-definition   --task-definition myapp-task   --query 'taskDefinition'   --output json > task-definition.json

# JSONファイルを編集した後、新しいリビジョンとして登録する
aws ecs register-task-definition   --cli-input-json file://task-definition.json

# Gitで変更を管理する
git add task-definition.json
git commit -m "Update myapp-task: increase memory from 1024 to 2048"

# ALB用セキュリティグループ（インターネットからの80/443を受け入れる）
aws ec2 create-security-group   --group-name myapp-alb-sg   --description "Security group for ALB"   --vpc-id vpc-0123456789abcdef0

# ALB SGにインターネットからのHTTPS（443）を許可する
aws ec2 authorize-security-group-ingress   --group-id sg-alb-xxxxxxxx   --protocol tcp --port 443   --cidr 0.0.0.0/0

# ECSタスク用セキュリティグループ（ALBのSGからのみコンテナポートを受け入れる）
aws ec2 create-security-group   --group-name myapp-ecs-sg   --description "Security group for ECS Fargate tasks"   --vpc-id vpc-0123456789abcdef0

# ECSタスクSGへの許可：ソースをALBのSGに限定する（0.0.0.0/0は絶対に使わない）
aws ec2 authorize-security-group-ingress   --group-id sg-ecs-xxxxxxxx   --protocol tcp --port 8080   --source-group sg-alb-xxxxxxxx

# ターゲットグループを作成する（FargateはIPターゲット）
aws elbv2 create-target-group   --name myapp-tg   --protocol HTTP   --port 8080   --vpc-id vpc-0123456789abcdef0   --target-type ip   --health-check-path /health   --health-check-interval-seconds 30   --healthy-threshold-count 2   --unhealthy-threshold-count 3

# 出力例
{
    "TargetGroups": [
        {
            "TargetGroupArn": "arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/myapp-tg/abc123def456",
            "TargetGroupName": "myapp-tg",
            "Protocol": "HTTP",
            "Port": 8080,
            "HealthCheckPath": "/health",
            ...
        }
    ]
}

# ECSサービスを作成する（ALBと連携・マルチAZ・デプロイcircuit breaker有効）
aws ecs create-service   --cluster myapp-cluster   --service-name myapp-service   --task-definition myapp-task:1   --desired-count 2   --launch-type FARGATE   --network-configuration "awsvpcConfiguration={
    subnets=[subnet-0a1b2c3d4e,subnet-0f1e2d3c4b],
    securityGroups=[sg-ecs-xxxxxxxx],
    assignPublicIp=DISABLED
  }"   --load-balancers "targetGroupArn=arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/myapp-tg/abc123,containerName=myapp,containerPort=8080"   --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true},maximumPercent=200,minimumHealthyPercent=100"

# ECSサービスの起動状態を確認する
aws ecs describe-services   --cluster myapp-cluster   --services myapp-service   --query 'services[0].{Status:status,Running:runningCount,Desired:desiredCount,Pending:pendingCount}'

# 正常な出力例
{
    "Status": "ACTIVE",
    "Running": 2,
    "Desired": 2,
    "Pending": 0
}

# タスク配置戦略を確認する
aws ecs describe-services   --cluster myapp-cluster   --services myapp-service   --query 'services[0].placementStrategy'

# AZ均等分散の配置戦略を設定する（update-service）
aws ecs update-service   --cluster myapp-cluster   --service myapp-service   --placement-strategy "[{"type":"spread","field":"attribute:ecs.availability-zone"}]"

# ECSサービスをAuto Scalingのターゲットとして登録する
aws application-autoscaling register-scalable-target   --service-namespace ecs   --scalable-dimension ecs:service:DesiredCount   --resource-id service/myapp-cluster/myapp-service   --min-capacity 2   --max-capacity 10

# CPU使用率70%を目標にするターゲットトラッキングポリシーを設定する
aws application-autoscaling put-scaling-policy   --service-namespace ecs   --scalable-dimension ecs:service:DesiredCount   --resource-id service/myapp-cluster/myapp-service   --policy-name myapp-cpu-scaling   --policy-type TargetTrackingScaling   --target-tracking-scaling-policy-configuration '{
    "TargetValue": 70.0,
    "PredefinedMetricSpecification": {
      "PredefinedMetricType": "ECSServiceAverageCPUUtilization"
    },
    "ScaleOutCooldown": 60,
    "ScaleInCooldown": 300
  }'

# メモリ使用率80%でもスケールするポリシーを追加する（CPU・メモリの両方を監視）
aws application-autoscaling put-scaling-policy   --service-namespace ecs   --scalable-dimension ecs:service:DesiredCount   --resource-id service/myapp-cluster/myapp-service   --policy-name myapp-memory-scaling   --policy-type TargetTrackingScaling   --target-tracking-scaling-policy-configuration '{
    "TargetValue": 80.0,
    "PredefinedMetricSpecification": {
      "PredefinedMetricType": "ECSServiceAverageMemoryUtilization"
    },
    "ScaleOutCooldown": 60,
    "ScaleInCooldown": 300
  }'

# 実行ロールに必要な最低限のポリシー（AWSマネージドポリシー）
# AmazonECSTaskExecutionRolePolicy に以下が含まれる
# - ecr:GetAuthorizationToken
# - ecr:BatchGetImage
# - logs:CreateLogStream
# - logs:PutLogEvents

# SecretsManagerを使う場合は追加で以下が必要
# - secretsmanager:GetSecretValue
# - kms:Decrypt（KMSで暗号化している場合）

# 実行ロールの信頼ポリシー（ecs-tasks.amazonaws.com が引き受ける）
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "ecs-tasks.amazonaws.com"},
    "Action": "sts:AssumeRole"
  }]
}

# タスクロールの作成例（S3とDynamoDBを使うアプリケーション用）
aws iam create-role   --role-name myapp-task-role   --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "ecs-tasks.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

# タスクロールに最小権限ポリシーをアタッチする
# 例: S3バケットへのPUTのみ許可（GetやDeleteは付与しない）
aws iam put-role-policy   --role-name myapp-task-role   --policy-name myapp-s3-put   --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "arn:aws:s3:::myapp-uploads/*"
    }]
  }'

# ECRイメージpullに必要なVPCエンドポイントを確認する
aws ec2 describe-vpc-endpoints   --filters "Name=vpc-id,Values=vpc-0123456789abcdef0"   --query 'VpcEndpoints[*].{service:ServiceName,state:State}'

# ECRのイメージpullに必要な3つのエンドポイント
# - com.amazonaws.ap-northeast-1.ecr.dkr  → Dockerイメージの取得
# - com.amazonaws.ap-northeast-1.ecr.api  → ECR API呼び出し
# - com.amazonaws.ap-northeast-1.s3       → ECRレイヤーの取得（S3バケット経由）

# CloudWatch Logsへの書き込みに必要
# - com.amazonaws.ap-northeast-1.logs

# SecretsManagerを使う場合も必要
# - com.amazonaws.ap-northeast-1.secretsmanager

# 停止したタスクの停止理由を確認する
aws ecs describe-tasks   --cluster myapp-cluster   --tasks arn:aws:ecs:ap-northeast-1:123456789012:task/myapp-cluster/a1b2c3d4   --query 'tasks[0].{status:lastStatus,stopCode:stopCode,reason:stoppedReason}'

# 出力例（実行ロールの権限不足の場合）
{
    "status": "STOPPED",
    "stopCode": "TaskFailedToStart",
    "reason": "CannotPullContainerError: pull image manifest has been retried 5 time(s): ..."
}

# CloudWatch Logsでコンテナのエラーログを確認する
aws logs get-log-events   --log-group-name /ecs/myapp   --log-stream-name ecs/myapp/a1b2c3d4   --limit 50

# ターゲットグループのヘルスチェック状態を確認する
aws elbv2 describe-target-health   --target-group-arn arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/myapp-tg/abc123   --query 'TargetHealthDescriptions[*].{id:Target.Id,port:Target.Port,state:TargetHealth.State,reason:TargetHealth.Reason}'

# 出力例（unhealthyの場合）
[
    {
        "id": "10.0.1.45",
        "port": 8080,
        "state": "unhealthy",
        "reason": "Target.ResponseCodeMismatch"
    }
]

# プライベートサブネットのルートテーブルを確認する
# 0.0.0.0/0 がNATゲートウェイ（nat-xxxxxxxxx）に向いているか確認
aws ec2 describe-route-tables   --filters "Name=association.subnet-id,Values=subnet-0a1b2c3d4e"   --query 'RouteTables[0].Routes[*].{dest:DestinationCidrBlock,gw:GatewayId,nat:NatGatewayId}'

# 出力例（正常な場合）
[
    {"dest": "10.0.0.0/16", "gw": "local",          "nat": null},
    {"dest": "0.0.0.0/0",   "gw": null,              "nat": "nat-0abc12345def67890"}
]

# VPCエンドポイント経由でECRにアクセスする場合は以下のエンドポイントを作成する
# - com.amazonaws.ap-northeast-1.ecr.dkr  （イメージpull）
# - com.amazonaws.ap-northeast-1.ecr.api  （API呼び出し）
# - com.amazonaws.ap-northeast-1.s3       （ECRレイヤーの取得）
# - com.amazonaws.ap-northeast-1.logs     （CloudWatch Logsへの書き込み）
# - com.amazonaws.ap-northeast-1.secretsmanager  （シークレット取得）
aws ec2 describe-vpc-endpoints   --filters "Name=vpc-id,Values=vpc-0123456789abcdef0"   --query 'VpcEndpoints[*].{service:ServiceName,state:State}'

# ECSサービスのイベントを確認する（直近の10件）
aws ecs describe-services   --cluster myapp-cluster   --services myapp-service   --query 'services[0].events[:10].{createdAt:createdAt,message:message}'

# 出力例（ヘルスチェック失敗でタスクが入れ替わり続けている場合）
[
    {
        "createdAt": "2024-01-15T10:23:45+09:00",
        "message": "(service myapp-service) (task a1b2c3d4) failed container health checks."
    },
    {
        "createdAt": "2024-01-15T10:23:20+09:00",
        "message": "(service myapp-service) registered 1 targets in (target-group arn:...)"
    }
]

# ターゲットグループのプロトコルを確認する
aws elbv2 describe-target-groups   --names myapp-tg   --query 'TargetGroups[0].{Protocol:Protocol,TargetType:TargetType,Port:Port}'

# 出力例（間違ってTCPになっている場合）
{
    "Protocol": "TCP",
    "TargetType": "ip",
    "Port": 8080
}

# 修正方法: ターゲットグループを削除して再作成する（protocolはHTTPを指定）
aws elbv2 delete-target-group   --target-group-arn arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/myapp-tg/abc123

aws elbv2 create-target-group   --name myapp-tg   --protocol HTTP   --port 8080   --vpc-id vpc-0123456789abcdef0   --target-type ip   --health-check-path /health