Note

You are viewing the documentation for an older version of boto (boto2).

Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.

For more information, see the documentation for boto3.

Auto Scaling Reference

boto.ec2.autoscale

This module provides an interface to the Elastic Compute Cloud (EC2) Auto Scaling service.

class boto.ec2.autoscale.AutoScaleConnection(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, proxy_user=None, proxy_pass=None, debug=0, https_connection_factory=None, region=None, path='/', security_token=None, validate_certs=True, profile_name=None, use_block_device_types=False)

Init method to create a new connection to the AutoScaling service.

B{Note:} The host argument is overridden by the host specified in the
boto configuration file.
APIVersion = '2011-01-01'
DefaultRegionEndpoint = 'autoscaling.us-east-1.amazonaws.com'
DefaultRegionName = 'us-east-1'
attach_instances(name, instance_ids)

Attach instances to an autoscaling group.

build_list_params(params, items, label)

Items is a list of dictionaries or strings:

[
    {
        'Protocol' : 'HTTP',
        'LoadBalancerPort' : '80',
        'InstancePort' : '80'
    },
    ..
] etc.

or:

['us-east-1b',...]
create_auto_scaling_group(as_group)

Create auto scaling group.

create_launch_configuration(launch_config)

Creates a new Launch Configuration.

Parameters:launch_config (boto.ec2.autoscale.launchconfig.LaunchConfiguration) – LaunchConfiguration object.
create_or_update_tags(tags)

Creates new tags or updates existing tags for an Auto Scaling group.

Parameters:tags (List of boto.ec2.autoscale.tag.Tag) – The new or updated tags.
create_scaling_policy(scaling_policy)

Creates a new Scaling Policy.

Parameters:scaling_policy (boto.ec2.autoscale.policy.ScalingPolicy) – ScalingPolicy object.
create_scheduled_group_action(as_group, name, time=None, desired_capacity=None, min_size=None, max_size=None, start_time=None, end_time=None, recurrence=None)

Creates a scheduled scaling action for a Auto Scaling group. If you leave a parameter unspecified, the corresponding value remains unchanged in the affected Auto Scaling group.

Parameters:
  • as_group (string) – The auto scaling group to get activities on.
  • name (string) – Scheduled action name.
  • time (datetime.datetime) – The time for this action to start. (Depracated)
  • desired_capacity (int) – The number of EC2 instances that should be running in this group.
  • min_size (int) – The minimum size for the new auto scaling group.
  • max_size (int) – The minimum size for the new auto scaling group.
  • start_time (datetime.datetime) – The time for this action to start. When StartTime and EndTime are specified with Recurrence, they form the boundaries of when the recurring action will start and stop.
  • end_time (datetime.datetime) – The time for this action to end. When StartTime and EndTime are specified with Recurrence, they form the boundaries of when the recurring action will start and stop.
  • recurrence (string) – The time when recurring future actions will start. Start time is specified by the user following the Unix cron syntax format. EXAMPLE: ‘0 10 * * *
delete_auto_scaling_group(name, force_delete=False)

Deletes the specified auto scaling group if the group has no instances and no scaling activities in progress.

delete_launch_configuration(launch_config_name)

Deletes the specified LaunchConfiguration.

The specified launch configuration must not be attached to an Auto Scaling group. Once this call completes, the launch configuration is no longer available for use.

delete_notification_configuration(autoscale_group, topic)

Deletes notifications created by put_notification_configuration.

Parameters:
  • autoscale_group (str or boto.ec2.autoscale.group.AutoScalingGroup object) – The Auto Scaling group to put notification configuration on.
  • topic (str) – The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic.
delete_policy(policy_name, autoscale_group=None)

Delete a policy.

Parameters:
  • policy_name (str) – The name or ARN of the policy to delete.
  • autoscale_group (str) – The name of the autoscale group.
delete_scheduled_action(scheduled_action_name, autoscale_group=None)

Deletes a previously scheduled action.

Parameters:
  • scheduled_action_name (str) – The name of the action you want to delete.
  • autoscale_group (str) – The name of the autoscale group.
delete_tags(tags)

