Amazon Elastic Container Service
开发人员指南 (API 版本 2014-11-13)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

服务定义参数

服务定义将定义要用于您的服务的任务定义、该任务要运行的实例化的数量、要与您的任务关联的负载均衡器(如果有)以及其他服务参数。

{ "cluster": "", "serviceName": "", "taskDefinition": "", "loadBalancers": [ { "targetGroupArn": "", "loadBalancerName": "", "containerName": "", "containerPort": 0 } ], "serviceRegistries": [ { "registryArn": "", "port": 0, "containerName": "", "containerPort": 0 } ], "desiredCount": 0, "clientToken": "", "launchType": "EC2", "platformVersion": "", "role": "", "deploymentConfiguration": { "maximumPercent": 0, "minimumHealthyPercent": 0 }, "placementConstraints": [ { "type": "distinctInstance", "expression": "" } ], "placementStrategy": [ { "type": "binpack", "field": "" } ], "networkConfiguration": { "awsvpcConfiguration": { "subnets": [ "" ], "securityGroups": [ "" ], "assignPublicIp": "ENABLED" } }, "healthCheckGracePeriodSeconds": 0, "schedulingStrategy": "REPLICA", "deploymentController": { "type": "ECS" }, "tags": [ { "key": "", "value": "" } ], "enableECSManagedTags": true, "propagateTags": "TASK_DEFINITION" }

注意

您可使用以下 AWS CLI 命令创建上述服务定义模板。

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

您可在服务定义中指定以下参数。

cluster

The short name or full Amazon Resource Name (ARN) of the cluster on which to run your service. If you do not specify a cluster, the default cluster is assumed.

serviceName

The name of your service. 最多能包含 255 个字母 (大写和小写字母)、数字、连字符和下划线。 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: Yes

taskDefinition

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

loadBalancers

表示要用于您的服务的负载均衡器的负载均衡器对象。当前,对每个服务只能使用一个负载均衡器或目标组。在创建服务后,在服务定义中指定的负载均衡器名称或目标组 ARN、容器名称和容器端口是不可变的。

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

对于应用程序负载均衡器和网络负载均衡器,此对象必须包含负载均衡器目标组 ARN、容器名称(与在容器定义中显示的相同)和容器端口才能从负载均衡器进行访问。将此服务中的任务放在容器实例上后,容器实例和端口组合将注册为在此处指定的目标组中的目标。

targetGroupArn

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

loadBalancerName

负载均衡器的名称。

containerName

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

containerPort

要与负载均衡器关联的容器上的端口。此端口必须对应于服务的任务定义中的 containerPort。您的容器实例必须允许端口映射的 hostPort 上的入口流量。

serviceRegistries

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

registryArn

服务注册表的 Amazon 资源名称 (ARN)。当前支持的服务注册表是 Amazon Route 53 自动命名。有关更多信息,请参阅服务

port

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

containerName

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

containerPort

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

desiredCount

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

clientToken

您为确保请求的幂等性而提供的唯一、区分大小写的标识符。最多允许 32 个 ASCII 字符。

launchType

The launch type on which to run your service. Accepted values are FARGATE or EC2. If a launch type is not specified, EC2 is used by default. For more information, see Amazon ECS 启动类型.

platformVersion

The platform version on which your tasks in the service are running. A platform version is only specified for tasks using the Fargate launch type. If one is not specified, the latest version (LATEST) is used by default.

AWS Fargate platform versions are used to refer to a specific runtime environment for the Fargate task infrastructure. When specifying the LATEST platform version when running a task or creating a service, you get the most current platform version available for your tasks. When you scale up your service, those tasks receive the platform version that was specified on the service's current deployment. For more information, see AWS Fargate 平台版本.

注意

Platform versions are not specified for tasks using the EC2 launch type.

role

The short name or full ARN of the IAM role that allows Amazon ECS to make calls to your load balancer on your behalf. This parameter is only permitted if you are using a load balancer with your service and your task definition does not use the awsvpc network mode. If you specify the role parameter, you must also specify a load balancer object with the loadBalancers parameter.

