c7n.tags module

class c7n.tags.CopyRelatedResourceTag(data=None, manager=None, log_dir=None)

Bases: c7n.tags.Tag

Copy a related resource tag to its associated resource

In some scenarios, resource tags from a related resource should be applied to its child resource. For example, EBS Volume tags propogating to their snapshots. To use this action, specify the resource type that contains the tags that are to be copied, which can be found by using the custodian schema command.

Then, specify the key on the resource that references the related resource. In the case of ebs-snapshot, the VolumeId attribute would be the key that identifies the related resource, ebs.

Finally, specify a list of tag keys to copy from the related resource onto the original resource. The special character “*” can be used to signify that all tags from the related resource should be copied to the original resource.

To raise an error when related resources cannot be found, use the skip_missing option. By default, this is set to True.

Example:

policies:
    - name: copy-tags-from-ebs-volume-to-snapshot
      resource: ebs-snapshot
      actions:
        - type: copy-related-tag
          resource: ebs
          skip_missing: True
          key: VolumeId
          tags: '*'

get_permissions()

get_resource_tag_map(r_type, ids)

Returns a mapping of {resource_id: {tagkey: tagvalue}}

process(resources)

process_resource(client, r, related_tags, tag_keys, tag_action)

classmethod register_resources(registry, resource_class)

schema = {'additionalProperties': False, 'properties': {'key': {'type': 'string'}, 'resource': {'type': 'string'}, 'skip_missing': {'type': 'boolean'}, 'tags': {'oneOf': [{'enum': ['*']}, {'type': 'array'}]}, 'type': {'enum': ['copy-related-tag']}}, 'required': ['tags', 'key', 'resource', 'type'], 'type': 'object'}

schema_alias = True

type = 'copy-related-tag'

validate()

class c7n.tags.NormalizeTag(data=None, manager=None, log_dir=None)

Bases: c7n.actions.core.Action

Transform the value of a tag.

Set the tag value to uppercase, title, lowercase, or strip text from a tag key.

policies:
  - name: ec2-service-transform-lower
    resource: ec2
    comment: |
      ec2-service-tag-value-to-lower
    query:
      - instance-state-name: running
    filters:
      - "tag:testing8882": present
    actions:
      - type: normalize-tag
        key: lower_key
        action: lower

  - name: ec2-service-strip
    resource: ec2
    comment: |
      ec2-service-tag-strip-blah
    query:
      - instance-state-name: running
    filters:
      - "tag:testing8882": present
    actions:
      - type: normalize-tag
        key: strip_key
        action: strip
        value: blah

create_set(instances)

create_tag(client, ids, key, value)

filter_resources(resources)

permissions = ('ec2:CreateTags',)

process(resources)

process_transform(tag_value, resource_set)

Transform tag value

• Collect value from tag
• Transform Tag value
• Assign new value for key

