Using tags with S3 directory buckets - Amazon Simple Storage Service
How tags workCommon ways to use tagsWorking with tags
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using tags with S3 directory buckets

An Amazon tag is a key-value pair that holds metadata about resources, in this case Amazon S3 directory buckets. You can tag S3 directory buckets when you create them or manage tags on existing directory buckets. There is no additional charge for using tags on directory buckets beyond the standard S3 API request rates. For more information, see Amazon S3 pricing.

How tags work

Amazon S3 directory buckets support two types of tags:

  • Amazon-generated tags: Amazon automatically applies these tags, and you cannot modify them or remove them. To learn more about Amazon-generated tags, see Using Amazon-generated tags.

  • User-defined tags: You apply these tags to your S3 directory buckets or other resources and manage them.

User-defined tags

A user-defined tag is a tag key-value pair that you use to label your resources. User-defined tags consists of a required key and an optional value. These are the main components of a user-defined tag:

The tag key

The tag key is the required name of the tag. For example, project is the tag key in the following tag key-value pair:

Key Value
project Trinity

The tag key is a case-sensitive string that must contain between 1 and 128 Unicode characters.

The tag value

The tag value is an optional string. For example, Trinity is the tag value in this tag key-value pair:

Key Value
project Trinity

The tag value is a case-sensitive string that can contain between 0 and 256 Unicode characters.

For details on the characters allowed in user-defined tags and other restrictions, see User-Defined Tag Restrictions in the Amazon Billing and Cost Management User Guide.

The tag set

Each S3 directory bucket has one tag set that contains all of the tag key and value pairs that are assigned to that bucket. A tag set can contain as many as 50 user-defined tags, or it can be empty.

While each key must be unique in a tag set, you can use the same value multiple times. For example, you can have the same value, Trinity, for following two tag keys:

Key Value
project Trinity
cost-center Trinity

Within a bucket, when you add a tag that has the same key as an existing tag, the new value overwrites the old value.

Amazon doesn't apply any semantic meaning to your tags. We interpret tags strictly as character strings.

To add, list, modify, or delete tags, you can use the Amazon S3 console, the Amazon Command Line Interface (Amazon CLI), or the Amazon S3 API.

Common ways to use tags

Use tags on your S3 directory buckets for:

  1. Cost allocation – Track storage costs by bucket tag in Amazon Billing and Cost Management.

  2. Attribute based access control (ABAC) – Scale access permissions and grant access to S3 directory buckets based on their tags.

Note

You can use the same tags for both cost allocation and access control.

Using tags for cost allocation

Track your Amazon S3 storage costs by applying tags to S3 directory buckets and activating these tags for cost allocation.

To start tracking costs:

  1. Add tags to your S3 directory buckets or use existing tags. For more information on how to add user-defined tags to your directory buckets, see Working with tags. For example, you can label buckets with a tag that identifies a project or a group of projects.

  2. Activate the tags for cost allocation in the Amazon Billing and Cost Management console. See Activating user-defined cost allocation tags in the Amazon Billing and Cost Management User Guide. You can activate user-defined or Amazon-generated tags. For more information, see Organizing and tracking costs using Amazon cost allocation tags.

Amazon uses the activated tags to organize your resource costs in various billing and cost management tools, such as:

  • Cost allocation report

    Provides a high-level view of costs organized by your activated tags. For more information, see Using the monthly cost allocation report in the Amazon Billing User Guide.

  • Cost and Usage Report (CUR)

    Provides the most detailed set of Amazon cost and usage data, including tag-based cost breakdowns. For more information, see What are Amazon Cost and Usage Reports? in the Amazon Data Export User Guide.

Using tags for attribute based access control (ABAC)

Attribute-based access control (ABAC) is an authorization strategy that defines permissions based on attributes, i.e., tags. You can attach tags to Amazon Identity and Access Management (IAM) entities (users or roles) and to Amazon resources, such as Amazon S3 directory buckets. Then, you control permissions to these resources using tag-based conditions in access control policies to allow or deny operations when these conditions are met.

ABAC for S3 directory buckets

Amazon S3 directory buckets support attribute-based access control (ABAC) using tags. Use tag based condition keys in your Amazon organizations, IAM, and S3 directory bucket policies. For enterprises, ABAC in Amazon S3 supports authorization across multiple Amazon accounts.

