Migrate an Amazon ECS short service ARN to a long ARN - Amazon Elastic Container Service
PrerequisitesProcedureTroubleshooting

Migrate an Amazon ECS short service ARN to a long ARN

Amazon ECS assigns a unique Amazon Resource Name (ARN) to each service. Services that were created before 2021 have a short ARN format:

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

Amazon ECS changed the ARN format to include the cluster name. This is a long ARN format:

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

Your service must have the long ARN format in order to tag your service.

You can migrate a service with a short ARN format to a long ARN format without having to recreate the service. You can use the API, CLI, or the console. You can't undo the migration operation.

If you want to use AWS CloudFormation to tag a service with short ARN format, you must migrate the service using the API, CLI, or console. After the migration completes you can use AWS CloudFormation to tag the service.

If you want to use Terraform to tag a service with short ARN format, you must migrate the service using the API, CLI, or console. After the migration completes you can use Terraform to tag the service.

After the migration is complete, the service has the following changes:

  • The long ARN format

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

  • When you migrate using the console, Amazon ECS adds a tag to the service with the key set to "ecs:serviceArnMigratedAt" and the value set to the migration timestamp (UTC format).

    This tag counts toward your tag quota.

  • When the PhysicalResourceId in a AWS CloudFormation stack represents a service ARN, the value does not change and will continue to be the short service ARN.

Prerequisites

Perform the following operations before you migrate the service ARN.

  1. To see if you have a short service ARN, view the service details in the Amazon ECS console (you see a warning when the service has the short ARN format), or the serviceARN return parameter from describe-services. When the ARN does not include the cluster name, you have a short ARN. The following is the format of a short ARN:

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

  2. Note the created at date.

  3. If you have IAM policies that use the short ARN format, update it to the long ARN format.

    Replace each user input placeholder with your own information.

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

    For more information, see Editing IAM policies in the AWS Identity and Access Management User Guide.

  4. If you have tools that use the short ARN format, update it to the long ARN format.

    Replace each user input placeholder with your own information.

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

  5. Enable the service long ARN format. Run put-account-setting with the serviceLongArnFormat option set to enabled. For more information, see, put-account-setting in the Amazon Elastic Container Service API Reference.

    Run the command as the root user when your service has an unknown createdAt date.

    aws ecs put-account-setting --name serviceLongArnFormat --value enabled

    Example output

    {
    "setting": {
        "name": "serviceLongArnFormat",
        "value": "enabled",
        "principalArn": "arn:aws:iam::123456789012:role/your-role",
        "type": user
    }
}

  6. Enable the task long ARN format. This allows tasks that are running as part of a service to have the long ARN format. Run put-account-setting with the taskLongArnFormat option set to enabled. For more information, see, put-account-setting in the Amazon Elastic Container Service API Reference.

    Run the command as the root user when your service has an unknown createdAt date.

    aws ecs put-account-setting --name taskLongArnFormat --value enabled

    Example output

    {
    "setting": {
        "name": "taskLongArnFormat",
        "value": "enabled",
        "principalArn": "arn:aws:iam::123456789012:role/your-role",
        "type": user
    }
}

Procedure

Use the following to migrate your service ARN.

  1. Open the console at https://console.aws.amazon.com/ecs/v2.

  2. On the Clusters page, choose the cluster.

  3. In the Services section, choose a service that has a warning in the ARN column.

    The service details page appears.

  4. Choose Migrate to long ARN.

    The Migrate service dialog box appears.

  5. Choose Migrate.

After you complete the prerequisites, you can tag your service. Run the following command:

Amazon ECS considers passing the long ARN format in a tag-resource API request for a service with a short ARN as a signal to migrate the service to use the long ARN format.

aws ecs tag-resource \
    --resource-arn arn:aws:ecs:region:aws_account_id:service/cluster-name/service-name
    --tags key=key1,value=value1

The following example tags MyService with a tag that has a key set to "TestService" and a value set to "WebServers:

aws ecs tag-resource \
    --resource-arn arn:aws:ecs:us-east-1:123456789012:service/MyCluster/MyService
    --tags key=TestService1,value=WebServers

After you complete the prerequisites, you can tag your service. Create an aws_ecs_service resource and set the tags reference. For more information, see Resource: aws_ecs_service in the Terraform documentation.

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

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

Next steps

You can add tags to the service. For more information, see Adding tags to Amazon ECS resources.

If you want Amazon ECS to propagate the tags from the task definition or the service to the task, run update-service with the propagateTags parameter. For more information, see update-service in the AWS Command Line Interface Reference.

Troubleshooting

Some users might encounter the following error when they migrate from the short ARN format to the long ARN format.

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.

If you have already enabled the serviceLongArnFormat account setting but still encounter this error, it might be because the account settings for the long ARN format hasn't been enabled for the specific IAM principal that originally created the service.

  1. Identify the principal that created the service.

    1. In the console, the information is available in the Created by field in the Configuration and networking tab on the Service details page in the Amazon ECS console.

    2. For the AWS CLI, run the following command:

      Replace the user-input with your values.

      aws ecs describe-services --cluster cluster-name --services service-name --query 'services[0].{createdBy: createdBy}'

  2. Enable the required account settings for that specific principal. You can do this in one of the following ways:

    1. Assume the IAM user or role for that principal. Then run put-account-setting.

    2. Use the root user to run the command while specifying the creating principal with the principal-arn.

      Example.

      Replace the principal-arn with the value from Step 1.

      aws ecs put-account-setting --name serviceLongArnFormat --value enabled --principal-arn arn:aws:iam::123456789012:role/jdoe

Both methods enable the required serviceLongArnFormat account setting on the principal that created the service, which allows the ARN migration to proceed.