AWS CloudFormation ECS - Reference

AWS CloudFormation ECS - Reference

This reference guide contains detailed information about AWS CloudFormation resources, intrinsic functions, and configurations for ECS container infrastructure.

AWS::ECS::Cluster

Creates an Amazon ECS cluster.

Properties

ClusterSetting Structure

Example

Resources:
  ECSCluster:
    Type: AWS::ECS::Cluster
    Properties:
      ClusterName: !Sub "${AWS::StackName}-cluster"
      ClusterSettings:
        - Name: containerInsights
          Value: enabled
      Tags:
        - Key: Environment
          Value: !Ref Environment

Attributes

AWS::ECS::TaskDefinition

Creates a task definition for ECS.

Properties

ContainerDefinition Structure

PortMapping Structure

Secret Structure

LogConfiguration Structure

HealthCheck Structure

Example

Resources:
  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      Family: web-app
      Cpu: "512"
      Memory: "1024"
      NetworkMode: awsvpc
      RequiresCompatibilities:
        - EC2
        - FARGATE
      ExecutionRoleArn: !Ref TaskExecutionRole
      ContainerDefinitions:
        - Name: web
          Image: nginx:latest
          Cpu: 256
          Memory: 512
          PortMappings:
            - ContainerPort: 80
              Protocol: tcp
          Environment:
            - Name: ENV
              Value: !Ref Environment
          LogConfiguration:
            LogDriver: awslogs
            Options:
              awslogs-group: !Ref LogGroup
              awslogs-region: !Ref AWS::Region
              awslogs-stream-prefix: ecs
          HealthCheck:
            Command:
              - CMD-SHELL
              - curl -f http://localhost:80/health || exit 1
            Interval: 30
            Timeout: 5
            Retries: 3

Attributes

AWS::ECS::Service

Creates an Amazon ECS service.

Properties

DeploymentConfiguration Structure

DeploymentCircuitBreaker Structure

CapacityProviderStrategyItem Structure

NetworkConfiguration Structure

AwsVpcConfiguration Structure

LoadBalancer Structure

ServiceRegistry Structure

PlacementConstraint Structure

PlacementStrategy Structure

Example

Resources:
  EcsService:
    Type: AWS::ECS::Service
    Properties:
      ServiceName: !Sub "${AWS::StackName}-service"
      Cluster: !Ref ECSCluster
      TaskDefinition: !Ref TaskDefinition
      DesiredCount: 2
      LaunchType: FARGATE
      DeploymentConfiguration:
        MaximumPercent: 200
        MinimumHealthyPercent: 50
        DeploymentCircuitBreaker:
          Enable: true
          Rollback: true
      NetworkConfiguration:
        AwsvpcConfiguration:
          AssignPublicIp: DISABLED
          SecurityGroups:
            - !Ref EcsSecurityGroup
          Subnets: !Ref PrivateSubnets
      LoadBalancers:
        - ContainerName: web
          ContainerPort: 80
          TargetGroupArn: !Ref TargetGroup
      PropagateTags: SERVICE
      ServiceRegistries:
        - RegistryArn: !GetAtt ServiceDiscoveryService.Arn

Attributes

AWS::ECS::TaskSet

Creates a task set for an ECS service.

Properties

Scale Structure

Attributes

AWS::ECS::CapacityProvider

Creates a capacity provider for ECS.

Properties

AutoScalingGroupProvider Structure

ManagedScaling Structure

Example

Resources:
  CapacityProvider:
    Type: AWS::ECS::CapacityProvider
    Properties:
      Name: !Sub "${AWS::StackName}-capacity-provider"
      AutoScalingGroupProvider:
        AutoScalingGroupArn: !Ref AutoScalingGroup
        ManagedScaling:
          Status: ENABLED
          TargetCapacity: 80
          MinimumScalingStepSize: 1
          MaximumScalingStepSize: 10
        ManagedTerminationProtection: DISABLED

AWS::ApplicationAutoScaling::ScalableTarget

Creates a scalable target for ECS service auto scaling.

Properties

Example

Resources:
  ScalableTarget:
    Type: AWS::ApplicationAutoScaling::ScalableTarget
    Properties:
      MaxCapacity: 10
      MinCapacity: 2
      ResourceId: !Sub "service/${ClusterName}/${ServiceName}"
      RoleARN: !Ref AutoScalingRoleArn
      ScalableDimension: ecs:service:DesiredCount
      ServiceNamespace: ecs

