AWS::ECS::Service - AWS CloudFormation
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS::ECS::Service

AWS::ECS::Service 资源创建一个 Amazon Elastic Container Service (Amazon ECS) 服务,该服务运行和维护请求数量的任务和关联的负载均衡器。

语法

要在 AWS CloudFormation 模板中声明此实体,请使用以下语法:

JSON

{ "Type" : "AWS::ECS::Service", "Properties" : { "Cluster" : String, "DeploymentConfiguration" : DeploymentConfiguration, "DeploymentController" : DeploymentController, "DesiredCount" : Integer, "EnableECSManagedTags" : Boolean, "HealthCheckGracePeriodSeconds" : Integer, "LaunchType" : String, "LoadBalancers" : [ LoadBalancer, ... ], "NetworkConfiguration" : NetworkConfiguration, "PlacementConstraints" : [ PlacementConstraint, ... ], "PlacementStrategies" : [ PlacementStrategy, ... ], "PlatformVersion" : String, "PropagateTags" : String, "Role" : String, "SchedulingStrategy" : String, "ServiceName" : String, "ServiceRegistries" : [ ServiceRegistry, ... ], "Tags" : [ Tag, ... ], "TaskDefinition" : String } }

属性

Cluster

要在其上运行您的服务的集群的短名称或完整 Amazon 资源名称 (ARN)。如果您未指定集群,则采用默认集群。

必需:否

类型:字符串

Update requires: Replacement

DeploymentConfiguration

可选部署参数,用于控制部署期间运行的任务数以及停止和开始任务的顺序。

必需:否

类型DeploymentConfiguration

Update requires: No interruption

DeploymentController

要用于该服务的部署控制器。

必需:否

类型DeploymentController

Update requires: Replacement

DesiredCount

要在您的集群中放置并保持运行的指定任务定义的实例化数量。

如果 schedulingStrategyREPLICA 或未指定,则这是必需的。如果 schedulingStrategyDAEMON,则不需要此项。

必需:条件

类型:整数

Update requires: No interruption

EnableECSManagedTags

指定是否要为该服务内的任务启用 Amazon ECS 托管标签。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的标记您的 Amazon ECS 资源

必需:否

类型:布尔值

Update requires: Replacement

HealthCheckGracePeriodSeconds

任务首次启动后的一段时间(以秒为单位),在此段时间内,Amazon ECS 服务计划程序将忽略未正常运行的 Elastic Load Balancing 目标运行状况检查。只有在您的服务配置为使用负载均衡器时,才使用此设置。如果您的服务定义了负载均衡器,并且您没有指定运行状况检查宽限期值,则使用默认值 0

如果您的服务的任务需要一段时间才能启动和响应 Elastic Load Balancing 运行状况检查,则您最长可以指定 2147483647 秒的运行状况检查宽限期。在此期间,Amazon ECS 服务计划程序忽略运行状况检查状态。此宽限期可防止服务计划程序将由于时间不足尚未启动的任务标记为不正常并停止它们。

必需:否

类型:整数

Update requires: No interruption

LaunchType

运行您的服务的启动类型。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的 Amazon ECS 启动类型

必需:否

类型:字符串

允许的值EC2 | FARGATE

Update requires: Replacement

LoadBalancers

要与服务关联的负载均衡器对象的列表。如果您指定了 Role 属性,则还必须指定 LoadBalancers。有关可为每个服务指定的负载均衡器的数目的信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的 Service Load Balancing

必需:否

类型LoadBalancer 列表

Update requires: Replacement

NetworkConfiguration

服务的网络配置。对于使用 awsvpc 网络模式接收其自己的弹性网络接口的任务定义,该参数是必需的,其他网络模式不支持该参数。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的任务联网

必需:条件

类型NetworkConfiguration

Update requires: No interruption

PlacementConstraints

您的服务中的任务使用的一组放置约束对象。对于每个任务,您可以指定多达 10 种约束(此限制包括任务定义中的约束和这些在运行时指定的约束)。

必需:否

类型PlacementConstraint 的列表

Update requires: Replacement

PlacementStrategies

您的服务中的任务所用的放置策略对象。对于每项服务,您最多可以指定 5 种策略规则。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的任务放置策略

必需:否

类型PlacementStrategy 的列表

Update requires: Replacement

PlatformVersion

服务中的任务运行于的平台版本。仅为使用 Fargate 启动类型的任务指定平台版本。如果未指定任何版本,将默认使用 LATEST 平台版本。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的 AWS Fargate 平台版本

必需:否

类型:字符串

Update requires: Replacement

PropagateTags

指定是否要将标签从任务定义或服务传播到服务中的任务。如果未指定任何值,则不会传播标签。只能在创建服务的过程中将标签传播到服务中的任务。要在创建服务后将标签添加到任务,请使用 TagResource API 操作。

必需:否

类型:字符串

允许的值SERVICE | TASK_DEFINITION

Update requires: Replacement

Role

允许 Amazon ECS 代表您调用负载均衡器的 IAM 角色的名称或完整 Amazon 资源名称 (ARN)。仅当您在服务中使用负载均衡器且任务定义未使用 awsvpc 网络模式时,才允许使用此参数。如果您指定 role 参数,则还必须指定具有 loadBalancers 参数的负载均衡器对象。

