服务定义参数 - Amazon Elastic Container Service
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

服务定义参数

服务定义用于定义如何运行您的 Amazon ECS 服务。可以在服务定义中指定以下参数。

启动类型

launchType

类型:字符串

有效值:EC2 |FARGATE |EXTERNAL

必需:否

运行您的服务的启动类型。如果没有指定启动类型,将默认使用 EC2。有关更多信息,请参阅Amazon ECS 启动类型

如果指定 launchType,必须省略 capacityProviderStrategy 参数。

容量提供程序策略

capacityProviderStrategy

类型: 对象数组

必需:否

要用于服务的容量提供程序策略。

容量提供程序策略由一个或多个容量提供程序以及要分配给它们的 baseweight 组成。容量提供程序必须与要在容量提供程序策略中使用的集群相关联。PutClusterCapacityProviders API 用于将容量提供程序与集群相关联。只能使用具有 ACTIVEUPDATING 状态的容量提供程序。

如果指定 capacityProviderStrategy,必须省略 launchType 参数。如果没有指定 capacityProviderStrategylaunchType,将使用集群的 defaultCapacityProviderStrategy

如果要指定使用自动扩缩组的容量提供程序,则必须先创建该容量提供程序。可以通过 CreateCapacityProvider API 操作创建新的容量提供程序。

要使用 Amazon Fargate 容量提供程序,请指定 FARGATEFARGATE_SPOT 容量提供程序。Amazon Fargate 容量提供程序对所有账户都可用,只需要与要使用的集群相关联。

PutClusterCapacityProviders API 操作用于在创建集群后更新集群的可用容量提供程序列表。

capacityProvider

类型:字符串

必需:是

容量提供程序的短名称或完整的 Amazon 资源名称(ARN)。

weight

类型:整数

有效范围:介于 0 到 1000 之间的整数。

必需:否

权重值指明使用指定容量提供程序的已启动任务总数的相对百分比。

例如,假定您的策略包含两个容量提供程序,并且两个容量提供程序的权重均为 1。当满足基准时,任务会在两个容量提供程序之间均匀分配。按照相同的逻辑,假定您指定 capacityProviderA 的权重为 1,并指定 capacityProviderB 的权重为 4,那么,对于使用 capacityProviderA 运行的每个任务,都会有四个任务使用 capacityProviderB

base

类型:整数

有效范围:介于 0 到 100000 万之间的整数。

必需:否

基准值指明在指定的容量提供程序上至少运行多少个任务。在一个容量提供程序策略中,只能有一个容量提供程序策略定义了基准。

任务定义

taskDefinition

类型:字符串

必需:否

要在您的服务中运行的任务定义的 familyrevision (family:revision) 或完整 Amazon Resource Name (ARN)。如果未指定 revision,则会使用指定系列的最新 ACTIVE 版本。

使用滚动更新 (ECS) 部署控制器时,必须指定任务定义。

平台操作系统

platformFamily

类型:字符串

必需:条件

原定设置:Linux

对于在 Fargate 上托管的 Amazon ECS 服务,此参数是必需的。

对于在 Amazon EC2 上托管的 Amazon ECS 服务,可忽略此参数。

运行服务的容器上的操作系统。有效值为 LINUXWINDOWS_SERVER_2019_FULLWINDOWS_SERVER_2019_COREWINDOWS_SERVER_2022_FULLWINDOWS_SERVER_2022_CORE

为服务指定的每个任务的 platformFamily 值都必须与服务 platformFamily 值匹配。例如,如果您将 platformFamily 设置为 WINDOWS_SERVER_2019_FULL,则所有任务的 platformFamily 值必须是 WINDOWS_SERVER_2019_FULL

平台版本

platformVersion

类型:字符串

必需:否

正在运行服务中任务的平台版本。仅为使用 Fargate 启动类型的任务指定平台版本。如果没有指定任何版本,将默认使用最新版本 (LATEST)。

Amazon Fargate 平台版本用于指代 任务基础设施的特定运行时环境。在运行任务或创建服务的过程中指定 LATEST 平台版本时,您将获得可用于任务的最新平台版本。当您扩展服务时,这些任务将收到在服务的当前部署中指定的平台版本。有关更多信息,请参阅Amazon Fargate 平台版本