Deletes existing tags for an Auto Scaling group.

Parameters:tags (List of boto.ec2.autoscale.tag.Tag) – The new or updated tags.
detach_instances(name, instance_ids, decrement_capacity=True)

Detach instances from an Auto Scaling group.

Parameters:
  • name (str) – The name of the Auto Scaling group from which to detach instances.
  • instance_ids (list) – Instance ids to be detached from the Auto Scaling group.
  • decrement_capacity (bool) – Whether to decrement the size of the Auto Scaling group or not.
disable_metrics_collection(as_group, metrics=None)

Disables monitoring of group metrics for the Auto Scaling group specified in AutoScalingGroupName. You can specify the list of affected metrics with the Metrics parameter.

enable_metrics_collection(as_group, granularity, metrics=None)

Enables monitoring of group metrics for the Auto Scaling group specified in AutoScalingGroupName. You can specify the list of enabled metrics with the Metrics parameter.

Auto scaling metrics collection can be turned on only if the InstanceMonitoring.Enabled flag, in the Auto Scaling group’s launch configuration, is set to true.

Parameters:
  • autoscale_group (string) – The auto scaling group to get activities on.
  • granularity (string) – The granularity to associate with the metrics to collect. Currently, the only legal granularity is “1Minute”.
  • metrics (string list) – The list of metrics to collect. If no metrics are specified, all metrics are enabled.
execute_policy(policy_name, as_group=None, honor_cooldown=None)
get_account_limits()

Returns the limits for the Auto Scaling resources currently granted for your AWS account.

get_all_activities(autoscale_group, activity_ids=None, max_records=None, next_token=None)

Get all activities for the given autoscaling group.

This action supports pagination by returning a token if there are more pages to retrieve. To get the next page, call this action again with the returned token as the NextToken parameter

Parameters:
Return type:

list

Returns:

List of boto.ec2.autoscale.activity.Activity instances.

get_all_adjustment_types()
get_all_autoscaling_instances(instance_ids=None, max_records=None, next_token=None)

Returns a description of each Auto Scaling instance in the instance_ids list. If a list is not provided, the service returns the full details of all instances up to a maximum of fifty.

This action supports pagination by returning a token if there are more pages to retrieve. To get the next page, call this action again with the returned token as the NextToken parameter.

Parameters:
  • instance_ids (list) – List of Autoscaling Instance IDs which should be searched for.
  • max_records (int) – Maximum number of results to return.
Return type:

list

Returns:

List of boto.ec2.autoscale.instance.Instance objects.

get_all_groups(names=None, max_records=None, next_token=None)

Returns a full description of each Auto Scaling group in the given list. This includes all Amazon EC2 instances that are members of the group. If a list of names is not provided, the service returns the full details of all Auto Scaling groups.

This action supports pagination by returning a token if there are more pages to retrieve. To get the next page, call this action again with the returned token as the NextToken parameter.

Parameters:
  • names (list) – List of group names which should be searched for.
  • max_records (int) – Maximum amount of groups to return.
Return type:

list

Returns:

List of boto.ec2.autoscale.group.AutoScalingGroup instances.

get_all_launch_configurations(**kwargs)

Returns a full description of the launch configurations given the specified names.

If no names are specified, then the full details of all launch configurations are returned.

Parameters:
  • names (list) – List of configuration names which should be searched for.
  • max_records (int) – Maximum amount of configurations to return.
  • next_token (str) – If you have more results than can be returned at once, pass in this parameter to page through all results.
Return type:

list

Returns:

List of boto.ec2.autoscale.launchconfig.LaunchConfiguration instances.

get_all_metric_collection_types()

Returns a list of metrics and a corresponding list of granularities for each metric.

get_all_policies(as_group=None, policy_names=None, max_records=None, next_token=None)

Returns descriptions of what each policy does. This action supports pagination. If the response includes a token, there are more records available. To get the additional records, repeat the request with the response token as the NextToken parameter.

If no group name or list of policy names are provided, all available policies are returned.

