Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource Types Reference » AWS::ECS::Service

AWS::ECS::Service

The AWS::ECS::Service resource creates an Amazon Elastic Container Service (Amazon ECS) service that runs and maintains the requested number of tasks and associated load balancers.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "Type" : "AWS::ECS::Service",
  "Properties" : {
    "Cluster" : String,
    "DeploymentConfiguration" : DeploymentConfiguration,
    "DesiredCount" : Integer,
    "HealthCheckGracePeriodSeconds" : Integer,
    "LaunchType" : String,
    "LoadBalancers" : [ Load Balancer Objects, ... ],
    "NetworkConfiguration" : NetworkConfiguration,
    "PlacementConstraints" : [ PlacementConstraints, ... ],
    "Role" : String,
    "PlacementStrategies" : [ PlacementStrategies, ... ],
    "PlatformVersion" : String,
    "SchedulingStrategy" : String,
    "ServiceName" : String,
    "ServiceRegistries" : [ ServiceRegistry, ... ,
    "TaskDefinition" : String
  }
}

YAML

Type: AWS::ECS::Service
Properties: 
  Cluster: String
  DeploymentConfiguration:
    DeploymentConfiguration
  DesiredCount: Integer
  HealthCheckGracePeriodSeconds: Integer
  LaunchType: String
  LoadBalancers:
    - Load Balancer Objects, ...
  NetworkConfiguration: 
    NetworkConfiguration
  PlacementConstraints: 
   - PlacementConstraints, ...
  PlacementStrategies: 
   - PlacementStrategies, ...
  PlatformVersion: String
  Role: String 
  SchedulingStrategy: String
  ServiceName: String
  ServiceRegistries: 
   - ServiceRegistry
  TaskDefinition: String

Properties

For more information on properties and valid parameters, see CreateService in the Amazon Elastic Container Service API Reference.

Note

When you use Auto Scaling or Amazon Elastic Compute Cloud (Amazon EC2) to create container instances for an Amazon ECS cluster, the Amazon ECS service resource must have a dependency on the Auto Scaling group or the Amazon EC2 instances. This makes the container instances available and associates them with the Amazon ECS cluster before AWS CloudFormation creates the Amazon ECS service.

Cluster

The name or Amazon Resource Name (ARN) of the cluster that you want to run your Amazon ECS service on. If you do not specify a cluster, Amazon ECS uses the default cluster.

Required: No

Type: String

Update requires: Replacement

DeploymentConfiguration

Configures how many tasks run during a deployment.

Required: No

Type: Amazon Elastic Container Service Service DeploymentConfiguration

Update requires: No interruption

DesiredCount

The number of simultaneous tasks that you want to run on the cluster. Specify the tasks with the TaskDefinition property.

Required: Conditional. Required only when creating an Amazon ECS Service.

Type: Integer

Update requires: No interruption

HealthCheckGracePeriodSeconds

The period of time, in seconds, that the Amazon ECS service scheduler ignores unhealthy Elastic Load Balancing target health checks after a task has first started.

Required: No

Type: Integer

Update requires: No interruption

LaunchType

The launch type on which to run your service. If one is not specified, EC2 will be used by default. Valid values include EC2 and FARGATE.

Required: No

Type: String

Update requires: Replacement

LoadBalancers

A list of load balancer objects to associate with the cluster. If you specify the Role property, LoadBalancers must be specified as well. For information about the number of load balancers that you can specify per service, see Service Load Balancing in the Amazon Elastic Container Service Developer Guide.

Required: Conditional

Type: List of Amazon Elastic Container Service Service LoadBalancers

Update requires: Replacement

NetworkConfiguration

The network configuration for the service. This parameter is required for task definitions that use the awsvpc network mode to receive their own Elastic Network Interface, and it is not supported for other network modes. For more information, see Task Networking in the Amazon Elastic Container Service Developer Guide.

Required: No

Type: Amazon ECS Service NetworkConfiguration

Update requires: No interruption

PlacementConstraints

The placement constraints for the tasks in the service.

Required: No

Type: Amazon Elastic Container Service Service PlacementConstraint

Update requires: Replacement

PlacementStrategies

The placement strategies that determine how tasks for the service are placed.

Required: No

Type: Amazon Elastic Container Service Service PlacementStrategies

Update requires: Replacement

PlatformVersion

The platform version on which to run your service. If one is not specified, the latest version will be used by default.

