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.

ELB Reference

boto.ec2.elb

This module provides an interface to the Elastic Compute Cloud (EC2) load balancing service from AWS.

class boto.ec2.elb.ELBConnection(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)

Init method to create a new connection to EC2 Load Balancing Service.

Note

The region argument is overridden by the region specified in the boto configuration file.

APIVersion = '2012-06-01'
DefaultRegionEndpoint = 'elasticloadbalancing.us-east-1.amazonaws.com'
DefaultRegionName = 'us-east-1'
apply_security_groups_to_lb(name, security_groups)

Associates one or more security groups with the load balancer. The provided security groups will override any currently applied security groups.

Parameters:
  • name (string) – The name of the Load Balancer
  • security_groups (List of strings) – The name of the security group(s) to add.
Return type:

List of strings

Returns:

An updated list of security groups for this Load Balancer.

attach_lb_to_subnets(name, subnets)

Attaches load balancer to one or more subnets. Attaching subnets that are already registered with the Load Balancer has no effect.

Parameters:
  • name (string) – The name of the Load Balancer
  • subnets (List of strings) – The name of the subnet(s) to add.
Return type:

List of strings

Returns:

An updated list of subnets for this Load Balancer.

build_list_params(params, items, label)
configure_health_check(name, health_check)

Define a health check for the EndPoints.

Parameters:
  • name (string) – The mnemonic name associated with the load balancer
  • health_check (boto.ec2.elb.healthcheck.HealthCheck) – A HealthCheck object populated with the desired values.
Return type:

boto.ec2.elb.healthcheck.HealthCheck

Returns:

The updated boto.ec2.elb.healthcheck.HealthCheck

Generates a stickiness policy with sticky session lifetimes that follow that of an application-generated cookie. This policy can only be associated with HTTP listeners.

This policy is similar to the policy created by CreateLBCookieStickinessPolicy, except that the lifetime of the special Elastic Load Balancing cookie follows the lifetime of the application-generated cookie specified in the policy configuration. The load balancer only inserts a new stickiness cookie when the application response includes a new application cookie.

If the application cookie is explicitly removed or expires, the session stops being sticky until a new application cookie is issued.

Generates a stickiness policy with sticky session lifetimes controlled by the lifetime of the browser (user-agent) or a specified expiration period. This policy can only be associated only with HTTP listeners.

When a load balancer implements this policy, the load balancer uses a special cookie to track the backend server instance for each request. When the load balancer receives a request, it first checks to see if this cookie is present in the request. If so, the load balancer sends the request to the application server specified in the cookie. If not, the load balancer sends the request to a server that is chosen based on the existing load balancing algorithm.

A cookie is inserted into the response for binding subsequent requests from the same user to that server. The validity of the cookie is based on the cookie expiration time, which is specified in the policy configuration.

None may be passed for cookie_expiration_period.

create_lb_policy(lb_name, policy_name, policy_type, policy_attributes)

Creates a new policy that contains the necessary attributes depending on the policy type. Policies are settings that are saved for your load balancer and that can be applied to the front-end listener, or the back-end application server.

create_load_balancer(name, zones, listeners=None, subnets=None, security_groups=None, scheme='internet-facing', complex_listeners=None)

Create a new load balancer for your account. By default the load balancer will be created in EC2. To create a load balancer inside a VPC, parameter zones must be set to None and subnets must not be None. The load balancer will be automatically created under the VPC that contains the subnet(s) specified.

