@deftai/directive-content 0.55.0

package/deployments/aws/via-ecs-fargate.md

@@ -0,0 +1,561 @@
+# Deploy via ECS Fargate
+
+Deploy containerized applications using Amazon ECS (Elastic Container Service) with Fargate. Managed container orchestration without server management.
+
+## Overview
+
+ECS Fargate provides serverless container compute:
+- **No Infrastructure Management**: No EC2 instances to manage
+- **Task Definitions**: Define containers declaratively
+- **Service Auto-scaling**: Scale based on metrics
+- **Load Balancer Integration**: ALB/NLB built-in
+- **VPC Networking**: Full networking control
+
+## Prerequisites
+
+- AWS account with IAM permissions
+- Docker image in ECR or public registry
+- AWS CLI installed
+- ECS CLI (optional but recommended)
+
+## Quick Start
+
+### 1. Create ECR Repository and Push Image
+
+```bash
+# Create repository
+aws ecr create-repository --repository-name my-app
+
+# Login to ECR
+aws ecr get-login-password --region us-east-1 | \
+  docker login --username AWS --password-stdin \
+  ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com
+
+# Build and push
+docker build -t my-app .
+docker tag my-app:latest ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/my-app:latest
+docker push ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/my-app:latest
+```
+
+### 2. Create Task Definition
+
+```json
+{
+  "family": "my-app",
+  "networkMode": "awsvpc",
+  "requiresCompatibilities": ["FARGATE"],
+  "cpu": "256",
+  "memory": "512",
+  "containerDefinitions": [
+    {
+      "name": "app",
+      "image": "ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/my-app:latest",
+      "portMappings": [
+        {
+          "containerPort": 8080,
+          "protocol": "tcp"
+        }
+      ],
+      "environment": [
+        {
+          "name": "APP_ENV",
+          "value": "production"
+        }
+      ],
+      "logConfiguration": {
+        "logDriver": "awslogs",
+        "options": {
+          "awslogs-group": "/ecs/my-app",
+          "awslogs-region": "us-east-1",
+          "awslogs-stream-prefix": "ecs"
+        }
+      }
+    }
+  ],
+  "executionRoleArn": "arn:aws:iam::ACCOUNT_ID:role/ecsTaskExecutionRole",
+  "taskRoleArn": "arn:aws:iam::ACCOUNT_ID:role/ecsTaskRole"
+}
+```
+
+```bash
+# Register task definition
+aws ecs register-task-definition --cli-input-json file://task-definition.json
+```
+
+### 3. Create ECS Cluster
+
+```bash
+aws ecs create-cluster --cluster-name my-cluster
+```
+
+### 4. Create Service with Load Balancer
+
+```bash
+aws ecs create-service \
+  --cluster my-cluster \
+  --service-name my-app \
+  --task-definition my-app:1 \
+  --desired-count 2 \
+  --launch-type FARGATE \
+  --network-configuration "awsvpcConfiguration={
+    subnets=[subnet-xxx,subnet-yyy],
+    securityGroups=[sg-xxx],
+    assignPublicIp=ENABLED
+  }" \
+  --load-balancers "targetGroupArn=arn:aws:elasticloadbalancing:...,containerName=app,containerPort=8080"
+```
+
+## Task Definition Patterns
+
+### Basic Web Application
+
+```json
+{
+  "family": "web-app",
+  "networkMode": "awsvpc",
+  "requiresCompatibilities": ["FARGATE"],
+  "cpu": "1024",
+  "memory": "2048",
+  "containerDefinitions": [
+    {
+      "name": "nginx",
+      "image": "nginx:latest",
+      "portMappings": [
+        {
+          "containerPort": 80
+        }
+      ],
+      "dependsOn": [
+        {
+          "containerName": "app",
+          "condition": "START"
+        }
+      ]
+    },
+    {
+      "name": "app",
+      "image": "my-app:latest",
+      "portMappings": [
+        {
+          "containerPort": 8080
+        }
+      ],
+      "environment": [
+        {"name": "PORT", "value": "8080"}
+      ]
+    }
+  ]
+}
+```
+
+### With Secrets from Secrets Manager
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "app",
+      "image": "my-app:latest",
+      "secrets": [
+        {
+          "name": "DB_PASSWORD",
+          "valueFrom": "arn:aws:secretsmanager:region:account:secret:db-password-xxx"
+        },
+        {
+          "name": "API_KEY",
+          "valueFrom": "arn:aws:ssm:region:account:parameter/api-key"
+        }
+      ]
+    }
+  ],
+  "executionRoleArn": "arn:aws:iam::account:role/ecsTaskExecutionRole"
+}
+```
+
+### With EFS Volumes
+
+```json
+{
+  "family": "app-with-storage",
+  "volumes": [
+    {
+      "name": "shared-data",
+      "efsVolumeConfiguration": {
+        "fileSystemId": "fs-xxxxx",
+        "transitEncryption": "ENABLED",
+        "authorizationConfig": {
+          "accessPointId": "fsap-xxxxx"
+        }
+      }
+    }
+  ],
+  "containerDefinitions": [
+    {
+      "name": "app",
+      "mountPoints": [
+        {
+          "sourceVolume": "shared-data",
+          "containerPath": "/data",
+          "readOnly": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Service Configuration
+
+### Auto-scaling
+
+```bash
+# Register scalable target
+aws application-autoscaling register-scalable-target \
+  --service-namespace ecs \
+  --resource-id service/my-cluster/my-app \
+  --scalable-dimension ecs:service:DesiredCount \
+  --min-capacity 2 \
+  --max-capacity 10
+
+# CPU-based scaling
+aws application-autoscaling put-scaling-policy \
+  --service-namespace ecs \
+  --scalable-dimension ecs:service:DesiredCount \
+  --resource-id service/my-cluster/my-app \
+  --policy-name cpu-scaling \
+  --policy-type TargetTrackingScaling \
+  --target-tracking-scaling-policy-configuration '{
+    "TargetValue": 75.0,
+    "PredefinedMetricSpecification": {
+      "PredefinedMetricType": "ECSServiceAverageCPUUtilization"
+    },
+    "ScaleInCooldown": 300,
+    "ScaleOutCooldown": 60
+  }'
+```
+
+### Load Balancer Integration
+
+```bash
+# Create Application Load Balancer
+aws elbv2 create-load-balancer \
+  --name my-alb \
+  --subnets subnet-xxx subnet-yyy \
+  --security-groups sg-xxx \
+  --scheme internet-facing \
+  --type application
+
+# Create target group
+aws elbv2 create-target-group \
+  --name my-targets \
+  --protocol HTTP \
+  --port 80 \
+  --vpc-id vpc-xxx \
+  --target-type ip \
+  --health-check-path /health
+
+# Create listener
+aws elbv2 create-listener \
+  --load-balancer-arn arn:aws:elasticloadbalancing:... \
+  --protocol HTTP \
+  --port 80 \
+  --default-actions Type=forward,TargetGroupArn=arn:aws:elasticloadbalancing:...
+```
+
+## Infrastructure as Code
+
+### CloudFormation Template
+
+```yaml
+# ecs-stack.yaml
+Resources:
+  ECSCluster:
+    Type: AWS::ECS::Cluster
+    Properties:
+      ClusterName: my-cluster
+      
+  TaskDefinition:
+    Type: AWS::ECS::TaskDefinition
+    Properties:
+      Family: my-app
+      NetworkMode: awsvpc
+      RequiresCompatibilities:
+        - FARGATE
+      Cpu: '256'
+      Memory: '512'
+      ContainerDefinitions:
+        - Name: app
+          Image: !Sub ${AWS::AccountId}.dkr.ecr.${AWS::Region}.amazonaws.com/my-app:latest
+          PortMappings:
+            - ContainerPort: 8080
+          LogConfiguration:
+            LogDriver: awslogs
+            Options:
+              awslogs-group: !Ref LogGroup
+              awslogs-region: !Ref AWS::Region
+              awslogs-stream-prefix: ecs
+      ExecutionRoleArn: !GetAtt ExecutionRole.Arn
+      TaskRoleArn: !GetAtt TaskRole.Arn
+  
+  Service:
+    Type: AWS::ECS::Service
+    DependsOn: LoadBalancerListener
+    Properties:
+      ServiceName: my-app
+      Cluster: !Ref ECSCluster
+      TaskDefinition: !Ref TaskDefinition
+      DesiredCount: 2
+      LaunchType: FARGATE
+      NetworkConfiguration:
+        AwsvpcConfiguration:
+          Subnets:
+            - !Ref PrivateSubnet1
+            - !Ref PrivateSubnet2
+          SecurityGroups:
+            - !Ref ContainerSecurityGroup
+      LoadBalancers:
+        - ContainerName: app
+          ContainerPort: 8080
+          TargetGroupArn: !Ref TargetGroup
+```
+
+### Terraform
+
+```hcl
+# main.tf
+resource "aws_ecs_cluster" "main" {
+  name = "my-cluster"
+}
+
+resource "aws_ecs_task_definition" "app" {
+  family                   = "my-app"
+  network_mode             = "awsvpc"
+  requires_compatibilities = ["FARGATE"]
+  cpu                      = 256
+  memory                   = 512
+  execution_role_arn       = aws_iam_role.execution.arn
+  task_role_arn            = aws_iam_role.task.arn
+
+  container_definitions = jsonencode([
+    {
+      name  = "app"
+      image = "${data.aws_caller_identity.current.account_id}.dkr.ecr.us-east-1.amazonaws.com/my-app:latest"
+      portMappings = [
+        {
+          containerPort = 8080
+          protocol      = "tcp"
+        }
+      ]
+      logConfiguration = {
+        logDriver = "awslogs"
+        options = {
+          "awslogs-group"         = aws_cloudwatch_log_group.app.name
+          "awslogs-region"        = "us-east-1"
+          "awslogs-stream-prefix" = "ecs"
+        }
+      }
+    }
+  ])
+}
+
+resource "aws_ecs_service" "app" {
+  name            = "my-app"
+  cluster         = aws_ecs_cluster.main.id
+  task_definition = aws_ecs_task_definition.app.arn
+  desired_count   = 2
+  launch_type     = "FARGATE"
+
+  network_configuration {
+    subnets          = [aws_subnet.private1.id, aws_subnet.private2.id]
+    security_groups  = [aws_security_group.ecs_tasks.id]
+    assign_public_ip = false
+  }
+
+  load_balancer {
+    target_group_arn = aws_lb_target_group.app.arn
+    container_name   = "app"
+    container_port   = 8080
+  }
+}
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to ECS
+
+on:
+  push:
+    branches: [main]
+
+env:
+  AWS_REGION: us-east-1
+  ECR_REPOSITORY: my-app
+  ECS_SERVICE: my-app
+  ECS_CLUSTER: my-cluster
+  CONTAINER_NAME: app
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v3
+      
+      - uses: aws-actions/configure-aws-credentials@v2
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: ${{ env.AWS_REGION }}
+      
+      - name: Login to ECR
+        id: login-ecr
+        uses: aws-actions/amazon-ecr-login@v1
+      
+      - name: Build and push image
+        id: build-image
+        env:
+          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
+          IMAGE_TAG: ${{ github.sha }}
+        run: |
+          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
+          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
+          echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT
+      
+      - name: Update task definition
+        id: task-def
+        uses: aws-actions/amazon-ecs-render-task-definition@v1
+        with:
+          task-definition: task-definition.json
+          container-name: ${{ env.CONTAINER_NAME }}
+          image: ${{ steps.build-image.outputs.image }}
+      
+      - name: Deploy to ECS
+        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
+        with:
+          task-definition: ${{ steps.task-def.outputs.task-definition }}
+          service: ${{ env.ECS_SERVICE }}
+          cluster: ${{ env.ECS_CLUSTER }}
+          wait-for-service-stability: true
+```
+
+## Monitoring & Logging
+
+### CloudWatch Container Insights
+
+```bash
+# Enable Container Insights
+aws ecs update-cluster-settings \
+  --cluster my-cluster \
+  --settings name=containerInsights,value=enabled
+```
+
+### Custom Metrics with FireLens
+
+```json
+{
+  "containerDefinitions": [
+    {
+      "name": "log_router",
+      "image": "amazon/aws-for-fluent-bit:latest",
+      "firelensConfiguration": {
+        "type": "fluentbit"
+      }
+    },
+    {
+      "name": "app",
+      "logConfiguration": {
+        "logDriver": "awsfirelens",
+        "options": {
+          "Name": "cloudwatch",
+          "region": "us-east-1",
+          "log_group_name": "/ecs/my-app",
+          "auto_create_group": "true"
+        }
+      }
+    }
+  ]
+}
+```
+
+## Best Practices
+
+1. **Use Private Subnets**: Run tasks in private subnets with NAT Gateway
+2. **Least Privilege IAM**: Separate execution and task roles
+3. **Resource Limits**: Set appropriate CPU/memory reservations
+4. **Health Checks**: Configure ALB health checks
+5. **Auto-scaling**: Set up target tracking policies
+6. **Secrets Management**: Use Secrets Manager, not environment variables
+7. **Logging**: Use CloudWatch Logs or FireLens
+8. **Tagging**: Tag all resources for cost tracking
+9. **Blue/Green Deployments**: Use CodeDeploy for zero-downtime
+10. **Cost Optimization**: Use Fargate Spot for non-critical workloads
+
+## Fargate Spot
+
+```json
+{
+  "capacityProviderStrategy": [
+    {
+      "capacityProvider": "FARGATE_SPOT",
+      "weight": 4,
+      "base": 0
+    },
+    {
+      "capacityProvider": "FARGATE",
+      "weight": 1,
+      "base": 2
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+### Tasks Won't Start
+
+```bash
+# Check service events
+aws ecs describe-services \
+  --cluster my-cluster \
+  --services my-app \
+  | jq '.services[0].events[:5]'
+
+# Check task status
+aws ecs list-tasks --cluster my-cluster --service-name my-app
+aws ecs describe-tasks --cluster my-cluster --tasks TASK_ARN
+```
+
+### Common Issues
+
+**CannotPullContainerError**
+- Check ECR permissions in execution role
+- Verify image exists and tag is correct
+
+**Resource Initialization Error**
+- Check VPC configuration (subnets, security groups)
+- Ensure NAT Gateway or VPC endpoints for private subnets
+
+**Health Check Failures**
+- Verify target group health check path
+- Check security group allows ALB → task traffic
+- Ensure app responds on correct port
+
+## Cost Optimization
+
+```bash
+# Use Fargate Spot (up to 70% savings)
+# Right-size CPU/memory
+# Use auto-scaling to minimize idle capacity
+# Consider EC2 launch type for predictable, always-on workloads
+```
+
+## References
+
+- [AWS ECS Documentation](https://docs.aws.amazon.com/ecs/)
+- [Fargate Documentation](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/AWS_Fargate.html)
+- [Task Definition Parameters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html)
+- [ECS Best Practices](https://docs.aws.amazon.com/AmazonECS/latest/bestpracticesguide/)