# 为 Amazon ECS 资源添加标签
<a name="ecs-using-tags"></a>

为了帮助您管理 Amazon ECS 资源，您可以选择使用*标签*将自己的元数据分配给任何基于 ARN 的资源。每个*标签*都由一个*键*和一个可选*值*组成。

您可以使用标签按照不同方式（例如按用途、所有者或环境）对 Amazon ECS 资源进行分类。这在您有许多相同类型的资源时会非常有用。您可以根据分配到特定资源的标签来快速识别该资源。例如，您可以为您账户的 Amazon ECS 实例定义一组标签。这有助于您跟踪每个实例的所有者和堆栈级别。

您可以将标签用于成本和使用情况报告。您可以使用这些报告来分析 Amazon ECS 资源的成本和使用情况。有关更多信息，请参阅 [Amazon ECS 使用率报告](usage-reports.md)。

**警告**  
许多 API 会返回标签密钥及其值。拒绝访问 `DescribeTags` 不会自动拒绝访问其他 API 返回的标签。作为最佳实践，我们建议您不要在标签中包含敏感数据。

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

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

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

## 如何为资源添加标签
<a name="tag-resources"></a>

有多种方式可以为 Amazon ECS 任务、服务、任务定义和集群添加标签：
+ 用户使用 Amazon Web Services 管理控制台、Amazon ECS API、Amazon CLI 或 Amazon SDK 为资源手动添加标签。
+ 用户创建服务或运行独立任务，然后选择 Amazon ECS 托管标签选项。

  Amazon ECS 会自动为所有新启动的任务添加标签。有关更多信息，请参阅 [Amazon ECS 托管标签](#managed-tags)。
+ 用户使用控制台创建资源。控制台会自动为资源添加标签。

  这些标签在 Amazon CLI 和 Amazon SDK 响应中返回，并显示在控制台中。您无法修改或删除这些标签。

  有关添加的标签的信息，请参阅 **Amazon ECS 资源标签支持**表中的**控制台自动添加的标签**列。

如果您在创建资源时指定了标签但无法应用标签，Amazon ECS 会回滚创建过程。这样可确保要么创建带有标签的资源，要么根本不创建资源，即任何时候都不会创建出未标记的资源。通过在创建资源时对其进行标记，无需在创建资源后运行自定义标记脚本。

下表描述了支持标签的 Amazon ECS 资源。


|  资源  |  支持标签  |  支持标签传播  | 控制台自动添加的标签 | 
| --- | --- | --- | --- | 
| Amazon ECS 任务 | 是 | 是，从任务定义。 | 键：aws:ecs:clusterName*值*：`cluster-name` | 
| Amazon ECS 服务 | 是 | 是，从任务定义或服务到服务中的任务。 | 键：ecs:service:stackId*值* `arn:aws:cloudformation:{{arn}}` | 
| Amazon ECS 任务集 | 是 | 否 | 不适用 | 
| Amazon ECS 任务定义 | 是 | 否 | 键：ecs:taskDefinition:createdFrom*值*：`ecs-console-v2` | 
| Amazon ECS 集群 | 是 | 否 | 键：aws:cloudformation:logical-id*值*：`ECSCluster`键：aws:cloudformation:stack-id<br />*值*：`arn:aws:cloudformation:{{arn}}`<br />*键*：`aws:cloudformation:stack-name`<br />*值*：`ECS-Console-V2-Cluster-{{EXAMPLE}}` | 
| Amazon ECS 容器实例。 | 是 | 是，从 Amazon EC2 实例。有关更多信息，请参阅 [向 Amazon ECS 的 Amazon EC2 容器实例添加标签](instance-details-tags.md)。 | 不适用 | 
| Amazon ECS 外部实例 | 是 | 否 | 不适用 | 
| Amazon ECS 容量提供程序 |  可以。您不能为预定义的 `FARGATE` 和 `FARGATE_SPOT` 容量提供程序添加标签。 | 是的，仅来自 Amazon ECS 托管实例的容量提供程序。您可以将标签从 Amazon ECS 托管实例的容量提供程序传播到该提供程序管理的所有资源，例如 Amazon EC2 实例、启动模板、弹性网络接口和卷。 | 不适用 | 

## 在创建时标记资源
<a name="tags-on-creation"></a>

以下资源支持在创建时使用 Amazon ECS API、Amazon CLI 或 Amazon SDK 进行标记：
+ Amazon ECS 任务
+ Amazon ECS 服务
+ Amazon ECS 任务定义
+ Amazon ECS 任务集
+ Amazon ECS 集群
+ Amazon ECS 容器实例。
+ Amazon ECS 容量提供程序

Amazon ECS 可以选择使用标记授权来创建资源。配置 Amazon Web Services 账户 进行标记授权时，用户必须对创建资源的操作具有权限，例如 `ecsCreateCluster`。在资源创建操作中指定标签时，Amazon 会执行额外的授权，以验证用户或角色是否具备创建标签的权限。因此，您必须授予使用 `ecs:TagResource` 操作的显式权限。有关更多信息，请参阅 [在创建时授予标记资源的权限](supported-iam-actions-tagging.md)。有关如何配置选项的信息，请参阅[标记授权](ecs-account-settings.md#tag-resources-setting)。

## 限制
<a name="tag-restrictions"></a>

以下限制适用于标签：
+ 一个资源最多可以关联 50 个标签。
+ 不能对一个资源重复使用标签键。每个标签键必须具有唯一性，而且只能有一个值。
+ 键最长可达 128 个字符（采用 UTF-8 格式）。
+ 值最长可达 256 个字符（采用 UTF-8 格式）。
+ 如果有多个 Amazon Web Services 服务 和资源使用您的标记方案，请限制您使用的字符类型。某些服务可能对允许使用的字符有限制。通常允许使用的字符包括字母、数字、空格以及以下字符：`+` `-` `=` `.` `_` `:` `/` `@`。
+ 标签键和值区分大小写。
+ 不能使用 `aws:`、`AWS:` 或它们的任何大写或小写组合作为键或值的前缀。它们保留供 Amazon 使用。无法编辑或删除带此前缀的标签键或值。具有此前缀的标签不计入每个资源的标签数限制。

## Amazon ECS 托管标签
<a name="managed-tags"></a>

当您使用 Amazon ECS 托管标签时，Amazon ECS 会自动使用集群信息和用户添加的任务定义标签或服务标签来标记所有新启动的任务和附加到任务的任何 Amazon EBS 卷。下面介绍了添加的标签：
+ 独立任务 – *键*为 `aws:ecs:clusterName` 且*值*设置为集群名称的标签。用户添加的所有任务定义标签。附加到独立任务的 Amazon EBS 卷将收到带有*密钥*为 `aws:ecs:clusterName`、*值*设置为集群名称的标签。有关 Amazon EBS 卷标记的更多信息，请参阅[标记 Amazon EBS 卷](https://docs.amazonaws.cn/AmazonECS/latest/developerguide/specify-ebs-config.html#ebs-volume-tagging)。
+ 服务所包含的任务 – *键*为 `aws:ecs:clusterName` 且*值*设置为集群名称的标签。*键*为 `aws:ecs:serviceName` 且*值*设置为服务名称的标签。来自以下资源之一的标签：
  + 任务定义 – 用户添加的所有任务定义标签。
  + 服务 – 用户添加的所有服务标签。

    附加到作为服务一部分的任务的 Amazon EBS 卷将收到一个*键*为 `aws:ecs:clusterName`、*值*设置为集群名称的标签，以及一个*键*为 `aws:ecs:serviceName`、*值*设置为服务名称的标签。有关 Amazon EBS 卷标记的更多信息，请参阅[标记 Amazon EBS 卷](https://docs.amazonaws.cn/AmazonECS/latest/developerguide/specify-ebs-config.html#ebs-volume-tagging)。

此功能需要以下选项：
+ 您必须选择使用新的 Amazon 资源名称（ARN）和资源标识符（ID）格式。有关更多信息，请参阅 [Amazon 资源名称（ARN）和 ID](ecs-account-settings.md#ecs-resource-ids)。
+ 当您使用 API 创建服务或运行任务时，您必须将 `run-task` 和 `create-service` 的 `enableECSManagedTags` 设置为 `true`。有关更多信息，请参阅 *Amazon Command Line Interface API 参考*中的 [create-service](https://docs.amazonaws.cn/AmazonECS/latest/APIReference/API_CreateService.html) 和 [run-task](https://docs.amazonaws.cn/AmazonECS/latest/APIReference/API_RunTask.html)。
+ Amazon ECS 使用托管标签来确定何时启用某些功能，例如集群自动扩缩。建议您不要手动修改标签，以便 Amazon ECS 可以有效地管理这些功能。

## 使用标签记账
<a name="tag-resources-for-billing"></a>

Amazon 提供了名为 Cost Explorer 的报告工具，您可以使用它来分析 Amazon ECS 资源的成本和用量。

您可以使用 Cost Explorer 查看用量和成本的图表。您可以查看过去 13 个月的数据，并预测您在接下来三个月内可能产生的费用。您可以使用 Cost Explorer 查看您在 Amazon 资源上花费的时间模式。如，您可以使用它来确定需要进一步查询的方面，并查看可用于了解成本的趋势。您还可以指定数据的时间范围，并按天或按月查看时间数据。

您可以为成本和使用情况报告使用 Amazon ECS 托管标签或用户添加的标签。有关更多信息，请参阅 [Amazon ECS 使用率报告](usage-reports.md)。

如需查看组合资源的成本，请按具有相同标签键值的资源组织您的账单信息。例如，您可以将特定的应用程序名称用作几个资源的标签，然后组织账单信息，以查看在数个服务中的使用该应用程序的总成本。有关设置带有标签的成本分配报告的更多信息，请参阅 *Amazon Billing 用户指南*中的[月度成本分配报告](https://docs.amazonaws.cn/awsaccountbilling/latest/aboutv2/configurecostallocreport.html)。

此外，您可以启用*拆分成本分配数据*，以获取成本和使用量报告中的任务级 CPU 和内存使用情况数据。有关更多信息，请参阅 [任务级成本和使用量报告](usage-reports.md#task-cur)。

**注意**  
如果已启用报告，则最多需要 24 小时才能后查看当月的数据。