注意

不会使用 EC2 启动类型为任务指定平台版本。

Cluster

cluster

类型:字符串

必需:否

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

服务名称

serviceName

类型:字符串

必需:是

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

计划策略

schedulingStrategy

类型:字符串

有效值:REPLICA | DAEMON

必需:否

要使用的计划策略。如果未指定计划策略,则使用 REPLICA 策略。有关更多信息,请参阅服务计划程序概念

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

  • REPLICA:副本计划策略在集群中放置和维护所需数量的任务。默认情况下,服务计划程序可在多个可用区之间分布任务,但您可以使用任务放置策略和约束自定义任务放置决策。有关更多信息,请参阅副本

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

    注意

    Fargate 任务不支持 DAEMON 计划策略。

预期数量

desiredCount

类型:整数

必需:否

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

如果使用 REPLICA 计划策略,则需要此参数。如果服务使用 DAEMON 计划策略,则此参数是可选的。

部署配置

deploymentConfiguration

类型:对象

必需:否

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

maximumPercent

类型:整数

必需:否

如果服务使用滚动更新(ECS)部署类型,maximumPercent 参数表示在部署期间允许处于 RUNNINGPENDING 状态的服务任务数上限。其表示为向下取整到最近整数的 desiredCount 的百分比。您可以使用此参数定义部署批次大小。例如,如果服务使用 REPLICA 服务调度器且任务的 desiredCount 为 4,maximumPercent 值为 200%,则调度器会在停止 4 个旧任务之前开始 4 个新任务。这样做的前提是具有执行此操作所需的集群资源。使用 REPLICA 服务计划程序的服务的默认 maximumPercent 值为 200%。

如果服务使用的是 DAEMON 服务调度器类型,则 maximumPercent 应保持在 100%。这是默认值。

部署期间的最大任务数为 desiredCount 乘以 maximumPercent/100(向下取整到最近的整数值)。

如果服务使用的是蓝/绿 (CODE_DEPLOY) 或 EXTERNAL 部署类型以及使用 EC2 启动类型的任务,最大百分比值将设置为原定设置值,用于在容器实例处于 RUNNING 状态时,定义服务中保持 DRAINING 状态的任务数上限。如果服务中的任务使用 Fargate 启动类型,则不会使用最大百分比值,但会在描述服务时返回该值。

minimumHealthyPercent

类型:整数

必需:否

如果服务使用滚动更新(ECS)部署类型,minimumHealthyPercent 则表示在部署期间必须处于 RUNNING 状态的服务任务数下限。其表示为向上取整到最近整数的 desiredCount 的百分比。您可以使用此参数进行部署,而无需使用额外的集群容量。例如,如果服务的任务 desiredCount 为 4,minimumHealthyPercent 为 50%,则该服务计划程序可能会在开始 2 个新任务之前停止 2 个现有任务以释放集群容量。

对于使用负载均衡器的服务,请注意以下事项:

  • 如果某个服务中任务内的所有基本容器都通过了运行状况检查,则该服务将被视为正常运行。

  • 如果任务没有已定义运行状况检查的基本容器,服务调度器会在任务达到 RUNNING 状态后等待 40 秒,然后将其计入最低正常运行百分比总计。

  • 如果任务具有一个或多个已定义运行状况检查的基本容器,服务计划程序会等待任务达到正常运行状态,然后将其计入最低正常运行百分比总计。当某个任务中的所有基本容器都通过了其运行状况检查时,该任务将被视为正常运行。服务计划程序可以等待的时间由容器运行状况检查设置决定。有关更多信息,请参阅运行状况检查

对于确实使用负载均衡器的服务,请注意以下事项:

  • 如果任务不包含已定义运行状况检查的基本容器,服务计划程序会等待负载均衡器目标组运行状况检查返回正常运行状态,然后将任务计入最低正常运行百分比总计。

  • 如果任务具有一个已定义运行状况检查的基本容器,服务计划程序会等待任务达到正常运行状态且负载均衡器目标组运行状况检查返回正常运行状态,然后将任务计入最低正常运行百分比总计。

