aws.ebs

Filters

config-compliance

cost-optimization

event

fault-tolerant

finding

health-event

instance

json-diff

kms-alias

list-item

marked-for-op

metrics

modifyable

ops-item

reduce

snapshots

tag-count

value

fault-tolerant

This filter will return any EBS volume that does/does not have a snapshot within the last 7 days. ‘Fault-Tolerance’ in this instance means that, in the event of a failure, the volume can be restored from a snapshot with (reasonable) data loss

policies:
 - name: ebs-volume-tolerance
   resource: ebs
   filters:
     - type: fault-tolerant
       tolerant: True

properties:
  tolerant:
    type: boolean
  type:
    enum:
    - fault-tolerant
required:
- type

Permissions - support:RefreshTrustedAdvisorCheck, support:DescribeTrustedAdvisorCheckResult

health-event

Check if there are operations health events (phd) related to the resources

https://aws.amazon.com/premiumsupport/technology/personal-health-dashboard/

Health events are stored as annotation on a resource.

Custodian also supports responding to phd events via a lambda execution mode.

properties:
  statuses:
    items:
      enum:
      - open
      - upcoming
      - closed
      type: string
    type: array
  type:
    enum:
    - health-event
  types:
    items:
      enum:
      - AWS_EBS_DEGRADED_EBS_VOLUME_PERFORMANCE
      - AWS_EBS_VOLUME_LOST
      type: string
    type: array
required:
- type

Permissions - health:DescribeEvents, health:DescribeAffectedEntities, health:DescribeEventDetails, config:GetResourceConfigHistory

instance

Filter volumes based on filtering on their attached instance

example:

policies:
  - name: instance-ebs-volumes
    resource: ebs
    filters:
      - type: instance
        key: tag:Name
        value: OldManBySea

properties:
  default:
    type: object
  key:
    type: string
  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
    - mod
  type:
    enum:
    - instance
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      headers:
        patternProperties:
          ? ''
          : type: string
        type: object
      query:
        type: string
      url:
        type: string
    required:
    - url
    type: object
  value_path:
    type: string
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - ec2:DescribeInstances, ec2:DescribeTags, ec2:DescribeTags

json-diff

Compute the diff from the current resource to a previous version.

A resource matches the filter if a diff exists between the current resource and the selected revision.

Utilizes config as a resource revision database.

Revisions can be selected by date, against the previous version, and against a locked version (requires use of is-locked filter).

properties:
  selector:
    enum:
    - previous
    - date
    - locked
  selector_value:
    type: string
  type:
    enum:
    - json-diff
required:
- type

Permissions - config:GetResourceConfigHistory

kms-alias

properties:
  default:
    type: object
  key:
    type: string
  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
    - mod
  type:
    enum:
    - kms-alias
  value:
    oneOf:
    - type: array
    - type: string
    - type: boolean
    - type: number
    - type: 'null'
  value_from:
    additionalProperties: 'False'
    properties:
      expr:
        oneOf:
        - type: integer
        - type: string
      format:
        enum:
        - csv
        - json
        - txt
        - csv2dict
      headers:
        patternProperties:
          ? ''
          : type: string
        type: object
      query:
        type: string
      url:
        type: string
    required:
    - url
    type: object
  value_path:
    type: string
  value_regex:
    type: string
  value_type:
    enum:
    - age
    - integer
    - expiration
    - normalize
    - size
    - cidr
    - cidr_size
    - swap
    - resource_count
    - expr
    - unique_size
    - date
    - version
    - float
required:
- type

Permissions - kms:ListAliases

modifyable

Check if an ebs volume is modifyable online.

Considerations:

https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/limitations.html

Consideration Summary

only current instance types are supported (one exception m3.medium) Current Generation Instances (2017-2) https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#current-gen-instances
older magnetic volume types are not supported
shrinking volumes is not supported
must wait at least 6hrs between modifications to the same volume.
volumes must have been attached after nov 1st, 2016.

See modify action for examples.

properties:
  type:
    enum:
    - modifyable
required:
- type

Permissions - ec2:DescribeInstances

Actions

auto-tag-user

copy-instance-tags

copy-related-tag

delete

detach

encrypt-instance-volumes

invoke-lambda

invoke-sfn

mark-for-op

modify

normalize-tag

notify

post-finding

post-item

put-metric

remove-tag

rename-tag

snapshot

tag

tag-trim

webhook

copy-instance-tags

Copy instance tags to its attached volume.

Useful for cost allocation to ebs volumes and tracking usage info for volumes.

Mostly useful for volumes not set to delete on termination, which are otherwise candidates for garbage collection, copying the instance tags gives us more semantic information to determine if their useful, as well letting us know the last time the volume was actually used.

example:

policies:
  - name: ebs-copy-instance-tags
    resource: ebs
    filters:
      - type: value
        key: "Attachments[0].Device"
        value: not-null
    actions:
      - type: copy-instance-tags
        tags:
          - Name

properties:
  tags:
    items:
      type: string
    type: array
  type:
    enum:
    - copy-instance-tags
required:
- type

