AWS CloudFormation
User Guide (API Version 2010-05-15)

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