Elastic Cloud Compute (EC2)¶

Query¶

Basic JMESPath Query (see c7n.filters.ValueFilter)
Valid EC2 Query Filters (see EC2 Describe Instances)

EC2_VALID_FILTERS = {
    'architecture': ('i386', 'x86_64'),
    'availability-zone': str,
    'iam-instance-profile.arn': str,
    'image-id': str,
    'instance-id': str,
    'instance-lifecycle': ('spot',),
    'instance-state-name': (
        'pending',
        'terminated',
        'running',
        'shutting-down',
        'stopping',
        'stopped'),
    'instance.group-id': str,
    'instance.group-name': str,
    'tag-key': str,
    'tag-value': str,
    'tag:': str,
    'tenancy': ('dedicated', 'default', 'host'),
    'vpc-id': str}

Filters¶

Standard Value Filter (see Generic Filters)

ebs

Filter based on Volumes attached to Instance

Filter by State Transition Filter

Filter instances by state (see Instance Lifecycle)

additionalProperties: false
properties:
  default:
    type: object
  key:
    type: string
  op:
    $ref: '#/definitions/filters_common/comparison_operators'
  operator:
    enum:
    - and
    - or
  skip-devices:
    items:
      type: string
    type: array
  type:
    enum:
    - ebs
  value:
    $ref: '#/definitions/filters_common/value'
  value_from:
    $ref: '#/definitions/filters_common/value_from'
  value_regex:
    type: string
  value_type:
    $ref: '#/definitions/filters_common/value_types'
required:
- type
type: object

image-age

Filter on the age of the instance AMI based on the ImageId CreationDate

Deprecated use image filter with value_type: age

additionalProperties: false
properties:
  days:
    type: number
  op:
    $ref: '#/definitions/filters_common/comparison_operators'
  type:
    enum:
    - image-age
required:
- type
type: object

image

Filter on the ImageId of the instance

additionalProperties: false
properties:
  default:
    type: object
  key:
    type: string
  op:
    $ref: '#/definitions/filters_common/comparison_operators'
  type:
    enum:
    - image
  value:
    $ref: '#/definitions/filters_common/value'
  value_from:
    $ref: '#/definitions/filters_common/value_from'
  value_regex:
    type: string
  value_type:
    $ref: '#/definitions/filters_common/value_types'
required:
- type
type: object

offhour

Filter for c7n.resources.ec2.InstanceOffHour

additionalProperties: false
properties:
  default_tz:
    type: string
  offhour:
    maximum: 23
    minimum: 0
    type: integer
  opt-out:
    type: boolean
  skip-days:
    items:
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}
      type: string
    type: array
  skip-days-from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  tag:
    type: string
  type:
    enum:
    - offhour
  weekends:
    type: boolean
  weekends-only:
    type: boolean
required:
- offhour
- default_tz
- type
type: object

onhour

Filter for c7n.resources.ec2.InstanceOnHour

additionalProperties: false
properties:
  default_tz:
    type: string
  onhour:
    maximum: 23
    minimum: 0
    type: integer
  opt-out:
    type: boolean
  skip-days:
    items:
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}
      type: string
    type: array
  skip-days-from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      url:
        type: string
    required:
    - url
    type: object
  tag:
    type: string
  type:
    enum:
    - onhour
  weekends:
    type: boolean
  weekends-only:
    type: boolean
required:
- onhour
- default_tz
- type
type: object

ephemeral

Filter for instances that have ephemeral drives

additionalProperties: false
properties:
  type:
    enum:
    - ephemeral
required:
- type
type: object

instance-uptime

Filter based on instance LaunchTime in days

additionalProperties: false
properties:
  days:
    type: number
  op:
    $ref: '#/definitions/filters_common/comparison_operators'
  type:
    enum:
    - instance-uptime
required:
- type
type: object

instance-age

Filter based on the AttachTime of the EBS Volumes in days

additionalProperties: false
properties:
  days:
    type: number
  hours:
    type: number
  minutes:
    type: number
  op:
    $ref: '#/definitions/filters_common/comparison_operators'
  type:
    enum:
    - instance-age
required:
- type
type: object

termination-protected

Filter based on the disableApiTermination instance attribute.

additionalProperties: false
properties:
  type:
    enum:
    - termination-protected
required:
- type
type: object

user-data

Filter for EC2’s with user data matching the value given.

additionalProperties: false
properties:
  default:
    type: object
  key:
    type: string
  op:
    $ref: '#/definitions/filters_common/comparison_operators'
  type:
    enum:
    - user-data
  value:
    $ref: '#/definitions/filters_common/value'
  value_from:
    $ref: '#/definitions/filters_common/value_from'
  value_regex:
    type: string
  value_type:
    $ref: '#/definitions/filters_common/value_types'
required:
- type
type: object

Actions¶

Mark

Tag instances with mark instances matching filters with a c7n_status tag by default and configurable value. Here’s an example of renaming an extant tag:

policies:
  - name: ec2-tag-instances
    resource: ec2
    filters:
      - "tag:CostCenter": foobar
    actions:
      - type: mark
        tag: CostCenter
        msg: barrum

Start

Start a set of instances (presumably) already stopped, the start action will automatically filter instances to those that are already in the correct state.

additionalProperties: false
properties:
  type:
    enum:
    - start
required:
- type
type: object

This example will restart all stopped instances.

policies:
  - name: ec2-start
    resources: ec2
    actions:
      - start

Stop

Will stop the instances. Stopped instances do not incur EC2 instance costs.

additionalProperties: false
properties:
  terminate-ephemeral:
    type: boolean
  type:
    enum:
    - stop
required:
- type
type: object

Terminate

Will terminate the instances. Use with caution!

additionalProperties: false
properties:
  force:
    type: boolean
  type:
    enum:
    - terminate
required:
- type
type: object

Snapshot

Snapshots the instances’ attached EBS volumes.

additionalProperties: false
properties:
  copy-tags:
    items:
      type: string
    type: array
  copy-volume-tags:
    type: boolean
  exclude-boot:
    default: false
    type: boolean
  type:
    enum:
    - snapshot
required:
- type
type: object

This example will create snapshots for all instances and copy the Owner tag value from the instance to the new snapshot.

policies:
   - name: ec2-nightly-backup
     resource: ec2
     actions:
       - type: snapshot
         copy-tags:
           - Owner

PropagateSpotTags

In case the EC2 instance is a Spot Instance, created by a Spot Instance Request, this action will propagate all (or a subset) of the Tags that are attached to the original Spot Instance Request. Spot Instance Request do not propagate their tags to the Spot Instances. (see Tagging Spot Instance Requests)

However, Spot Fleets are said to propagate their Tags. (see Tag Your Spot Fleet EC2 Instances)

additionalProperties: false
properties:
  only_tags:
    items:
      type: string
    type: array
  type:
    enum:
    - propagate-spot-tags
required:
- type
type: object

This example will copy the Name and the BillingTag tag values from the Spot Instance Request to the pending EC2 instances (only if they are Spot Instances)