schema = {'additionalProperties': False, 'properties': {'action': {'items': {'enum': ['upper', 'lower', 'titlestrip', 'replace']}, 'type': 'string'}, 'key': {'type': 'string'}, 'type': {'enum': ['normalize-tag']}, 'value': {'type': 'string'}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

type = 'normalize-tag'

class c7n.tags.RemoveTag(data=None, manager=None, log_dir=None)

Bases: c7n.actions.core.Action

Remove tags from ec2 resources.

batch_size = 100

concurrency = 2

get_client()

permissions = ('ec2:DeleteTags',)

process(resources)

process_resource_set(client, resource_set, tag_keys)

schema = {'additionalProperties': False, 'properties': {'tags': {'items': {'type': 'string'}, 'type': 'array'}, 'type': {'enum': ['remove-tag', 'unmark', 'untag', 'remove-tag']}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

type = 'remove-tag'

class c7n.tags.RenameTag(data=None, manager=None, log_dir=None)

Bases: c7n.actions.core.Action

Create a new tag with identical value & remove old tag

create_set(instances)

create_tag(client, ids, key, value)

delete_tag(client, ids, key, value)

filter_resources(resources)

get_client()

permissions = ('ec2:CreateTags', 'ec2:DeleteTags')

process(resources)

process_rename(client, tag_value, resource_set)

Move source tag value to destination tag value

• Collect value from old tag
• Delete old tag
• Create new tag & assign stored value

schema = {'additionalProperties': False, 'properties': {'new_key': {'type': 'string'}, 'old_key': {'type': 'string'}, 'type': {'enum': ['rename-tag']}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

tag_count_max = 50

type = 'rename-tag'

class c7n.tags.Tag(data=None, manager=None, log_dir=None)

Bases: c7n.actions.core.Action

Tag an ec2 resource.

batch_size = 25

concurrency = 2

get_client()

id_key = None

interpolate_values(tags)

permissions = ('ec2:CreateTags',)

process(resources)

process_resource_set(client, resource_set, tags)

schema = {'additionalProperties': False, 'properties': {'key': {'type': 'string'}, 'tag': {'type': 'string'}, 'tags': {'type': 'object'}, 'type': {'enum': ['tag', 'mark']}, 'value': {'type': 'string'}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

type = 'tag'

validate()

class c7n.tags.TagActionFilter(data, manager=None)

Bases: c7n.filters.core.Filter

Filter resources for tag specified future action

Filters resources by a ‘custodian_status’ tag which specifies a future date for an action.

The filter parses the tag values looking for an ‘op@date’ string. The date is parsed and compared to do today’s date, the filter succeeds if today’s date is gte to the target date.

The optional ‘skew’ parameter provides for incrementing today’s date a number of days into the future. An example use case might be sending a final notice email a few days before terminating an instance, or snapshotting a volume prior to deletion.

The optional ‘skew_hours’ parameter provides for incrementing the current time a number of hours into the future.

Optionally, the ‘tz’ parameter can get used to specify the timezone in which to interpret the clock (default value is ‘utc’)

policies:
  - name: ec2-stop-marked
    resource: ec2
    filters:
      - type: marked-for-op
        # The default tag used is custodian_status
        # but that is configurable
        tag: custodian_status
        op: stop
        # Another optional tag is skew
        tz: utc
    actions:
      - type: stop

current_date = None

schema = {'additionalProperties': False, 'properties': {'op': {'type': 'string'}, 'skew': {'minimum': 0, 'type': 'number'}, 'skew_hours': {'minimum': 0, 'type': 'number'}, 'tag': {'type': 'string'}, 'type': {'enum': ['marked-for-op']}, 'tz': {'type': 'string'}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

type = 'marked-for-op'

validate()

validate filter config, return validation error or self

class c7n.tags.TagCountFilter(data, manager=None)

Bases: c7n.filters.core.Filter

Simplify tag counting..

ie. these two blocks are equivalent

- filters:
    - type: value
      op: gte
      count: 8

- filters:
    - type: tag-count
      count: 8

schema = {'additionalProperties': False, 'properties': {'count': {'minimum': 0, 'type': 'integer'}, 'op': {'enum': ['eq', 'equal', 'ne', 'not-equal', 'gt', 'greater-than', 'ge', 'gte', 'le', 'lte', 'lt', 'less-than', 'glob', 'regex', 'regex-case', 'in', 'ni', 'not-in', 'contains', 'difference', 'intersect']}, 'type': {'enum': ['tag-count']}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

type = 'tag-count'

class c7n.tags.TagDelayedAction(data=None, manager=None, log_dir=None)

Bases: c7n.actions.core.Action

Tag resources for future action.

The optional ‘tz’ parameter can be used to adjust the clock to align with a given timezone. The default value is ‘utc’.

If neither ‘days’ nor ‘hours’ is specified, Cloud Custodian will default to marking the resource for action 4 days in the future.

policies:
  - name: ec2-mark-for-stop-in-future
    resource: ec2
    filters:
      - type: value
        key: Name
        value: instance-to-stop-in-four-days
    actions:
      - type: mark-for-op
        op: stop

batch_size = 200

concurrency = 2

default_template = 'Resource does not meet policy: {op}@{action_date}'

generate_timestamp(days, hours)

get_client()

get_config_values()

get_permissions()

process(resources)

process_resource_set(client, resource_set, tags)

schema = {'additionalProperties': False, 'properties': {'days': {'exclusiveMinimum': False, 'minimum': 0, 'type': 'integer'}, 'hours': {'exclusiveMinimum': False, 'minimum': 0, 'type': 'integer'}, 'msg': {'type': 'string'}, 'op': {'type': 'string'}, 'tag': {'type': 'string'}, 'type': {'enum': ['mark-for-op']}, 'tz': {'type': 'string'}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

type = 'mark-for-op'

validate()

class c7n.tags.TagTrim(data=None, manager=None, log_dir=None)

Bases: c7n.actions.core.Action

Automatically remove tags from an ec2 resource.

EC2 Resources have a limit of 50 tags, in order to make additional tags space on a set of resources, this action can be used to remove enough tags to make the desired amount of space while preserving a given set of tags.

policies:
  - name: ec2-tag-trim
    comment: |
      Any instances with 48 or more tags get tags removed until
      they match the target tag count, in this case 47 so we
      that we free up a tag slot for another usage.
    resource: ec2
    filters:
          # Filter down to resources which already have 8 tags
          # as we need space for 3 more, this also ensures that
          # metrics reporting is correct for the policy.
        - type: value
          key: "length(Tags)"
          op: ge
          value: 48
    actions:
       - type: tag-trim
         space: 3
         preserve:
           - OwnerContact
           - ASV
           - CMDBEnvironment
           - downtime
           - custodian_status

max_tag_count = 50

permissions = ('ec2:DeleteTags',)

process(resources)

process_resource(client, i)

process_tag_removal(client, resource, tags)

schema = {'additionalProperties': False, 'properties': {'preserve': {'items': {'type': 'string'}, 'type': 'array'}, 'space': {'type': 'integer'}, 'type': {'enum': ['tag-trim']}}, 'required': ['type'], 'type': 'object'}

schema_alias = True

type = 'tag-trim'

class c7n.tags.UniversalTag(data=None, manager=None, log_dir=None)

Bases: c7n.tags.Tag

Applies one or more tags to the specified resources.

batch_size = 20

concurrency = 1

get_client()

permissions = ('resourcegroupstaggingapi:TagResources',)

process(resources)

process_resource_set(client, resource_set, tags)

type = 'tag'

class c7n.tags.UniversalTagDelayedAction(data=None, manager=None, log_dir=None)

Bases: c7n.tags.TagDelayedAction

Tag resources for future action.

Example:

policies:
- name: ec2-mark-stop
  resource: ec2
  filters:
    - type: image-age
      op: ge
      days: 90
  actions:
    - type: mark-for-op
      tag: custodian_cleanup
      op: terminate
      days: 4

batch_size = 20

concurrency = 2

get_client()

permissions = ('resourcegroupstaggingapi:TagResources',)

process(resources)

process_resource_set(client, resource_set, tags)

type = 'mark-for-op'

class c7n.tags.UniversalUntag(data=None, manager=None, log_dir=None)

Bases: c7n.tags.RemoveTag

Removes the specified tags from the specified resources.

batch_size = 20

concurrency = 1

get_client()

permissions = ('resourcegroupstaggingapi:UntagResources',)

process_resource_set(client, resource_set, tag_keys)

type = 'remove-tag'

c7n.tags._common_tag_processer(executor_factory, batch_size, concurrency, client, process_resource_set, id_key, resources, tags, log)

c7n.tags.coalesce_copy_user_tags(resource, copy_tags, user_tags)

Returns a list of tags from resource and user supplied in the format: [{‘Key’: ‘key’, ‘Value’: ‘value’}]

Due to drift on implementation on copy-tags/tags used throughout the code base, the following options are supported:

copy_tags (Tags to copy from the resource):

• list of str, e.g. [‘key1’, ‘key2’, ‘*’]
• bool

user_tags (User supplied tags to apply):

• dict of key-value pairs, e.g. {Key: Value, Key2: Value}
• list of dict e.g. [{‘Key’: k, ‘Value’: v}]

In the case that there is a conflict in a user supplied tag and an existing tag on the resource, the user supplied tags will take priority.

Additionally, a value of ‘*’ in copy_tags can be used to signify to copy all tags from the resource.

c7n.tags.register_ec2_tags(filters, actions)

c7n.tags.register_universal_tags(filters, actions, compatibility=True)

c7n.tags.universal_augment(self, resources)

c7n.tags.universal_retry(method, ResourceARNList, **kw)

Retry support for resourcegroup tagging apis.

The resource group tagging api typically returns a 200 status code with embedded resource specific errors. To enable resource specific retry on throttles, we extract those, perform backoff w/ jitter and continue. Other errors are immediately raised.

We do not aggregate unified resource responses across retries, only the last successful response is returned for a subset of the resources if a retry is performed.