aws.asg

Filters

capacity-delta

config-compliance

cost-optimization

event

finding

image

image-age

invalid

json-diff

launch-config

list-item

marked-for-op

metrics

network-location

not-encrypted

offhour

onhour

ops-item

progagated-tags

reduce

scaling-policy

security-group

subnet

tag-count

user-data

valid

value

vpc-id

capacity-delta

Filter returns ASG that have less instances than desired or required

example:

policies:
  - name: asg-capacity-delta
    resource: asg
    filters:
      - capacity-delta

properties:
  type:
    enum:
    - capacity-delta
required:
- type

image-age

Filter asg by image age (in days).

example:

policies:
  - name: asg-older-image
    resource: asg
    filters:
      - type: image-age
        days: 90
        op: ge

properties:
  days:
    type: number
  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:
    - image-age
required:
- type

Permissions - ec2:DescribeImages, autoscaling:DescribeLaunchConfigurations

invalid

Filter autoscale groups to find those that are structurally invalid.

Structurally invalid means that the auto scale group will not be able to launch an instance succesfully as the configuration has

invalid subnets
invalid security groups
invalid key pair name
invalid launch config volume snapshots
invalid amis
invalid health check elb (slower)

Internally this tries to reuse other resource managers for better cache utilization.

example:

policies:
  - name: asg-invalid-config
    resource: asg
    filters:
      - invalid

properties:
  type:
    enum:
    - invalid
required:
- type

Permissions - ec2:DescribeSubnets, ec2:DescribeSecurityGroups, ec2:DescribeKeyPairs, elasticloadbalancing:DescribeLoadBalancers, elasticloadbalancing:DescribeLoadBalancerAttributes, elasticloadbalancing:DescribeTags, elasticloadbalancing:DescribeTargetGroups, elasticloadbalancing:DescribeTags, ec2:DescribeSnapshots, ec2:DescribeImages

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

launch-config

Filter asg by launch config attributes.

This will also filter to launch template data in addition to launch configurations.

example:

policies:
  - name: launch-configs-with-public-address
    resource: asg
    filters:
      - type: launch-config
        key: AssociatePublicIpAddress
        value: true

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:
    - launch-config
  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 - autoscaling:DescribeLaunchConfigurations

not-encrypted

Check if an ASG is configured to have unencrypted volumes.

Checks both the ami snapshots and the launch configuration.

example:

policies:
  - name: asg-unencrypted
    resource: asg
    filters:
      - type: not-encrypted
        exclude_image: true

properties:
  exclude_image:
    type: boolean
  type:
    enum:
    - not-encrypted
required:
- type

Permissions - ec2:DescribeImages, ec2:DescribeSnapshots, autoscaling:DescribeLaunchConfigurations

progagated-tags

Filter ASG based on propagated tags

This filter is designed to find all autoscaling groups that have a list of tag keys (provided) that are set to propagate to new instances. Using this will allow for easy validation of asg tag sets are in place across an account for compliance.

example:

policies:
  - name: asg-non-propagated-tags
    resource: asg
    filters:
      - type: propagated-tags
        keys: ["ABC", "BCD"]
        match: false
        propagate: true

properties:
  keys:
    items:
      type: string
    type: array
  match:
    type: boolean
  propagate:
    type: boolean
  type:
    enum:
    - progagated-tags
    - propagated-tags
required:
- type

Permissions - autoscaling:DescribeLaunchConfigurations, autoscaling:DescribeAutoScalingGroups

scaling-policy

Filter asg by scaling-policies attributes.

example:

policies:
  - name: scaling-policies-with-target-tracking
    resource: asg
    filters:
      - type: scaling-policy
        key: PolicyType
        value: "TargetTrackingScaling"

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:
    - scaling-policy
  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 - autoscaling:DescribePolicies

user-data

Filter on ASG’s whose launch configs have matching userdata. Note: It is highly recommended to use regexes with the ?sm flags, since Custodian uses re.match() and userdata spans multiple lines.

example:

policies:
  - name: lc_userdata
    resource: asg
    filters:
      - type: user-data
        op: regex
        value: (?smi).*password=
    actions:
      - delete

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:
    - user-data
  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 - autoscaling:DescribeAutoScalingGroups, autoscaling:DescribeTags

valid

Filters autoscale groups to find those that are structurally valid.

This operates as the inverse of the invalid filter for multi-step workflows.

See details on the invalid filter for a list of checks made.

example:

policies:
  - name: asg-valid-config
    resource: asg
    filters:
     - valid

properties:
  type:
    enum:
    - valid
required:
- type

Permissions - ec2:DescribeSubnets, ec2:DescribeSecurityGroups, ec2:DescribeKeyPairs, elasticloadbalancing:DescribeLoadBalancers, elasticloadbalancing:DescribeLoadBalancerAttributes, elasticloadbalancing:DescribeTags, elasticloadbalancing:DescribeTargetGroups, elasticloadbalancing:DescribeTags, ec2:DescribeSnapshots, ec2:DescribeImages

