Try SpotterCreate or delete AWS AutoScaling Groups (ASGs)
| "added in version" 1.0.0 of community.aws"
Authors: Gareth Rushgrove (@garethr)
Install with ansible-galaxy collection install community.aws:==4.3.0
collections:
- name: community.aws
version: 4.3.0Can create or delete AWS AutoScaling Groups.
Can be used with the M(community.aws.ec2_lc) module to manage Launch Configurations.
# Basic configuration with Launch Configuration
- community.aws.ec2_asg:
name: special
load_balancers: [ 'lb1', 'lb2' ]
availability_zones: [ 'eu-west-1a', 'eu-west-1b' ]
launch_config_name: 'lc-1'
min_size: 1
max_size: 10
desired_capacity: 5
vpc_zone_identifier: [ 'subnet-abcd1234', 'subnet-1a2b3c4d' ]
tags:
- environment: production
propagate_at_launch: no
# Rolling ASG Updates
# Below is an example of how to assign a new launch config to an ASG and terminate old instances.
#
# All instances in "myasg" that do not have the launch configuration named "my_new_lc" will be terminated in
# a rolling fashion with instances using the current launch configuration, "my_new_lc".
#
# This could also be considered a rolling deploy of a pre-baked AMI.
#
# If this is a newly created group, the instances will not be replaced since all instances
# will have the current launch configuration.
- name: create launch config
community.aws.ec2_lc:
name: my_new_lc
image_id: ami-lkajsf
key_name: mykey
region: us-east-1
security_groups: sg-23423
instance_type: m1.small
assign_public_ip: yes
- community.aws.ec2_asg:
name: myasg
launch_config_name: my_new_lc
health_check_period: 60
health_check_type: ELB
replace_all_instances: yes
min_size: 5
max_size: 5
desired_capacity: 5
region: us-east-1
# To only replace a couple of instances instead of all of them, supply a list
# to "replace_instances":
- community.aws.ec2_asg:
name: myasg
launch_config_name: my_new_lc
health_check_period: 60
health_check_type: ELB
replace_instances:
- i-b345231
- i-24c2931
min_size: 5
max_size: 5
desired_capacity: 5
region: us-east-1
# Basic Configuration with Launch Template
- community.aws.ec2_asg:
name: special
load_balancers: [ 'lb1', 'lb2' ]
availability_zones: [ 'eu-west-1a', 'eu-west-1b' ]
launch_template:
version: '1'
launch_template_name: 'lt-example'
launch_template_id: 'lt-123456'
min_size: 1
max_size: 10
desired_capacity: 5
vpc_zone_identifier: [ 'subnet-abcd1234', 'subnet-1a2b3c4d' ]
tags:
- environment: production
propagate_at_launch: no
# Basic Configuration with Launch Template using mixed instance policy
- community.aws.ec2_asg:
name: special
load_balancers: [ 'lb1', 'lb2' ]
availability_zones: [ 'eu-west-1a', 'eu-west-1b' ]
launch_template:
version: '1'
launch_template_name: 'lt-example'
launch_template_id: 'lt-123456'
mixed_instances_policy:
instance_types:
- t3a.large
- t3.large
- t2.large
instances_distribution:
on_demand_percentage_above_base_capacity: 0
spot_allocation_strategy: capacity-optimized
min_size: 1
max_size: 10
desired_capacity: 5
vpc_zone_identifier: [ 'subnet-abcd1234', 'subnet-1a2b3c4d' ]
tags:
- environment: production
propagate_at_launch: no
name:
description:
- Unique name for group to be created or deleted.
required: true
type: str
tags:
description:
- A list of tags to add to the Auto Scale Group.
- Optional key is I(propagate_at_launch), which defaults to true.
- When I(propagate_at_launch) is true the tags will be propagated to the Instances
created.
elements: dict
type: list
state:
choices:
- present
- absent
default: present
description:
- Register or deregister the instance.
type: str
region:
aliases:
- aws_region
- ec2_region
description:
- The AWS region to use. If not specified then the value of the AWS_REGION or EC2_REGION
environment variable, if any, is used. See U(http://docs.aws.amazon.com/general/latest/gr/rande.html#ec2_region)
type: str
ec2_url:
aliases:
- aws_endpoint_url
- endpoint_url
description:
- Url to use to connect to EC2 or your Eucalyptus cloud (by default the module will
use EC2 endpoints). Ignored for modules where region is required. Must be specified
for all other modules if region is not used. If not set then the value of the EC2_URL
environment variable, if any, is used.
type: str
profile:
aliases:
- aws_profile
description:
- Uses a boto profile. Only works with boto >= 2.24.0.
- Using I(profile) will override I(aws_access_key), I(aws_secret_key) and I(security_token)
and support for passing them at the same time as I(profile) has been deprecated.
- I(aws_access_key), I(aws_secret_key) and I(security_token) will be made mutually
exclusive with I(profile) after 2022-06-01.
type: str
lc_check:
default: true
description:
- Check to make sure instances that are being replaced with I(replace_instances) do
not already have the current I(launch_config).
type: bool
lt_check:
default: true
description:
- Check to make sure instances that are being replaced with I(replace_instances) do
not already have the current I(launch_template or I(launch_template) I(version).
type: bool
max_size:
description:
- Maximum number of instances in group, if unspecified then the current group value
will be used.
type: int
min_size:
description:
- Minimum number of instances in group, if unspecified then the current group value
will be used.
type: int
aws_config:
description:
- A dictionary to modify the botocore configuration.
- Parameters can be found at U(https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html#botocore.config.Config).
- Only the 'user_agent' key is used for boto modules. See U(http://boto.cloudhackers.com/en/latest/boto_config_tut.html#boto)
for more boto configuration.
type: dict
purge_tags:
default: false
description:
- If C(true), existing tags will be purged from the resource to match exactly what
is defined by I(tags) parameter.
- If the I(tags) parameter is not set then tags will not be modified.
type: bool
version_added: 3.2.0
version_added_collection: community.aws
metrics_list:
default:
- GroupMinSize
- GroupMaxSize
- GroupDesiredCapacity
- GroupInServiceInstances
- GroupPendingInstances
- GroupStandbyInstances
- GroupTerminatingInstances
- GroupTotalInstances
description:
- List of autoscaling metrics to collect when I(metrics_collection=true).
elements: str
type: list
wait_timeout:
default: 300
description:
- How long to wait for instances to become viable when replaced. If you experience
the error "Waited too long for ELB instances to be healthy", try increasing this
value.
type: int
aws_ca_bundle:
description:
- The location of a CA Bundle to use when validating SSL certificates.
- Only used for boto3 based modules.
- 'Note: The CA Bundle is read ''module'' side and may need to be explicitly copied
from the controller if not run locally.'
type: path
aws_access_key:
aliases:
- ec2_access_key
- access_key
description:
- AWS access key. If not set then the value of the AWS_ACCESS_KEY_ID, AWS_ACCESS_KEY
or EC2_ACCESS_KEY environment variable is used.
- If I(profile) is set this parameter is ignored.
- Passing the I(aws_access_key) and I(profile) options at the same time has been deprecated
and the options will be made mutually exclusive after 2022-06-01.
type: str
aws_secret_key:
aliases:
- ec2_secret_key
- secret_key
description:
- AWS secret key. If not set then the value of the AWS_SECRET_ACCESS_KEY, AWS_SECRET_KEY,
or EC2_SECRET_KEY environment variable is used.
- If I(profile) is set this parameter is ignored.
- Passing the I(aws_secret_key) and I(profile) options at the same time has been deprecated
and the options will be made mutually exclusive after 2022-06-01.
type: str
load_balancers:
description:
- List of ELB names to use for the group. Use for classic load balancers.
elements: str
type: list
security_token:
aliases:
- aws_security_token
- access_token
description:
- AWS STS security token. If not set then the value of the AWS_SECURITY_TOKEN or EC2_SECURITY_TOKEN
environment variable is used.
- If I(profile) is set this parameter is ignored.
- Passing the I(security_token) and I(profile) options at the same time has been deprecated
and the options will be made mutually exclusive after 2022-06-01.
type: str
validate_certs:
default: true
description:
- When set to "no", SSL certificates will not be validated for boto versions >= 2.6.0.
type: bool
launch_template:
description:
- Dictionary describing the Launch Template to use
suboptions:
launch_template_id:
description:
- The id of the launch template. Only one of I(launch_template_name) or I(launch_template_id)
is required.
type: str
launch_template_name:
description:
- The name of the launch template. Only one of I(launch_template_name) or I(launch_template_id)
is required.
type: str
version:
description:
- The version number of the launch template to use.
- Defaults to latest version if not provided.
type: str
type: dict
placement_group:
description:
- Physical location of your cluster placement group created in Amazon EC2.
type: str
default_cooldown:
default: 300
description:
- The number of seconds after a scaling activity completes before another can begin.
type: int
desired_capacity:
description:
- Desired number of instances in group, if unspecified then the current group value
will be used.
type: int
detach_instances:
description:
- Removes one or more instances from the specified AutoScalingGroup.
- If I(decrement_desired_capacity) flag is not set, new instance(s) are launched to
replace the detached instance(s).
- If a Classic Load Balancer is attached to the AutoScalingGroup, the instances are
also deregistered from the load balancer.
- If there are target groups attached to the AutoScalingGroup, the instances are also
deregistered from the target groups.
elements: str
type: list
version_added: 3.2.0
version_added_collection: community.aws
health_check_type:
choices:
- EC2
- ELB
default: EC2
description:
- The service you want the health status from, Amazon EC2 or Elastic Load Balancer.
required: false
type: str
replace_instances:
description:
- List of I(instance_ids) belonging to the named AutoScalingGroup that you would like
to terminate and be replaced with instances matching the current launch configuration.
elements: str
type: list
suspend_processes:
default: []
description:
- A list of scaling processes to suspend.
- 'Valid values include:'
- C(Launch), C(Terminate), C(HealthCheck), C(ReplaceUnhealthy), C(AZRebalance), C(AlarmNotification),
C(ScheduledActions), C(AddToLoadBalancer)
- 'Full documentation of valid values can be found in the AWS documentation:'
- U(https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-suspend-resume-processes.html)
elements: str
type: list
target_group_arns:
description:
- List of target group ARNs to use for the group. Use for application load balancers.
elements: str
type: list
availability_zones:
description:
- List of availability zone names in which to create the group.
- Defaults to all the availability zones in the region if I(vpc_zone_identifier) is
not set.
elements: str
type: list
launch_config_name:
description:
- Name of the Launch configuration to use for the group. See the community.aws.ec2_lc)
module for managing these.
- If unspecified then the current group value will be used. One of I(launch_config_name)
or I(launch_template) must be provided.
type: str
metrics_collection:
default: false
description:
- Enable ASG metrics collection.
type: bool
notification_topic:
description:
- A SNS topic ARN to send auto scaling notifications to.
type: str
notification_types:
default:
- autoscaling:EC2_INSTANCE_LAUNCH
- autoscaling:EC2_INSTANCE_LAUNCH_ERROR
- autoscaling:EC2_INSTANCE_TERMINATE
- autoscaling:EC2_INSTANCE_TERMINATE_ERROR
description:
- A list of auto scaling events to trigger notifications on.
elements: str
required: false
type: list
replace_batch_size:
default: 1
description:
- Number of instances you'd like to replace at a time. Used with I(replace_all_instances).
required: false
type: int
wait_for_instances:
default: true
description:
- Wait for the ASG instances to be in a ready state before exiting. If instances
are behind an ELB, it will wait until the ELB determines all instances have a lifecycle_state
of "InService" and a health_status of "Healthy".
type: bool
health_check_period:
default: 300
description:
- Length of time in seconds after a new EC2 instance comes into service that Auto
Scaling starts checking its health.
required: false
type: int
metrics_granularity:
default: 1Minute
description:
- When I(metrics_collection=true) this will determine the granularity of metrics collected
by CloudWatch.
type: str
vpc_zone_identifier:
description:
- List of VPC subnets to use
elements: str
type: list
termination_policies:
default: Default
description:
- An ordered list of criteria used for selecting instances to be removed from the
Auto Scaling group when reducing capacity.
- Using I(termination_policies=Default) when modifying an existing AutoScalingGroup
will result in the existing policy being retained instead of changed to C(Default).
- 'Valid values include: C(Default), C(OldestInstance), C(NewestInstance), C(OldestLaunchConfiguration),
C(ClosestToNextInstanceHour)'
- 'Full documentation of valid values can be found in the AWS documentation:'
- U(https://docs.aws.amazon.com/autoscaling/ec2/userguide/as-instance-termination.html#custom-termination-policy)
elements: str
type: list
max_instance_lifetime:
description:
- The maximum amount of time, in seconds, that an instance can be in service.
- Maximum instance lifetime must be equal to 0, between 604800 and 31536000 seconds
(inclusive), or not specified.
- Value of 0 removes lifetime restriction.
type: int
replace_all_instances:
default: false
description:
- In a rolling fashion, replace all instances that used the old launch configuration
with one from the new launch configuration. It increases the ASG size by I(replace_batch_size),
waits for the new instances to be up and running. After that, it terminates a batch
of old instances, waits for the replacements, and repeats, until all old instances
are replaced. Once that's done the ASG size is reduced back to the expected size.
type: bool
mixed_instances_policy:
description:
- A mixed instance policy to use for the ASG.
- Only used when the ASG is configured to use a Launch Template (I(launch_template)).
- See also U(https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-autoscaling-autoscalinggroup-mixedinstancespolicy.html)
required: false
suboptions:
instance_types:
description:
- A list of instance_types.
elements: str
required: false
type: list
instances_distribution:
description:
- Specifies the distribution of On-Demand Instances and Spot Instances, the maximum
price to pay for Spot Instances, and how the Auto Scaling group allocates instance
types to fulfill On-Demand and Spot capacity.
- See also U(https://docs.aws.amazon.com/autoscaling/ec2/APIReference/API_InstancesDistribution.html)
required: false
suboptions:
on_demand_allocation_strategy:
description:
- Indicates how to allocate instance types to fulfill On-Demand capacity.
required: false
type: str
version_added: 1.5.0
version_added_collection: community.aws
on_demand_base_capacity:
description:
- The minimum amount of the Auto Scaling group's capacity that must be fulfilled
by On-Demand Instances. This base portion is provisioned first as your group
scales.
- Default if not set is 0. If you leave it set to 0, On-Demand Instances are
launched as a percentage of the Auto Scaling group's desired capacity, per
the OnDemandPercentageAboveBaseCapacity setting.
required: false
type: int
version_added: 1.5.0
version_added_collection: community.aws
on_demand_percentage_above_base_capacity:
description:
- Controls the percentages of On-Demand Instances and Spot Instances for your
additional capacity beyond OnDemandBaseCapacity.
- Default if not set is 100. If you leave it set to 100, the percentages are
100% for On-Demand Instances and 0% for Spot Instances.
- 'Valid range: 0 to 100'
required: false
type: int
version_added: 1.5.0
version_added_collection: community.aws
spot_allocation_strategy:
description:
- Indicates how to allocate instances across Spot Instance pools.
required: false
type: str
version_added: 1.5.0
version_added_collection: community.aws
spot_instance_pools:
description:
- The number of Spot Instance pools across which to allocate your Spot Instances.
The Spot pools are determined from the different instance types in the Overrides
array of LaunchTemplate. Default if not set is 2.
- Used only when the Spot allocation strategy is lowest-price.
- 'Valid Range: Minimum value of 1. Maximum value of 20.'
required: false
type: int
version_added: 1.5.0
version_added_collection: community.aws
spot_max_price:
description:
- The maximum price per unit hour that you are willing to pay for a Spot Instance.
- If you leave the value of this parameter blank (which is the default), the
maximum Spot price is set at the On-Demand price.
- To remove a value that you previously set, include the parameter but leave
the value blank.
required: false
type: str
version_added: 1.5.0
version_added_collection: community.aws
type: dict
version_added: 1.5.0
version_added_collection: community.aws
type: dict
decrement_desired_capacity:
default: false
description:
- Indicates whether the AutoScalingGroup decrements the desired capacity value by
the number of instances detached.
type: bool
version_added: 3.2.0
version_added_collection: community.aws
debug_botocore_endpoint_logs:
default: 'no'
description:
- Use a botocore.endpoint logger to parse the unique (rather than total) "resource:action"
API calls made during a task, outputing the set to the resource_actions key in the
task results. Use the aws_resource_action callback to output to total list made
during a playbook. The ANSIBLE_DEBUG_BOTOCORE_LOGS environment variable may also
be used.
type: bool
auto_scaling_group_arn:
description: The unique ARN of the autoscaling group
returned: success
sample: arn:aws:autoscaling:us-east-1:123456789012:autoScalingGroup:6a09ad6d-eeee-1234-b987-ee123ced01ad:autoScalingGroupName/myasg
type: str
auto_scaling_group_name:
description: The unique name of the auto scaling group
returned: success
sample: myasg
type: str
availability_zones:
description: The availability zones for the auto scaling group
returned: success
sample:
- us-east-1d
type: list
created_time:
description: Timestamp of create time of the auto scaling group
returned: success
sample: '2017-11-08T14:41:48.272000+00:00'
type: str
default_cooldown:
description: The default cooldown time in seconds.
returned: success
sample: 300
type: int
desired_capacity:
description: The number of EC2 instances that should be running in this group.
returned: success
sample: 3
type: int
healthcheck_period:
description: Length of time in seconds after a new EC2 instance comes into service
that Auto Scaling starts checking its health.
returned: success
sample: 30
type: int
healthcheck_type:
description: The service you want the health status from, one of "EC2" or "ELB".
returned: success
sample: ELB
type: str
healthy_instances:
description: Number of instances in a healthy state
returned: success
sample: 5
type: int
in_service_instances:
description: Number of instances in service
returned: success
sample: 3
type: int
instance_facts:
description: Dictionary of EC2 instances and their status as it relates to the ASG.
returned: success
sample:
i-0123456789012:
health_status: Healthy
launch_config_name: public-webapp-production-1
lifecycle_state: InService
type: dict
instances:
description: list of instance IDs in the ASG
returned: success
sample:
- i-0123456789012
type: list
launch_config_name:
description: 'Name of launch configuration associated with the ASG. Same as launch_configuration_name,
provided for compatibility with ec2_asg module.
'
returned: success
sample: public-webapp-production-1
type: str
load_balancers:
description: List of load balancers names attached to the ASG.
returned: success
sample:
- elb-webapp-prod
type: list
max_instance_lifetime:
description: The maximum amount of time, in seconds, that an instance can be in
service.
returned: success
sample: 604800
type: int
max_size:
description: Maximum size of group
returned: success
sample: 3
type: int
metrics_collection:
description: List of enabled AutosSalingGroup metrics
returned: success
sample:
- Granularity: 1Minute
Metric: GroupInServiceInstances
type: list
min_size:
description: Minimum size of group
returned: success
sample: 1
type: int
mixed_instances_policy:
description: Returns the list of instance types if a mixed instances policy is set.
returned: success
sample:
- t3.micro
- t3a.micro
type: list
mixed_instances_policy_full:
description: Returns the full dictionary representation of the mixed instances policy
if a mixed instances policy is set.
returned: success
sample:
instances_distribution:
on_demand_allocation_strategy: prioritized
on_demand_base_capacity: 0
on_demand_percentage_above_base_capacity: 0
spot_allocation_strategy: capacity-optimized
launch_template:
launch_template_specification:
launch_template_id: lt-53c2425cffa544c23
launch_template_name: random-LaunchTemplate
version: '2'
overrides:
- instance_type: m5.xlarge
- instance_type: m5a.xlarge
type: dict
pending_instances:
description: Number of instances in pending state
returned: success
sample: 1
type: int
tags:
description: List of tags for the ASG, and whether or not each tag propagates to
instances at launch.
returned: success
sample:
- key: Name
propagate_at_launch: 'true'
resource_id: public-webapp-production-1
resource_type: auto-scaling-group
value: public-webapp-production-1
- key: env
propagate_at_launch: 'true'
resource_id: public-webapp-production-1
resource_type: auto-scaling-group
value: production
type: list
target_group_arns:
description: List of ARNs of the target groups that the ASG populates
returned: success
sample:
- arn:aws:elasticloadbalancing:ap-southeast-2:123456789012:targetgroup/target-group-host-hello/1a2b3c4d5e6f1a2b
- arn:aws:elasticloadbalancing:ap-southeast-2:123456789012:targetgroup/target-group-path-world/abcd1234abcd1234
type: list
target_group_names:
description: List of names of the target groups that the ASG populates
returned: success
sample:
- target-group-host-hello
- target-group-path-world
type: list
termination_policies:
description: A list of termination policies for the group.
returned: success
sample:
- Default
type: list
unhealthy_instances:
description: Number of instances in an unhealthy state
returned: success
sample: 0
type: int
viable_instances:
description: Number of instances in a viable state
returned: success
sample: 1
type: int
vpc_zone_identifier:
description: VPC zone ID / subnet id for the auto scaling group
returned: success
sample: subnet-a31ef45f
type: str