Claude Code × AWS ECS/Fargate संपूर्ण गाइड | सुरक्षित कंटेनर डिप्लॉयमेंट

AWS पर containers चलाने के लिए ECS/Fargate अच्छा विकल्प है, खासकर जब आप EC2 instances manage नहीं करना चाहते। मुश्किल Dockerfile लिखना नहीं है। मुश्किल है ECR, task definitions, IAM roles, Secrets Manager, load balancing, CloudWatch Logs, health checks और cost control को सही तरीके से जोड़ना।

इस guide में Claude Code को unchecked autopilot नहीं, implementation assistant की तरह इस्तेमाल किया गया है। Task definition container की launch spec है, Fargate serverless runtime है जो container चलाता है, execution role ECS को image pull, secrets और logs की permission देता है, और task role application code को AWS API call करने की permission देता है।

Masa की एक real Fargate migration में पहला failure Docker की वजह से नहीं हुआ। App को boot होने में करीब 40 seconds लगते थे और ECS health check बहुत जल्दी चल गया। Claude Code files जल्दी लिख सकता है, लेकिन उसे startup time, private network, logs, rollback और IAM boundary साफ बतानी पड़ती है।

Target Architecture

Developer
  |
  | docker build / push
  v
Amazon ECR ----> Amazon ECS Service on AWS Fargate
                       |
                       | pulls secrets / writes logs
                       v
Secrets Manager     CloudWatch Logs
                       ^
                       |
Application Load Balancer -> /health -> Node.js container

Examples ap-northeast-1, existing VPC और existing ALB target group पर आधारित हैं। अगर network और ALB भी IaC से बनाना है, तो internal Claude Code × AWS CloudFormation/CDK guide देखें। Permission model के लिए पहले Claude Code × AWS IAM guide पढ़ना बेहतर है।

तीन practical use cases

Use case	Fargate क्यों फिट है	ध्यान देने वाली बात
SaaS REST API	ALB के पीछे दो या अधिक tasks रखकर rolling deploy कर सकते हैं	DB connections और health checks पहले design करें
Admin backend	EC2 patching और AMI management के बिना छोटा start	`desiredCount` 0 करने पर first request धीमी हो सकती है
API और batch के लिए same image	वही image service और `run-task` में use हो सकती है	task role को minimum permission दें

अगर workload छोटा और event-driven है, तो Claude Code × AWS Lambda guide आसान हो सकती है। Always-on HTTP, long requests, Docker parity या Lambda में मुश्किल runtime के लिए Fargate बेहतर है।

1. Health check वाली minimal API

पहले ऐसी app बनाएं जो locally चले। /health को ECS और ALB दोनों देखते हैं, इसलिए इसे lightweight रखें। अगर database थोड़ी देर slow है और /health 500 देता है, तो ECS healthy tasks भी replace कर सकता है।

{
  "scripts": {
    "start": "node src/server.js"
  },
  "dependencies": {
    "express": "^4.19.2"
  }
}

// src/server.js
const express = require("express");

const app = express();
const port = Number(process.env.PORT || 3000);

app.get("/health", (_req, res) => {
  res.status(200).json({
    ok: true,
    service: "myapp",
    time: new Date().toISOString(),
  });
});

app.get("/", (_req, res) => {
  res.json({ message: "Hello from ECS Fargate" });
});

app.listen(port, "0.0.0.0", () => {
  console.log(`myapp listening on ${port}`);
});

# Dockerfile
FROM node:22-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev

COPY src ./src
ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000

CMD ["node", "src/server.js"]

ECS पर जाने से पहले curl -f http://localhost:3000/health check करें। Claude Code को prompt देते समय लिखें कि ALB और ECS same health path use करेंगे, app 0.0.0.0 पर listen करेगी, और startup को startPeriod protect करेगा।

2. ECR में build और push

यह script जरूरत होने पर ECR repository बनाता है, login करता है, image build करता है और versioned tag push करता है। सिर्फ latest पर depend न करें, वरना rollback और audit मुश्किल हो जाते हैं।

set -euo pipefail

export AWS_REGION="ap-northeast-1"
export AWS_ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
export ECR_REPOSITORY="myapp"
export IMAGE_TAG="$(git rev-parse --short HEAD 2>/dev/null || date +%Y%m%d%H%M%S)"
export IMAGE_URI="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/${ECR_REPOSITORY}:${IMAGE_TAG}"

aws ecr describe-repositories \
  --repository-names "${ECR_REPOSITORY}" \
  --region "${AWS_REGION}" >/dev/null 2>&1 || \
aws ecr create-repository \
  --repository-name "${ECR_REPOSITORY}" \
  --image-scanning-configuration scanOnPush=true \
  --region "${AWS_REGION}"

