How do I troubleshoot tagging issues for Amazon ECS tasks?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

When you set task tags with Amazon ECS, you might experience the following issues:

• Your tags aren't propagated from the service or task definition to tasks.
• The ARN and resource ID format for your tags is outdated.
• Because of missing AWS Identity and Access Management (IAM) permissions or tag restrictions, you can't create new Amazon ECS resources or add tags to them.
• You can't see Amazon ECS tags on the Billing page of the AWS Billings and Cost Management console.

Use the PropagateTags parameter to propagate from the service or task definitions to tasks

The PropagateTags parameter isn't activated by default. To copy tags from the task definition or service to the task, activate PropagateTags. You can copy tags when you run a task, create a service, or update a service.

Note: In the following commands, replace servicename with your service name, clustername with your cluster name, and region with your AWS Region. Also replace taskdefinitionname with your task definition name, and taskdefinitionversion with your task definition version.

To check whether PropagateTags is activated in a specific service, run the following describe-services command:

aws ecs describe-services --services servicename --cluster clustername --region region --query 'services[*].propagateTags' --output text

To activate tag propagation for a new standalone task, run the following run-task command:

aws ecs run-task --cluster clustername --task-definition taskdefinitionname:taskdefinitionversion --launch-type FARGATE/EC2 --propagate-tags TASK_DEFINITION/SERVICE

To activate tag propagation for a new service , run the following create-service command:

aws ecs create-service --cluster clustername --service-name servicename --task-definition taskdefinitionname:taskdefinitionversion --desired-count 2 --launch-type FARGATE --platform-version LATEST --network-configuration "awsvpcConfiguration={subnets=[subnet-abcdef123],securityGroups=[sg-pqrst5678]}" --propagateTags TASK_DEFINITION/SERVICE

To activate tag propagation for an existing service, run the following update-service command:

aws ecs update-service --cluster clustername --service servicename --propagate-tags SERVICE/TASK_DEFINITION --force-new-deployment

You can also use the Amazon ECS console to turn on tag propagation.

Complete the following steps:

1. Open the Amazon ECS console.
2. Select the Region for your Amazon ECS resource.
3. In the navigation pane, choose Task definitions.
4. Select the task definition from the resource list, and then choose Actions.
5. Choose Create service or Run task.
6. For Task tagging configuration, select Service or Task definitions.
   Note: The default option is Do not propagate.

To use AWS CloudFormation to configure tags in Amazon ECS, you must declare the AWS::ECS::Service resource. To declare AWS::ECS::Service, use the EnableECSManagedTags and PropagateTags properties with the SERVICE or TASK_DEFINITION value.

Note:

• To use Amazon ECS property-related service tags after you create a stack in CloudFormation, you must update your stack and resource replacement. For more information, see Understand update behaviors of stack resources.
• You can access the same configurations for scheduled tasks that you can for tasks that you launch directly from the Amazon ECS RunTask API.

Use the correct ARN format

To tag Amazon ECS resources, you must use the new ARN and ID format. To migrate your Amazon ECS deployment to the new format, see Migrating your Amazon ECS deployment to the new ARN and resource ID format.

Note: Your existing resources receive the new ARN format only after you recreate the resources.

Verify that the IAM entity has the required permissions and check tags restrictions

All AWS accounts use tagging authorization. To tag Amazon ECS resources when you create them, the IAM principal must have the ecs:TagResource permission. The following Amazon ECS APIs must also have this permission:

• CreateCapacityProvider
• CreateCluster
• CreateService
• CreateTaskSet
• RegisterContainerInstance
• RegisterTaskDefinition
• RunTask
• StartTask

If you can't add tags to your Amazon ECS service or create resources, then complete the following steps to troubleshoot this issue:

1. Check AWS CloudTrail events for TagResource events.
2. Review the events for one of the following error messages:
   "AccessDenied"
   -or-
   "The tags cannot be updated at this time. Wait a few minutes and try again"
   If you receive one of the preceding errors, then the IAM entity doesn't have the ecs:TagResource permissions.
3. Use the IAM console or the AWS CLI to add the ecs:TagResource permissions to the IAM entities.
4. Recreate the resource, or add the tags to the Amazon ECS cluster again.
5. Confirm that your Amazon ECS tags adhere to the tag restrictions.

Check whether you have an Billing and Cost Management issue

If you can't filter Amazon ECS tasks by tags to check the cost, then verify that the required tags are on the Amazon ECS tasks. Run the following the list-tags-for-resource command:

aws ecs list-tags-for-resource --resource-arn value

Note: Replace value with your task ARN.

To use the Amazon ECS console to check the tags on Amazon ECS tasks, complete the following steps:

1. Open the Amazon ECS console.
2. Select the Region for your Amazon ECS resource.
3. In the navigation pane, choose a resource type, for example Clusters.
4. Select your resource, and then choose Tags to see all tags that exist for that resource.

To check for managed tags, you must activate Amazon ECS managed tags. To check whether Amazon ECS managed tags is activated, run the following describe-services command:

aws ecs describe-services --services servicename --cluster clustername --region region --query 'services[*].enableECSManagedTags' --output text

Note: Replace servicename with your service name, clustername with your cluster name, and region with your Region.

In the command's output, check whether enableECSManagedTags is set to true.

To use the console to activate Amazon ECS managed tags, complete the following steps:

1. Open the Amazon ECS console.
2. Select the Region for your Amazon ECS resource.
3. In the navigation pane, choose Task definitions.
4. Select the task definition from the resource list, and then choose Actions.
5. Choose Create service or Run task.
6. In the Task tagging configuration, choose Enable ECS managed tags.

To use the AWS CLI to activate Amazon ECS managed tags, run the update-service command:

aws ecs update-service --cluster clustername --service servicename --enable-ecs-managed-tags --force-new-deployment

Note: Replace clustername with your cluster name, and servicename with your service name.

Tags that you use for billing might be listed, even if you don't see the tags in AWS Cost Explorer. To resolve this issue, activate your cost allocation tags on the Billing and Cost Management console.

Note: It can take up to 24 hours for tags to activate.

Related information

Amazon ECS troubleshooting

Tagging Amazon ECS resources

Grant permission to tag resources on creation