Required: No

Type: String

Update requires: Replacement

Role

The name or ARN of an AWS Identity and Access Management (IAM) role that allows your Amazon ECS container agent to make calls to your load balancer.

Note

In some cases, you might need to add a dependency on the service role's policy. For more information, see IAM role policy in DependsOn Attribute.

Required: No

Type: String

Update requires: Replacement

SchedulingStrategy

The scheduling strategy to use for the service.

There are two service scheduler strategies available:

  • REPLICA: The replica scheduling strategy places and maintains the desired number of tasks across your cluster. By default, the service scheduler spreads tasks across Availability Zones. You can use task placement strategies and constraints to customize task placement decisions.

  • DAEMON: The daemon scheduling strategy deploys exactly one task on each container instance in your cluster. When using this strategy, do not specify a desired number of tasks or any task placement strategies.

Valid values include REPLICA and DAEMON.

Note

Fargate tasks do not support the DAEMON scheduling strategy

Required: No

Type: String

Update requires: Replacement

ServiceName

The name of your service. The name is limited to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores. Service names must be unique within a cluster, but you can have similarly named services in multiple clusters within a region or across multiple regions.

Required: No

Type: String

Update requires: Replacement

ServiceRegistries

Details of the service registry.

Required: No

Type: Amazon ECS Service ServiceRegistry

Update requires: Replacement

TaskDefinition

The ARN of the task definition (including the revision number) that you want to run on the cluster, such as arn:aws:ecs:us-east-1:123456789012:task-definition/mytask:3. You can't use :latest to specify a revision because it's ambiguous. For example, if AWS CloudFormation needed to roll back an update, it wouldn't know which revision to roll back to.

Required: Yes

Type: String

Update requires: Some interruptions

Return Values

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the ARN.

In the following sample, the Ref function returns the ARN of the MyECSService service, such as arn:aws:ecs:us-west-2:123456789012:service/sample-webapp. 

{ "Ref": "MyECSService" }

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

Name

The name of the Amazon ECS service, such as sample-webapp.

For more information about using Fn::GetAtt, see Fn::GetAtt.

Examples

Define a Basic Amazon ECS Service

The following examples define an Amazon ECS service that uses a cluster and task definition that are declared elsewhere in the same template.

JSON

"WebApp": {
  "Type": "AWS::ECS::Service",
  "Properties" : {
    "Cluster": { "Ref": "cluster" },
    "DesiredCount": { "Ref": "desiredcount" },
    "TaskDefinition" : { "Ref": "taskdefinition" }
  }
}

YAML

WebApp: 
  Type: AWS::ECS::Service
  Properties: 
    Cluster: 
      Ref: "cluster"
    DesiredCount: 
      Ref: "desiredcount"
    TaskDefinition: 
      Ref: "taskdefinition"

Associate an Application Load Balancer with a Service

The following example associates an Application Load Balancer with an Amazon ECS service by referencing an AWS::ElasticLoadBalancingV2::TargetGroup resource.

Note

The Amazon ECS service requires an explicit dependency on the Application load balancer listener rule and the Application load balancer listener. This prevents the service from starting before the listener is ready.

JSON

"service" : {
  "Type" : "AWS::ECS::Service",
  "DependsOn": ["Listener"],
  "Properties" : {
    "Role" : { "Ref" : "ECSServiceRole" },
    "TaskDefinition" : { "Ref" : "taskdefinition" },
    "DesiredCount" : "1",
    "LoadBalancers" : [{
      "TargetGroupArn" : { "Ref" : "TargetGroup" },
      "ContainerPort" : "80",
      "ContainerName" : "sample-app"
    }],
    "Cluster" : { "Ref" : "ECSCluster" }
  }
}

YAML

service:
  Type: AWS::ECS::Service
  DependsOn:
  - Listener
  Properties:
    Role:
      Ref: ECSServiceRole
    TaskDefinition:
      Ref: taskdefinition
    DesiredCount: 1
    LoadBalancers:
    - TargetGroupArn:
        Ref: TargetGroup
      ContainerPort: 80
      ContainerName: sample-app
    Cluster:
      Ref: ECSCluster

Define a Service with a Health Check Grace Period

The following example defines a service with a parameter that enables users to specify how many seconds that the Amazon ECS service scheduler should ignore unhealthy Elastic Load Balancing target health checks after a task has first started.

JSON