Permissions - ec2:DescribeInstances, ec2:DescribeTags, ec2:DescribeTags, ec2:CreateTags

delete

Delete an ebs volume.

If the force boolean is true, we will detach an attached volume from an instance. Note this cannot be done for running instance root volumes.

example:

policies:
  - name: delete-unattached-volumes
    resource: ebs
    filters:
      - Attachments: []
      - State: available
    actions:
      - delete

properties:
  force:
    type: boolean
  type:
    enum:
    - delete
required:
- type

Permissions - ec2:DetachVolume, ec2:DeleteVolume, ec2:DescribeVolumes

detach

Detach an EBS volume from an Instance.

If ‘Force’ Param is True, then we’ll do a forceful detach of the Volume. The default value for ‘Force’ is False.

example:

policies:
  - name: detach-ebs-volumes
    resource: ebs
    filters:
      - VolumeId :  volumeid
    actions:
      - detach

properties:
  force:
    type: boolean
  type:
    enum:
    - detach
required:
- type

Permissions - ec2:DetachVolume

encrypt-instance-volumes

Encrypt extant volumes attached to an instance

Requires instance restart
Not suitable for autoscale groups.

Multistep process:

Stop instance (if running)
For each volume
- Create snapshot
- Wait on snapshot creation
- Copy Snapshot to create encrypted snapshot
- Wait on snapshot creation
- Create encrypted volume from snapshot
- Wait on volume creation
- Delete transient snapshots
- Detach Unencrypted Volume
- Attach Encrypted Volume
- Set DeleteOnTermination instance attribute equal to source volume
For each volume
- Delete unencrypted volume
Start Instance (if originally running)
For each newly encrypted volume
- Delete transient tags

example:

policies:
  - name: encrypt-unencrypted-ebs
    resource: ebs
    filters:
      - Encrypted: false
    actions:
      - type: encrypt-instance-volumes
        key: alias/encrypted

properties:
  delay:
    type: number
  key:
    type: string
  type:
    enum:
    - encrypt-instance-volumes
  verbose:
    type: boolean
required:
- key
- type

Permissions - ec2:CopySnapshot, ec2:CreateSnapshot, ec2:CreateVolume, ec2:DescribeInstances, ec2:DescribeSnapshots, ec2:DescribeVolumes, ec2:StopInstances, ec2:StartInstances, ec2:ModifyInstanceAttribute, ec2:DeleteTags

modify

Modify an ebs volume online.

Note this action requires use of modifyable filter

Intro Blog & Use Cases:: https://aws.amazon.com/blogs/aws/amazon-ebs-update-new-elastic-volumes-change-everything/
Docs:: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-modify-volume.html
Considerations:: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/limitations.html

example:: Find under utilized provisioned iops volumes older than a week and change their type.

policies:
 - name: ebs-remove-piops
   resource: ebs
   filters:
    - type: value
      key: CreateTime
      value_type: age
      value: 7
      op: greater-than
    - VolumeType: io1
    - type: metrics
      name: VolumeConsumedReadWriteOps
      statistics: Maximum
      value: 100
      op: less-than
      days: 7
    - modifyable
   actions:
    - type: modify
      volume-type: gp2

iops-percent and size-percent can be used to modify respectively iops on io1/io2 volumes and volume size.

When converting to io1/io2, iops-percent is used to set the iops allocation for the new volume against the extant value for the old volume.

example:: Double storage and quadruple iops for all io1 volumes.

policies:
 - name: ebs-upsize-piops
   resource: ebs
   filters:
     - VolumeType: io1
     - modifyable
   actions:
     - type: modify
       size-percent: 200
       iops-percent: 400

Note resizing down aka shrinking requires OS and FS support and potentially additional preparation, else data-loss may occur. To prevent accidents, shrinking must be explicitly enabled by also setting shrink: true on the action.

properties:
  iops-percent:
    type: number
  shrink: false
  size-percent:
    type: number
  type:
    enum:
    - modify
  volume-type:
    enum:
    - io1
    - io2
    - gp2
    - gp3
    - st1
    - sc1
required:
- type

Permissions - ec2:ModifyVolumeAttribute

snapshot

Snapshot an EBS volume.

Tags may be optionally added to the snapshot during creation.

copy-volume-tags copies all the tags from the specified volume to the corresponding snapshot.
copy-tags copies the listed tags from each volume to the snapshot. This is mutually exclusive with copy-volume-tags.
tags allows new tags to be added to each snapshot. If no tags are specified, then the tag custodian_snapshot is added.

The default behavior is copy-volume-tags: true.

example:

policies:
  - name: snapshot-volumes
    resource: ebs
    filters:
      - Attachments: []
      - State: available
    actions:
      - type: snapshot
        copy-tags:
          - Name
        tags:
            custodian_snapshot: True

properties:
  copy-tags:
    items:
      type: string
    type: array
  copy-volume-tags:
    type: boolean
  description:
    type: string
  tags:
    type: object
  type:
    enum:
    - snapshot
required:
- type

Permissions - ec2:CreateSnapshot, ec2:CreateTags