vpc-id

Filters ASG based on the VpcId

This filter is available as a ValueFilter as the vpc-id is not natively associated to the results from describing the autoscaling groups.

example:

policies:
  - name: asg-vpc-xyz
    resource: asg
    filters:
      - type: vpc-id
        value: vpc-12ab34cd

properties:
  default:
    type: object
  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:
    - vpc-id
  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:DescribeSubnets

Actions

auto-tag-user

copy-related-tag

delete

invoke-lambda

invoke-sfn

mark-for-op

notify

post-finding

post-item

propagate-tags

put-metric

remove-tag

rename-tag

resize

resume

suspend

tag

tag-trim

update

webhook

auto-tag-user

Tag a resource with the user who created/modified it.

policies:
  - name: ec2-auto-tag-ownercontact
    resource: ec2
    description: |
      Triggered when a new EC2 Instance is launched. Checks to see if
      it's missing the OwnerContact tag. If missing it gets created
      with the value of the ID of whomever called the RunInstances API
    mode:
      type: cloudtrail
      role: arn:aws:iam::123456789000:role/custodian-auto-tagger
      events:
        - RunInstances
    filters:
     - tag:OwnerContact: absent
    actions:
     - type: auto-tag-user
       tag: OwnerContact

There’s a number of caveats to usage. Resources which don’t include tagging as part of their api may have some delay before automation kicks in to create a tag. Real world delay may be several minutes, with worst case into hours[0]. This creates a race condition between auto tagging and automation.

In practice this window is on the order of a fraction of a second, as we fetch the resource and evaluate the presence of the tag before attempting to tag it.

References

CloudTrail User https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html

properties:
  principal_id_tag:
    type: string
  propagate:
    type: boolean
  tag:
    type: string
  type:
    enum:
    - auto-tag-user
  update:
    type: boolean
  user-type:
    items:
      enum:
      - IAMUser
      - AssumedRole
      - FederatedUser
      type: string
    type: array
  value:
    enum:
    - userName
    - arn
    - sourceIPAddress
    - principalId
    type: string
required:
- type

Permissions - autoscaling:CreateOrUpdateTags

delete

Action to delete an ASG

The ‘force’ parameter is needed when deleting an ASG that has instances attached to it.

example:

policies:
  - name: asg-delete-bad-encryption
    resource: asg
    filters:
      - type: not-encrypted
        exclude_image: true
    actions:
      - type: delete
        force: true

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

Permissions - autoscaling:DeleteAutoScalingGroup

mark-for-op

Action to create a delayed action for a later date

example:

policies:
  - name: asg-suspend-schedule
    resource: asg
    filters:
      - type: value
        key: MinSize
        value: 2
    actions:
      - type: mark-for-op
        tag: custodian_suspend
        message: "Suspending: {op}@{action_date}"
        op: suspend
        days: 7

properties:
  days:
    minimum: 0
    type: number
  hours:
    minimum: 0
    type: number
  key:
    type: string
  message:
    type: string
  msg:
    type: string
  op:
    type: string
  tag:
    type: string
  type:
    enum:
    - mark-for-op
  tz:
    type: string
required:
- type

Permissions - autoscaling:CreateOrUpdateTags

propagate-tags

Propagate tags to an asg instances.

In AWS changing an asg tag does not automatically propagate to extant instances even if the tag is set to propagate. It only is applied to new instances.

This action exists to ensure that extant instances also have these propagated tags set, and can also trim older tags not present on the asg anymore that are present on instances.

example:

policies:
  - name: asg-propagate-required
    resource: asg
    filters:
      - "tag:OwnerName": present
    actions:
      - type: propagate-tags
        tags:
          - OwnerName

properties:
  tags:
    items:
      type: string
    type: array
  trim:
    type: boolean
  type:
    enum:
    - propagate-tags
required:
- type

Permissions - ec2:DeleteTags, ec2:CreateTags

remove-tag

Action to remove tag/tags from an ASG

example:

policies:
  - name: asg-remove-unnecessary-tags
    resource: asg
    filters:
      - "tag:UnnecessaryTag": present
    actions:
      - type: remove-tag
        key: UnnecessaryTag

properties:
  key:
    type: string
  tags:
    items:
      type: string
    type: array
  type:
    enum:
    - remove-tag
    - untag
    - unmark
required:
- type

Permissions - autoscaling:DeleteTags

rename-tag

Rename a tag on an AutoScaleGroup.

example:

policies:
  - name: asg-rename-owner-tag
    resource: asg
    filters:
      - "tag:OwnerNames": present
    actions:
      - type: rename-tag
        propagate: true
        source: OwnerNames
        dest: OwnerName

