giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-aws/skills/aws-cloudformation/aws-cloudformation-task-ecs-deploy-gh
aws-cloudformation-task-ecs-deploy-gh
VerifiedProvides patterns to deploy ECS tasks and services with GitHub Actions CI/CD. Use when building Docker images, pushing to ECR, updating ECS task definitions, deploying ECS services, integrating with CloudFormation stacks, configuring AWS OIDC authentication for GitHub Actions, and implementing production-ready container deployment pipelines. Supports ECS deployments with proper security (OIDC or IAM keys), multi-environment support, blue/green deployments, ECR private repositories with image scanning, and CloudFormation infrastructure updates.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.9 KB |
| references/authentication.md | markdown | 6.6 KB |
| references/best-practices.md | markdown | 7.9 KB |
| references/deployment-strategies.md | markdown | 9.5 KB |
| references/ecr-and-task-definitions.md | markdown | 6.9 KB |
| references/examples.md | markdown | 63.3 KB |
| references/reference.md | markdown | 45.2 KB |
| references/workflow-examples.md | markdown | 5.2 KB |
references/best-practices.md
View on GitHub# Best Practices, Monitoring, and Troubleshooting
## Security Best Practices
### Use OIDC Authentication
OpenID Connect (OIDC) provides secure, passwordless authentication between GitHub Actions and AWS, eliminating the need for long-lived IAM credentials.
**Benefits:**
- No IAM access keys to manage or rotate
- Temporary credentials with limited lifetime
- Scoped permissions by repository/branch
- Centralized audit trail
### Implement Least Privilege IAM Roles
```yaml
Policies:
- PolicyName: ECSDeployPolicy
PolicyDocument:
Version: '2012-10-17'
Statement:
- Effect: Allow
Action:
- ecs:UpdateService
- ecs:RegisterTaskDefinition
Resource: !Sub 'arn:aws:ecs:${AWS::Region}:${AWS::AccountId}:service/cluster-name/*'
```
### Enable ECR Image Scanning
```yaml
ECRRepository:
Type: AWS::ECR::Repository
Properties:
ImageScanningConfiguration:
ScanOnPush: true
```
### Use AWS Secrets Manager
Never store secrets in GitHub repository or workflow files.
```yaml
secrets:
- Name: DB_PASSWORD
ValueFrom: arn:aws:secretsmanager:us-east-1:123456789012:secret:my-app/db-password
```
### VPC Endpoints for Private Networks
```yaml
ECRInterfaceEndpoint:
Type: AWS::EC2::VPCEndpoint
Properties:
ServiceName: !Sub 'com.amazonaws.${AWS::Region}.ecr.dkr'
VpcEndpointType: Interface
PrivateDnsEnabled: true
SubnetIds:
- !Ref PrivateSubnetA
SecurityGroupIds:
- !Ref EndpointSecurityGroup
```
## Performance Optimization
### Docker Layer Caching
```yaml
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build and push
uses: docker/build-push-action@v5
with:
cache-from: type=gha
cache-to: type=gha,mode=max
```
### Multi-Stage Builds
Minimize image size by using multi-stage Dockerfiles.
```dockerfile
# Build stage
FROM maven:3.8-openjdk-11 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package
# Runtime stage
FROM openjdk:11-jre-slim
COPY --from=build /app/target/*.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]
```
### Parallel Deployments
Deploy to multiple environments in parallel using matrix strategy.
```yaml
strategy:
matrix:
environment: [dev, staging, prod]
```
### Fargate Spot for Cost Savings
```yaml
CapacityProviderStrategy:
- Base: FARGATE_SPOT
Weight: 1
- Base: FARGATE
Weight: 3
```
## Cost Optimization
### ECR Lifecycle Policies
```yaml
LifecyclePolicy:
LifecyclePolicyText: |
{
"rules": [
{
"rulePriority": 1,
"description": "Expire untagged images older than 7 days",
"selection": {
"tagStatus": "untagged",
"countType": "sinceImagePushed",
"countUnit": "days",
"countNumber": 7
},
"action": {
"type": "expire"
}
},
{
"rulePriority": 2,
"description": "Keep last 30 tagged images",
"selection": {
"tagStatus": "tagged",
"tagPrefixList": ["v"],
"countType": "imageCountMoreThan",
"countNumber": 30
},
"action": {
"type": "expire"
}
}
]
}
```
### Right-Sized Task CPU and Memory
Monitor and adjust CPU/memory based on actual usage.
```yaml
AutoScalingTarget:
Type: AWS::ApplicationAutoScaling::ScalableTarget
Properties:
MaxCapacity: 10
MinCapacity: 2
ResourceId: !Sub 'service/${ECSCluster}/${ECSService}'
ScalableDimension: ecs:service:DesiredCount
ServiceNamespace: ecs
```
### Scheduled Scaling
```yaml
ScheduledAction:
Type: AWS::ApplicationAutoScaling::ScheduledAction
Properties:
ScheduledActionName: scale-up-during-business-hours
Schedule: 'cron(0 8 * * ? *)'
ScalableTargetAction:
MinCapacity: 5
MaxCapacity: 10
```
## Monitoring and Observability
### CloudWatch Container Insights
```yaml
Cluster:
Type: AWS::ECS::Cluster
Properties:
ClusterSettings:
- Name: containerInsights
Value: enabled
```
### Centralized Logging
```yaml
LogConfiguration:
LogDriver: awslogs
Options:
awslogs-group: !Ref LogGroup
awslogs-region: !Ref AWS::Region
awslogs-stream-prefix: ecs
```
### Health Check Configuration
```yaml
HealthCheckGracePeriodSeconds: 60
```
### CloudWatch Alarms
```yaml
CPUPercentageAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
MetricName: CPUUtilization
Namespace: AWS/ECS
Statistic: Average
Period: 300
EvaluationPeriods: 2
Threshold: 80
ComparisonOperator: GreaterThanThreshold
```
### X-Ray Tracing
```yaml
TracingConfiguration:
Mode: Active
```
## Troubleshooting
### Authentication Failures
**Symptoms**: `User is not authorized to perform action: ecs:UpdateService`
**Solutions**:
- Verify OIDC trust relationship matches GitHub organization/repository
- Check IAM role has proper permissions for ECR and ECS
- Ensure GitHub Actions repository has `id-token: write` permission
- Verify role assumption conditions match repository path
**Debug Commands**:
```yaml
- name: Debug AWS credentials
run: |
aws sts get-caller-identity
aws iam list-attached-role-policies --role-name github-actions-ecs-role
```
### Deployment Failures
**Symptoms**: Tasks fail to start or service never stabilizes
**Solutions**:
- Check CloudWatch Logs for application errors
- Verify task definition matches service requirements
- Ensure sufficient CPU/memory in Fargate cluster
- Review health check configuration
- Verify security group rules allow necessary traffic
**Debug Commands**:
```bash
aws ecs describe-services --cluster my-cluster --services my-service
aws ecs describe-tasks --cluster my-cluster --tasks <task-ids>
```
### ECR Push Failures
**Symptoms**: `denied: Your authorization token has expired` or `no basic creds`
**Solutions**:
- Verify repository exists and permissions are correct
- Check image tag format and registry URL
- Ensure Docker daemon is running in GitHub Actions runner
- Verify image size doesn't exceed ECR limits (10 GB per image layer)
### CloudFormation Rollback
**Symptoms**: Stack creation/update fails and rolls back
**Solutions**:
- Review stack events in AWS Console
- Check parameter values match resource constraints
- Verify IAM role has `cloudformation:UpdateStack` permission
- Enable termination protection for production stacks
- Check for resource quotas and limits
**Debug Commands**:
```bash
aws cloudformation describe-stack-events --stack-name my-stack --max-items 10
aws cloudformation describe-stack-resources --stack-name my-stack
```
### Task Stuck in PENDING State
**Symptoms**: Tasks remain in PENDING state and never start
**Solutions**:
- Check if there are sufficient resources in the VPC (subnets, ENIs)
- Verify security groups allow outbound traffic
- Check IAM task execution role has proper permissions
- Review task definition for misconfigurations
- Verify container image exists in ECR and is accessible
### Service Deployment Timeout
**Symptoms**: Deployment exceeds timeout and fails
**Solutions**:
- Increase deployment timeout with `deploy_timeout` parameter
- Adjust health check grace period
- Review application startup time
- Check if service is receiving enough traffic for health checks
- Verify load balancer target group is healthy
## Additional Monitoring Commands
### View Service Events
```bash
aws ecs describe-services --cluster my-cluster --services my-service --query 'services[0].events'
```
### View Task Logs
```bash
aws logs tail /ecs/my-app --follow
```
### View CloudWatch Metrics
```bash
aws cloudwatch get-metric-statistics \
--namespace AWS/ECS \
--metric-name CPUUtilization \
--dimensions Name=ServiceName,Value=my-service \
--statistic Average \
--period 300
```
### Check Deployment Status
```bash
aws ecs describe-services \
--cluster my-cluster \
--services my-service \
--query 'services[0].deployments[0]'
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |