# Tagging Amazon ECS resources To help you manage your Amazon ECS resources, you can optionally assign your own metadata to each resource using *tags*. Each *tag* consists of a *key* and an optional *value*. You can use tags to categorize your Amazon ECS resources in different ways, for example, by purpose, owner, or environment. This is useful when you have many resources of the same type. You can quickly identify a specific resource based on the tags that you assigned to it. For example, you can define a set of tags for your account's Amazon ECS container instances. This helps you track each instance's owner and stack level. You can use tags for your Cost and Usage reports. You can use these reports to analyze the cost and usage of your Amazon ECS resources. For more information, see [Amazon ECS usage reports](usage-reports.md). **Warning** There are many APIs that return tag keys and their values. Denying access to `DescribeTags` doesn’t automatically deny access to tags returned by other APIs. As a best practice, we recommend that you do not include sensitive data in your tags. We recommend that you devise a set of tag keys that meets your needs for each resource type. You can use a consistent set of tag keys for easier management of your resources. You can search and filter the resources based on the tags you add. Tags don't have any semantic meaning to Amazon ECS and are interpreted strictly as a string of characters. You can edit tag keys and values, and you can remove tags from a resource at any time. You can set the value of a tag to an empty string, but you can't set the value of a tag to null. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the earlier value. When you delete a resource, any tags for the resource are also deleted. If you use AWS Identity and Access Management (IAM), you can control which users in your AWS account have permission to manage tags. ## How resources are tagged There are multiple ways that Amazon ECS tasks, services, task definitions, and clusters are tagged: + A user manually tags a resource by using the AWS Management Console, Amazon ECS API, the AWS CLI, or an AWS SDK. + A user creates a service or runs a standalone task and selects the Amazon ECS-managed tags option. Amazon ECS automatically tags all newly launched tasks. For more information, see [Amazon ECS-managed tags](#managed-tags). + A user creates a resource using the console. The console automatically tags the resources. These tags are returned in the AWS CLI, and AWS SDK responses and are displayed in the console. You cannot modify or delete these tags. For information about the added tags, see the **Tags automatically added by the console** column in the **Tagging support for Amazon ECS resources** table. If you specify tags when you create a resource and the tags can't be applied, Amazon ECS rolls back the creation process. This ensures that resources are either created with tags or not created at all, and that no resources are left untagged at any time. By tagging resources while they're being created, you can eliminate the need to run custom tagging scripts after resource creation. The following table describes the Amazon ECS resources that support tagging. | Resource | Supports tags | Supports tag propagation | Tags automatically added by the console | | --- | --- | --- | --- | | Amazon ECS tasks | Yes | Yes, from the task definition. | Key: aws:ecs:clusterName *Value*: `cluster-name` | | Amazon ECS services | Yes | Yes, from either the task definition or the service to the tasks in the service. | Key: ecs:service:stackId *Value* `arn:aws:cloudformation:arn` | | Amazon ECS task sets | Yes | No | N/A | | Amazon ECS task definitions | Yes | No | Key: ecs:taskDefinition:createdFrom *Value*: `ecs-console-v2` | | Amazon ECS clusters | Yes | No | Key: aws:cloudformation:logical-id *Value*: `ECSCluster` Key: aws:cloudformation:stack-id*Value*: `arn:aws:cloudformation:arn`*Key*: `aws:cloudformation:stack-name`*Value*: `ECS-Console-V2-Cluster-EXAMPLE` | | Amazon ECS container instances | Yes | Yes, from the Amazon EC2 instance. For more information, see [Adding tags to an Amazon EC2 container instance for Amazon ECS](instance-details-tags.md). | N/A | | Amazon ECS External instances | Yes | No | N/A | | Amazon ECS capacity provider | Yes. You cannot tag the predefined `FARGATE` and `FARGATE_SPOT` capacity providers. | Yes, only from capacity providers for Amazon ECS Managed Instances. You can propagate tags from the capacity provider for Amazon ECS Managed Instances to all resources managed by the provider such as Amazon EC2 instances, launch template, Elastic Network Interfaces, and volumes. | N/A | ## Tagging resources on creation The following resources support tagging on creation using the Amazon ECS API, AWS CLI, or AWS SDK: + Amazon ECS tasks + Amazon ECS services + Amazon ECS task definition + Amazon ECS task sets + Amazon ECS clusters + Amazon ECS container instances + Amazon ECS capacity providers Amazon ECS has the option to use tagging authorization for resource creation. When the AWS account is configured for tagging authorization, users must have permissions for actions that create the resource, such as `ecsCreateCluster`. If you specify tags in the resource-creating action, AWS performs additional authorization to verify if users or roles have permissions to create tags. Therefore, you must grant explicit permissions to use the `ecs:TagResource` action. For more information, see [Grant permission to tag resources on creation](supported-iam-actions-tagging.md). For information about how to configure the option, see [Tagging authorization](ecs-account-settings.md#tag-resources-setting). ## Restrictions The following restrictions apply to tags: + A maximum of 50 tags can be associated with a resource. + Tag keys can't be repeated for one resource. Each tag key must be unique, and can only have one value. + Keys can be up to 128 characters long in UTF-8. + Values can be up to 256 characters long in UTF-8. + If multiple AWS services and resources use your tagging schema, limit the types of characters you use. Some services might have restrictions on allowed characters. Generally, allowed characters are letters, numbers, spaces, and the following characters: `+` `-` `=` `.` `_` `:` `/` `@`. + Tag keys and values are case sensitive. + You can't use `aws:`, `AWS:`, or any upper or lowercase combination of such as a prefix for either keys or values. These are reserved only for AWS use. You can't edit or delete tag keys or values with this prefix. Tags with this prefix don't count against your tags-per-resource limit. ## Amazon ECS-managed tags When you use Amazon ECS-managed tags, Amazon ECS automatically tags all newly launched tasks and any Amazon EBS volumes attached to the tasks with the cluster information and either the user-added task definition tags or the service tags. The following describes the added tags: + Standalone tasks – a tag with a *Key* as `aws:ecs:clusterName` and a *Value* set to the cluster name. All task definition tags that were added by users. An Amazon EBS volume attached to a standalone task will receive the tag with a *Key* as `aws:ecs:clusterName` and a *Value* set to the cluster name. For more information about Amazon EBS volume tagging, see [Tagging Amazon EBS volumes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specify-ebs-config.html#ebs-volume-tagging). + Tasks that are part of a service – a tag with a *Key* as `aws:ecs:clusterName` and a *Value* set to the cluster name. A tag with a *Key* as `aws:ecs:serviceName` and a *Value* set to the service name. Tags from one of the following resources: + Task definitions – All task definition tags that were added by users. + Services – All service tags that were added by users. An Amazon EBS volume attached to a task that is part of a service will receive a tag with a *Key* as `aws:ecs:clusterName` and a *Value* set to the cluster name, and a tag with a *Key* as `aws:ecs:serviceName` and a *Value* set to the service name. For more information about Amazon EBS volume tagging, see [Tagging Amazon EBS volumes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specify-ebs-config.html#ebs-volume-tagging). The following options are required for this feature: + You must opt in to the new Amazon Resource Name (ARN) and resource identifier (ID) formats. For more information, see [Amazon Resource Names (ARNs) and IDs](ecs-account-settings.md#ecs-resource-ids). + When you use the APIs to create a service or run a task, you must set `enableECSManagedTags` to `true` for `run-task` and `create-service`. For more information, see [create-service](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html) and [run-task](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html) in the *AWS Command Line Interface API Reference*. + Amazon ECS uses managed tags to determine when some features are enabled, for example cluster Auto Scaling. We recommend that you do not manually modify tags so that the Amazon ECS can effectively manage the features. ## Use tags for billing AWS provides a reporting tool called Cost Explorer that you can use to analyze the cost and usage of your Amazon ECS resources. You can use Cost Explorer to view charts of your usage and costs. You can view data from the last 13 months, and forecast how much you're likely to spend for the next three months. You can use Cost Explorer to see patterns in how much you spend on AWS resources over time. For example, you can use it to identify areas that need further inquiry and see trends that you can use to understand your costs. You also can specify time ranges for the data, and view time data by day or by month. You can use Amazon ECS-managed tags or user-added tags for your Cost and Usage Report. For more information, see [Amazon ECS usage reports](usage-reports.md). To see the cost of your combined resources, you can organize your billing information based on resources that have the same tag key values. For example, you can tag several resources with a specific application name, and then organize your billing information to see the total cost of that application across several services. For more information about setting up a cost allocation report with tags, see [The Monthly Cost Allocation Report](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/configurecostallocreport.html) in the *AWS Billing User Guide*. Additionally, you can turn on *Split Cost Allocation Data* to get task-level CPU and memory usage data in your Cost and Usage Reports. For more information, see [Task-level Cost and Usage Reports](usage-reports.md#task-cur). **Note** If you've turned on reporting, it can take up to 24 hours before the data for the current month is available for viewing. # Adding tags to Amazon ECS resources You can tag new or existing tasks, services, task definitions, or clusters. For information about tagging your container instances, see [Adding tags to an Amazon EC2 container instance for Amazon ECS](instance-details-tags.md). **Warning** Do not add personally identifiable information (PII) or other confidential or sensitive information in tags. Tags are accessible to many AWS services, including billing. Tags are not intended to be used for private or sensitive data. You can use the following resources to specify tags when you create the resource. | Task | Console | AWS CLI | API Action | | --- | --- | --- | --- | | Run one or more tasks. | [Running an application as an Amazon ECS task](standalone-task-create.md) | [run-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/run-task.html) | [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html) | | Create a service. | [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md) | [create-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html) | [CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html) | | Create a task set. | [Deploy Amazon ECS services using a third-party controller](deployment-type-external.md) | [create-task-set](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-task-set.html) | [CreateTaskSet](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateTaskSet.html) | | Register a task definition. | [Creating an Amazon ECS task definition using the console](create-task-definition.md) | [register-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html) | [RegisterTaskDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html) | | Create a cluster. | [Creating an Amazon ECS cluster for Fargate workloads](create-cluster-console-v2.md) | [create-cluster](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-cluster.html) | [CreateCluster](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCluster.html) | | Run one or more container instances. | [Launching an Amazon ECS Linux container instance](launch_container_instance.md) | [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) | [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) | | Create a capacity provider for Amazon ECS Managed Instances. | [Creating a capacity provider for Amazon ECS Managed Instances](create-capacity-provider-managed-instances.md) | [create-capacity-provider](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-capacity-provider.html) | [CreateCapacityProvider](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateCapacityProvider.html) | ## Adding tags to existing resources (Amazon ECS console) You can add or delete tags that are associated with your clusters, services, tasks, and task definitions directly from the resource's page. **To modify a tag for an individual resource** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. From the navigation bar, select the AWS Region to use. 1. In the navigation pane, select a resource type (for example, **Clusters**). 1. Select the resource from the resource list, choose the **Tags** tab, and then choose **Manage tags**. 1. Configure your tags. [Add a tag] Choose **Add tag**, and then do the following: + For **Key**, enter the key name. + For **Value**, enter the key value. 1. Choose **Save**. ## Adding tags to existing resources (AWS CLI) You can add or overwrite one or more tags by using the AWS CLI or an API. **Note** You can use dual-stack service endpoints to interact with Amazon ECS from the AWS CLI, SDKs, and the Amazon ECS API over both IPv4 and IPv6. For more information, see [Using Amazon ECS dual-stack endpoints](dual-stack-endpoint.md). + AWS CLI - [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/ecs/tag-resource.html) + API action - [TagResource](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_TagResource.html) # Tags for Amazon ECS Managed Instances Amazon ECS Managed Instances support a combination of custom tags and tags added by AWS that can be used for cost optimization. For more information about using tags for billing, see [Use tags for billing](ecs-using-tags.md#tag-resources-for-billing). ## Tags added by AWS AWS adds the following tags to each Amazon ECS Managed Instance created by the capacity provider: + Amazon ECS automatically adds the reserved tags `AmazonECSCreated` and `AmazonECSManaged` to Amazon ECS Managed Instances. + Amazon ECS adds the following system tags to each instance: + A tag with a *Key* as `aws:ecs:clusterName` and a *Value* set to the name of the cluster. + A tag with a *Key* as `aws:ecs:capacityProviderName` and a *Value* set to the name of the capacity provider. + A tag with a *Key* as `aws:ecs:containerInstanceId` and a *Value* as the container instance ID for the Amazon ECS Managed Instance. + Amazon EC2 adds the system tag `aws:ec2:managed-launch` with the value `ecs-managed-instances`. In addition, Amazon EC2 adds system tags denoting the launch template that was used to create the managed instance, and the Amazon EC2 fleet that the managed instance is part of. ## Custom tags You can add additional custom tags to Amazon ECS Managed Instances by adding tags to the capacity provider and enabling tag propagation using the `propagateTags` property. Tags on the capacity provider propagate to the managed instances that the capacity provider launches The following example capacity provider definition shows how tags can be specified and propagated from the capacity provider when creating the capacity provider using the `CAPACITY_PROVIDER` value for `propagateTags`. ``` { "name": "my-cluster-managed-instances-cp", "cluster": "my-cluster", "tags": [ { "key":"tag_key", "value":"tag_value" } ], "managedInstancesProvider": { "infrastructureRoleArn": "arn:aws:iam::123456789012:role/ecsInfrastructureRole", "propagateTags": "CAPACITY_PROVIDER", "instanceLaunchTemplate": { "ec2InstanceProfileArn": "arn:aws:iam::123456789012:instance-profile/ecsInstanceProfile", "networkConfiguration": { "subnets": [ "subnet-abcdef01234567", "subnet-bcdefa98765432" ], "securityGroups": [ "sg-0123456789abcdef" ] } } } } ``` **Note** When you add new tags to a capacity provider, the newly added tags will not be propagated to existing instances but will be propagated to any newly created instances. Customers are allowed to add tags directly to the EC2 instances, but those tags don't propagate back to the capacity provider You can also tag or untag the capacity provider using [Adding tags to existing resources (AWS CLI)](tag-resources-console.md#tag-resources-api-sdk) or [Adding tags to existing resources (Amazon ECS console)](tag-resources-console.md#adding-or-deleting-tags) For more information about Amazon ECS Managed Instances capacity providers, see [Amazon ECS Managed Instances capacity providers](managed-instances-capacity-providers-concept.md). # Adding tags to an Amazon EC2 container instance for Amazon ECS You can associate tags with your Amazon EC2 container instances for Amazon ECS using one of the following methods: + Method 1 – When creating the container instance using the Amazon EC2 API, CLI, or console, specify tags by passing user data to the instance using the container agent configuration parameter `ECS_CONTAINER_INSTANCE_TAGS`. This creates tags that are associated with the container instance in Amazon ECS only, they cannot be listed using the Amazon EC2 API. For more information, see [Bootstrapping Amazon ECS Linux container instances to pass data](bootstrap_container_instance.md). **Important** If you launch your container instances using an Amazon EC2 Auto Scaling group, then you should use the ECS\$1CONTAINER\$1INSTANCE\$1TAGS agent configuration parameter to add tags. This is due to the way in which tags are added to Amazon EC2 instances that are launched using Auto Scaling groups. The following is an example of a user data script that associates tags with your container instance: ``` #!/bin/bash cat <<'EOF' >> /etc/ecs/ecs.config ECS_CLUSTER=MyCluster ECS_CONTAINER_INSTANCE_TAGS={"tag_key": "tag_value"} EOF ``` + Method 2 – When you create your container instance using the Amazon EC2 API, CLI, or console, first specify tags using the `TagSpecification.N` parameter. Then, pass user data to the instance by using the container agent configuration parameter `ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM`. Doing so propagates them from Amazon EC2 to Amazon ECS. The following is an example of a user data script that propagates the tags that are associated with an Amazon EC2 instance, and registers the instance with a cluster that's named `MyCluster`. ``` #!/bin/bash cat <<'EOF' >> /etc/ecs/ecs.config ECS_CLUSTER=MyCluster ECS_CONTAINER_INSTANCE_PROPAGATE_TAGS_FROM=ec2_instance EOF ``` To provide access to allow container instance tags to propagate from Amazon EC2 to Amazon ECS, manually add the following permissions as an inline policy to the Amazon ECS container instance IAM role. For more information, see [Adding and Removing IAM Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html). + `ec2:DescribeTags` The following is an example policy that's used to add these permissions. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:DescribeTags" ], "Resource": "*" } ] } ``` ------ # Adding tags to External container instances for Amazon ECS You can associate tags with your external container instances for Amazon ECS by using one of the following methods. + Method 1 – Before running the installation script to register your external instance with your cluster, create or edit the Amazon ECS container agent configuration file at `/etc/ecs/ecs.config` and add the `ECS_CONTAINER_INSTANCE_TAGS` container agent configuration parameter. This creates tags that are associated with the external instance. The following is example syntax. ``` ECS_CONTAINER_INSTANCE_TAGS={"tag_key": "tag_value"} ``` + Method 2 – After your external instance is registered to your cluster, you can use the AWS Management Console to add tags. For more information, see [Adding tags to existing resources (Amazon ECS console)](tag-resources-console.md#adding-or-deleting-tags). # Amazon ECS usage reports AWS provides a reporting tool called Cost Explorer that you can use to analyze the cost and usage of your Amazon ECS resources. You can use Cost Explorer to view charts of your usage and costs. You can view data from the last 13 months, and forecast how much you're likely to spend for the next three months. You can use Cost Explorer to see patterns in how much you spend on AWS resources over time. For example, you can use it to identify areas that need further inquiry and see trends that you can use to understand your costs. You also can specify time ranges for the data, and view time data by day or by month. The metering data in your Cost and Usage Report shows usage across all of your Amazon ECS tasks. The metering data includes CPU usage as `vCPU-Hours` and memory usage as `GB-Hours` for each task that was run. How that data is presented depends on the compute option of the task. For tasks using Fargate, the `lineItem/Operation` column shows `FargateTask` and you will see the cost associated with each task. For tasks that use EC2, the `lineItem/Operation` column shows `ECSTask-EC2` and the tasks don't have a direct cost associated with them. The metering data that's shown in the report, such as memory usage, represents the total resources that the task reserved over the billing period that you specify. You can use this data to determine the cost of your underlying cluster of Amazon EC2 instances. The cost and usage data for your Amazon EC2 instances are listed separately under the Amazon EC2 service. You can also use the Amazon ECS managed tags to identify the service or cluster that each task belongs to. For more information, see [Use tags for billing](ecs-using-tags.md#tag-resources-for-billing). **Important** The metering data is only viewable for tasks that are launched on or after November 16, 2018. Tasks that are launched before this date don't show metering data. The following is an example of some of the fields that you can use to sort cost allocation data in Cost Explorer. + Cluster name + Service name + Resource tags + Launch type + AWS Region + Usage type For more information about creating an AWS Cost and Usage Report, see [AWS Cost and Usage Report](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/billing-reports-costusage.html) in the *AWS Billing User Guide*. ## Task-level Cost and Usage Reports AWS Cost Management can provide CPU and memory usage data in the AWS Cost and Usage Report for the each task on Amazon ECS, including tasks on Fargate and tasks on EC2. This data is called *Split Cost Allocation Data*. You can use this data to analyze costs and usage for applications. Additionally, you can split and allocate the costs to individual business units and teams with cost allocation tags and cost categories. For more information about *Split Cost Allocation Data*, see [Understanding split cost allocation data](https://docs.aws.amazon.com/cur/latest/userguide/split-cost-allocation-data.html) in the AWS Cost and Usage Report User Guide. You can opt in to task-level *Split Cost Allocation Data* for the account in the AWS Cost Management Console. If you have a management (payer) account, you can opt in from the payer account to apply this configuration to every linked account. After you set up *Split Cost Allocation Data*, there will be additional columns under the **splitLineItem** header in the report. For more information see [Split line item details](https://docs.aws.amazon.com/cur/latest/userguide/split-line-item-columns.html) in the AWS Cost and Usage Report User Guide For tasks on EC2, this data splits the cost of the EC2 instance based on the resource usage or reservations and the remaining resources on the instance. The following are prerequistites: + Set the `ECS_DISABLE_METRICS` Amazon ECS agent configuration parameter to `false`. When this setting is `false`, the Amazon ECS agent sends metrics to Amazon CloudWatch. On Linux, this setting is `false` by default and metrics are sent to CloudWatch. On Windows, this setting is `true` by default, so you must change the setting to `false` to send the metrics to CloudWatch for AWS Cost Management to use. For more information about ECS agent configuration, see [Amazon ECS container agent configuration](ecs-agent-config.md). + The minimum Docker version for reliable metrics is Docker version v20.10.13 and newer, which is included in Amazon ECS-optimized AMI 20220607 and newer. To use *Split Cost Allocation Data*, you must create a report, and select **Split cost allocation data**. For more information, see [Creating Cost and Usage Reports](https://docs.aws.amazon.com/cur/latest/userguide/cur-create.html) in the AWS Cost and Usage Report User Guide. AWS Cost Management calculates the *Split Cost Allocation Data* with the task CPU and memory usage. AWS Cost Management can use the task CPU and memory reservation instead of the usage, if the usage is unavailable. If you see the CUR is using the reservations, check that your container instances meet the prerequisites and the task resource usage metrics appear in CloudWatch.