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)

{
  "default": {
    "type": "object"
  },
  "key": {
    "type": "string"
  },
  "op": {
    "$ref": "#/definitions/filters_common/comparison_operators"
  },
  "operator": {
    "enum": [
      "and",
      "or"
    ]
  },
  "skip-devices": {
    "items": {
      "type": "string"
    },
    "type": "array"
  },
  "value": {
    "$ref": "#/definitions/filters_common/value"
  },
  "value_from": {
    "$ref": "#/definitions/filters_common/value_from"
  },
  "value_type": {
    "$ref": "#/definitions/filters_common/value_types"
  }
}

image-age

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

{
  "days": {
    "type": "number"
  },
  "op": {
    "$ref": "#/definitions/filters_common/comparison_operators"
  }
}

image

Filter on the ImageId of the instance

{
  "default": {
    "type": "object"
  },
  "key": {
    "type": "string"
  },
  "op": {
    "$ref": "#/definitions/filters_common/comparison_operators"
  },
  "value": {
    "$ref": "#/definitions/filters_common/value"
  },
  "value_from": {
    "$ref": "#/definitions/filters_common/value_from"
  },
  "value_type": {
    "$ref": "#/definitions/filters_common/value_types"
  }
}

offhour

Filter for c7n.resources.ec2.InstanceOffHour

{
  "default_tz": {
    "required": true,
    "type": "string"
  },
  "offhour": {
    "maximum": 23,
    "minimum": 0,
    "required": true,
    "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"
  },
  "weekends": {
    "type": "boolean"
  },
  "weekends-only": {
    "type": "boolean"
  }
}

onhour

Filter for c7n.resources.ec2.InstanceOnHour

{
  "default_tz": {
    "required": true,
    "type": "string"
  },
  "onhour": {
    "maximum": 23,
    "minimum": 0,
    "required": true,
    "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"
  },
  "weekends": {
    "type": "boolean"
  },
  "weekends-only": {
    "type": "boolean"
  }
}

ephemeral

Filter for instances that have ephemeral drives

{}

instance-uptime

Filter based on instance LaunchTime in days

{
  "days": {
    "type": "number"
  },
  "op": {
    "$ref": "#/definitions/filters_common/comparison_operators"
  }
}

instance-age

Filter based on the AttachTime of the EBS Volumes in days

{
  "days": {
    "type": "number"
  },
  "hours": {
    "type": "number"
  },
  "minutes": {
    "type": "number"
  },
  "op": {
    "$ref": "#/definitions/filters_common/comparison_operators"
  }
}

termination-protected

Filter based on the disableApiTermination instance attribute.

{}

user-data

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

{
  "default": {
    "type": "object"
  },
  "key": {
    "type": "string"
  },
  "op": {
    "$ref": "#/definitions/filters_common/comparison_operators"
  },
  "value": {
    "$ref": "#/definitions/filters_common/value"
  },
  "value_from": {
    "$ref": "#/definitions/filters_common/value_from"
  },
  "value_type": {
    "$ref": "#/definitions/filters_common/value_types"
  }
}

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.

{}

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.

{
  "terminate-ephemeral": {
    "type": "boolean"
  }
}

Terminate

Will terminate the instances. Use with caution!

{
  "force": {
    "type": "boolean"
  }
}

Snapshot

Snapshots the instances’ attached EBS volumes.

{
  "copy-tags": {
    "items": {
      "type": "string"
    },
    "type": "array"
  }
}

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)

{
  "only_tags": {
    "items": {
      "type": "string"
    },
    "type": "array"
  }
}

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)