为您的 Amazon ECS 资源添加标签 - Amazon Elastic Container Service
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

为您的 Amazon ECS 资源添加标签

为了帮助您管理 Amazon ECS 资源,您可以选择使用标签将自己的元数据分配给任何基于 ARN 的资源。本主题概述 Amazon ECS 中的标签以及您如何创建标签。

要使用此功能,需要您选择使用新 Amazon Resource Name (ARN) 和资源标识符 (ID) 格式。有关更多信息,请参阅 Amazon Resource Names (ARN) 和 ID

重要

请勿在标签中添加个人身份信息(PII)或其他机密或敏感信息。标签可供许多 Amazon 服务访问,包括计费。标签不适合用于私有或敏感数据。

有关标签的基本知识

标签是为 Amazon 资源分配的标记。每个标签都包含您定义的一个 和一个可选

标签可让您按各种标准 (例如用途、所有者或环境) 对 Amazon 资源进行分类。这在您有许多相同类型的资源时会非常有用。您可以根据分配到特定资源的标签来快速识别该资源。例如,您可以为账户中的 Amazon ECS 实例定义一组标签,以跟踪每个实例的所有者和堆栈级别。

我们建议您针对每类资源设计一组标签,以满足您的需要。使用一组连续的标签键,管理资源时会更加轻松。您可以根据添加的标签搜索和筛选资源。

标签对 Amazon ECS 没有任何语义意义,应严格按字符串进行解析。同时,标签不会自动分配至您的资源。您可以修改标签的密钥和值,还可以随时删除资源的标签。您可以将标签的值设为空的字符串,但是不能将其设为空值。如果您添加的标签的键与该资源上现有标签的键相同,则新值会覆盖旧值。如果删除资源,资源的所有标签也会被删除。

可以使用 Amazon Web Services Management Console、Amazon CLI 和 Amazon ECS API 处理标签。

如果您使用的是 Amazon Identity and Access Management (IAM),则可以控制您的Amazon账户中的哪些用户拥有管理标签的权限。

给资源加标签

您可以标记新的或现有的 Amazon ECS 任务、服务、任务定义和集群。

重要

请勿在标签中添加个人身份信息(PII)或其他机密或敏感信息。标签可供许多 Amazon 服务访问,包括计费。标签不适合用于私有或敏感数据。

如果您使用的是 Amazon ECS 控制台,您可以随时使用相关资源页面上的标签选项卡将标记应用于新资源或现有资源。当您使用 Amazon ECS 托管的标签选项(来自选项的传播标签),则标签将从任务定义或服务复制到任务。可以在运行任务或创建服务时完成此操作。

如果您使用的是 Amazon ECS API、Amazon CLI 或 Amazon 开发工具包,则可以使用相关 API 操作上的 tags 参数对新资源应用标签,或使用相关 API 操作对现有资源应用标签。此外,也可以使用 TagResource API 操作将标签应用到现有资源。有关更多信息,请参阅 TagResourcepropagateTags 参数可用于将标签从任务定义或服务复制到服务中的任务。可以在运行任务或创建服务时完成此操作。有关更多信息,请参阅 RunTaskCreateService

此外,某些资源创建操作允许您在创建资源时为其指定标签。如果在创建资源时无法应用标签,我们将回滚创建资源的过程。这样可确保要么创建带有标签的资源,要么根本不创建资源,即任何时候都不会创建出未标记的资源。通过在创建资源时对其进行标记,无需在创建资源后运行自定义标记脚本。

下表描述了可以标记的 Amazon ECS 资源以及可在创建时标记的资源。

Amazon ECS 资源标记支持

资源

支持标签

支持标签传播

支持在创建时添加标签(Amazon ECS API、Amazon CLI、Amazon SDK)

Amazon ECS 任务

是,从任务定义。

Amazon ECS 服务

是,从任务定义或服务到服务中的任务。

Amazon ECS 任务集

Amazon ECS 任务定义

Amazon ECS 集群

Amazon ECS 容器实例。

是,从 Amazon EC2 实例。有关更多信息,请参阅 向 Amazon EC2 容器实例添加标签

Amazon ECS 外部实例

不,您可以在使用 Amazon Web Services Management Console 或使用 Amazon ECS API、Amazon CLI 或 Amazon SDK 将外部实例注册到集群后添加标记。有关更多信息,请参阅 使用经典控制台为单个资源添加和删除标签