Parameters:
  • name (string) – The mnemonic name associated with the new load balancer
  • zones (List of strings) – The names of the availability zone(s) to add.
  • listeners (List of tuples) – Each tuple contains three or four values, (LoadBalancerPortNumber, InstancePortNumber, Protocol, [SSLCertificateId]) where LoadBalancerPortNumber and InstancePortNumber are integer values between 1 and 65535, Protocol is a string containing either ‘TCP’, ‘SSL’, HTTP’, or ‘HTTPS’; SSLCertificateID is the ARN of a AWS IAM certificate, and must be specified when doing HTTPS.
  • subnets (list of strings) – A list of subnet IDs in your VPC to attach to your LoadBalancer.
  • security_groups (list of strings) – The security groups assigned to your LoadBalancer within your VPC.
  • scheme (string) –

    The type of a LoadBalancer. By default, Elastic Load Balancing creates an internet-facing LoadBalancer with a publicly resolvable DNS name, which resolves to public IP addresses.

    Specify the value internal for this option to create an internal LoadBalancer with a DNS name that resolves to private IP addresses.

    This option is only available for LoadBalancers attached to an Amazon VPC.

  • complex_listeners (List of tuples) –

    Each tuple contains four or five values, (LoadBalancerPortNumber, InstancePortNumber, Protocol,

    InstanceProtocol, SSLCertificateId).
    Where:
    • LoadBalancerPortNumber and InstancePortNumber are integer values between 1 and 65535
    • Protocol and InstanceProtocol is a string containing either ‘TCP’, ‘SSL’, ‘HTTP’, or ‘HTTPS’
    • SSLCertificateId is the ARN of an SSL certificate loaded into AWS IAM
Return type:

boto.ec2.elb.loadbalancer.LoadBalancer

Returns:

The newly created boto.ec2.elb.loadbalancer.LoadBalancer

create_load_balancer_listeners(name, listeners=None, complex_listeners=None)

Creates a Listener (or group of listeners) for an existing Load Balancer

Parameters:
  • name (string) – The name of the load balancer to create the listeners for
  • listeners (List of tuples) – Each tuple contains three or four values, (LoadBalancerPortNumber, InstancePortNumber, Protocol, [SSLCertificateId]) where LoadBalancerPortNumber and InstancePortNumber are integer values between 1 and 65535, Protocol is a string containing either ‘TCP’, ‘SSL’, HTTP’, or ‘HTTPS’; SSLCertificateID is the ARN of a AWS IAM certificate, and must be specified when doing HTTPS.
  • complex_listeners (List of tuples) –

    Each tuple contains four or five values, (LoadBalancerPortNumber, InstancePortNumber, Protocol,

    InstanceProtocol, SSLCertificateId).
    Where:
    • LoadBalancerPortNumber and InstancePortNumber are integer values between 1 and 65535
    • Protocol and InstanceProtocol is a string containing either ‘TCP’, ‘SSL’, ‘HTTP’, or ‘HTTPS’
    • SSLCertificateId is the ARN of an SSL certificate loaded into AWS IAM
Returns:

The status of the request

delete_lb_policy(lb_name, policy_name)

Deletes a policy from the LoadBalancer. The specified policy must not be enabled for any listeners.

delete_load_balancer(name)

Delete a Load Balancer from your account.

Parameters:name (string) – The name of the Load Balancer to delete
delete_load_balancer_listeners(name, ports)

Deletes a load balancer listener (or group of listeners)

Parameters:
  • name (string) – The name of the load balancer to create the listeners for
  • ports (List int) – Each int represents the port on the ELB to be removed
Returns:

The status of the request

deregister_instances(load_balancer_name, instances)

Remove Instances from an existing Load Balancer.

Parameters:
  • load_balancer_name (string) – The name of the Load Balancer
  • instances (List of strings) – The instance ID’s of the EC2 instances to remove.
Return type:

List of strings

Returns:

An updated list of instances for this Load Balancer.

describe_instance_health(load_balancer_name, instances=None)

Get current state of all Instances registered to an Load Balancer.

Parameters:
  • load_balancer_name (string) – The name of the Load Balancer
  • instances (List of strings) – The instance ID’s of the EC2 instances to return status for. If not provided, the state of all instances will be returned.
Return type:

List of boto.ec2.elb.instancestate.InstanceState

Returns:

list of state info for instances in this Load Balancer.

detach_lb_from_subnets(name, subnets)

Detaches load balancer from one or more subnets.

Parameters:
  • name (string) – The name of the Load Balancer
  • subnets (List of strings) – The name of the subnet(s) to detach.
Return type:

List of strings

Returns:

An updated list of subnets for this Load Balancer.

disable_availability_zones(load_balancer_name, zones_to_remove)

Remove availability zones from an existing Load Balancer. All zones must be in the same region as the Load Balancer. Removing zones that are not registered with the Load Balancer has no effect. You cannot remove all zones from an Load Balancer.

Parameters:
  • load_balancer_name (string) – The name of the Load Balancer
  • zones (List of strings) – The name of the zone(s) to remove.
Return type:

List of strings

Returns:

An updated list of zones for this Load Balancer.

enable_availability_zones(load_balancer_name, zones_to_add)

Add availability zones to an existing Load Balancer All zones must be in the same region as the Load Balancer Adding zones that are already registered with the Load Balancer has no effect.

Parameters:
  • load_balancer_name (string) – The name of the Load Balancer
  • zones (List of strings) – The name of the zone(s) to add.
Return type:

List of strings

Returns:

An updated list of zones for this Load Balancer.

get_all_lb_attributes(load_balancer_name)

Gets all Attributes of a Load Balancer

Parameters:load_balancer_name (string) – The name of the Load Balancer
Return type:boto.ec2.elb.attribute.LbAttributes
Returns:The attribute object of the ELB.
get_all_load_balancers(load_balancer_names=None, marker=None)

Retrieve all load balancers associated with your account.

Parameters:
  • load_balancer_names (list) – An optional list of load balancer names.
  • marker (string) – Use this only when paginating results and only in follow-up request after you’ve received a response where the results are truncated. Set this to the value of the Marker element in the response you just received.
Return type:

boto.resultset.ResultSet

Returns:

A ResultSet containing instances of boto.ec2.elb.loadbalancer.LoadBalancer

get_lb_attribute(load_balancer_name, attribute)

Gets an attribute of a Load Balancer

This will make an EC2 call for each method call.

Parameters:
  • load_balancer_name (string) – The name of the Load Balancer
  • attribute (string) –

    The attribute you wish to see.

    • accessLog - AccessLogAttribute instance
    • crossZoneLoadBalancing - Boolean
    • connectingSettings - ConnectionSettingAttribute instance
    • connectionDraining - ConnectionDrainingAttribute instance
Return type:

Attribute dependent

Returns:

The new value for the attribute

modify_lb_attribute(load_balancer_name, attribute, value)

Changes an attribute of a Load Balancer

Parameters:
  • load_balancer_name (string) – The name of the Load Balancer
  • attribute (string) – The attribute you wish to change.
  • crossZoneLoadBalancing - Boolean (true)
  • connectingSettings - ConnectionSettingAttribute instance
  • accessLog - AccessLogAttribute instance
  • connectionDraining - ConnectionDrainingAttribute instance
Parameters:value (string) – The new value for the attribute
Return type:bool
Returns:Whether the operation succeeded or not
register_instances(load_balancer_name, instances)

Add new Instances to an existing Load Balancer.

Parameters:
  • load_balancer_name (string) – The name of the Load Balancer
  • instances (List of strings) – The instance ID’s of the EC2 instances to add.
Return type:

List of strings

Returns:

An updated list of instances for this Load Balancer.

set_lb_listener_SSL_certificate(lb_name, lb_port, ssl_certificate_id)

Sets the certificate that terminates the specified listener’s SSL connections. The specified certificate replaces any prior certificate that was used on the same LoadBalancer and port.

set_lb_policies_of_backend_server(lb_name, instance_port, policies)

Replaces the current set of policies associated with a port on which the back-end server is listening with a new set of policies.

set_lb_policies_of_listener(lb_name, lb_port, policies)

Associates, updates, or disables a policy with a listener on the load balancer. Currently only zero (0) or one (1) policy can be associated with a listener.

boto.ec2.elb.connect_to_region(region_name, **kw_params)

Given a valid region name, return a boto.ec2.elb.ELBConnection.

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

Get all available regions for the ELB service.

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

boto.ec2.elb.healthcheck

class boto.ec2.elb.healthcheck.HealthCheck(access_point=None, interval=30, target=None, healthy_threshold=3, timeout=5, unhealthy_threshold=5)