minimumHealthyPercent 的副本服务的默认值为 100%。使用 DAEMON 服务调度的原定设置 minimumHealthyPercent 值对于 Amazon CLI、Amazon 开发工具包和 API 为 0%,对于 Amazon Web Services Management Console 为 50%。

部署期间的最小正常任务数为 desiredCount 乘以 minimumHealthyPercent/100(向上取整到最近的整数值)。

如果服务使用的是蓝/绿 (CODE_DEPLOY) 或 EXTERNAL 部署类型以及使用 EC2 启动类型的运行任务,最小正常百分比值将设置为原定设置值,用于在容器实例处于 RUNNING 状态时,定义服务中保持在 DRAINING 状态的任务数下限。如果服务使用蓝色/绿色 (CODE_DEPLOY) 或 EXTERNAL 部署类型,并且正在运行使用 Fargate 启动类型的任务,则不会使用最小健康百分比值,尽管在描述服务时会返回该值。

部署控制器

deploymentController

类型:对象

必需:否

要用于该服务的部署控制器。如果未指定部署控制器,则使用 ECS 控制器。有关更多信息,请参阅Amazon ECS 部署类型

type

类型:字符串

有效值:ECS |CODE_DEPLOY |EXTERNAL

必需:是

要使用的部署控制器类型。部署控制器有三种类型:

ECS

滚动更新 (ECS) 部署类型涉及将当前运行版本的容器替换为最新版本。可以调整在服务部署期间允许的最小和最大正常任务数量,以控制滚动更新期间 Amazon ECS 在服务中添加或删除的容器数量,如 deploymentConfiguration 中指定。

CODE_DEPLOY

蓝/绿 (CODE_DEPLOY) 部署类型使用 CodeDeploy 支持的蓝/绿部署模型,以允许您先验证新的服务部署,然后再向其发送生产流量。

EXTERNAL

外部 部署类型允许您使用任何第三方部署控制器,以完全控制 Amazon ECS 服务的部署过程。

任务放置

placementConstraints

类型: 对象数组

必需:否

您的服务中的任务使用的一组放置约束对象。您可以为每个任务指定最多 10 个约束。此限制包括任务定义中的约束以及在运行时指定的约束。如果您使用的是 Fargate 启动类型,则不支持任务放置约束。

type

类型:字符串

必需:否

约束类型。使用 distinctInstance 确保特定组中的每个任务在不同的容器实例上运行。使用 memberOf 将选择限制为一组有效的候选。任务定义不支持值 distinctInstance

expression

类型:字符串

必需:否

应用于约束的集群查询语言表达式。如果约束类型为 distinctInstance,则不能指定表达式。有关更多信息,请参阅集群查询语言

placementStrategy

类型: 对象数组

必需:否

您的服务中的任务所用的放置策略对象。对于每项服务,您最多可以指定 4 种策略。

type

类型:字符串

有效值:random |spread |binpack

必需:否

放置策略的类型。random 放置策略将任务随机放置在可用的候选上。spread 放置策略基于 field 参数将任务均匀地放置在可用候选上。binpack 策略将任务放置在可用资源数量最少(使用 field 参数指定)的可用候选上。例如,如果对内存使用装填,则会将任务放置到剩余内存最少但足以运行该任务的实例上。

field

类型:字符串

必需:否

应用放置策略的字段。对于 spread 放置策略,有效值为 instanceId(或具有相同效果的 host)或应用于容器实例的任何平台或自定义属性,例如 attribute:ecs.availability-zone。对于 binpack 放置策略,有效值为 cpumemory。对于 random 放置策略,该字段未用。

标签

tags

类型: 对象数组

必需:否

您应用于服务以帮助您对其进行分类和组织的元数据。每个标签都包含您定义的一个键和一个可选值。在服务被删除时,标签也会随之被删除。该服务最多可应用 50 个标签。有关更多信息,请参阅为您的 Amazon ECS 资源添加标签

key

类型:字符串

长度限制:最小长度为 1。最大长度为 128。

必需:否

构成标签的键-值对的一个部分。键是一种常见的标签,行为类似于更具体的标签值的类别。

value

类型:字符串

长度约束:最小长度为 0。长度上限为 256。

必需:否

构成标签的键-值对的可选部分。值充当标签类别(键)中的描述符。