Amazon ECS 容量提供程序 是。无法对预定义的 FARGATEFARGATE_SPOT 容量提供程序进行标记。

标签限制

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

  • 每个资源的标签数上限 – 50

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

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

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

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

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

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

标记资源以便于计费

使用 Amazon ECS 托管的标签时,Amazon ECS 会自动使用集群名称标记所有新启动的任务。对于属于某个服务的任务,它们也会被标记为服务名称。在成本和使用率报告中启用这些托管标签后,在查看成本分配时这些托管标签非常有帮助。有关更多信息,请参阅 Amazon ECS 使用率报告

如需查看组合资源的成本,请按具有相同标签键值的资源组织您的账单信息。例如,您可以将特定的应用程序名称用作几个资源的标签,然后组织账单信息,以查看在数个服务中的使用该应用程序的总成本。有关设置带有标签的成本分配报告的更多信息,请参阅 Amazon Billing and Cost Management 用户指南中的月度成本分配报告

重要

要使用此功能,需要您选择使用新 Amazon Resource Name (ARN) 和资源标识符 (ID) 格式。有关更多信息,请参阅 Amazon Resource Names (ARN) 和 ID

注意

如果您已启用报告,则可以在 24 小时后查看当月的数据。

通过控制台使用标签

使用 Amazon ECS 控制台,您可以管理与新的或现有的任务、服务、任务定义、集群或容器实例相关的标签。

当您在 Amazon ECS 控制台中选择特定资源页面时,它会显示这些资源的列表。例如,如果您从导航窗格中选择 Clusters (集群),则控制台会显示 Amazon ECS 集群列表。当您从其中一个列表中选择一种支持标签的资源(例如,特定集群)时,您可以在标签选项卡上查看和管理其标签。

重要

请勿在标签中添加个人身份信息(PII)或其他机密或敏感信息。标签可供许多 Amazon 服务访问,包括计费。标签不适合用于私有或敏感数据。

在启动过程中为单个资源添加标签

以下资源允许您在创建该资源时指定标签。

任务

控制台

运行一个或多个任务。

运行独立任务

创建服务。

创建 Amazon ECS 服务

创建任务集。

外部部署

注册任务定义。

使用新控制台创建任务定义

创建集群。

使用经典控制台创建集群

运行一个或多个容器实例。

启动 Amazon ECS Linux 容器实例

使用经典控制台为单个资源添加和删除标签

Amazon ECS 允许您直接从资源的页面中添加或删除与集群、服务、任务和任务定义相关的标签。有关标记容器实例的信息,请参阅。向 Amazon EC2 容器实例添加标签

向单个资源添加标签

  1. 打开位于 https://console.aws.amazon.com/ecs/的 Amazon ECS 控制台。

  2. 从导航栏中,选择要使用的区域。

  3. 在导航窗格中,选择资源类型(例如,Clusters (集群))。

  4. 从资源列表中选择资源,然后依次选择 Tags (标签)Edit (编辑)

  5. Edit Tags (编辑标签) 对话框中,为每个标签指定键和值,然后选择 Save (保存)

删除单个资源的标签

  1. 打开位于 https://console.aws.amazon.com/ecs/的 Amazon ECS 控制台。

  2. 从导航栏中,选择要使用的区域。

  3. 在导航窗格中,选择资源类型(例如,Clusters (集群))。

  4. 从资源列表中选择资源,然后依次选择 Tags (标签)Edit (编辑)

  5. Edit Tags (编辑标签) 页面上,选择要删除的每个标签对应的 Delete (删除) 图标,然后选择 Save (保存)

向 Amazon EC2 容器实例添加标签