Parameters:
  • as_group (str) – The name of the boto.ec2.autoscale.group.AutoScalingGroup to filter for.
  • policy_names (list) – List of policy names which should be searched for.
  • max_records (int) – Maximum amount of groups to return.
  • next_token (str) – If you have more results than can be returned at once, pass in this parameter to page through all results.
get_all_scaling_process_types()

Returns scaling process types for use in the ResumeProcesses and SuspendProcesses actions.

get_all_scheduled_actions(as_group=None, start_time=None, end_time=None, scheduled_actions=None, max_records=None, next_token=None)
get_all_tags(filters=None, max_records=None, next_token=None)

Lists the Auto Scaling group tags.

This action supports pagination by returning a token if there are more pages to retrieve. To get the next page, call this action again with the returned token as the NextToken parameter.

Parameters:
  • filters (dict) – The value of the filter type used to identify the tags to be returned. NOT IMPLEMENTED YET.
  • max_records (int) – Maximum number of tags to return.
Return type:

list

Returns:

List of boto.ec2.autoscale.tag.Tag instances.

get_termination_policies()

Gets all valid termination policies.

These values can then be used as the termination_policies arg when creating and updating autoscale groups.

put_notification_configuration(autoscale_group, topic, notification_types)

Configures an Auto Scaling group to send notifications when specified events take place.

Parameters:
  • autoscale_group (str or boto.ec2.autoscale.group.AutoScalingGroup object) – The Auto Scaling group to put notification configuration on.
  • topic (str) – The Amazon Resource Name (ARN) of the Amazon Simple Notification Service (SNS) topic.
  • notification_types (list) – The type of events that will trigger the notification. Valid types are: ‘autoscaling:EC2_INSTANCE_LAUNCH’, ‘autoscaling:EC2_INSTANCE_LAUNCH_ERROR’, ‘autoscaling:EC2_INSTANCE_TERMINATE’, ‘autoscaling:EC2_INSTANCE_TERMINATE_ERROR’, ‘autoscaling:TEST_NOTIFICATION’
resume_processes(as_group, scaling_processes=None)

Resumes Auto Scaling processes for an Auto Scaling group.

Parameters:
  • as_group (string) – The auto scaling group to resume processes on.
  • scaling_processes (list) – Processes you want to resume. If omitted, all processes will be resumed.
set_desired_capacity(group_name, desired_capacity, honor_cooldown=False)

Adjusts the desired size of the AutoScalingGroup by initiating scaling activities. When reducing the size of the group, it is not possible to define which Amazon EC2 instances will be terminated. This applies to any Auto Scaling decisions that might result in terminating instances.

Parameters:
  • group_name (string) – name of the auto scaling group
  • desired_capacity (integer) – new capacity setting for auto scaling group
  • honor_cooldown (boolean) – by default, overrides any cooldown period
set_instance_health(instance_id, health_status, should_respect_grace_period=True)

Explicitly set the health status of an instance.

Parameters:
  • instance_id (str) – The identifier of the EC2 instance.
  • health_status (str) – The health status of the instance. “Healthy” means that the instance is healthy and should remain in service. “Unhealthy” means that the instance is unhealthy. Auto Scaling should terminate and replace it.
  • should_respect_grace_period (bool) – If True, this call should respect the grace period associated with the group.
suspend_processes(as_group, scaling_processes=None)

Suspends Auto Scaling processes for an Auto Scaling group.

Parameters:
  • as_group (string) – The auto scaling group to suspend processes on.
  • scaling_processes (list) – Processes you want to suspend. If omitted, all processes will be suspended.
terminate_instance(instance_id, decrement_capacity=True)

Terminates the specified instance. The desired group size can also be adjusted, if desired.

Parameters:
  • instance_id (str) – The ID of the instance to be terminated.
  • decrement_capacity – Whether to decrement the size of the autoscaling group or not.
boto.ec2.autoscale.connect_to_region(region_name, **kw_params)

Given a valid region name, return a boto.ec2.autoscale.AutoScaleConnection.

Parameters:region_name (str) – The name of the region to connect to.
Return type:boto.ec2.AutoScaleConnection or None
Returns:A connection to the given region, or None if an invalid region name is given
boto.ec2.autoscale.regions()

Get all available regions for the Auto Scaling service.