In your IAM policies, you can control access to S3 directory buckets based on the bucket's tags by using the following global condition keys:

  • aws:ResourceTag/key-name

    • Use this key to compare the tag key-value pair that you specify in the policy with the key-value pair attached to the resource. For example, you could require that access to a resource is allowed only if the resource has the attached tag key Dept with the value Marketing. For more information, see Controlling access to Amazon resources.

  • aws:RequestTag/key-name

    • Use this key to compare the tag key-value pair that was passed in the request with the tag pair that you specify in the policy. For example, you could check whether the request includes the tag key Dept and that it has the value Accounting. For more information, see Controlling access during Amazon requests. You can use this condition key to restrict which tag key-value pairs can be passed during the TagResource and CreateBucket API operations.

  • aws:TagKeys

    • Use this key to compare the tag keys in a request with the keys that you specify in the policy. We recommend that when you use policies to control access using tags, use the aws:TagKeys condition key to define what tag keys are allowed. For example policies and more information, see Controlling access based on tag keys. You can create an S3 directory bucket with tags. To allow tagging during the CreateBucket API operation, you must create a policy that includes both the s3express:TagResource and s3express:CreateBucket actions. You can then use the aws:TagKeys condition key to enforce using specific tags in the CreateBucket request.

  • s3express:BucketTag/tag-key

    • Use this condition key to grant permissions to specific data in directory buckets using tags. When accessing a directory bucket by using an access point, this condition key references the tags on the directory bucket both when authorizing against the access point and the directory bucket, while the aws:ResourceTag/tag-key will reference the tags only of the resource it is being authorized against.

Example policies

See the following example ABAC policies for Amazon S3 directory buckets.

1.1 - IAM policy to create or modify buckets with specific tags

In this IAM policy, users or roles with this policy can only create S3 directory buckets if they tag the bucket with the tag key project and tag value Trinity in the bucket creation request. They can also add or modify tags on existing S3 directory buckets as long as the TagResource request includes the tag key-value pair project:Trinity. This policy does not grant read, write, or delete permissions on the buckets or its objects. 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CreateBucketWithTags",
      "Effect": "Allow",
      "Action": [
        "s3express:CreateBucket",
        "s3express:TagResource"
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/project": [
            "Trinity"
          ]
        }
      }
    }
  ]
}
1.2 - Bucket policy to restrict operations on the bucket using tags

In this bucket policy, IAM principals (users and roles) can perform operations using the CreateSession action on the bucket only if the value of the bucket's project tag matches the value of the principal's project tag.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowObjectOperations",
      "Effect": "Allow",
      "Principal": {
        "AWS": "111122223333"
      },
      "Action": "s3express:CreateSession",
      "Resource": "arn:aws:s3express:us-west-2:111122223333:bucket/amzn-s3-demo-bucket--usw2-az1--x-s3",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/project": "${aws:PrincipalTag/project}"
        }
      }
    }
  ]
}
1.3 - IAM policy to modify tags on existing resources maintaining tagging governence

In this IAM policy, IAM principals (users or roles) can modify tags on a bucket only if the value of the bucket's project tag matches the value of the principal's project tag. Only the four tags project, environment, owner, and cost-center specified in the aws:TagKeys condition keys are permitted for these directory buckets. This helps enforce tag governance, prevents unauthorized tag modifications, and keeps the tagging schema consistent across your buckets.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EnforceTaggingRulesOnModification",
      "Effect": "Allow",
      "Action": [
        "s3express:TagResource"
      ],
      "Resource": "arn:aws:s3express:*:*:bucket/*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/project": "${aws:PrincipalTag/project}"
        },
        "ForAllValues:StringEquals": {
          "aws:TagKeys": [
            "project",
            "environment",
            "owner",
            "cost-center"
          ]
        }
      }
    }
  ]
}
1.4 - Using the s3express:BucketTag condition key

In this IAM policy, the condition statement allows access to the bucket's data only if the bucket have the tag key Environment and tag value Production. 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAccessToSpecificAccessPoint",
      "Effect": "Allow",
      "Action": "*",
      "Resource": "arn:aws:s3express:*:*:accesspoint/*",
      "Condition": {
        "StringEquals": {
          "s3express:BucketTag/Environment": "Production"
        }
      }
    }
  ]
}

Working with tags

You can add or manage tags for S3 directory buckets using the Amazon S3 Console, the Amazon Command Line Interface (CLI), the Amazon SDKs, or using the S3 APIs: TagResource, UntagResource, and ListTagsForResource. For more information, see:

Topics