If your specified role has a path other than /, then you must either specify the full role ARN (this is recommended) or prefix the role name with the path. For example, if a role with the name bar has a path of /foo/ then you would specify /foo/bar as the role name. For more information, see Friendly Names and Paths in the IAM 用户指南.

重要

If your account has already created the Amazon ECS service-linked role, that role is used by default for your service unless you specify a role here. The service-linked role is required if your task definition uses the awsvpc network mode, in which case you should not specify a role here. For more information, see 对 Amazon ECS 使用服务相关角色.

deploymentConfiguration

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

maximumPercent

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

如果您的服务使用的是 DAEMON 服务计划程序类型,则 maximumPercent 应保持在 100%,这是默认值。

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

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

minimumHealthyPercent

如果服务使用滚动更新 (ECS) 部署类型, minimumHealthyPercentdesiredCount 的百分比形式表示您的服务中在部署期间必须保持在 RUNNING 状态的任务数的下限(向上取整到最近的整数)。此参数使您不必使用额外的集群容量就能部署。例如,如果您的服务的任务 desiredCount 为 4,minimumHealthyPercent 为 50%,则该服务计划程序可能在开始两个新任务之前停止两个现有任务以释放集群容量。服务任务的状态如果为 RUNNING,而且 使用负载均衡器,即为运行正常。服务任务的状态如果为 RUNNING确实 使用了负载均衡器,同时托管负载均衡器的容器实例报告为正常,即为运行正常。minimumHealthyPercent 的副本服务的默认值在 AWS 管理控制台中为 50%,对于 AWS CLI、AWS 开发工具包和 API 为 100%。使用 DAEMON 服务计划的默认 minimumHealthyPercent 值对于 AWS CLI、AWS 开发工具包和 API 为 0%,对于 AWS 管理控制台为 50%。

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

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

placementConstraints

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

type

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

expression

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

placementStrategy

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

type

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

field

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

networkConfiguration

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

awsvpcConfiguration

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

subnets

与任务或服务相关联的子网。

securityGroups

与任务或服务相关联的安全组。如果您未指定安全组,将使用 VPC 的默认安全组。

assignPublicIP

任务的弹性网络接口是否接收公有 IP 地址。

healthCheckGracePeriodSeconds

The period of time, in seconds, that the Amazon ECS service scheduler should ignore unhealthy Elastic Load Balancing target health checks, container health checks, and Route 53 health checks after a task has first started. This is only valid if your service is configured to use a load balancer. If your service's tasks take a while to start and respond to health checks, you can specify a health check grace period of up to 2,147,483,647 seconds during which the ECS service scheduler ignores the health check status. This grace period can prevent the ECS service scheduler from marking tasks as unhealthy and stopping them before they have time to come up.

schedulingStrategy

要使用的计划策略。有关更多信息,请参阅 服务计划程序概念

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. For more information, see 副本.

  • DAEMON—The daemon scheduling strategy deploys exactly one task on each active container instance that meets all of the task placement constraints that you specify in your cluster. When using this strategy, there is no need to specify a desired number of tasks, a task placement strategy, or use Service Auto Scaling policies. For more information, see 守护程序.

    注意

    Fargate tasks do not support the DAEMON scheduling strategy.

deploymentController

要用于该服务的部署控制器。有关更多信息,请参阅 Amazon ECS 部署类型

type

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

ECS

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

CODE_DEPLOY

蓝/绿 (CODE_DEPLOY) 部署类型使用 CodeDeploy 提供技术支持的蓝/绿部署模型,从而让您可以先验证服务的新部署,然后再向其发送生产流量。

EXTERNAL

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

tags

The metadata that you apply to the service to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. When a service is deleted, the tags are deleted as well. Tag keys can have a maximum character length of 128 characters, and tag values can have a maximum length of 256 characters. For more information, see 标记您的 Amazon ECS 资源.

key

One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.

value

The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).

enableECSManagedTags

指定是否要为服务中的任务启用 Amazon ECS 托管标签。有关更多信息,请参阅标记资源以便于计费

propagateTags

Specifies whether to copy the tags from the task definition or the service to the tasks in the service. If no value is specified, the tags are not copied. Tags can only be copied to the tasks within the service during service creation. To add tags to a task after service creation, use the TagResource API action.