properties:
  dest:
    type: string
  propagate:
    type: boolean
  source:
    type: string
  type:
    enum:
    - rename-tag
required:
- source
- dest
- type

Permissions - autoscaling:CreateOrUpdateTags, autoscaling:DeleteTags, ec2:CreateTags, ec2:DeleteTags

resize

Action to resize the min/max/desired instances in an ASG

There are several ways to use this action:

set min/desired to current running instances

policies:
  - name: asg-resize
    resource: asg
    filters:
      - capacity-delta
    actions:
      - type: resize
        desired-size: "current"

apply a fixed resize of min, max or desired, optionally saving the previous values to a named tag (for restoring later):

policies:
  - name: offhours-asg-off
    resource: asg
    filters:
      - type: offhour
        offhour: 19
        default_tz: bst
    actions:
      - type: resize
        min-size: 0
        desired-size: 0
        save-options-tag: OffHoursPrevious

restore previous values for min/max/desired from a tag:

policies:
  - name: offhours-asg-on
    resource: asg
    filters:
      - type: onhour
        onhour: 8
        default_tz: bst
    actions:
      - type: resize
        restore-options-tag: OffHoursPrevious

properties:
  desired-size:
    anyOf:
    - enum:
      - current
    - minimum: 0
      type: integer
  desired_size:
    anyOf:
    - enum:
      - current
    - minimum: 0
      type: integer
  max-size:
    minimum: 0
    type: integer
  min-size:
    minimum: 0
    type: integer
  restore-options-tag:
    type: string
  save-options-tag:
    type: string
  type:
    enum:
    - resize
required:
- type

Permissions - autoscaling:UpdateAutoScalingGroup, autoscaling:CreateOrUpdateTags

resume

Resume a suspended autoscale group and its instances

Parameter ‘delay’ is the amount of time (in seconds) to wait between resuming instances in the asg, and restarting the internal asg processed which gives some grace period before health checks turn on within the ASG (default value: 30)

example:

policies:
  - name: asg-resume-processes
    resource: asg
    filters:
      - "tag:Resume": present
    actions:
      - type: resume
        delay: 300

properties:
  delay:
    type: number
  exclude:
    items:
      enum:
      - Launch
      - Terminate
      - HealthCheck
      - ReplaceUnhealthy
      - AlarmNotification
      - ScheduledActions
      - AZRebalance
      - InstanceRefresh
      - AddToLoadBalancer
    title: ASG Processes to not resume
    type: array
  type:
    enum:
    - resume
required:
- type

Permissions - autoscaling:ResumeProcesses, ec2:StartInstances

suspend

Action to suspend ASG processes and instances

AWS ASG suspend/resume and process docs: https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-suspend-resume-processes.html

example:

policies:
  - name: asg-suspend-processes
    resource: asg
    filters:
      - "tag:SuspendTag": present
    actions:
      - type: suspend

properties:
  exclude:
    items:
      enum:
      - Launch
      - Terminate
      - HealthCheck
      - ReplaceUnhealthy
      - AZRebalance
      - AlarmNotification
      - ScheduledActions
      - AddToLoadBalancer
      - InstanceRefresh
    title: ASG Processes to not suspend
    type: array
  type:
    enum:
    - suspend
required:
- type

Permissions - autoscaling:SuspendProcesses, ec2:StopInstances

tag

Action to add a tag to an ASG

The propagate parameter can be used to specify that the tag being added will need to be propagated down to each ASG instance associated or simply to the ASG itself.

example:

policies:
  - name: asg-add-owner-tag
    resource: asg
    filters:
      - "tag:OwnerName": absent
    actions:
      - type: tag
        key: OwnerName
        value: OwnerName
        propagate: true

properties:
  key:
    type: string
  msg:
    type: string
  propagate:
    type: boolean
  tag:
    type: string
  tags:
    type: object
  type:
    enum:
    - tag
    - mark
  value:
    type: string
required:
- type

Permissions - autoscaling:CreateOrUpdateTags

update

Action to update ASG configuration settings

example:

policies:
  - name: set-asg-instance-lifetime
    resource: asg
    filters:
      - MaxInstanceLifetime: empty
    actions:
      - type: update
        max-instance-lifetime: 604800  # (7 days)

  - name: set-asg-by-policy
    resource: asg
    actions:
      - type: update
        default-cooldown: 600
        max-instance-lifetime: 0      # (clear it)
        new-instances-protected-from-scale-in: true
        capacity-rebalance: true

properties:
  capacity-rebalance:
    type: boolean
  default-cooldown:
    minimum: 0
    type: integer
  max-instance-lifetime:
    anyOf:
    - enum:
      - 0
    - minimum: 86400
      type: integer
  new-instances-protected-from-scale-in:
    type: boolean
  type:
    enum:
    - update
required:
- type

Permissions - autoscaling:UpdateAutoScalingGroup