{
  "AWSTemplateFormatVersion" : "2010-09-09",
  "Description" : "Creating ECS service",
  "Parameters": {
    "AppName": {
      "Type":"String",
      "Description": "Name of app requiring ELB exposure",
      "Default": "simple-app"
    },
    "AppContainerPort": {
      "Type":"Number",
      "Description": "Container port of app requiring ELB exposure",
      "Default": "80"
    },
    "AppHostPort": {
      "Type":"Number",
      "Description": "Host port of app requiring ELB exposure",
      "Default": "80"
    },
    "ServiceName": {
      "Type": "String"
    },
    "LoadBalancerName": {
      "Type": "String"
    },
    "HealthCheckGracePeriodSeconds": {
      "Type": "String"
    }
  },
  "Resources": {
    "cluster": {
      "Type": "AWS::ECS::Cluster"
    },
    "taskdefinition": {
      "Type": "AWS::ECS::TaskDefinition",
      "Properties" : {
        "ContainerDefinitions" : [
          {
            "Name": {"Ref": "AppName"},
            "MountPoints": [
              {
                "SourceVolume": "my-vol",
                "ContainerPath": "/var/www/my-vol"
              }
            ],
            "Image":"amazon/amazon-ecs-sample",
            "Cpu": "10",
            "PortMappings":[
              {
                "ContainerPort": {"Ref":"AppContainerPort"},
                "HostPort": {"Ref":"AppHostPort"}
              }
            ],
            "EntryPoint": [
              "/usr/sbin/apache2",
              "-D",
              "FOREGROUND"
            ],
            "Memory":"500",
            "Essential": "true"
          },
          {
            "Name": "busybox",
            "Image": "busybox",
            "Cpu": "10",
            "EntryPoint": [
              "sh",
              "-c"
            ],
            "Memory": "500",
            "Command": [
              "/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1; done\""
            ],
            "Essential" : "false",
            "VolumesFrom": [
              {
                "SourceContainer": {"Ref":"AppName"}
              }
            ]
          }
        ],
        "Volumes": [
          {
            "Host": {
              "SourcePath": "/var/lib/docker/vfs/dir/"
            },
            "Name": "my-vol"
          }
        ]
      }
    },
    "service": {
      "Type": "AWS::ECS::Service",
      "Properties" : {
        "Cluster": {"Ref": "cluster"},
        "DeploymentConfiguration": {
          "MaximumPercent": 200,
          "MinimumHealthyPercent": 100
        },
        "DesiredCount": 0,
        "HealthCheckGracePeriodSeconds": {"Ref": "HealthCheckGracePeriodSeconds"},
        "LoadBalancers": [{
          "ContainerName": {"Ref" : "AppName"},
          "ContainerPort": {"Ref":"AppContainerPort"},
          "LoadBalancerName": {"Ref": "elb"}
        }],
        "PlacementStrategies": [{
          "Type" : "binpack",
          "Field": "memory"
        }, {
          "Type": "spread",
          "Field": "host"
        }],
        "PlacementConstraints": [{
          "Type": "memberOf",
          "Expression": "attribute:ecs.availability-zone != us-east-1d"
        }, {
          "Type": "distinctInstance"
        }],
        "TaskDefinition" : {"Ref":"taskdefinition"},
        "ServiceName": {"Ref": "ServiceName"},
        "Role": {"Ref": "Role"}
      }
    },
    "elb": {
      "Type": "AWS::ElasticLoadBalancing::LoadBalancer",
      "Properties": {
        "LoadBalancerName": {"Ref": "LoadBalancerName"},
        "Listeners": [{
          "InstancePort": {"Ref": "AppHostPort"},
          "LoadBalancerPort": "80",
          "Protocol": "HTTP"
        }],
        "Subnets": [{"Ref":"Subnet1"}]
      },
      "DependsOn": "GatewayAttachment"
    },
    "VPC": {
      "Type": "AWS::EC2::VPC",
      "Properties": {
        "CidrBlock": "10.0.0.0/24"
      }
    },
    "Subnet1": {
      "Type": "AWS::EC2::Subnet",
      "Properties": {
        "VpcId": { "Ref": "VPC" },
        "CidrBlock": "10.0.0.0/25"
      }
    },
    "InternetGateway": {
      "Type": "AWS::EC2::InternetGateway"
    },
    "GatewayAttachment": {
      "Type": "AWS::EC2::VPCGatewayAttachment",
      "Properties": {
        "InternetGatewayId": {"Ref": "InternetGateway"},
        "VpcId": {"Ref": "VPC"}
      }
    },
    "Role": {
      "Type": "AWS::IAM::Role",
      "Properties": {
        "AssumeRolePolicyDocument": {
          "Version": "2008-10-17",
          "Statement": [
            {
              "Sid": "",
              "Effect": "Allow",
              "Principal": {
                "Service": "ecs.amazonaws.com"
              },
              "Action": "sts:AssumeRole"
            }
          ]
        },
        "ManagedPolicyArns": ["arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceRole"]
      }
    }
  },
  "Outputs" : {
    "Cluster": {
      "Value": {"Ref" : "cluster"}
    }
  }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Description: Creating ECS service
Parameters:
  AppName:
    Type: String
    Description: Name of app requiring ELB exposure
    Default: simple-app
  AppContainerPort:
    Type: Number
    Description: Container port of app requiring ELB exposure
    Default: '80'
  AppHostPort:
    Type: Number
    Description: Host port of app requiring ELB exposure
    Default: '80'
  ServiceName:
    Type: String
  LoadBalancerName:
    Type: String
  HealthCheckGracePeriodSeconds:
    Type: String
Resources:
  cluster:
    Type: AWS::ECS::Cluster
  taskdefinition:
    Type: AWS::ECS::TaskDefinition
    Properties:
      ContainerDefinitions:
        - Name: !Ref AppName
          MountPoints:
            - SourceVolume: my-vol
              ContainerPath: /var/www/my-vol
          Image: amazon/amazon-ecs-sample
          Cpu: '10'
          PortMappings:
            - ContainerPort: !Ref AppContainerPort
              HostPort: !Ref AppHostPort
          EntryPoint:
            - /usr/sbin/apache2
            - '-D'
            - FOREGROUND
          Memory: '500'
          Essential: 'true'
        - Name: busybox
          Image: busybox
          Cpu: '10'
          EntryPoint:
            - sh
            - '-c'
          Memory: '500'
          Command:
            - >-
              /bin/sh -c "while true; do /bin/date > /var/www/my-vol/date; sleep
              1; done"
          Essential: 'false'
          VolumesFrom:
            - SourceContainer: !Ref AppName
      Volumes:
        - Host:
            SourcePath: /var/lib/docker/vfs/dir/
          Name: my-vol
  service:
    Type: AWS::ECS::Service
    Properties:
      Cluster: !Ref cluster
      DeploymentConfiguration:
        MaximumPercent: 200
        MinimumHealthyPercent: 100
      DesiredCount: 0
      HealthCheckGracePeriodSeconds: !Ref HealthCheckGracePeriodSeconds
      LoadBalancers:
        - ContainerName: !Ref AppName
          ContainerPort: !Ref AppContainerPort
          LoadBalancerName: !Ref elb
      PlacementStrategies:
        - Type: binpack
          Field: memory
        - Type: spread
          Field: host
      PlacementConstraints:
        - Type: memberOf
          Expression: 'attribute:ecs.availability-zone != us-east-1d'
        - Type: distinctInstance
      TaskDefinition: !Ref taskdefinition
      ServiceName: !Ref ServiceName
      Role: !Ref Role
  elb:
    Type: AWS::ElasticLoadBalancing::LoadBalancer
    Properties:
      LoadBalancerName: !Ref LoadBalancerName
      Listeners:
        - InstancePort: !Ref AppHostPort
          LoadBalancerPort: '80'
          Protocol: HTTP
      Subnets:
        - !Ref Subnet1
    DependsOn: GatewayAttachment
  VPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.0.0.0/24
  Subnet1:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VPC
      CidrBlock: 10.0.0.0/25
  InternetGateway:
    Type: AWS::EC2::InternetGateway
  GatewayAttachment:
    Type: AWS::EC2::VPCGatewayAttachment
    Properties:
      InternetGatewayId: !Ref InternetGateway
      VpcId: !Ref VPC
  Role:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: 2008-10-17
        Statement:
          - Sid: ''
            Effect: Allow
            Principal:
              Service: ecs.amazonaws.com
            Action: 'sts:AssumeRole'
      ManagedPolicyArns:
        - 'arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceRole'
Outputs:
  Cluster:
    Value: !Ref cluster

More Info