# Amazon ECS 服务定义参数 服务定义用于定义如何运行您的 Amazon ECS 服务。可以在服务定义中指定以下参数。 ## 启动类型 `launchType` 类型：字符串 有效值：`EC2` \$1`FARGATE` \$1`EXTERNAL` 必需：否 运行您的服务的启动类型。如果没有指定启动类型，将默认使用默认的 `capacityProviderStrategy`。 更新服务时，此参数会触发新的服务部署。 如果指定 `launchType`，必须省略 `capacityProviderStrategy` 参数。 ## 容量提供程序策略 `capacityProviderStrategy` 类型： 对象数组 必需：否 要用于服务的容量提供程序策略。 更新服务时，此参数不会触发新的服务部署。 容量提供程序策略由一个或多个容量提供程序以及要分配给它们的 `base` 和 `weight` 组成。容量提供程序必须与要在容量提供程序策略中使用的集群相关联。PutClusterCapacityProviders API 用于将容量提供程序与集群相关联。只能使用具有 `ACTIVE` 或 `UPDATING` 状态的容量提供程序。 如果指定 `capacityProviderStrategy`，必须省略 `launchType` 参数。如果没有指定 `capacityProviderStrategy` 或 `launchType`，将使用集群的 `defaultCapacityProviderStrategy`。 如果要指定使用自动扩缩组的容量提供程序，则必须先创建该容量提供程序。可以通过 CreateCapacityProvider API 操作创建新的容量提供程序。 要使用 AWS Fargate 容量提供程序，请指定 `FARGATE` 或 `FARGATE_SPOT` 容量提供程序。AWS Fargate 容量提供程序对所有账户都可用，只需要与要使用的集群相关联。 PutClusterCapacityProviders API 操作用于在创建集群后更新集群的可用容量提供程序列表。 `capacityProvider` 类型：字符串 是否必需：是 容量提供程序的短名称或完整的 Amazon 资源名称（ARN）。 `weight` 类型：整数 有效范围：介于 0 到 1000 之间的整数。 必需：否 权重值指明使用指定容量提供程序的已启动任务总数的相对百分比。 例如，假定您的策略包含两个容量提供程序，并且两个容量提供程序的权重均为 1。当满足基准时，任务会在两个容量提供程序之间均匀分配。按照相同的逻辑，假定您指定 *capacityProviderA* 的权重为 1，并指定 *capacityProviderB* 的权重为 4，那么，对于使用 *capacityProviderA* 运行的每个任务，都会有四个任务使用 *capacityProviderB*。 `base` 类型：整数 有效范围：介于 0 到 100000 万之间的整数。 必需：否 基准值指明在指定的容量提供程序上至少运行多少个任务。在一个容量提供程序策略中，只能有一个容量提供程序策略定义了基准。 ## 任务定义 `taskDefinition` 类型：字符串 必需：否 要在您的服务中运行的任务定义的 `family` 和 `revision`（`family:revision`）或完整 Amazon 资源名称（ARN）。如果未指定 `revision`，则会使用指定系列的最新 `ACTIVE` 版本。 更新服务时，此参数会触发新的服务部署。 使用滚动更新（`ECS`）部署控制器时，必须指定任务定义。 ## 平台操作系统 `platformFamily` 类型：字符串 必需：条件 原定设置：Linux 对于在 Fargate 上托管的 Amazon ECS 服务，此参数是必需的。 对于在 Amazon EC2 上托管的 Amazon ECS 服务，可忽略此参数。 运行服务的容器上的操作系统。有效值为 `LINUX`、`WINDOWS_SERVER_2019_FULL`、`WINDOWS_SERVER_2019_CORE`、`WINDOWS_SERVER_2022_FULL` 和 `WINDOWS_SERVER_2022_CORE`。 为服务指定的每个任务的 `platformFamily` 值都必须与服务 `platformFamily` 值匹配。例如，如果您将 `platformFamily` 设置为 `WINDOWS_SERVER_2019_FULL`，则所有任务的 `platformFamily` 值必须是 `WINDOWS_SERVER_2019_FULL`。 ## 平台版本 `platformVersion` 类型：字符串 必需：否 正在运行服务中任务的平台版本。仅为使用 Fargate 启动类型的任务指定平台版本。如果没有指定任何版本，将默认使用最新版本（`LATEST`）。 更新服务时，此参数会触发新的服务部署。 AWS Fargate 平台版本用于指代 Fargate 任务基础设施的特定运行时环境。在运行任务或创建服务的过程中指定 `LATEST` 平台版本时，您将获得可用于任务的最新平台版本。当您纵向扩展服务时，这些任务将收到在服务的当前部署中指定的平台版本。有关更多信息，请参阅 [适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。 不会使用 EC2 启动类型为任务指定平台版本。 ## 集群 `cluster` 类型：字符串 必需：否 要在其上运行您的服务的集群的短名称或完整 Amazon 资源名称（ARN）。如果您未指定集群，则采用 `default` 集群。 ## 服务名称 `serviceName` 类型：字符串 是否必需：是 您的服务的名称。最多能包含 255 个字母（大写和小写字母）、数字、连字符和下划线。一个集群中的服务名称必须唯一，但是您可以为一个区域或多个区域中多个集群中的服务提供相似的名称。 ## 计划策略 `schedulingStrategy` 类型：字符串 有效值：`REPLICA` \$1 `DAEMON` 必需：否 要使用的计划策略。如果未指定计划策略，则使用 `REPLICA` 策略。有关更多信息，请参阅 [Amazon ECS 服务](ecs_services.md)。 有两种服务计划程序策略可用： + `REPLICA`：副本计划策略在集群中放置和维护所需数量的任务。默认情况下，服务计划程序可在多个可用区之间分布任务，但您可以使用任务放置策略和约束自定义任务放置决策。有关更多信息，请参阅 [副本计划策略](ecs_service-options.md#service_scheduler_replica)。 + `DAEMON`：进程守护程序计划策略只在每个活动容器实例上部署一个任务，以满足您在集群中指定的所有任务放置约束。当使用此策略时，无需指定所需的任务数、任务放置策略，也无需使用服务自动扩缩策略。有关更多信息，请参阅 [进程守护程序计划策略](ecs_service-options.md#service_scheduler_daemon)。 **注意** Fargate 任务不支持 `DAEMON` 计划策略。 ## 预期数量 `desiredCount` 类型：整数 必需：否 要在您的服务中放置并保持运行的指定任务定义的实例化数量。 更新服务时，此参数不会触发新的服务部署。 如果使用 `REPLICA` 计划策略，则需要此参数。如果服务使用 `DAEMON` 计划策略，则此参数是可选的。 当您使用服务自动扩缩时，若您使用少于当前正在运行的任务数的 `desiredCount` 更新正在运行的服务时，该服务会缩减到指定的 `desiredCount`。 ## 部署配置 `deploymentConfiguration` 类型：对象 必需：否 可选部署参数，用于控制部署期间运行的任务数以及停止和开始任务的顺序。 更新服务时，此参数不会触发新的服务部署。 `maximumPercent` 类型：整数 必需：否 如果服务使用滚动更新（`ECS`）部署类型，`maximumPercent` 参数表示在部署期间允许处于 `RUNNING`、`STOPPING` 或 `PENDING` 状态的服务任务数上限。其表示为向下取整到最近整数的 `desiredCount` 的百分比。您可以使用此参数定义部署批次大小。例如，如果服务使用 `REPLICA` 服务调度器且任务的 `desiredCount` 为 4，`maximumPercent` 值为 200%，则调度器会在停止 4 个旧任务之前开始 4 个新任务。这样做的前提是具有执行此操作所需的集群资源。使用 `REPLICA` 服务计划程序的服务的默认 `maximumPercent` 值为 200%。 只要有用于启动替换任务的集群资源可用，Amazon ECS 调度器就会使用此参数替换运行状况不佳的任务，方法是先启动替换任务，然后停止运行状况不佳的任务。有关调度器如何替换运行状况不佳的任务的更多信息，请参阅 [Amazon ECS 服务](ecs_services.md)。 如果服务使用的是 `DAEMON` 服务调度器类型，则 `maximumPercent` 应保持在 100%。这是默认值。 部署期间的最大任务数为 `desiredCount` 乘以 `maximumPercent`/100（向下取整到最近的整数值）。 如果服务使用蓝绿（`CODE_DEPLOY`）或 `EXTERNAL` 部署类型，并且具有使用 EC2 启动类型的任务，则**最大百分比**值将设置为默认值。该值用于定义当容器实例处于 `DRAINING` 状态时该服务中仍保持在 `RUNNING` 状态的任务数上限。 如果服务使用蓝绿（`CODE_DEPLOY`）或 `EXTERNAL` 部署类型并且具有使用 EC2 的任务，您无法为该服务指定自定义 `maximumPercent` 值。 如果服务使用蓝绿（`CODE_DEPLOY`）或 `EXTERNAL` 部署类型，并且服务中的任务使用 Fargate，则不会使用最大百分比值。在描述您的服务时仍会返回该值。 `minimumHealthyPercent` 类型：整数 必需：否 如果服务使用滚动更新（`ECS`）部署类型，`minimumHealthyPercent` 则表示在部署期间必须处于 `RUNNING` 状态的服务任务数下限。其表示为向上取整到最近整数的 `desiredCount` 的百分比。您可以使用此参数进行部署，而无需使用额外的集群容量。 例如，如果您的服务的任务 `desiredCount` 为 4，`minimumHealthyPercent` 为 50% 且 `maximumPercent` 为 100%，则服务调度器可能先停止两个现有任务以释放集群容量，然后再启动两个新任务。 如果有任何任务运行状况不佳，并且 `maximumPercent` 不允许 Amazon ECS 调度器启动替换任务，则调度器将使用 `minimumHealthyPercent` 作为约束条件逐一停止运行状况不佳的任务，清理容量以便启动替换任务。有关调度器如何替换运行状况不佳的任务的更多信息，请参阅 [Amazon ECS 服务](ecs_services.md)。 对于*不*使用负载均衡器的服务，请注意以下事项： + 如果某个服务中任务内的所有基本容器都通过了运行状况检查，则该服务将被视为正常运行。 + 如果任务没有已定义运行状况检查的基本容器，服务调度器会在任务达到 `RUNNING` 状态后等待 40 秒，然后将其计入最低正常运行百分比总计。 + 如果任务具有一个或多个已定义运行状况检查的基本容器，服务计划程序会等待任务达到正常运行状态，然后将其计入最低正常运行百分比总计。当某个任务中的所有基本容器都通过了其运行状况检查时，该任务将被视为正常运行。服务计划程序可以等待的时间由容器运行状况检查设置决定。有关更多信息，请参阅 [运行状况检查](task_definition_parameters.md#container_definition_healthcheck)。 对于*确实*使用负载均衡器的服务，请注意以下事项： + 如果任务不包含已定义运行状况检查的基本容器，服务计划程序会等待负载均衡器目标组运行状况检查返回正常运行状态，然后将任务计入最低正常运行百分比总计。 + 如果任务具有一个已定义运行状况检查的基本容器，服务计划程序会等待任务达到正常运行状态且负载均衡器目标组运行状况检查返回正常运行状态，然后将任务计入最低正常运行百分比总计。 `minimumHealthyPercent` 的副本服务的默认值为 100%。使用 `DAEMON` 服务调度的原定设置 `minimumHealthyPercent` 值对于 AWS CLI、AWS 开发工具包和 API 为 0%，对于 AWS 管理控制台 为 50%。 部署期间的最小正常任务数为 `desiredCount` 乘以 `minimumHealthyPercent`/100（向上取整到最近的整数值）。 如果服务使用蓝绿（`CODE_DEPLOY`）或 `EXTERNAL` 部署类型，并且正在运行使用 EC2 的任务，则**最小正常运行百分比**值将设置为默认值。该值用于定义当容器实例处于 `DRAINING` 状态时该服务中仍保持在 `RUNNING` 状态的任务数下限。 如果服务使用蓝绿（`CODE_DEPLOY`）或 `EXTERNAL` 部署类型并且具有使用 EC2 的任务，您无法为该服务指定自定义 `maximumPercent` 值。 如果服务使用蓝绿（`CODE_DEPLOY`）或 `EXTERNAL` 部署类型，并且正在运行使用 Fargate 的任务，则不会使用最小健康百分比值，尽管在描述服务时会返回该值。 ## 部署控制器 `deploymentController` 类型：对象 必需：否 要用于该服务的部署控制器。如果未指定部署控制器，则使用 `ECS` 控制器。有关更多信息，请参阅 [Amazon ECS 服务](ecs_services.md)。 更新服务时，此参数不会触发新的服务部署。 `type` 类型：字符串 有效值：`ECS` \$1`CODE_DEPLOY` \$1`EXTERNAL` 是否必需：是 要使用的部署控制器类型。部署控制器有三种类型： `ECS` Amazon ECS 部署控制器支持多种部署策略：滚动更新、蓝绿、线性和金丝雀。滚动更新部署类型涉及将当前运行版本的容器替换为最新版本。蓝绿部署会创建新环境并一次性转移所有流量。线性部署会以相等百分比增量逐渐转移流量。金丝雀部署首先转移一小部分流量，然后转移剩余流量。可以调整在服务部署期间允许的最小和最大正常任务数量，以控制滚动更新期间 Amazon ECS 在服务中添加或删除的容器数量，如 [deploymentConfiguration](#deploymentConfiguration) 中指定。 `CODE_DEPLOY` 蓝绿（`CODE_DEPLOY`）部署类型使用 CodeDeploy 支持的蓝绿部署模型，以允许您先验证新的服务部署，然后再向其发送生产流量。 `EXTERNAL` 当您需要使用任何第三方部署控制器来完全控制 Amazon ECS 服务的部署过程时，使用外部部署类型。 ## 任务放置 `placementConstraints` 类型： 对象数组 必需：否 您的服务中的任务使用的一组放置约束对象。您可以为每个任务指定最多 10 个约束。此限制包括任务定义中的约束以及在运行时指定的约束。如果您使用的是 Fargate，则不支持任务放置约束。 更新服务时，此参数不会触发新的服务部署。 `type` 类型：字符串 必需：否 约束类型。使用 `distinctInstance` 确保特定组中的每个任务在不同的容器实例上运行。使用 `memberOf` 将选择限制为一组有效的候选。任务定义不支持值 `distinctInstance`。 `expression` 类型：字符串 必需：否 应用于约束的集群查询语言表达式。如果约束类型为 `distinctInstance`，则不能指定表达式。有关更多信息，请参阅 [创建表达式，以为 Amazon ECS 任务定义容器实例](cluster-query-language.md)。 `placementStrategy` 类型： 对象数组 必需：否 您的服务中的任务所用的放置策略对象。对于每项服务，您最多可以指定 4 种策略。 更新服务时，此参数不会触发新的服务部署。 `type` 类型：字符串 有效值：`random` \$1`spread` \$1`binpack` 必需：否 放置策略的类型。`random` 放置策略将任务随机放置在可用的候选上。`spread` 放置策略基于 `field` 参数将任务均匀地放置在可用候选上。`binpack` 策略将任务放置在可用资源数量最少（使用 `field` 参数指定）的可用候选上。例如，如果对内存使用装填，则会将任务放置到剩余内存最少但足以运行该任务的实例上。 `field` 类型：字符串 必需：否 应用放置策略的字段。对于 `spread` 放置策略，有效值为 `instanceId`（或具有相同效果的 `host`）或应用于容器实例的任何平台或自定义属性，例如 `attribute:ecs.availability-zone`。对于 `binpack` 放置策略，有效值为 `cpu` 和 `memory`。对于 `random` 放置策略，该字段未用。 ## 标签 `tags` 类型： 对象数组 必需：否 您应用于服务以帮助您对其进行分类和组织的元数据。每个标签都包含您定义的一个键和一个可选值。在服务被删除时，标签也会随之被删除。该服务最多可应用 50 个标签。有关更多信息，请参阅 [为 Amazon ECS 资源添加标签](ecs-using-tags.md)。 更新服务时，此参数不会触发新的服务部署。 `key` 类型：字符串 长度限制：最小长度为 1。最大长度为 128。 必需：否 构成标签的键-值对的一个部分。键是一种常见的标签，行为类似于更具体的标签值的类别。 `value` 类型：字符串 长度限制：最小长度为 0。长度上限为 256。 必需：否 构成标签的键-值对的可选部分。值充当标签类别（键）中的描述符。 `enableECSManagedTags` 类型：布尔值 有效值：`true` \$1 `false` 必需：否 指定是否要为该服务内的任务使用 Amazon ECS 托管标签。如果未指定值，则默认值为 `false`。有关更多信息，请参阅 [使用标签记账](ecs-using-tags.md#tag-resources-for-billing)。 更新服务时，此参数不会触发新的服务部署。 `propagateTags` 类型：字符串 有效值：`TASK_DEFINITION` \$1 `SERVICE` 必需：否 指定是否要将标签从任务定义或服务复制到服务中的任务。如果未指定值，则不会复制标签。只能在创建服务的过程中将标签复制到服务中的任务。要在创建服务或任务以后将标签添加到任务，请使用 `TagResource` API 操作。 更新服务时，此参数不会触发新的服务部署。 ## 网络配置 `networkConfiguration` 类型：对象 必需：否 服务的网络配置。对于使用 `awsvpc` 网络模式接收其自己的弹性网络接口的任务定义，此参数是必需的，但其他网络模式不支持该参数。如果使用 Fargate，则需要 `awsvpc` 网络模式。有关 EC2 联网的更多信息，请参阅 [EC2 的 Amazon ECS 任务联网选项](task-networking.md)。有关 Fargate 联网的更多信息，请参阅 [Fargate 的 Amazon ECS 任务联网选项](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-task-networking.html)。 更新服务时，此参数会触发新的服务部署。 `awsvpcConfiguration` 类型：对象 必需：否 表示任务或服务的子网和安全组的对象。 `subnets` 类型：字符串数组 是否必需：是 与任务或服务相关联的子网。根据 `awsvpcConfiguration`，可指定的子网数量限制为 16 个。 `securityGroups` 类型：字符串数组 必需：否 与任务或服务相关联的安全组。如果您未指定安全组，将使用 VPC 的默认安全组。根据 `awsvpcConfiguration`，可指定的安全组数量限制为 5 个。 `assignPublicIP` 类型：字符串 有效值：`ENABLED` \$1 `DISABLED` 必需：否 任务的弹性网络接口是否接收公有 IP 地址。如果未指定值，则使用默认值 `DISABLED`。 `healthCheckGracePeriodSeconds` 类型：整数 必需：否 任务首次启动后的一段时间（以秒为单位），在此段时间内，Amazon ECS 服务计划程序将忽略未正常运行的 Elastic Load Balancing、VPC Lattice 和容器运行状况检查。如果没有指定运行状况检查宽限期值，则使用默认值 0。如果不使用任何运行状况检查，则未使用 `healthCheckGracePeriodSeconds`。 如果服务的任务需要一段时间才能启动和响应，则您可以指定最长 2147483647 秒（大约 69 年）的运行状况检查宽限期。在此期间，Amazon ECS 服务计划程序将忽略运行状况检查状态。此宽限期可防止服务计划程序将由于时间不足尚未启动的任务标记为不正常并停止它们。 更新服务时，此参数不会触发新的服务部署。 `loadBalancers` 类型： 对象数组 必需：否 表示要用于您的服务的负载均衡器的负载均衡器对象。对于使用应用程序负载均衡器或网络负载均衡器的服务，最多可将 5 个目标组附加到服务。 更新服务时，此参数会触发新的服务部署。 创建服务后，无法从 AWS 管理控制台 更改负载均衡器配置。您只能使用 AWS Copilot、AWS CloudFormation、AWS CLI 或 SDK 来修改 `ECS` 滚动部署控制器的负载均衡器配置，而不是 AWS CodeDeploy 蓝/绿或外部控制器。当您添加、更新或删除负载均衡器配置时，Amazon ECS 会使用更新后的 Elastic Load Balancing 配置启动新部署。这将导致任务注册到负载均衡器或从负载均衡器取消注册。我们建议您在更新 Elastic Load Balancing 配置之前在测试环境中对此进行验证。有关如何修改配置的信息，请参阅 *Amazon Elastic Container Service API 参考*中的 [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html)。 对于应用程序负载均衡器和网络负载均衡器，此对象必须包含负载均衡器目标组ARN、容器名称（如容器定义中所示）以及要从负载均衡器访问的容器端口。将此服务中的任务放置于容器实例之后，容器实例和端口组合会注册为指定目标组中的目标。 `targetGroupArn` 类型：字符串 必需：否 与服务关联的 Elastic Load Balancing 目标组的完整 Amazon 资源名称（ARN）。 目标组 ARN 仅在使用应用程序负载均衡器或网络负载均衡器时指定。 `loadBalancerName` 类型：字符串 必需：否 要与该服务关联的负载均衡器的名称。 如果您使用的是应用程序负载均衡器或网络负载均衡器，则会省略负载均衡器名称参数。 `containerName` 类型：字符串 必需：否 要与负载均衡器关联的容器的名称（与在容器定义中显示的相同）。 `containerPort` 类型：整数 必需：否 要与负载均衡器关联的容器上的端口。此端口必须对应于服务中的任务所使用任务定义中的 `containerPort`。对于使用 EC2 的任务，容器实例必须允许端口映射的 `hostPort` 上的入站流量。 `role` 类型：字符串 必需：否 允许 Amazon ECS 代表您调用负载均衡器的 IAM 角色的名称或完整 ARN 。仅当为服务使用具有单个目标组的负载均衡器，并且任务定义不使用 `awsvpc` 网络模式时，才允许使用此参数。如果您指定 `role` 参数，则还必须指定具有 `loadBalancers` 参数的负载均衡器对象。 更新服务时，此参数不会触发新的服务部署。 如果您的指定角色的路径并非 `/`，则必须指定完整角色 ARN（推荐）或将此路径作为角色名称的前缀。例如，如果名称为 `bar` 的角色的路径为 `/foo/`，您应指定 `/foo/bar` 作为角色名称。有关更多信息，请参阅 *IAM 用户指南*中的[友好名称和路径](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names)。 如果您的账户已创建 Amazon ECS 服务相关角色，则默认情况下会为您的服务使用该角色，除非您在此处指定一个角色。如果您的任务定义使用 awsvpc 网络模式（在这种情况下，您不应在此处指定角色），则需要服务相关角色。有关更多信息，请参阅 [对 Amazon ECS 使用服务相关角色](using-service-linked-roles.md)。 `serviceConnectConfiguration` 类型：对象 必需：否 此服务的配置用于发现和连接到服务，以及由命名空间内的其他服务发现和连接。 更新服务时，此参数会触发新的服务部署。 有关更多信息，请参阅 [使用 Service Connect 连接具有短名称的 Amazon ECS 服务](service-connect.md)。 `enabled` 类型：布尔值 是否必需：是 指定是否将 Service Connect 与此服务结合使用。 `namespace` 类型：字符串 必需：否 与 Service Connect 结合使用的 AWS Cloud Map 命名空间的 Amazon 资源名称（ARN）短名称或全称。命名空间必须与 Amazon ECS 服务和集群在同一个 AWS 区域 内。命名空间的类型不影响 Service Connect。有关 AWS Cloud Map 的更多信息，请参阅**《AWS Cloud Map 开发人员指南》中的[使用服务](https://docs.aws.amazon.com/cloud-map/latest/dg/working-with-services.html)。 `services` 类型： 对象数组 必需：否 一组 Service Connect 服务对象。这些是其他 Amazon ECS 服务用来连接到此服务的名称和别名（也称为端点）。 对于作为命名空间成员的“客户端”Amazon ECS 服务，只有连接到命名空间内的其他服务时，才需要此字段。例如，接受来自附加到服务的负载均衡器或通过其他方式所传入请求的前端应用程序。 对象从任务定义中选择一个端口，为 AWS Cloud Map 服务分配一个名称，并为客户端应用程序分配别名（也称为端点）数组和端口，以供客户端应用程序引用此服务。 `portName` 类型：字符串 是否必需：是 `portName` 必须与该 Amazon ECS 服务的任务定义中所有容器中的 `portMappings` 的其中一个的 `name` 相匹配。 `discoveryName` 类型：字符串 必需：否 `discoveryName` 是 Amazon ECS 为该 Amazon ECS 服务创建的新 AWS Cloud Map 服务的名称。此名称在 AWS Cloud Map 命名空间内必须是唯一的。 如果未指定此字段，则使用 `portName`。 `clientAliases` 类型： 对象数组 必需：否 此 Service Connect 服务的客户端别名列表。您可以使用这些列表来分配供客户端应用程序使用的名称。您可以在此列表中包含的最大客户端别名数为 1。 每个别名（“端点”）都是 DNS 名称和端口号，其他 Amazon ECS 服务（“客户端”）可以使用该 DNS 名称和端口号连接到此服务。 每个名称和端口组合在命名空间内必须是唯一的。 这些名称是在客户端服务的每项任务中配置的，而不是在 AWS Cloud Map 中配置的。解析这些名称的 DNS 请求不会离开任务，也不会计入每个弹性网络接口每秒的 DNS 请求的配额。 `port` 类型：整数 是否必需：是 Service Connect 代理的侦听端口号。此端口在同一个命名空间内的所有任务中都可用。 为避免更改客户端 Amazon ECS 服务中的应用程序，请将其设置为客户端应用程序默认使用的同一个端口。 `dnsName` 类型：字符串 必需：否 `dnsName` 是您在客户端任务的应用程序中用来连接到此服务的名称。该名称必须是有效的 DNS 标签。 如果未指定该字段，则值默认为 `discoveryName.namespace`。如果未指定 `discoveryName`，则使用任务定义中的 `portName`。 为避免更改客户端 Amazon ECS 服务中的应用程序，请将其设置为客户端应用程序默认使用的同一个名称。例如，一些常用名称是 `database`、`db` 或数据库的小写名称，例如 `mysql` 或 `redis`。 `ingressPortOverride` 类型：整数 必需：否 （可选）Service Connect 代理侦听的端口号。 使用此字段的值绕过此应用程序的任务定义中的已命名 `portMapping` 中指定的端口号上的流量代理，然后在 Amazon VPC 安全组中使用该代理，以允许流量进入该 Amazon ECS 服务的代理。 在 `awsvpc` 模式下，默认值是容器端口号，该端口号在此应用程序的任务定义的已命名 `portMapping` 中指定。在 `bridge` 模式下，默认值是 Service Connect 代理的动态临时端口。 `logConfiguration` 类型：[LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 对象 必需：否 这定义了 Service Connect 代理日志的发布位置。在意外事件期间使用日志进行调试。此配置在此 Amazon ECS 服务的每个任务的 Service Connect 代理容器中设置 `logConfiguration` 参数。没有在任务定义中指定代理容器。 我们建议您使用与该 Amazon ECS 服务任务定义的应用程序容器相同的日志配置。对于 FireLens，这是应用程序容器的日志配置。使用 `fluent-bit` 或 `fluentd ` 容器映像的不是 FireLens 日志路由器容器。 `accessLogConfiguration` 类型：[ServiceConnectAccessLogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 对象 必需：否 Service Connect 访问日志记录的配置，包括日志格式以及日志是否应包含查询字符串。访问日志会捕获有关向服务发出的请求的详细信息，包括请求模式、响应代码和计时数据。要启用访问日志，您还必须在 `serviceConnectConfiguration` 中指定 `logConfiguration`。 `serviceRegistries` 类型： 对象数组 必需：否 服务的服务发现配置的详细信息。有关更多信息，请参阅 [使用服务发现连接具有 DNS 名称的 Amazon ECS 服务](service-discovery.md)。 更新服务时，此参数会触发新的服务部署。 `registryArn` 类型：字符串 必需：否 服务注册表的 Amazon 资源名称（ARN）。当前支持的服务注册表是 AWS Cloud Map。有关更多信息，请参阅 *AWS Cloud Map 开发人员指南*中的[使用服务](https://docs.aws.amazon.com/cloud-map/latest/dg/working-with-services.html)。 `port` 类型：整数 必需：否 在服务发现服务指定 SRV 记录时使用的端口值。如果使用 `awsvpc` 网络模式和 SRV 记录，则需要此字段。 `containerName` 类型：字符串 必需：否 用于服务发现服务的容器名称值。此值可在任务定义中指定。如果服务任务指定的任务定义使用 `bridge` 或 `host` 网络模式，则必须从任务定义中指定 `containerName` 和 `containerPort` 组合。如果服务任务指定的任务定义使用 `awsvpc` 网络模式，并且使用类型 SRV DNS 记录，则必须指定 `containerName` 和 `containerPort` 组合或 `port` 值，但不能同时指定二者。 `containerPort` 类型：整数 必需：否 用于服务发现服务的端口值。此值可在任务定义中指定。如果服务任务指定的任务定义使用 `bridge` 或 `host` 网络模式，则必须从任务定义中指定 `containerName` 和 `containerPort` 组合。如果服务任务指定的任务定义使用 `awsvpc` 网络模式，并且使用类型 SRV DNS 记录，则必须指定 `containerName` 和 `containerPort` 组合或 `port` 值，但不能同时指定二者。 ## 客户端令牌 `clientToken` 类型：字符串 必需：否 用于确保请求的幂等性而提供的唯一、区分大小写的标识符。最长可为 32 个 ASCII 字符。 ## 可用区再平衡 `availabilityZoneRebalancing` 类型：字符串 必需：否 指示服务是否使用可用区重新平衡。有效值为 `ENABLED` 和 `DISABLED`。 更新服务时，此参数不会触发新的服务部署。 默认行为： + 对于新服务：如果未指定值，则默认值为 `DISABLED`。 + 对于现有服务：如果未指定任何值，则 Amazon ECS 会将该值默认为现有值。如果之前未设置任何值，则 Amazon ECS 会将该值设置为 `DISABLED`。 有关可用区再平衡的更多信息，请参阅[在可用区之间平衡 Amazon ECS 服务](service-rebalancing.md)。 ## 卷配置 `volumeConfigurations` 类型：对象 必需：否 用于为服务管理的任务而创建卷的配置。只有在任务定义中标记为 `configuredAtLaunch` 的卷才能使用此对象进行配置。 更新服务时，此参数会触发新的服务部署。 此对象是将 Amazon EBS 卷附加到服务管理的任务所必需的。有关更多信息，请参阅 [将 Amazon EBS 卷与 Amazon ECS 结合使用](ebs-volumes.md)。 `name` 类型：字符串 是否必需：是 创建或更新服务时配置的卷的名称。最多可允许 255 个字母（大写和小写字母）、数字、下划线（`_`）和连字符（`-`）。此值必须与任务定义中指定的卷名称相匹配。 `managedEBSVolume` 类型：对象 必需：否 用于创建 Amazon EBS 卷的卷配置，这些卷附加到在创建或更新服务时由服务维护的任务。每个任务附加一个卷。 `encrypted` 类型：布尔值 必需：否 有效值：`true`\$1`false` 指定是否加密每个创建的 Amazon EBS 卷。如果您已为 AWS 账户的特定 AWS 区域默认启用了 Amazon EBS 加密，但将此参数设置为 `false`，则此参数将被覆盖，并且卷将默认使用指定用于加密的 KMS 密钥进行加密。有关默认 Amazon EBS 加密的更多信息，请参阅《*Amazon EBS 用户指南*》中的 [Enable Amazon EBS encryption by default](https://docs.aws.amazon.com/ebs/latest/userguide/encryption-by-default.html)。有关加密附加到 Amazon ECS 任务的 Amazon EBS 卷的更多信息，请参阅[加密附加到 Amazon ECS 任务的 Amazon EBS 卷中存储的数据](ebs-kms-encryption.md)。 `kmsKeyId` 类型：字符串 必需：否 用于 Amazon EBS 加密的 AWS Key Management Service（AWS KMS）密钥的标识符。如果指定了 `kmsKeyId`，加密状态必须为 `true`。 使用此参数指定的密钥将覆盖 Amazon EBS 默认值或您可能已指定的 Amazon ECS 托管存储加密的任何集群级 KMS 密钥。有关更多信息，请参阅 [加密附加到 Amazon ECS 任务的 Amazon EBS 卷中存储的数据](ebs-kms-encryption.md)。 您可以使用以下任一项指定 KMS 密钥： + **密钥 ID** – 例如 `1234abcd-12ab-34cd-56ef-1234567890ab`。 + **密钥别名** – 例如 `alias/ExampleAlias`。 + **密钥 ARN** – 例如 `arn:aws:kms:us-east-1:012345678910:key/1234abcd-12ab-34cd-56ef-1234567890ab`。 + **别名 ARN** – 例如 `arn:aws:kms:us-east-1:012345678910:alias/ExampleAlias`。 AWS 异步验证 KMS 密钥的身份。因此，如果您指定了无效的 ID、别名或 ARN，则操作可能会显示成功，但最终会失败。有关更多信息，请参阅[排查 Amazon EBS 卷附加问题](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/troubleshoot-ebs-volumes.html)。 `volumeType` 类型：字符串 必需：否 有效值：`gp2`\$1`gp3`\$1`io1`\$1`io2`\$1`sc1`\$1`st1`\$1`standard` Amazon EBS 卷类型。有关卷类型的更多信息，请参阅《Amazon EBS 用户指南》**中的 [Amazon EBS volume types](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-volume-types.html)。默认卷类型为 `gp3`。 Fargate 任务不支持 `standard` 卷类型。 `sizeInGiB` 类型：整数 必需：否 有效范围：介于 1 到 16384 之间的整数 EBS 卷的大小，以吉字节（GiB）为单位。如果您没有提供快照 ID 来配置要附加的卷，则必须提供大小值。如果使用快照配置卷以进行附加，则默认值为快照大小。然后，您可以指定大于或等于快照大小的大小。 对于 `gp2` 和 `gp3` 卷类型，有效范围为 1-16384。 对于 `io1` 和 `io2` 卷类型，有效范围为 4-16384。 对于 `st1` 和 `sc1` 卷类型，有效范围为 125-16384。 对于 `standard` 卷类型，有效范围为 1-1024。 `snapshotId` 类型：字符串 必需：否 Amazon ECS 用来创建要附加的新卷的现有 Amazon EBS 卷的快照的 ID。您必须指定 `snapshotId` 或 `sizeInGiB`。 `volumeInitializationRate` 类型：整数 必需：否 从现有 Amazon EBS 卷的快照中提取数据以创建要附加的新卷的速率（以 MiB/s 为单位）。仅当您指定了 `snapshotId` 时才可以指定此属性。有关此卷初始化速率的更多信息，包括支持的初始化速率范围，请参阅《*Amazon EBS 用户指南*》中的 [Initialize Amazon EBS volumes](https://docs.aws.amazon.com/ebs/latest/userguide/initalize-volume.html)。 `iops` 类型：整数 必需：否 每秒 I/O 操作数（IOPS）。对于 `gp3`、`io1` 和 `io2` 卷，这代表为卷预置的 IOPS 数。对于 `gp2` 卷，此值表示卷的基准性能和卷积累用于突增情况的 I/O 积分的速度。此参数是 `io1` 和 `io2` 卷的必需参数。`gp2`、`st1`、`sc1` 或 `standard` 卷不支持此参数。 对于 `gp3` 卷，值的有效范围为 3000 到 16000。 对于 `io1` 卷，值的有效范围为 100 到 64000。 对于 `io2` 卷，值的有效范围为 100 到 64000。 `throughput` 类型：整数 必需：否 为附加到服务维护的任务的卷预调配的吞吐量。 仅 `gp3` 卷支持此参数。 `roleArn` 类型：字符串 是否必需：是 基础设施 AWS Identity and Access Management（IAM）角色的 Amazon 资源 ARN（ARN），它为您的任务提供 Amazon ECS 管理 Amazon EBS 资源的权限。有关更多信息，请参阅 [Amazon ECS 基础设施 IAM 角色](infrastructure_IAM_role.md)。 `tagSpecifications` 类型：对象 必需：否 应用于每个 Amazon EBS 卷的标签的规范。 `resourceType` 类型：字符串 是否必需：是 有效值：`volume` 要在创建时标记的资源类型。 `tags` 类型： 对象数组 必需：否 您应用于卷以帮助您对其进行分类和组织的元数据。每个标签都包含您定义的一个键和一个可选值。`AmazonECSCreated` 和 `AmazonECSManaged` 是 Amazon ECS 代表您添加的保留标签，因此您最多可以自己指定 48 个标签。在卷被删除时，标签也会随之被删除。有关更多信息，请参阅 [为 Amazon ECS 资源添加标签](ecs-using-tags.md)。 `key` 类型：字符串 长度限制：最小长度为 1。最大长度为 128。 必需：否 构成标签的键-值对的一个部分。键是一种常见的标签，行为类似于更具体的标签值的类别。 `value` 类型：字符串 长度限制：最小长度为 0。长度上限为 256。 必需：否 构成标签的键-值对的可选部分。值充当标签类别（键）中的描述符。 `propagateTags` 类型：字符串 有效值：`TASK_DEFINITION` \$1`SERVICE` \$1`NONE` 必需：否 指定是否要将标签从任务定义或服务复制到卷中。如果指定 `NONE` 或未指定任何值，则不会复制标签。 `fileSystemType` 类型：字符串 必需：否 有效值：`xfs`\$1`ext3`\$1`ext4`\$1`NTFS` 卷上的文件系统的类型。卷的文件系统类型会决定在卷中存储和检索数据的方式。对于从快照创建的卷，必须指定创建快照时卷使用的相同文件系统类型。如果文件系统类型不匹配，则任务将无法启动。 Linux 的有效值为 `xfs`、ext3`, and ext4`。附加到 Linux 任务的卷的默认值为 `XFS`。 Windows 的有效值为 `NTFS`。对于挂载到 Windows 任务的卷，默认值为 `NTFS`。