Migrating your Amazon ECS deployment to the new ARN and resource ID format

Update – August 21, 2020 – Added a section with the latest timeline.

Starting today you can opt in to a new Amazon Resource Name (ARN) and resource ID format for Amazon ECS tasks, container instances, and services. The new format enables the enhanced ability to tag resources in your cluster, as well as tracking the cost of services and tasks running in your cluster.

In most cases, you don’t need to change your system beyond opting in to the new format. However, if your deployment mechanism uses regular expressions to parse the old format ARNs or task IDs, this may be a breaking change. It may also be a breaking change if you were storing the old format ARNs and IDs in a fixed-width database field or data structure.

After you have opted in, any new ECS services or tasks have the new ARN and ID format. Existing resources do not receive the new format. If you decide to opt out, any new resources that you later create then use the old format.

Timeline

There is a timeline for the opt-in and opt-out periods for the new Amazon Resource Name (ARN) and resource ID format for Amazon ECS resources. The ARN and resource ID is set at the time of creation and does not change after that. Therefore, opting in or out of the new format does not affect the ARN or resource ID of your existing resources.

The following are the important dates related to this change.

• From now until September 30, 2020 – The ability to opt in to and opt out of the new Amazon Resource Name (ARN) and resource IDs is provided on a per-Region basis. Any new accounts created are opted out by default.
• October 1, 2020 – March 31, 2021 – All new accounts are opted in to the new format by default. Any existing accounts that have not explicitly opted out of the new format are also opted in. The ability to opt in and opt out continues to be available on a per-Region basis.
• April 1, 2021 – All accounts will be opted in by default. All new resources created will receive the new format. The ability to opt out will no longer be available.

You can modify your opt-in setting for the new Amazon Resource Name (ARN) and resource ID format at any time between now and April 1, 2021. After you have opted in, any new resources that you create use the new format.

For more information on this change and its timeline you can refer to the AWS ECS documentation.

Approaches to opting in

Depending on whether your software interacts with instance, service, or task ARNs, you may want to be careful about how you opt in to avoid breaking your existing implementation. There are several ways to do this.

Separate testing and production accounts

The easiest way to opt in is to use separate AWS accounts for your testing and QA environment and your production environment. In this case, you could choose to opt in your entire test account by opting in for the AWS account root user. All IAM users and roles within the account are then opted-in. You can easily reverse the opt-in decision by opting out the root user. After you have verified that all your deployments work as expected, you can opt in for your main production account.

Single region

If you use a single account to host all your resources and want to test the new ARNs in a gradual rollout, you need to be more careful about how you opt in. You may consider testing by opting in one AWS Region that you don’t normally use. Spin up your resources there to verify that they work before opting in your primary Region.

Single IAM user or role

Alternatively, you can decide to opt in for a specific test IAM user or role and conduct testing before opting in for the entire account. In this post, I explore how to opt in for a specific IAM user and role and to migrate your resources.

Prerequisites to opting in

There are a few prerequisites to opting into the new ARN and resource ID format.

Root user access

First, make sure that you can access the AWS account root user, so that you can opt in for all IAM users and roles on the account by default. Additionally, the root user can opt in for any single IAM user or role on the account, per Region. Individual IAM users and roles can still opt in or out separately.

Instance role access

In particular, getting the new format on your cluster instances involves opting in for the instance role that the instance assumes when it boots up. This role allows the instance to communicate with the ECS control plane and register itself to receive an ARN. For the instance to get a new-format ARN, the role that the instance uses must be opted in.

Access for other IAM roles

Depending on how your organization deploys clusters, you may need to opt in to the new format on other IAM users or roles that touch your ECS cluster. For example, you may have an IAM user that you use to access the console and create an ECS cluster.

You also may use AWS CodeDeploy, which has an IAM role that allows it to make deployments and update that service with the latest version of your application’s Docker container. Both roles should be opted in. Otherwise, CodeDeploy causes your service to deploy tasks with the old format.

Opt in for your IAM user

For the best results, create a new IAM user that you can use for testing the new ARN format. That way, you can continue to interact with your existing ECS deployments on your original IAM user without accidentally switching your live services to the new ARN format.

After your testing IAM user is created, access the opt-in page and turn on the new ARN format for this user.

At this point, any services or tasks that you now create in any cluster with this IAM user will have the new ARN format. However, you also need to update the ARN format on the instances in the cluster.

Create and opt-in for an instance role

To get the new instance ARN format, create an instance role. This role is used for each instance in the ECS cluster. After you opt in for the role, any instance that registers itself with the ECS control plane using that role gets the new ARN format.

Open the IAM console and choose Roles, Create role. Specify the type of role you are creating. The type of trusted entity for the role needs to be “AWS Service”, and the service to be trusted is EC2. Select EC2 to create an IAM role that trusts ec2.amazonaws.com.

The next step is to add permissions for this role. In the search box, type AmazonEC2ContainerServiceforEC2Role. Select the check box to attach this policy to the role. This policy document is managed by AWS and has all the permissions required for an EC2 instance to act as a host in an ECS cluster.

Give the role a name and create it. Your finished role should look something like the following:

Finally, opt in for this role so that when an EC2 instance uses the role to register itself in the EC2 cluster, it receives the new ARN format. To do this, log in as the root user, and navigate to the opt-in page. This time, opt in for the instance role.

Launch a new cluster using an opted-in IAM user and instance role

Existing resources do not receive the new ARN format until they are re-created. To get the new ARNs, use the opted-in IAM user and opted-in instance role to create an opted-in cluster.

Open the cluster creation wizard, and create a new EC2 Linux + Networking cluster.

On the next screen, name your cluster and select the instance role that you previously opted in:

After the cluster launches, navigate to the ECS Instances list and verify that the instances have the new ID format.

Launch a new opted-in service

The last part is to launch a service in the cluster. Be sure to use the IAM user that you opted in earlier. Task definitions are not changed by this opt in, so you can create a clone of an existing service using the same task definitions that you are already using.

As a best practice, do a blue/green infrastructure rollout by creating a full parallel stack: a new cluster of EC2 instances, services, tasks, and any load balancers. Then, direct traffic from your previous cluster to the new cluster by switching the DNS CNAME of your website to point at the new stack’s load balancer.

This approach allows you to test the new stack without interrupting your existing stack. After you have verified that it works, you can switch traffic over to the new stack without any downtime.

Conclusion

You have now tested opting in to the new ARN and resource ID format for ECS container instances, services, and tasks. If everything worked properly, you can opt in across your full account today by using the root user to opt in.