aws.ebs

Filters

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

See modify action for examples.

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

Permissions - ec2:DescribeInstances

Actions

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