# 将 Amazon ECS 短服务 ARN 迁移到长 ARN
Amazon ECS 为每个服务分配一个唯一的 Amazon 资源名称（ARN）。2021 年之前创建的服务采用短 ARN 格式：
`arn:aws:ecs:region:aws_account_id:service/service-name`
Amazon ECS 已将 ARN 格式更改为包含集群名称。这是一种长 ARN 格式：
`arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name`
您的服务必须使用长 ARN 格式才能标记服务。
可以将短 ARN 格式的服务迁移到长 ARN 格式，而无需重新创建服务。您可以使用 API、CLI 或控制台。您不能撤消迁移操作。
迁移过程是无缝的，可确保服务零停机时间。迁移期间：
+ **服务可用性**：服务继续正常运行，流量或功能不会中断。
+ **正在运行的任务**：现有任务可以继续运行，不会中断。如果启用了 `taskLongArnFormat` 账户设置，迁移后启动的新任务将使用长 ARN 格式。
+ **容器实例**：容器实例不受服务 ARN 迁移的影响，可以继续正常运行。
+ **服务配置**：所有服务设置，包括任务定义、网络和负载均衡器配置，均保持不变。
如果要使用 CloudFormation 标记简短 ARN 格式的服务，则必须使用 API、CLI 或控制台迁移该服务。迁移完成后，您可以使用 CloudFormation 标记服务。
如果要使用 Terraform 标记简短 ARN 格式的服务，则必须使用 API、CLI 或控制台迁移该服务。迁移完成后，您可以使用 Terraform 标记服务。
完成迁移后，服务将具有以下更改：
+ 长 ARN 格式
`arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name`
+ 当您使用控制台进行迁移时，Amazon ECS 会向服务添加一个标签，其键设置为“ecs:serviceArnMigratedAt”，值设置为迁移时间戳（UTC 格式）。
此标签计入您的标签配额。
+ 当 CloudFormation 堆栈中的 `PhysicalResourceId` 表示服务 ARN 时，该值不会更改，并且将继续作为短服务 ARN。
## 先决条件
在迁移服务 ARN 之前执行以下操作。
1. 要查看您的服务 ARN 是否较短，请在 Amazon ECS 控制台中查看服务详细信息（当服务采用短 ARN 格式时，您会看到警告），或者查看来自 `describe-services` 的 `serviceARN` 返回参数。当 ARN 不包含集群名称时，您就有一个短 ARN。短 ARN 的格式如下所示：
`arn:aws:ecs:region:aws_account_id:service/service-name`
1. 记下已创建日期。
1. 如果您的 IAM 策略使用的是短 ARN 格式，则请将其更新为长 ARN 格式。
将每个*用户输入占位符*替换为您自己的信息。
`arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name`
有关更多信息，请参阅《AWS Identity and Access Management 用户指南》**中的[编辑 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-edit.html)。
1. 如果您的工具使用的是短 ARN 格式，则请将其更新为长 ARN 格式。
将每个*用户输入占位符*替换为您自己的信息。
`arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name`
1. 启用服务长 ARN 格式。在 `serviceLongArnFormat` 选项设置为 `enabled` 的情况下运行 `put-account-setting`。有关更多信息，请参阅《Amazon Elastic Container Service API 参考》**中的 [put-account-setting](https://docs.aws.amazon.com/cli/latest/reference/ecs/put-account-setting.html)。
当您的服务有未知 `createdAt` 日期时，以根用户身份运行该命令。
```
aws ecs put-account-setting --name serviceLongArnFormat --value enabled
```
输出示例
```
{
"setting": {
"name": "serviceLongArnFormat",
"value": "enabled",
"principalArn": "arn:aws:iam::123456789012:role/your-role",
"type": user
}
}
```
1. 启用任务长 ARN 格式。此账户设置会控制服务迁移完成后启动的新任务的 ARN 格式。在 `taskLongArnFormat` 选项设置为 `enabled` 的情况下运行 `put-account-setting`。有关更多信息，请参阅《Amazon Elastic Container Service API 参考》**中的 [put-account-setting](https://docs.aws.amazon.com/cli/latest/reference/ecs/put-account-setting.html)。
当您的服务有未知 `createdAt` 日期时，以根用户身份运行该命令。
```
aws ecs put-account-setting --name taskLongArnFormat --value enabled
```
输出示例
```
{
"setting": {
"name": "taskLongArnFormat",
"value": "enabled",
"principalArn": "arn:aws:iam::123456789012:role/your-role",
"type": user
}
}
```
**注意**
`taskLongArnFormat` 设置不会直接迁移现有任务，仅会影响在启用该设置后创建的新任务的 ARN 格式。现有的正在运行的任务会保留当前的 ARN 格式，直到正常的服务操作（例如部署或扩展活动）将其替换。
## 过程
使用以下内容迁移您的服务 ARN。
### 控制台
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在 **Clusters**（集群）页面上，选择集群。
1. 在**服务**部分中，选择 ARN 列中包含警告的服务。
此时系统会显示服务详细信息页面。
1. 选择**迁移到长 ARN**。
将显示“迁移服务”对话框。
1. 选择 **Migrate**。
### CLI
完成先决条件后，您可以标记服务。运行如下命令：
Amazon ECS 考虑在带有短 ARN 的服务的 `tag-resource` API 请求中传递长 ARN 格式，作为将服务迁移到使用长 ARN 格式的信号。
```
aws ecs tag-resource \
--resource-arn arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name
--tags key=key1,value=value1
```
以下示例使用键设置为“TestService”、值设置为“WebServers”的标签来标记 MyService：
```
aws ecs tag-resource \
--resource-arn arn:aws:ecs:us-east-1:123456789012:service/MyCluster/MyService
--tags key=TestService1,value=WebServers
```
### Terraform
完成先决条件后，您可以标记服务。创建 `aws_ecs_service` 资源并设置 `tags` 引用。有关更多信息，请参阅 Terraform 文档中的 [Resource: aws\$1ecs\$1service](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ecs_service)。
```
resource "aws_ecs_service" "MyService" {
name = "example"
cluster = aws_ecs_cluster.MyService.id
tags = {
"Name" = "MyService"
"Environment" = "Production"
"Department" = "QualityAssurance"
}
}
```
### 后续步骤
您可以向服务添加标签。有关更多信息，请参阅 [向 Amazon ECS 资源添加标签](tag-resources-console.md)。
如果您希望 Amazon ECS 将标签从任务定义或服务传播到任务中，则请使用 `propagateTags` 参数运行 `update-service`。有关更多信息，请参阅《AWS Command Line Interface 参考》**中的 [update-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/update-service.html)。
## 问题排查
一些用户在从短 ARN 格式迁移到长 ARN 格式时可能会遇到以下错误。
`There was an error while migrating the ARN of service service-name. The specified account does not have serviceLongArnFormat or taskLongArnFormat account settings enabled. Add account settings in order to enable tagging.`
如果您已经启用了 `serviceLongArnFormat` 账户设置，但仍然遇到此错误，则可能是因为最初创建服务的特定 IAM 主体尚未启用长 ARN 格式的账户设置。
1. 确定创建服务的主体。
1. 在控制台中，可以在 Amazon ECS 控制台的“服务详细信息”页面的**配置和网络**选项卡中的**创建者**字段中找到该信息。
1. 对于 AWS CLI，运行下面的命令：
将 *user-input* 替换为您的值。
```
aws ecs describe-services --cluster cluster-name --services service-name --query 'services[0].{createdBy: createdBy}'
```
1. 为该特定主体启用所需的账户设置。您可以通过下列方式之一来执行该操作：
1. 代入该主体的 IAM 用户或角色。然后运行 `put-account-setting`。
1. 使用根用户运行命令，同时使用 `principal-arn` 指定创建主体。
示例。
将 *principal-arn* 替换为步骤 1 中的值。
```
aws ecs put-account-setting --name serviceLongArnFormat --value enabled --principal-arn arn:aws:iam::123456789012:role/jdoe
```
这两种方法都会在创建服务的主体上启用所需的 `serviceLongArnFormat` 账户设置，从而允许 ARN 迁移继续进行。