Tagging your Amazon Batch resources - Amazon Batch
Tag basicsTagging your resourcesTag restrictionsWorking with tags using the consoleWorking with tags using the CLI or API
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).

Tagging your Amazon Batch resources

To help you manage your Amazon Batch resources, you can assign your own metadata to each resource in the form of tags. This topic describes tags and shows you how to create them.

Tag basics

A tag is a label that you assign to an Amazon resource. Each tag consists of a key and an optional value, both of which you define.

Tags enable you to categorize your Amazon resources by, for example, purpose, owner, or environment. When you have many resources of the same type, you can quickly identify a specific resource based on the tags you've assigned to it. For example, you can define a set of tags for your Amazon Batch services to help you track each service's owner and stack level. We recommend that you devise a consistent set of tag keys for each resource type.

Tags are not automatically assigned to your resources. After you add a tag, you can edit tag keys and values or remove tags from a resource at any time. If you delete a resource, any tags for the resource are also deleted.

Tags don't have any semantic meaning to Amazon Batch and are interpreted strictly as a string of characters. 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 old value.

You can work with tags using the Amazon Web Services Management Console, the Amazon CLI, and the Amazon Batch API.

If you're using Amazon Identity and Access Management (IAM), you can control which users in your Amazon account have permission to create, edit, or delete tags.

Tagging your resources

You can tag new or existing Amazon Batch compute environments, jobs, job definitions, job queues, and scheduling policies.

If you're using the Amazon Batch console, you can apply tags to new resources when they are created or to existing resources at any time using the Tags tab on the relevant resource page.

If you're using the Amazon Batch API, the Amazon CLI, or an Amazon SDK, you can apply tags to new resources using the tags parameter on the relevant API action or to existing resources using the TagResource API action. For more information, see TagResource.

Some resource-creating actions enable you to specify tags for a resource when the resource is created. If tags cannot be applied during resource creation, the resource creation process fails. This ensures that resources you intended to tag on creation are either created with specified tags or not created at all. If you tag resources at the time of creation, you don't need to run custom tagging scripts after resource creation.

The following table describes the Amazon Batch resources that can be tagged, and the resources that can be tagged on creation.

Tagging support for Amazon Batch resources
Resource Supports tags Supports tag propagation Supports tagging on creation (Amazon Batch API, Amazon CLI, Amazon SDK)

Amazon Batch compute environments

Yes

No. Compute environment tags do not propagate to any other resources. Tags for the resources are specified in the tags member of the computeResources object passed in the CreateComputeEnvironment API operation.

Yes

Amazon Batch jobs

Yes

No. Tags do not propagate to child jobs for array or multi-node parallel (MNP) jobs.

Yes

Amazon Batch job definitions

Yes

No.

Yes

Amazon Batch job queues

Yes

No.

Yes
Amazon Batch scheduling policies

Yes

No.

Yes

Tag restrictions

The following basic restrictions apply to tags:

  • Maximum number of tags per resource – 50

  • For each resource, each tag key must be unique, and each tag key can have only one value.

  • Maximum key length – 128 Unicode characters in UTF-8

  • Maximum value length – 256 Unicode characters in UTF-8

  • If your tagging schema is used across multiple Amazon services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are letters, numbers, spaces representable in UTF-8, and the following characters: + - = . _ : / @.

  • Tag keys and values are case sensitive.

  • Don't use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values, as it is reserved for Amazon use. You can't edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags-per-resource limit.

Working with tags using the console

Using the Amazon Batch console, you can manage the tags associated with new or existing compute environments, jobs, job definitions, and job queues.

Adding tags on an individual resource on creation

You can add tags to Amazon Batch compute environments, jobs, job definitions, job queues, and scheduling policies when you create them.

Adding and deleting tags on an individual resource

Amazon Batch allows you to add or delete tags associated with your clusters directly from the resource's page.

To add or delete a tag on an individual resource

  1. Open the Amazon Batch console at https://console.amazonaws.cn/batch/.

  2. From the navigation bar, choose the Region to use.

  3. In the navigation pane, choose a resource type (for example, Job Queues).

  4. Choose a specific resource, then choose Edit tags.

  5. Add or delete your tags as necessary.

    • To add a tag — specify the key and value in the empty text boxes at the end of the list.

    • To delete a tag — choose the Delete icon button next to the tag.

  6. Repeat this process for each tag you want to add or delete, and then choose Edit tags to finish.

Working with tags using the CLI or API

Use the following Amazon CLI commands or Amazon Batch API operations to add, update, list, and delete the tags for your resources.

Tagging support for Amazon Batch resources
Task API action Amazon CLI Amazon Tools for Windows PowerShell

Add or overwrite one or more tags.

TagResource

tag-resource

Add-BATResourceTag

Delete one or more tags.

UntagResource

untag-resource

Remove-BATResourceTag
List tags for a resource

ListTagsForResource

list-tags-for-resource

Get-BATResourceTag

The following examples show how to tag or untag resources using the Amazon CLI.

Example 1: Tag an existing resource

The following command tags an existing resource.

aws batch tag-resource --resource-arn resource_ARN --tags team=devs
Example 2: Untag an existing resource

The following command deletes a tag from an existing resource.

aws batch untag-resource --resource-arn resource_ARN --tag-keys tag_key
Example 3: List tags for a resource

The following command lists the tags associated with an existing resource.

aws batch list-tags-for-resource --resource-arn resource_ARN

Some resource-creating actions enable you to specify tags when you create the resource. The following actions support tagging on creation.

Task API action Amazon CLI Amazon Tools for Windows PowerShell

Create a compute environment

CreateComputeEnvironment

create-compute-environment

New-BATComputeEnvironment

Create a job queue

CreateJobQueue

create-job-queue

New-BATJobQueue

Create a scheduling policy

CreateSchedulingPolicy

create-scheduling-policy

New-BATSchedulingPolicy

Register a job definition

RegisterJobDefinition

register-job-definition

Register-BATJobDefinition

Submit a job

SubmitJob

submit-job

Submit-BATJob