AWS::ApplicationAutoScaling::ScalingPolicy

Creates a scaling policy for ECS.

Properties

TargetTrackingScalingPolicyConfiguration Structure

PredefinedMetricSpecification Structure

StepScalingPolicyConfiguration Structure

StepAdjustment Structure

Example

Resources:
  CpuScalingPolicy:
    Type: AWS::ApplicationAutoScaling::ScalingPolicy
    Properties:
      PolicyName: !Sub "${AWS::StackName}-cpu-scaling"
      PolicyType: TargetTrackingScaling
      ScalingTargetId: !Ref ScalableTarget
      TargetTrackingScalingPolicyConfiguration:
        PredefinedMetricSpecification:
          PredefinedMetricType: ECSServiceAverageCPUUtilization
        TargetValue: 70
        ScaleInCooldown: 300
        ScaleOutCooldown: 60

AWS::ServiceDiscovery::Service

Creates a service discovery service.

Properties

DnsConfig Structure

DnsRecord Structure

Example

Resources:
  ServiceDiscoveryService:
    Type: AWS::ServiceDiscovery::Service
    Properties:
      Name: web-app
      NamespaceId: !Ref ServiceDiscoveryNamespace
      DnsConfig:
        DnsRecords:
          - Type: A
            TTL: 60
      HealthCheckConfig:
        Type: HTTP
        ResourcePath: /health

Attributes

AWS::ServiceDiscovery::PrivateDnsNamespace

Creates a private DNS namespace.

Properties

Example

Resources:
  ServiceDiscoveryNamespace:
    Type: AWS::ServiceDiscovery::PrivateDnsNamespace
    Properties:
      Name: !Sub "${Environment}.internal"
      Vpc: !Ref VpcId

Attributes

AWS::CodeDeploy::BlueGreen

Creates a blue/green hook for ECS deployments.

Properties

TrafficRoutingConfig Structure

TimeBasedCanary Structure

TimeBasedLinear Structure

AdditionalOptions Structure

LifecycleEventHooks Structure

BlueGreenApplication Structure

BlueGreenTarget Structure

ECSAttributes Structure

TrafficRouting Structure

TrafficRoute Structure

Example

Hooks:
  BlueGreenHook:
    Type: AWS::CodeDeploy::BlueGreen
    Properties:
      TrafficRoutingConfig:
        Type: TimeBasedCanary
        TimeBasedCanary:
          StepPercentage: 15
          BakeTimeMins: 5
      AdditionalOptions:
        TerminationWaitTimeInMinutes: 5
      ServiceRole: !Ref CodeDeployRoleArn
      Applications:
        - Target:
            Type: AWS::ECS::Service
            LogicalID: EcsService
          ECSAttributes:
            TaskDefinitions:
              - TaskDefinitionBlue
              - TaskDefinitionGreen
            TaskSets:
              - TaskSetBlue
              - TaskSetGreen
            TrafficRouting:
              ProdTrafficRoute:
                Type: AWS::ElasticLoadBalancingV2::Listener
                LogicalID: ProductionListener
              TestTrafficRoute:
                Type: AWS::ElasticLoadBalancingV2::Listener
                LogicalID: TestListener
              TargetGroups:
                - BlueTargetGroup
                - GreenTargetGroup

AWS::ElasticLoadBalancingV2::TargetGroup

Creates a target group for ALB.

Properties

Matcher Structure

Example

Resources:
  BlueTargetGroup:
    Type: AWS::ElasticLoadBalancingV2::TargetGroup
    Properties:
      Name: !Sub "${AWS::StackName}-blue-tg"
      Port: 80
      Protocol: HTTP
      VpcId: !Ref VpcId
      HealthCheckPath: /health
      HealthCheckIntervalSeconds: 30
      HealthCheckTimeoutSeconds: 5
      HealthyThresholdCount: 2
      UnhealthyThresholdCount: 3
      Matcher:
        HttpCode: 200-499
      TargetType: ip

Attributes

AWS::ElasticLoadBalancingV2::Listener

Creates a listener for ALB.

Properties

Action Structure

Example

