Menu
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 EC2 Container Service (Amazon ECS) service that runs and maintains the requested number of tasks and associated load balancers.

Topics

Syntax

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

JSON

Copy
{
  "Type" : "AWS::ECS::Service",
  "Properties" : {
    "Cluster" : String,
    "DeploymentConfiguration" : DeploymentConfiguration,
    "DesiredCount" : Integer,
    "LoadBalancers" : [ Load Balancer Objects, ... ],
    "PlacementConstraints" : [ PlacementConstraints, ... ],
    "Role" : String,
    "PlacementStrategies" : [ PlacementStrategies, ... ],
    "ServiceName" : String,
    "TaskDefinition" : String
  }
}

YAML

Copy
Type: "AWS::ECS::Service"
Properties: 
  Cluster: String
  DeploymentConfiguration:
    DeploymentConfiguration
  DesiredCount: Integer
  LoadBalancers:
    - Load Balancer Objects, ...
  PlacementConstraints: 
   - PlacementConstraints, ...
  PlacementStrategies: 
   - PlacementStrategies, ...
  Role: String
  ServiceName: String
  TaskDefinition: String

Properties

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 EC2 Container Service Service DeploymentConfiguration

Update requires: No interruption

PlacementConstraints

The placement constraints for the tasks in the service.

Required: No

Type: Amazon EC2 Container Service Service PlacementConstraint

Update requires: Replacement

PlacementStrategies

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

Required: No

Type: Amazon EC2 Container Service Service PlacementStrategies

Update requires: Replacement

DesiredCount

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

Required: No

Type: Integer

Update requires: No interruption

LoadBalancers

A list of load balancer objects to associate with the cluster. For information about the number of load balancers that you can specify per service, see Service Load Balancing in the Amazon EC2 Container Service Developer Guide.

Required: No

Type: List of Amazon EC2 Container Service Service LoadBalancers

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: Conditional. Required only if you specify the LoadBalancers property.

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

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. 

Copy
{ "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

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

YAML

Copy
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

Copy
"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

Copy
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

More Info