enableECSManagedTags

类型:布尔值

有效值:true | false

必需:否

指定是否要为该服务内的任务使用 Amazon ECS 托管标签。如果未指定值,则默认值为 false。有关更多信息,请参阅标记资源以便于计费

propagateTags

类型:字符串

有效值:TASK_DEFINITION | SERVICE

必需:否

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

网络配置

networkConfiguration

类型:对象

必需:否

服务的网络配置。对于使用 awsvpc 网络模式接收其自己的弹性网络接口的任务定义,此参数是必需的,但其他网络模式不支持该参数。如果使用 Fargate 启动类型,则需要 awsvpc 网络模式。有关更多信息,请参阅 Amazon ECS 任务联网

awsvpcConfiguration

类型:对象

必需:否

表示任务或服务的子网和安全组的对象。

subnets

类型:字符串数组

必需:是

与任务或服务相关联的子网。根据 awsvpcConfiguration,可指定的子网数量限制为 16 个。

securityGroups

类型:字符串数组

必需:否

与任务或服务相关联的安全组。如果您未指定安全组,将使用 VPC 的默认安全组。根据 awsvpcConfiguration,可指定的安全组数量限制为 5 个。

assignPublicIP

类型:字符串

有效值:ENABLED | DISABLED

必需:否

任务的弹性网络接口是否接收公有 IP 地址。如果未指定值,则使用默认值 DISABLED

healthCheckGracePeriodSeconds

类型:整数

必需:否

在任务进入 RUNNING 状态后, Amazon ECS 服务计划程序应忽略不正常的 Elastic Load Balancing 目标运行状况检查、容器运行状况检查以及 Route 53 运行状况检查的时间段(以秒为单位)。您的服务只有配置为使用负载均衡器时此设置才适用。如果您的服务定义了负载均衡器,并且您没有指定运行状况检查宽限期值,则使用默认值 0

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

如果您不使用 Elastic Load Balancing,我们建议您在任务定义运行状况检查参数中使用 startPeriod。有关更多信息,请参阅运行状况检查

loadBalancers

类型: 对象数组

必需:否

表示要用于您的服务的负载均衡器的负载均衡器对象。对于使用 Application Load Balancer 或 Network Load Balancer 的服务,最多可将 5 个目标组附加到服务。

创建服务后,无法从 Amazon Web Services Management Console 更改负载均衡器配置。您只能使用 Amazon Copilot、Amazon CloudFormation、Amazon CLI 或 SDK 来修改 ECS 滚动部署控制器的负载均衡器配置,而不是 Amazon CodeDeploy 蓝/绿或外部控制器。当您添加、更新或删除负载均衡器配置时,Amazon ECS 会使用更新后的 Elastic Load Balancing 配置启动新部署。这将导致任务注册到负载均衡器或从负载均衡器取消注册。我们建议您在更新 Elastic Load Balancing 配置之前在测试环境中对此进行验证。有关如何修改配置的信息,请参阅 Amazon Elastic Container Service API 参考中的 UpdateService

对于 Classic Load Balancers,此对象必须包含负载均衡器名称、容器名称 (与在容器定义中显示的相同) 和容器端口才能从负载均衡器进行访问。将此服务中的任务放置于容器实例之后,容器实例会向指定的负载均衡器注册。

对于 Application Load Balancers 和 Network Load Balancers,此对象必须包含负载平衡器目标组ARN、容器名称(如容器定义中所示)以及要从负载平衡器访问的容器端口。将此服务中的任务放置于容器实例之后,容器实例和端口组合会注册为指定目标组中的目标。

targetGroupArn

类型:字符串

必需:否

与服务关联的 Elastic Load Balancing 目标组的完整 Amazon 资源名称(ARN)。

目标组 ARN 仅在使用 Application Load Balancer 或 Network Load Balancer时指定。如果您使用的是经典负载均衡器,则会省略目标组 ARN。

loadBalancerName

类型:字符串

必需:否

要与该服务关联的负载均衡器的名称。

负载均衡器名称仅在使用经典负载均衡器时指定。如果您使用的是 Application Load Balancer 或 Network Load Balancer,则会省略负载均衡器名称参数。