Resources:
  ProductionListener:
    Type: AWS::ElasticLoadBalancingV2::Listener
    Properties:
      DefaultActions:
        - Type: forward
          ForwardConfig:
            TargetGroupStickinessConfig:
              Enabled: true
              DurationSeconds: 3600
            TargetGroups:
              - TargetGroupArn: !Ref BlueTargetGroup
                Weight: 100
      LoadBalancerArn: !Ref ApplicationLoadBalancer
      Port: 80
      Protocol: HTTP

Intrinsic Functions Reference

!Ref

Returns the value of the specified parameter or resource.

# Reference a parameter
ClusterName: !Ref ClusterNameParam

# Reference a resource (returns the physical ID)
ClusterArn: !Ref ECSCluster

!GetAtt

Returns the value of an attribute from an ECS resource.

# Get the cluster ARN
ClusterArn: !GetAtt ECSCluster.Arn

# Get service ARN
ServiceArn: !GetAtt EcsService.Arn

# Get task definition ARN
TaskDefinitionArn: !Ref TaskDefinition

!Sub

Substitutes variables in an input string.

# With variable substitution
ClusterName: !Sub "${AWS::StackName}-cluster"

# With multiple variables
RoleArn: !Sub "arn:aws:iam::${AWS::AccountId}:role/${RoleName}"

!ImportValue

Imports values exported by other stacks.

# Import from another stack
ClusterArn: !ImportValue
  !Sub "${NetworkStackName}-ClusterArn"

!FindInMap

Returns the value from a mapping.

# Find in mapping
MemorySize: !FindInMap [EnvironmentConfig, !Ref Environment, Memory]

!If

Returns one value if condition is true, another if false.

# Conditional resource
DesiredCount: !If [IsProduction, 10, 2]

IAM Policy Templates for ECS

AmazonECSTaskExecutionRolePolicy

Policies:
  - AmazonECSTaskExecutionRolePolicy

Custom Policy for ECR

Policies:
  - PolicyName: EcrPullPolicy
    PolicyDocument:
      Version: "2012-10-17"
      Statement:
        - Effect: Allow
          Action:
            - ecr:GetDownloadUrlForLayer
            - ecr:BatchGetImage
            - ecr:BatchCheckLayerAvailability
          Resource: !Ref EcrRepositoryArn

Custom Policy for Secrets

Policies:
  - PolicyName: SecretsPolicy
    PolicyDocument:
      Version: "2012-10-17"
      Statement:
        - Effect: Allow
          Action:
            - secretsmanager:GetSecretValue
          Resource: !Ref SecretArn

Custom Policy for CloudWatch Logs

Policies:
  - PolicyName: CloudWatchLogsPolicy
    PolicyDocument:
      Version: "2012-10-17"
      Statement:
        - Effect: Allow
          Action:
            - logs:CreateLogStream
            - logs:PutLogEvents
          Resource: !GetAtt LogGroup.Arn

ECS Task Definition Parameters

CPU and Memory Values

Fargate CPU/Memory Combinations

Container Sizes

Common Tags for ECS

Resources:
  EcsService:
    Type: AWS::ECS::Service
    Properties:
      Tags:
        - Key: Environment
          Value: !Ref Environment
        - Key: Project
          Value: !Ref ProjectName
        - Key: Owner
          Value: team@example.com
        - Key: ManagedBy
          Value: CloudFormation
        - Key: CostCenter
          Value: "12345"
        - Key: Version
          Value: "1.0.0"

Limits and Quotas

ECS Limits

Fargate Limits

CloudWatch Limits

Health Check Best Practices

Health Check Command Examples

HealthCheck:
  Command:
    - CMD-SHELL
    - curl -f http://localhost:8080/health || exit 1
  Interval: 30
  Timeout: 5
  Retries: 3
  StartPeriod: 60

HTTP Health Check

HealthCheck:
  Command:
    - CMD-SHELL
    - wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

TCP Health Check

HealthCheck:
  Command:
    - CMD-SHELL
    - nc -z localhost 8080 || exit 1

Health Check Considerations

• Set StartPeriod to allow container initialization
• Keep Interval reasonable (15-30 seconds)
• Set Timeout shorter than interval
• Set Retries appropriately (2-3)
• Use specific endpoint for health checks