將 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 之前，請執行下列操作。

若要查看是否存在短服務 ARN，請在 Amazon ECS 主控台中檢視服務詳細資訊 (如果服務使用短 ARN 格式，您會看到警告)，或檢視 describe-services 傳回的 serviceARN 參數。如果 ARN 不包含叢集名稱，您將擁有短 ARN。短 ARN 的格式如下：

arn:aws:ecs:region:aws_account_id:service/service-name
請記下建立日期。
如果您有使用短 ARN 格式的 IAM 政策，請將其更新為長 ARN 格式。

將每個使用者輸入預留位置替換為自己的資訊。

arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name

如需詳細資訊，請參閱 AWS Identity and Access Management User Guide 中的 Editing IAM policies。
如果您有使用短 ARN 格式的工具，請將其更新為長 ARN 格式。

將每個使用者輸入預留位置替換為自己的資訊。

arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name
啟用服務長 ARN 格式。執行 put-account-setting 並將 serviceLongArnFormat 選項設定為 enabled。如需詳細資訊，請參閱 Amazon Elastic Container Service API Reference 中的 put-account-setting。

如果服務的 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
    }
}
```
啟用任務長 ARN 格式。此帳戶設定會控制服務遷移完成後啟動之新任務的 ARN 格式。執行 put-account-setting 並將 taskLongArnFormat 選項設定為 enabled。如需詳細資訊，請參閱 Amazon Elastic Container Service API Reference 中的 put-account-setting。

如果服務的 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。

開啟主控台，網址為 https://console.aws.amazon.com/ecs/v2。
在叢集頁面上，選擇叢集。
在服務區段中，選擇 ARN 資料欄中包含警告的服務。

服務資訊頁面隨即顯示。
選擇遷移至長 ARN。

「遷移服務」對話方塊隨即顯示。
選擇 Migrate (遷移)。

完成先決條件後，即可標記服務。執行以下命令：

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

完成先決條件後，即可標記服務。建立 aws_ecs_service 資源並設定 tags 參考。如需詳細資訊，請參閱 Terraform 文件中的 Resource： aws_ecs_service。


resource "aws_ecs_service" "MyService" {
  name    = "example"
  cluster = aws_ecs_cluster.MyService.id

 tags = {
 "Name"  =  "MyService"
 "Environment"  =  "Production"
 "Department"  =  "QualityAssurance"
  }
}

後續步驟

您可以將標籤新增至服務。如需更多詳細資訊，請參閱將標籤新增至 Amazon ECS 資源。

如果希望 Amazon ECS 將標籤從任務定義或服務傳播至任務，請使用 propagateTags 參數執行 update-service。如需詳細資訊，請參閱 AWS Command Line Interface Reference 中的 update-service。

故障診斷

某些使用者從短 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. 在主控台中，可在 Amazon ECS 主控台的「服務詳細資訊」頁面上的組態與網路索引標籤中的建立者欄位中取得此資訊。
2. 對於 AWS CLI，請執行下列命令：
  
  將 user-input 取代為實際值。
```
aws ecs describe-services --cluster cluster-name --services service-name --query 'services[0].{createdBy: createdBy}'
```
為該特定主體啟用所需的帳戶設定。您可採用下列其中一種方式來這麼做：
1. 擔任該主體的 IAM 使用者或角色。然後執行 put-account-setting。
2. 使用根使用者執行命令，同時使用 principal-arn 指定建立主體。
  
  範例。
  
  將 principal-arn 取代為步驟 1 中的值。
```
aws ecs put-account-setting --name serviceLongArnFormat --value enabled --principal-arn arn:aws:iam::123456789012:role/jdoe
```

這兩種方法都會在建立服務的主體上啟用所需的 serviceLongArnFormat 帳戶設定，從而允許繼續進行 ARN 遷移。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

刪除服務

服務調節邏輯

將 Amazon ECS 短服務 ARN 遷移到長 ARN

先決條件

注意

程序

後續步驟

故障診斷