Return type:list
Returns:A list of boto.RegionInfo instances

boto.ec2.autoscale.activity

class boto.ec2.autoscale.activity.Activity(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.autoscale.group

class boto.ec2.autoscale.group.AutoScalingGroup(connection=None, name=None, launch_config=None, availability_zones=None, load_balancers=None, default_cooldown=None, health_check_type=None, health_check_period=None, placement_group=None, vpc_zone_identifier=None, desired_capacity=None, min_size=None, max_size=None, tags=None, termination_policies=None, instance_id=None, **kwargs)

Creates a new AutoScalingGroup with the specified name.

You must not have already used up your entire quota of AutoScalingGroups in order for this call to be successful. Once the creation request is completed, the AutoScalingGroup is ready to be used in other calls.

Parameters:
  • name (str) – Name of autoscaling group (required).
  • availability_zones (list) – List of availability zones (required).
  • default_cooldown (int) – Number of seconds after a Scaling Activity completes before any further scaling activities can start.
  • desired_capacity (int) – The desired capacity for the group.
  • health_check_period (str) – Length of time in seconds after a new EC2 instance comes into service that Auto Scaling starts checking its health.
  • health_check_type (str) – The service you want the health status from, Amazon EC2 or Elastic Load Balancer.
  • launch_config (str or LaunchConfiguration) – Name of launch configuration (required).
  • load_balancers (list) – List of load balancers.
  • max_size (int) – Maximum size of group (required).
  • min_size (int) – Minimum size of group (required).
  • placement_group (str) – Physical location of your cluster placement group created in Amazon EC2.
  • vpc_zone_identifier (str or list) – A comma-separated string or python list of the subnet identifiers of the Virtual Private Cloud.
  • tags (list) – List of :class:`boto.ec2.autoscale.tag.Tag`s
  • termination_policies (list) – A list of termination policies. Valid values are: “OldestInstance”, “NewestInstance”, “OldestLaunchConfiguration”, “ClosestToNextInstanceHour”, “Default”. If no value is specified, the “Default” value is used.
  • instance_id (str) – The ID of the Amazon EC2 instance you want to use to create the Auto Scaling group.
Return type:

boto.ec2.autoscale.group.AutoScalingGroup

Returns:

An autoscale group.

cooldown
delete(force_delete=False)

Delete this auto-scaling group if no instances attached or no scaling activities in progress.

delete_notification_configuration(topic)

Deletes notifications created by put_notification_configuration.

endElement(name, value, connection)
get_activities(activity_ids=None, max_records=50)

Get all activies for this group.

put_notification_configuration(topic, notification_types)

Configures an Auto Scaling group to send notifications when specified events take place. Valid notification types are: ‘autoscaling:EC2_INSTANCE_LAUNCH’, ‘autoscaling:EC2_INSTANCE_LAUNCH_ERROR’, ‘autoscaling:EC2_INSTANCE_TERMINATE’, ‘autoscaling:EC2_INSTANCE_TERMINATE_ERROR’, ‘autoscaling:TEST_NOTIFICATION’

resume_processes(scaling_processes=None)

Resumes Auto Scaling processes for an Auto Scaling group.

set_capacity(capacity)

Set the desired capacity for the group.

shutdown_instances()

Convenience method which shuts down all instances associated with this group.

startElement(name, attrs, connection)
suspend_processes(scaling_processes=None)

Suspends Auto Scaling processes for an Auto Scaling group.

update()

Sync local changes with AutoScaling group.

class boto.ec2.autoscale.group.AutoScalingGroupMetric(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.group.EnabledMetric(connection=None, metric=None, granularity=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.group.ProcessType(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.group.SuspendedProcess(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.group.TerminationPolicies
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.autoscale.instance

class boto.ec2.autoscale.instance.Instance(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.autoscale.launchconfig

class boto.ec2.autoscale.launchconfig.BlockDeviceMapping(connection=None, device_name=None, virtual_name=None, ebs=None, no_device=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.launchconfig.Ebs(connection=None, snapshot_id=None, volume_size=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.launchconfig.InstanceMonitoring(connection=None, enabled='false')
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.launchconfig.LaunchConfiguration(connection=None, name=None, image_id=None, key_name=None, security_groups=None, user_data=None, instance_type='m1.small', kernel_id=None, ramdisk_id=None, block_device_mappings=None, instance_monitoring=False, spot_price=None, instance_profile_name=None, ebs_optimized=False, associate_public_ip_address=None, volume_type=None, delete_on_termination=True, iops=None, use_block_device_types=False, classic_link_vpc_id=None, classic_link_vpc_security_groups=None)

A launch configuration.

Parameters:
  • name (str) – Name of the launch configuration to create.
  • image_id (str) – Unique ID of the Amazon Machine Image (AMI) which was assigned during registration.
  • key_name (str) – The name of the EC2 key pair.
  • security_groups (list) – Names or security group id’s of the security groups with which to associate the EC2 instances or VPC instances, respectively.
  • user_data (str) – The user data available to launched EC2 instances.
  • instance_type (str) – The instance type
  • kernel_id (str) – Kernel id for instance
  • ramdisk_id (str) – RAM disk id for instance
  • block_device_mappings (list) – Specifies how block devices are exposed for instances
  • instance_monitoring (bool) – Whether instances in group are launched with detailed monitoring.
  • spot_price (float) – The spot price you are bidding. Only applies if you are building an autoscaling group with spot instances.
  • instance_profile_name (string) – The name or the Amazon Resource Name (ARN) of the instance profile associated with the IAM role for the instance.
  • ebs_optimized (bool) – Specifies whether the instance is optimized for EBS I/O (true) or not (false).
  • associate_public_ip_address (bool) – Used for Auto Scaling groups that launch instances into an Amazon Virtual Private Cloud. Specifies whether to assign a public IP address to each instance launched in a Amazon VPC.
  • classic_link_vpc_id (str) – ID of ClassicLink enabled VPC.
  • classic_link_vpc_security_groups (list) – Security group id’s of the security groups with which to associate the ClassicLink VPC instances.
delete()

Delete this launch configuration.

endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.autoscale.policy

class boto.ec2.autoscale.policy.AdjustmentType(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.policy.Alarm(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.policy.MetricCollectionTypes(connection=None)
class BaseType(connection)
arg = ''
endElement(name, value, connection)
startElement(name, attrs, connection)
class Granularity(connection)
arg = 'Granularity'
class Metric(connection)
arg = 'Metric'
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.policy.ScalingPolicy(connection=None, **kwargs)

Scaling Policy

Parameters:
  • name (str) – Name of scaling policy.
  • adjustment_type (str) – Specifies the type of adjustment. Valid values are ChangeInCapacity, ExactCapacity and PercentChangeInCapacity.
  • as_name (str or int) – Name or ARN of the Auto Scaling Group.
  • scaling_adjustment (int) – Value of adjustment (type specified in adjustment_type).
  • min_adjustment_step (int) – Value of min adjustment step required to apply the scaling policy (only make sense when use PercentChangeInCapacity as adjustment_type.).
  • cooldown (int) – Time (in seconds) before Alarm related Scaling Activities can start after the previous Scaling Activity ends.
delete()
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.autoscale.policy.TerminationPolicies(connection=None, **kwargs)
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.autoscale.request

class boto.ec2.autoscale.request.Request(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.autoscale.scheduled

class boto.ec2.autoscale.scheduled.ScheduledUpdateGroupAction(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.autoscale.tag

class boto.ec2.autoscale.tag.Tag(connection=None, key=None, value=None, propagate_at_launch=False, resource_id=None, resource_type='auto-scaling-group')

A name/value tag on an AutoScalingGroup resource.

Variables:
  • key – The key of the tag.
  • value – The value of the tag.
  • propagate_at_launch – Boolean value which specifies whether the new tag will be applied to instances launched after the tag is created.
  • resource_id – The name of the autoscaling group.
  • resource_type – The only supported resource type at this time is “auto-scaling-group”.
build_params(params, i)

Populates a dictionary with the name/value pairs necessary to identify this Tag in a request.

delete()
endElement(name, value, connection)
startElement(name, attrs, connection)