aws ecr get-login-password --region "${AWS_REGION}" | \
  docker login --username AWS --password-stdin \
  "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

docker build -t "${IMAGE_URI}" .
docker push "${IMAGE_URI}"

echo "Pushed ${IMAGE_URI}"

Official ECR flow में भी get-login-password use होता है। CI में long-lived AWS access keys रखने के बजाय GitHub Actions OIDC और short-lived AWS credentials बेहतर हैं।

3. ECS task definition register करें

Fargate tasks awsvpc network mode use करती हैं। Secrets Manager value inject करते समय execution role को secretsmanager:GetSecretValue चाहिए। अगर secret customer-managed KMS key से encrypted है, तो kms:Decrypt भी चाहिए। task role application code के लिए है, image pull या logs setup के लिए नहीं।

set -euo pipefail

export AWS_REGION="ap-northeast-1"
export AWS_ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
export IMAGE_URI="${IMAGE_URI:?Run the ECR push script first}"
export EXECUTION_ROLE_ARN="arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole"
export TASK_ROLE_ARN="arn:aws:iam::${AWS_ACCOUNT_ID}:role/myapp-task-role"
export SECRET_ARN="arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:prod/myapp/DATABASE_URL"

aws logs create-log-group --log-group-name /ecs/myapp --region "${AWS_REGION}" 2>/dev/null || true
aws logs put-retention-policy --log-group-name /ecs/myapp --retention-in-days 30 --region "${AWS_REGION}"

