本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 將 Amazon ECS 短服務 ARN 移轉到完整 ARN
Amazon ECS 會為每項服務指派唯一的 Amazon Resource Name (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. 如果您有使用短 ARN 格式的 IAM 政策，請將其更新為長 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 格式。執行 `put-account-setting` 並將 `serviceLongArnFormat` 選項設定為 `enabled`。如需詳細資訊，請參閱 *Amazon Elastic Container Service API Reference* 中的 [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 格式。執行 `put-account-setting` 並將 `taskLongArnFormat` 選項設定為 `enabled`。如需詳細資訊，請參閱 *Amazon Elastic Container Service API Reference* 中的 [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. 在**叢集**頁面上，選擇叢集。
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
```
下列範例將使用標籤標記 MyService，並將鍵設定為 "TestService"，值設定為 "WebServers"：
```
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 遷移。