Represents an EC2 Access Point Health Check. See Configuring a Health Check for a walkthrough on configuring load balancer health checks.

Variables:
  • access_point (str) – The name of the load balancer this health check is associated with.
  • interval (int) – Specifies how many seconds there are between health checks.
  • target (str) – Determines what to check on an instance. See the Amazon HealthCheck documentation for possible Target values.
endElement(name, value, connection)
startElement(name, attrs, connection)
update()

In the case where you have accessed an existing health check on a load balancer, this method applies this instance’s health check values to the load balancer it is attached to.

Note

This method will not do anything if the access_point attribute isn’t set, as is the case with a newly instantiated HealthCheck instance.

boto.ec2.elb.instancestate

class boto.ec2.elb.instancestate.InstanceState(load_balancer=None, description=None, state=None, instance_id=None, reason_code=None)

Represents the state of an EC2 Load Balancer Instance

Variables:
  • load_balancer (boto.ec2.elb.loadbalancer.LoadBalancer) – The load balancer this instance is registered to.
  • description (str) – A description of the instance.
  • instance_id (str) – The EC2 instance ID.
  • reason_code (str) – Provides information about the cause of an OutOfService instance. Specifically, it indicates whether the cause is Elastic Load Balancing or the instance behind the LoadBalancer.
  • state (str) – Specifies the current state of the instance.
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.elb.listelement

class boto.ec2.elb.listelement.ListElement

A list subclass that has some additional methods for interacting with Amazon’s XML API.

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

boto.ec2.elb.listener

class boto.ec2.elb.listener.Listener(load_balancer=None, load_balancer_port=0, instance_port=0, protocol='', ssl_certificate_id=None, instance_protocol=None)

Represents an EC2 Load Balancer Listener tuple

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

boto.ec2.elb.loadbalancer

class boto.ec2.elb.loadbalancer.Backend(connection=None)

Backend server description

endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.loadbalancer.LoadBalancer(connection=None, name=None, endpoints=None)

Represents an EC2 Load Balancer.