cat > ecs-task-definition.json <<EOF
{
  "family": "myapp-task",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "${EXECUTION_ROLE_ARN}",
  "taskRoleArn": "${TASK_ROLE_ARN}",
  "runtimePlatform": {
    "cpuArchitecture": "X86_64",
    "operatingSystemFamily": "LINUX"
  },
  "containerDefinitions": [
    {
      "name": "app",
      "image": "${IMAGE_URI}",
      "essential": true,
      "portMappings": [
        { "containerPort": 3000, "hostPort": 3000, "protocol": "tcp" }
      ],
      "environment": [
        { "name": "NODE_ENV", "value": "production" },
        { "name": "PORT", "value": "3000" }
      ],
      "secrets": [
        { "name": "DATABASE_URL", "valueFrom": "${SECRET_ARN}" }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/myapp",
          "awslogs-region": "${AWS_REGION}",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "healthCheck": {
        "command": ["CMD-SHELL", "wget -qO- http://localhost:3000/health || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 60
      }
    }
  ]
}
EOF

aws ecs register-task-definition \
  --cli-input-json file://ecs-task-definition.json \
  --region "${AWS_REGION}"

startPeriod छोटा setting लगता है, लेकिन debug करने में महंगा पड़ता है। यह ECS को app boot होने से पहले container fail मानने से रोकता है।

4. Fargate service बनाएं

नीचे command existing private subnets, task security group और ALB target group use करती है। task security group को ALB security group से port 3000 traffic ही allow करना चाहिए।

set -euo pipefail

export AWS_REGION="ap-northeast-1"
export CLUSTER_NAME="myapp-cluster"
export SERVICE_NAME="myapp-service"
export TASK_FAMILY="myapp-task"
export SUBNET_1="subnet-xxxxxxxx"
export SUBNET_2="subnet-yyyyyyyy"
export TASK_SECURITY_GROUP="sg-xxxxxxxx"
export TARGET_GROUP_ARN="arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/myapp/abc123"

aws ecs create-cluster \
  --cluster-name "${CLUSTER_NAME}" \
  --region "${AWS_REGION}" >/dev/null

aws ecs create-service \
  --cluster "${CLUSTER_NAME}" \
  --service-name "${SERVICE_NAME}" \
  --task-definition "${TASK_FAMILY}" \
  --desired-count 2 \
  --launch-type FARGATE \
  --platform-version LATEST \
  --health-check-grace-period-seconds 90 \
  --network-configuration "awsvpcConfiguration={subnets=[${SUBNET_1},${SUBNET_2}],securityGroups=[${TASK_SECURITY_GROUP}],assignPublicIp=DISABLED}" \
  --load-balancers "targetGroupArn=${TARGET_GROUP_ARN},containerName=app,containerPort=3000" \
  --region "${AWS_REGION}"

aws ecs wait services-stable \
  --cluster "${CLUSTER_NAME}" \
  --services "${SERVICE_NAME}" \
  --region "${AWS_REGION}"

Private subnets में assignPublicIp=DISABLED होने पर भी task को ECR, CloudWatch Logs और Secrets Manager तक path चाहिए। NAT Gateway या VPC endpoints use करें। NAT आसान है, लेकिन छोटे test environment में cost का बड़ा हिस्सा बन सकता है।

5. CloudWatch Logs और ECS events देखें

ECS troubleshooting में service events, stopped task reasons और application logs तीनों देखना पड़ता है। Claude Code से diagnosis मांगते समय तीनों दें।

export AWS_REGION="ap-northeast-1"
export CLUSTER_NAME="myapp-cluster"
export SERVICE_NAME="myapp-service"

aws ecs describe-services \
  --cluster "${CLUSTER_NAME}" \
  --services "${SERVICE_NAME}" \
  --query "services[0].events[0:5].[createdAt,message]" \
  --output table \
  --region "${AWS_REGION}"

aws ecs list-tasks \
  --cluster "${CLUSTER_NAME}" \
  --service-name "${SERVICE_NAME}" \
  --desired-status STOPPED \
  --region "${AWS_REGION}"

aws logs tail /ecs/myapp \
  --follow \
  --since 10m \
  --region "${AWS_REGION}"

Common failures हैं: ECR pull blocked, secret access denied, ALB task security group तक नहीं पहुंच रहा, या app localhost पर listen कर रही है जबकि उसे 0.0.0.0 चाहिए।

Claude Code implementation prompt

Node.js API के लिए AWS ECS/Fargate deployment implementation बनाएं।

Context:
- Region: ap-northeast-1
- ECR repository: myapp
- Container port: 3000
- Health endpoint: /health
- ECS launch type: FARGATE
- Network mode: awsvpc
- Desired count: 2
- Task CPU/memory: 512 / 1024
- Secret: Secrets Manager से DATABASE_URL inject करें
- Logs: CloudWatch Logs /ecs/myapp, retention 30 days

Deliverables:
1. Production Dockerfile
2. ECR push के लिए bash script
3. ECS task definition register करने के लिए bash script
4. Fargate service create करने के लिए bash script
5. CloudWatch Logs inspect करने के लिए bash script
6. execution role और task role को अलग-अलग समझाना

Constraints:
- Pseudocode नहीं। Variables भरने के बाद AWS CLI से commands runnable हों।
- Secret values hardcode न करें।
- Task को public subnet में direct expose न करें।
- आखिर में official AWS documentation points list करें जिन्हें verify करना चाहिए।

Official AWS docs में check points

AWS Fargate guide: Fargate constraints और platform behavior।
Task definition parameters: awsvpc, CPU/memory और health check fields।
Task execution IAM role: ECR pull, logs और Secrets Manager permissions।
ECS logs to CloudWatch: awslogs driver setup।
AWS Fargate pricing: Region, vCPU, memory, extra ephemeral storage और running time से price बदलता है।
AWS regional service list: target Region में सभी services supported हैं या नहीं।

Concrete pitfalls

पहला pitfall execution role और task role mix करना है। ECR, logging और secret retrieval execution role में जाते हैं। DynamoDB, S3, SQS और application permissions task role में जाते हैं।

दूसरा secret की region mismatch है। ECS task, Secrets Manager secret और KMS key एक ही region में align होने चाहिए। Multi-region setup में secret ARN को environment-specific deploy variable बनाएं।

तीसरा cost है। Fargate usage-based है, लेकिन ALB, NAT Gateway, CloudWatch Logs और ECR storage भी bill में आते हैं। Test environments में log retention set करें, unused services stop करें और NAT usage देखें।

चौथा overly strict health check है। /health हल्का रखें और deep dependency checks को /ready या smoke test में रखें।

पांचवां image architecture है। Apple Silicon पर ARM64 image build करके task में X86_64 रखने से startup fail होगा। docker buildx build --platform linux/amd64 use करें या runtimePlatform align करें।

CTA और next step

Solo builders इन scripts को छोटी API में copy करके free Claude Code cheatsheet से prompts improve कर सकते हैं। Teams जिन्हें ECS, IAM, CI/CD, observability और rollback साथ design करना है, वे Claude Code training और consultation से शुरू करें। Reusable prompts और review material के लिए ClaudeCodeLab products देखें।

Summary

ECS/Fargate सिर्फ Docker image upload करने की जगह नहीं है। यह IAM, network, secrets, logs, health checks और cost का combined design problem है। Claude Code सबसे useful तब है जब आप पहले operating rules बताते हैं और फिर runnable files मांगते हैं।

इस workflow को practical रूप से try करने पर सबसे बड़ा improvement Dockerfile से नहीं, prompt से आया। Claude Code से execution role और task role अलग करने, CloudWatch Logs commands include करने और health check grace period set करने को साफ कहने पर वही failure दोहराया नहीं गया। First run में secret permission missing निकली, लेकिन ECS events और logs वापस Claude Code को देने पर IAM fix और redeploy steps एक ही pass में मिल गए।