您可以使用以下方法之一将标签与您的容器实例相关联:

  • 方法 1 - 在使用 Amazon EC2 API、CLI 或控制台创建容器实例时,通过使用容器代理配置参数 ECS_CONTAINER_INSTANCE_TAGS 将用户数据传递到实例来指定标签。这只创建与 Amazon ECS 中的容器实例关联的标签,而无法使用 Amazon EC2 API 列出这些标签。有关更多信息,请参阅 使用 Amazon EC2 用户数据引导启动容器实例

    重要

    如果使用 Amazon EC2 Auto Scaling 组启动容器实例,则应使用ECS_CONTAINER_INSTANCE_TAGS 配置参数添加标签。这是由标签添加到使用 Auto Scaling 组启动的 Amazon EC2 实例的方式造成的。

    下面是将标签与您的容器实例相关联的用户数据脚本示例:

    #!/bin/bash cat <<'EOF' >> /etc/ecs/ecs.config ECS_CLUSTER=MyCluster ECS_CONTAINER_INSTANCE_TAGS={"tag_key": "tag_value"} EOF
  • 方法 2–使用 Amazon EC2 API、CLI 或控制台创建容器实例时,使用参数 TagSpecification.N 指定标记,然后使用容器代理配置参数 ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM 将用户数据传递给实例。这样做会将它们从 Amazon EC2 传播到 Amazon ECS。

    下面是一个用户数据脚本示例,该脚本将传播与 Amazon EC2 实例关联的标签,以及向名为 MyCluster 的集群注册实例:

    #!/bin/bash cat <<'EOF' >> /etc/ecs/ecs.config ECS_CLUSTER=MyCluster ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM=ec2_instance EOF

    要提供访问权限以允许容器实例标签从 Amazon EC2 传播到 Amazon ECS,请手动将以下权限作为内链策略添加到 Amazon ECS 容器实例 IAM 角色。有关更多信息,请参阅添加和删除 IAM 策略

    • ec2:DescribeTags

    以下示例内联策略会添加这些权限。

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:DescribeTags" ], "Resource": "*" } ] }

向外部容器实例添加标签

您可以使用以下方法之一将标签与您的外部容器实例相关联:

  • 方法 1–在运行安装脚本向集群注册外部实例之前,请在 /etc/ecs/ecs.config 处创建或编辑 Amazon ECS 容器代理配置文件,并添加 ECS_CONTAINER_INSTANCE_TAGS 容器代理配置参数。这将创建与外部实例关联的标签。

    下面是显示应使用的语法的示例。

    ECS_CONTAINER_INSTANCE_TAGS={"tag_key": "tag_value"}
  • 方法 2 — 将外部实例注册到集群后,您可以使用 Amazon Web Services Management Console 添加标签。有关更多信息,请参阅 使用经典控制台为单个资源添加和删除标签

通过 CLI 或 API 使用标签

使用以下命令添加、更新、列出和删除资源标签。相应文档提供了示例。

重要

请勿在标签中添加个人身份信息(PII)或其他机密或敏感信息。标签可供许多 Amazon 服务访问,包括计费。标签不适合用于私有或敏感数据。

Amazon ECS 资源标记支持

任务

Amazon CLI

API 操作

添加或覆盖一个或多个标签。

tag-resource

TagResource

删除一个或多个标签。

untag-resource

UntagResource

以下示例说明如何使用 Amazon CLI 标记或取消标记资源。

示例 1:标记现有集群

以下命令标记现有集群。

aws ecs tag-resource --resource-arn resource_ARN --tags key=stack,value=dev

示例 2:取消标记现有集群

以下命令从现有集群删除标签。

aws ecs untag-resource --resource-arn resource_ARN --tag-keys tag_key

示例 3:列出资源的标签

以下命令列出与现有资源关联的标签。

aws ecs list-tags-for-resource --resource-arn resource_ARN

某些资源创建操作允许您在创建资源时指定标签。以下操作支持在创建时进行标记。

任务

Amazon CLI

Amazon Tools for Windows PowerShell

API 操作

运行一个或多个任务。

run-task

Start-ECSTask

RunTask

创建服务。

create-service

New-ECSService

CreateService

创建任务集。

create-task-set

New-ECSTaskSet

CreateTaskSet

注册任务定义。

register-task-definition

Register-ECSTaskDefinition

RegisterTaskDefinition

创建集群。

create-cluster

New-ECSCluster

CreateCluster

运行一个或多个容器实例。

run-instances ()

New-EC2Instance()

RunInstances

以下示例说明如何在创建资源时应用标签。

示例 1:创建集群并应用标签

以下命令创建一个名为 devcluster 的集群并添加键为 team 且值为 devs 的标签。

aws ecs create-cluster --cluster-name devcluster --tags key=team,value=devs

示例 2:创建服务并应用标签

以下命令创建一个名为 application 的服务并添加键为 stack 且值为 dev 的标签。

aws ecs create-service --service-name application --task-definition task-def-app --tags key=stack,value=dev

示例 3:创建带标签的服务并将标签传播到任务。

--propagateTags 参数可用于将标签从任务定义或服务复制到服务中的任务。以下命令创建具有标签的服务并将标签传播到该服务中的任务。

aws ecs create-service --service-name application --task-definition task-def-app --tags key=stack,value=dev --propagateTags Service