Variables:
  • connection (boto.ec2.elb.ELBConnection) – The connection this load balancer was instance was instantiated from.
  • listeners (list) – A list of tuples in the form of (<Inbound port>, <Outbound port>, <Protocol>)
  • health_check (boto.ec2.elb.healthcheck.HealthCheck) – The health check policy for this load balancer.
  • policies (boto.ec2.elb.policies.Policies) – Cookie stickiness and other policies.
  • name (str) – The name of the Load Balancer.
  • dns_name (str) – The external DNS name for the balancer.
  • created_time (str) – A date+time string showing when the load balancer was created.
  • instances (list) – A list of boto.ec2.instanceinfo.InstanceInfo instances, representing the EC2 instances this load balancer is distributing requests to.
  • availability_zones (list) – The availability zones this balancer covers.
  • canonical_hosted_zone_name (str) – Current CNAME for the balancer.
  • canonical_hosted_zone_name_id (str) – The Route 53 hosted zone ID of this balancer. Needed when creating an Alias record in a Route 53 hosted zone.
  • source_security_group (boto.ec2.elb.securitygroup.SecurityGroup) – The security group that you can use as part of your inbound rules for your load balancer back-end instances to disallow traffic from sources other than your load balancer.
  • subnets (list) – A list of subnets this balancer is on.
  • security_groups (list) – A list of additional security groups that have been applied.
  • vpc_id (str) – The ID of the VPC that this ELB resides within.
  • backends (list) – A list of :py:class:`boto.ec2.elb.loadbalancer.Backend back-end server descriptions.
apply_security_groups(security_groups)

Associates one or more security groups with the load balancer. The provided security groups will override any currently applied security groups.

Parameters:security_groups (string or List of strings) – The name of the security group(s) to add.
attach_subnets(subnets)

Attaches load balancer to one or more subnets. Attaching subnets that are already registered with the Load Balancer has no effect.

Parameters:subnets (string or List of strings) – The name of the subnet(s) to add.
configure_health_check(health_check)

Configures the health check behavior for the instances behind this load balancer. See Configuring a Health Check for a walkthrough.

Parameters:health_check (boto.ec2.elb.healthcheck.HealthCheck) – A HealthCheck instance that tells the load balancer how to check its instances for health.
create_lb_policy(policy_name, policy_type, policy_attribute)
create_listener(inPort, outPort=None, proto='tcp')
create_listeners(listeners)
delete()

Delete this load balancer.

delete_listener(inPort)
delete_listeners(listeners)
delete_policy(policy_name)

Deletes a policy from the LoadBalancer. The specified policy must not be enabled for any listeners.

deregister_instances(instances)

Remove instances from this load balancer. Removing instances that are not registered with the load balancer has no effect.

Parameters:instances (list) – List of instance IDs (strings) that you’d like to remove from this load balancer.
detach_subnets(subnets)

Detaches load balancer from one or more subnets.

Parameters:subnets (string or List of strings) – The name of the subnet(s) to detach.
disable_cross_zone_load_balancing()

Turns off CrossZone Load Balancing for this ELB.

Return type:bool
Returns:True if successful, False if not.
disable_zones(zones)

Disable availability zones from this Access Point.

Parameters:zones (string or List of strings) – The name of the zone(s) to add.
enable_cross_zone_load_balancing()

Turns on CrossZone Load Balancing for this ELB.

Return type:bool
Returns:True if successful, False if not.
enable_zones(zones)

Enable availability zones to this Access Point. All zones must be in the same region as the Access Point.

Parameters:zones (string or List of strings) – The name of the zone(s) to add.
endElement(name, value, connection)
get_attributes(force=False)

Gets the LbAttributes. The Attributes will be cached.

Parameters:force (bool) – Ignore cache value and reload.
Return type:boto.ec2.elb.attributes.LbAttributes
Returns:The LbAttribues object
get_instance_health(instances=None)

Returns a list of boto.ec2.elb.instancestate.InstanceState objects, which show the health of the instances attached to this load balancer.

Return type:list
Returns:A list of InstanceState instances, representing the instances attached to this load balancer.
is_cross_zone_load_balancing(force=False)

Identifies if the ELB is current configured to do CrossZone Balancing.

Parameters:force (bool) – Ignore cache value and reload.
Return type:bool
Returns:True if balancing is enabled, False if not.
register_instances(instances)

Adds instances to this load balancer. All instances must be in the same region as the load balancer. Adding endpoints that are already registered with the load balancer has no effect.

Parameters:instances (list) – List of instance IDs (strings) that you’d like to add to this load balancer.
set_listener_SSL_certificate(lb_port, ssl_certificate_id)
set_policies_of_backend_server(instance_port, policies)
set_policies_of_listener(lb_port, policies)
startElement(name, attrs, connection)
class boto.ec2.elb.loadbalancer.LoadBalancerZones(connection=None)

Used to collect the zones for a Load Balancer when enable_zones or disable_zones are called.

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

boto.ec2.elb.policies

class boto.ec2.elb.policies.AppCookieStickinessPolicy(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.policies.LBCookieStickinessPolicy(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.policies.OtherPolicy(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.policies.Policies(connection=None)

ELB Policies

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

boto.ec2.elb.securitygroup

class boto.ec2.elb.securitygroup.SecurityGroup(connection=None)
endElement(name, value, connection)
startElement(name, attrs, connection)

boto.ec2.elb.attributes

class boto.ec2.elb.attributes.AccessLogAttribute(connection=None)

Represents the AccessLog segment of ELB attributes.

endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.attributes.ConnectionDrainingAttribute(connection=None)

Represents the ConnectionDraining segment of ELB attributes.

endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.attributes.ConnectionSettingAttribute(connection=None)

Represents the ConnectionSetting segment of ELB Attributes.

endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.attributes.CrossZoneLoadBalancingAttribute(connection=None)

Represents the CrossZoneLoadBalancing segement of ELB Attributes.

endElement(name, value, connection)
startElement(name, attrs, connection)
class boto.ec2.elb.attributes.LbAttributes(connection=None)

Represents the Attributes of an Elastic Load Balancer.

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