重要

如果您的账户已创建 Amazon ECS 服务相关角色,则默认情况下会为您的服务使用该角色,除非您在此处指定一个角色。如果任务定义使用 awsvpc 网络模式,或者将服务配置为使用服务发现、外部部署控制器、多个目标组或 Elastic Inference 加速器(在这种情况下,不应在此处指定角色),则需要使用服务相关角色。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的将服务相关角色用于 Amazon ECS

如果您的指定角色的路径并非 /,则必须指定完整角色 ARN(推荐)或将此路径作为角色名称的前缀。例如,如果名称为 bar 的角色的路径为 /foo/,您应指定 /foo/bar 作为角色名称。有关更多信息,请参阅 IAM 用户指南 中的友好名称和路径

必需:否

类型:字符串

Update requires: Replacement

SchedulingStrategy

要用于服务的计划策略。有关更多信息,请参阅服务

有两种服务计划程序策略可用:

  • REPLICA:副本计划策略在集群中放置和维护所需数量的任务。默认情况下,服务计划程序可在多个可用区之间分布任务,但您可以使用任务放置策略和约束自定义任务放置决策。如果服务使用的是 CODE_DEPLOYEXTERNAL 部署控制器类型,则需要此计划程序策略。

  • DAEMON - 守护程序计划策略只在每个活动容器实例上部署一个任务,以满足您在集群中指定的所有任务放置约束。服务计划程序还评估运行任务的任务放置约束,并停止不满足放置约束的任务。在使用此策略时,无需指定所需数目的任务、任务放置策略,也无需使用服务 Auto Scaling 策略。

    注意

    使用 Fargate 启动类型或 CODE_DEPLOYEXTERNAL 部署控制器类型的任务不支持 DAEMON 计划策略。

必需:否

类型:字符串

允许的值DAEMON | REPLICA

Update requires: Replacement

ServiceName

您的服务的名称。最多能包含 255 个字母(大写和小写字母)、数字和下划线。一个集群中的服务名称必须唯一,但是您可以为一个区域或多个区域中多个集群中的服务提供相似的名称。

必需:否

类型:字符串

Update requires: Replacement

ServiceRegistries

要分配给此服务的服务发现注册表的详细信息。有关更多信息,请参阅服务发现

注意

如果使用平台版本 v1.1.0 或更高版本,则 Fargate 任务支持服务发现。有关更多信息,请参阅 AWS Fargate 平台版本

必需:否

类型ServiceRegistry 列表

Update requires: Replacement

Tags

您应用于服务以帮助您对其进行分类和组织的元数据。每个标签都包含您定义的一个键和一个可选值。在服务被删除时,标签也会随之被删除。

下面是适用于标签的基本限制:

  • 每个资源的最大标签数 - 50

  • 对于每个资源,每个标签键都必须是唯一的,每个标签键只能有一个值。

  • 最大键长度 - 128 个 Unicode 字符(采用 UTF-8 格式)

  • 最大值长度 - 256 个 Unicode 字符(采用 UTF-8 格式)

  • 如果您的标记方案针对多个服务和资源使用,请记得其他服务可能对允许使用的字符有限制。通常允许使用的字符包括:可用 UTF-8 格式表示的字母、数字和空格,以及以下字符:+ - = . _ : / @。

  • 标签键和值区分大小写。

  • 请不要使用 aws:AWS: 或任何大写或小写组合(例如,键或值的前缀),因为它将保留以供 AWS 使用。您无法编辑或删除带此前缀的标签键或值。具有此前缀的标签不计入每个资源的标签数限制。

必需:否

类型Tag 的列表

最高50

Update requires: No interruption

TaskDefinition

要在您的服务中运行的任务定义的 familyrevision (family:revision) 或完整 ARN。需要 revision 才能使资源稳定。

如果服务使用的是 ECSCODE_DEPLOY 部署控制器,则必须指定任务定义。

必需:否

类型:字符串

Update requires: No interruption

返回值

Ref

在将此资源的逻辑 ID 传递给内部 Ref 函数时,Ref 返回 Amazon 资源名称 (ARN)。

在以下示例中,Ref 函数将返回 MyECSService 服务的 ARN,例如 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 内部函数返回此类型的一个指定属性的值。以下为可用属性和示例返回值。

有关使用 Fn::GetAtt 内部函数的更多信息,请参阅 Fn::GetAtt

Name

Amazon ECS 服务的名称,例如 sample-webapp

示例

定义基本 Amazon ECS 服务

以下示例定义了 Amazon ECS 服务,该服务使用在相同模板中的其他位置声明的集群和任务定义。

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"

将 Application Load Balancer 与服务关联

以下示例通过引用 AWS::ElasticLoadBalancingV2::TargetGroup 资源,将应用程序负载均衡器与 Amazon ECS 服务关联。

注意

Amazon ECS 服务需要显式依赖于应用程序负载均衡器侦听器规则和应用程序负载均衡器侦听器。这可以防止该服务在侦听器准备就绪前启动。

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

使用运行状况检查宽限期定义服务

以下示例使用参数定义了一个服务,使用户能够指定 Amazon ECS 服务计划程序在任务首次启动后应该忽略未正常运行的 Elastic Load Balancing 目标运行状况检查的秒数。

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