containerName

类型:字符串

必需:否

要与负载均衡器关联的容器的名称(与在容器定义中显示的相同)。

containerPort

类型:整数

必需:否

要与负载均衡器关联的容器上的端口。此端口必须对应于服务中的任务所使用任务定义中的 containerPort。对于使用 EC2 启动类型的任务,容器实例必须允许端口映射的 hostPort 上的入站流量。

role

类型:字符串

必需:否

允许 Amazon ECS 代表您调用负载均衡器的 IAM 角色的名称或完整 ARN 。仅当为服务使用具有单个目标组的负载平衡器,并且任务定义不使用 awsvpc 网络模式时,才允许使用此参数。如果您指定 role 参数,则还必须指定具有 loadBalancers 参数的负载均衡器对象。

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

重要

如果您的账户已创建 Amazon ECS 服务相关角色,则默认情况下会为您的服务使用该角色,除非您在此处指定一个角色。如果您的任务定义使用 awsvpc 网络模式(在这种情况下,您不应在此处指定角色),则需要服务相关角色。有关更多信息,请参阅对 Amazon ECS 使用服务相关角色

serviceRegistries

类型: 对象数组

必需:否

服务的服务发现配置的详细信息。有关更多信息,请参阅服务发现

registryArn

类型:字符串

必需:否

服务注册表的 Amazon 资源名称(ARN)。当前支持的服务注册表是 Amazon Cloud Map。有关更多信息,请参阅 Amazon Cloud Map 开发人员指南中的使用服务

port

类型:整数

必需:否

在服务发现服务指定 SRV 记录时使用的端口值。如果使用 awsvpc 网络模式和 SRV 记录,则需要此字段。

containerName

类型:字符串

必需:否

用于服务发现服务的容器名称值。此值可在任务定义中指定。如果服务任务指定的任务定义使用 bridgehost 网络模式,则必须从任务定义中指定 containerNamecontainerPort 组合。如果服务任务指定的任务定义使用 awsvpc 网络模式,并且使用类型 SRV DNS 记录,则必须指定 containerNamecontainerPort 组合或 port 值,但不能同时指定二者。

containerPort

类型:整数

必需:否

用于服务发现服务的端口值。此值可在任务定义中指定。如果服务任务指定的任务定义使用 bridgehost 网络模式,则必须从任务定义中指定 containerNamecontainerPort 组合。如果服务任务指定的任务定义使用 awsvpc 网络模式,并且使用类型 SRV DNS 记录,则必须指定 containerNamecontainerPort 组合或 port 值,但不能同时指定二者。

客户端令牌

clientToken

类型:字符串

必需:否

用于确保请求的幂等性而提供的唯一、区分大小写的标识符。最长可为 32 个 ASCII 字符。

服务定义模板

下面显示了 Amazon ECS 服务定义的 JSON 表示形式。

{ "cluster": "", "serviceName": "", "taskDefinition": "", "loadBalancers": [ { "targetGroupArn": "", "loadBalancerName": "", "containerName": "", "containerPort": 0 } ], "serviceRegistries": [ { "registryArn": "", "port": 0, "containerName": "", "containerPort": 0 } ], "desiredCount": 0, "clientToken": "", "launchType": "FARGATE", "capacityProviderStrategy": [ { "capacityProvider": "", "weight": 0, "base": 0 } ], "platformVersion": "", "platformFamily": "", "role": "", "deploymentConfiguration": { "maximumPercent": 0, "minimumHealthyPercent": 0 }, "placementConstraints": [ { "type": "distinctInstance", "expression": "" } ], "placementStrategy": [ { "type": "spread", "field": "" } ], "networkConfiguration": { "awsvpcConfiguration": { "subnets": [ "" ], "securityGroups": [ "" ], "assignPublicIp": "ENABLED" } }, "healthCheckGracePeriodSeconds": 0, "schedulingStrategy": "REPLICA", "deploymentController": { "type": "CODE_DEPLOY" }, "tags": [ { "key": "", "value": "" } ], "enableECSManagedTags": true, "propagateTags": "SERVICE" }

您可以使用以下 Amazon CLI 命令创建此服务定义模板。

aws ecs create-service --generate-cli-skeleton