Tag actions
Objective
Section titled “Objective”Tags are key-value pairs attached to resources. They organise resources, filter
Describe calls, and appear on usage records.
Permissions
Section titled “Permissions”| Action | Resource scope |
|---|---|
ec2:CreateTags | The resource being tagged |
ec2:DeleteTags | The resource being untagged |
ec2:DescribeTags | Requires "Resource": "*" |
ec2:CreateTags is also required by any create action that carries a
TagSpecification. A policy that allows ec2:RunInstances but not
ec2:CreateTags denies a launch that tags the instance.
Instructions
Section titled “Instructions”Tag constraints
Section titled “Tag constraints”PROPOSED, matching Amazon EC2 so that existing tooling’s client-side validation agrees with ours:
| Constraint | Value |
|---|---|
| Tags per resource | 50 |
| Key length | 1 to 128 characters |
| Value length | 0 to 256 characters |
| Character set | Letters, digits, spaces, and + - = . _ : / @ |
| Case | Keys and values are case-sensitive |
| Reserved prefix | shelf: is reserved and cannot be set by a customer |
A value may be empty. A key may not.
[!warning]
Tags are visible to anyone who can read the resource, they appear in usage records, and they may appear on invoices. Nothing sensitive belongs in a tag.
Tagging at creation
Section titled “Tagging at creation”Prefer this to tagging afterwards:
TagSpecification.1.ResourceType=instanceTagSpecification.1.Tag.1.Key=NameTagSpecification.1.Tag.1.Value=web-1The resource is never untagged, even briefly. A separate CreateTags call after
a create leaves a window in which the resource exists without its tags — and if
the second call fails, an untagged resource that nothing is tracking.
CreateTags
Section titled “CreateTags”| Parameter | Type | Required |
|---|---|---|
ResourceId.N | list | Yes |
Tag.N.Key, Tag.N.Value | list | Yes |
DryRun | boolean | No |
Sets tags to the values given. An existing key is overwritten; keys not mentioned are left alone.
Idempotent by nature, which is why it carries no ClientToken and needs
none: repeating the call with the same values changes nothing.
Resources of different types may be tagged in one call. It is all-or-nothing: if any resource id is invalid, none are tagged.
Response: return only. No tag data is echoed.
DeleteTags
Section titled “DeleteTags”| Parameter | Type | Required | Notes |
|---|---|---|---|
ResourceId.N | list | Yes | |
Tag.N.Key | list | No | Omit to delete all tags |
Tag.N.Value | list | No | See below |
The value parameter has behaviour worth reading twice:
- Key given, no value — the tag is deleted whatever its value.
- Key and value given — deleted only if the value matches. A mismatch is not an error; nothing is deleted and the call succeeds.
- Key given, value given as empty — deleted only if the value is empty.
Deleting a tag that does not exist succeeds.
DescribeTags
Section titled “DescribeTags”| Parameter | Type | Notes |
|---|---|---|
Filter.N | list | key, value, resource-id, resource-type |
MaxResults | integer | 5 to 1000 |
NextToken | string |
Paginated. Returns one entry per tag per resource, so a hundred resources with five tags each is five hundred entries.
Response: each entry has resourceId, resourceType, key, value.
Filtering other calls by tag
Section titled “Filtering other calls by tag”Every Describe action accepts tag filters:
shelf --profile shelf ec2 describe-instances \ --filters Name=tag:Environment,Values=production| Filter | Matches |
|---|---|
tag:<key> | Resources whose tag <key> has one of the given values |
tag-key | Resources carrying that key, whatever the value |
This is the mechanism most automation depends on, and the reason to tag at creation: a resource that missed its tags is invisible to every query that selects by tag.