Amazon EC2 Driver Documentation¶

Examples¶

Allocate, Associate, Disassociate, and Release an Elastic IP¶

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

ACCESS_ID = 'your access id'
SECRET_KEY = 'your secret key'

IMAGE_ID = 'ami-c8052d8d'
SIZE_ID = 't1.micro'

cls = get_driver(Provider.EC2_US_WEST)
driver = cls(ACCESS_ID, SECRET_KEY)

sizes = driver.list_sizes()
images = driver.list_images()

size = [s for s in sizes if s.id == SIZE_ID][0]
image = [i for i in images if i.id == IMAGE_ID][0]

node = driver.create_node(name='test-node', image=image, size=size)

# Here we allocate and associate an elastic IP
elastic_ip = driver.ex_allocate_address()
driver.ex_associate_address_with_node(node, elastic_ip)

# When we are done with our elastic IP, we can disassociate from our
# node, and release it
driver.ex_disassociate_address(elastic_ip)
driver.ex_release_address(elastic_ip)

API Docs¶

class libcloud.compute.drivers.ec2.BaseEC2NodeDriver(key, secret=None, secure=True, host=None, port=None, api_version=None, **kwargs)[source]¶

Base Amazon EC2 node driver.

Used for main EC2 and other derivate driver classes to inherit from it.

connectionCls¶: alias of EC2Connection

create_node(**kwargs)[source]¶

Create a new EC2 node

Reference: http://bit.ly/8ZyPSy [docs.amazonwebservices.com]

@inherits: NodeDriver.create_node

Parameters:

ex_keyname (str) – The name of the key pair
ex_userdata (str) – User data
ex_security_groups (list) – A list of names of security groups to assign to the node.
ex_metadata (dict) – Key/Value metadata to associate with a node
ex_mincount (int) – Minimum number of instances to launch
ex_maxcount (int) – Maximum number of instances to launch
ex_clienttoken (str) – Unique identifier to ensure idempotency
ex_blockdevicemappings (list of dict) –
list of dict block device mappings. Example: [{‘DeviceName’: ‘/dev/sda1’, ‘Ebs.VolumeSize’: 10},

{‘DeviceName’: ‘/dev/sdb’, ‘VirtualName’: ‘ephemeral0’}]
ex_iamprofile (str) – Name or ARN of IAM profile

create_volume(size, name, location=None, snapshot=None)[source]¶

Parameters:	location (`ExEC2AvailabilityZone`) – Datacenter in which to create a volume in.

create_volume_snapshot(volume, name=None)[source]¶

Create snapshot from volume

Parameters:	volume (`StorageVolume`) – Instance of `StorageVolume` name (`str`) – Description for snapshot
Return type:	`VolumeSnapshot`

deploy_node(**kwargs)¶

Create a new node, and start deployment.

In order to be able to SSH into a created node access credentials are required.

A user can pass either a NodeAuthPassword or NodeAuthSSHKey to the auth argument. If the create_node implementation supports that kind if credential (as declared in self.features['create_node']) then it is passed on to create_node. Otherwise it is not passed on to create_node and it is only used for authentication.

If the auth parameter is not supplied but the driver declares it supports generates_password then the password returned by create_node will be used to SSH into the server.

Finally, if the ssh_key_file is supplied that key will be used to SSH into the server.

This function may raise a DeploymentException, if a create_node call was successful, but there is a later error (like SSH failing or timing out). This exception includes a Node object which you may want to destroy if incomplete deployments are not desirable.

>>> from libcloud.compute.drivers.dummy import DummyNodeDriver
>>> from libcloud.compute.deployment import ScriptDeployment
>>> from libcloud.compute.deployment import MultiStepDeployment
>>> from libcloud.compute.base import NodeAuthSSHKey
>>> driver = DummyNodeDriver(0)
>>> key = NodeAuthSSHKey('...') # read from file
>>> script = ScriptDeployment("yum -y install emacs strace tcpdump")
>>> msd = MultiStepDeployment([key, script])
>>> def d():
...     try:
...         driver.deploy_node(deploy=msd)
...     except NotImplementedError:
...         print ("not implemented for dummy driver")
>>> d()
not implemented for dummy driver

Deploy node is typically not overridden in subclasses. The existing implementation should be able to handle most such.

Parameters:

deploy (Deployment) – Deployment to run once machine is online and availble to SSH.
ssh_username (str) – Optional name of the account which is used when connecting to SSH server (default is root)
ssh_alternate_usernames (list) – Optional list of ssh usernames to try to connect with if using the default one fails
ssh_port (int) – Optional SSH server port (default is 22)
ssh_timeout (float) – Optional SSH connection timeout in seconds (default is 10)
auth (NodeAuthSSHKey or NodeAuthPassword) – Initial authentication information for the node (optional)
ssh_key (str or list of str) – A path (or paths) to an SSH private key with which to attempt to authenticate. (optional)
timeout (int) – How many seconds to wait before timing out. (default is 600)
max_tries (int) – How many times to retry if a deployment fails before giving up (default is 3)
ssh_interface (str) – The interface to wait for. Default is ‘public_ips’, other option is ‘private_ips’.

ex_allocate_address()[source]¶

Allocate a new Elastic IP address

Returns:	String representation of allocated IP address
Return type:	`str`

ex_associate_address_with_node(node, elastic_ip_address)[source]¶

Associate an Elastic IP address with a particular node.

Parameters:	node (`Node`) – Node instance elastic_ip_address (`str`) – IP address which should be used
Returns:	True on success, False otherwise.
Return type:	`bool`

ex_associate_addresses(node, elastic_ip_address)[source]¶: Note: This method has been deprecated in favor of the ex_associate_address_with_node method.

ex_authorize_security_group(name, from_port, to_port, cidr_ip, protocol='tcp')[source]¶

Edit a Security Group to allow specific traffic.

@note: This is a non-standard extension API, and only works for EC2.

Parameters:	name (`str`) – The name of the security group to edit from_port (`str`) – The beginning of the port range to open to_port (`str`) – The end of the port range to open cidr_ip (`str`) – The ip to allow traffic for. protocol (`str`) – tcp/udp/icmp
Return type:	`bool`

ex_authorize_security_group_permissive(name)[source]¶

Edit a Security Group to allow all traffic.

@note: This is a non-standard extension API, and only works for EC2.

Parameters:	name (`str`) – The name of the security group to edit
Return type:	`list` of `str`

ex_change_node_size(node, new_size)[source]¶

Change the node size. Note: Node must be turned of before changing the size.

Parameters:	node (`Node`) – Node instance new_size (`NodeSize`) – NodeSize intance
Returns:	True on success, False otherwise.
Return type:	`bool`

ex_create_keypair(name)[source]¶

Creates a new keypair

@note: This is a non-standard extension API, and only works for EC2.

Parameters:	name (`str`) – The name of the keypair to Create. This must be unique, otherwise an InvalidKeyPair.Duplicate exception is raised.
Return type:	`dict`

ex_create_security_group(name, description)[source]¶

Creates a new Security Group

@note: This is a non-standard extension API, and only works for EC2.

Parameters:	name (`str`) – The name of the security group to Create. This must be unique. description – Human readable description of a Security

Group. :type description: str

Return type:	`str`

ex_create_tags(resource, tags)[source]¶

Create tags for a resource (Node or StorageVolume).

Parameters:	resource (`Node` or `StorageVolume`) – Resource to be tagged tags (`dict`) – A dictionary or other mapping of strings to strings, associating tag names with tag values.
Return type:	`bool`

ex_delete_keypair(keypair)[source]¶

Delete a key pair by name.

@note: This is a non-standard extension API, and only works with EC2.

Parameters:	keypair (`str`) – The name of the keypair to delete.
Return type:	`bool`

ex_delete_tags(resource, tags)[source]¶

Delete tags from a resource.

Parameters:	resource (`Node` or `StorageVolume`) – Resource to be tagged tags (`dict`) – A dictionary or other mapping of strings to strings, specifying the tag names and tag values to be deleted.
Return type:	`bool`

ex_describe_addresses(nodes)[source]¶

Return Elastic IP addresses for all the nodes in the provided list.

Parameters:	nodes (`list` of `Node`) – List of `Node` instances
Returns:	Dictionary where a key is a node ID and the value is a list with the Elastic IP addresses associated with this node.
Return type:	`dict`

ex_describe_addresses_for_node(node)[source]¶

Return a list of Elastic IP addresses associated with this node.

Parameters:	node (`Node`) – Node instance
Returns:	list Elastic IP addresses attached to this node.
Return type:	`list` of `str`

ex_describe_all_addresses(only_allocated=False)[source]¶

Return all the Elastic IP addresses for this account optionally, return only the allocated addresses

Parameters:	only_allocated (`str`) – If true, return only those addresses that are associated with an instance
Returns:	list list of elastic ips for this particular account.
Return type:	`list` of `str`

ex_describe_all_keypairs()[source]¶

Describes all keypairs. This is here for backward compatibilty.

@note: This is a non-standard extension API, and only works for EC2.

Return type:	`list` of `str`

ex_describe_keypair(name)[source]¶

Describes a keypair by name.

@note: This is a non-standard extension API, and only works for EC2.

Parameters:	name (`str`) – The name of the keypair to describe.
Return type:	`dict`

ex_describe_keypairs(name)[source]¶: Here for backward compatibility.

ex_describe_tags(resource)[source]¶

Return a dictionary of tags for a resource (Node or StorageVolume).

Parameters:	resource (`Node` or `StorageVolume`) – resource which should be used
Returns:	dict Node tags
Return type:	`dict`

ex_disassociate_address(elastic_ip_address)[source]¶

Disassociate an Elastic IP address

Parameters:	elastic_ip_address (`str`) – Elastic IP address which should be used
Returns:	True on success, False otherwise.
Return type:	`bool`

ex_find_or_import_keypair_by_key_material(pubkey)[source]¶

Given a public key, look it up in the EC2 KeyPair database. If it exists, return any information we have about it. Otherwise, create it.

Keys that are created are named based on their comment and fingerprint.

ex_get_metadata_for_node(node)[source]¶

Return the metadata associated with the node.

Parameters:	node (`Node`) – Node instance
Returns:	A dictionary or other mapping of strings to strings, associating tag names with tag values.
Rtype tags:	`dict`

ex_import_keypair(name, keyfile)[source]¶

imports a new public key where the public key is passed via a filename

@note: This is a non-standard extension API, and only works for EC2.

Parameters:	name (`str`) – The name of the public key to import. This must be unique, otherwise an InvalidKeyPair.Duplicate exception is raised. keyfile (`str`) – The filename with path of the public key to import.
Return type:	`dict`

ex_import_keypair_from_string(name, key_material)[source]¶

imports a new public key where the public key is passed in as a string

@note: This is a non-standard extension API, and only works for EC2.

Parameters:	name (`str`) – The name of the public key to import. This must be unique, otherwise an InvalidKeyPair.Duplicate exception is raised. key_material (`str`) – The contents of a public key file.
Return type:	`dict`

ex_list_availability_zones(only_available=True)[source]¶

Return a list of ExEC2AvailabilityZone objects for the current region.

Note: This is an extension method and is only available for EC2 driver.

Parameters:	only_available (`str`) – If true, return only availability zones with state ‘available’
Return type:	`list` of `ExEC2AvailabilityZone`

ex_list_keypairs()[source]¶

Lists all the keypair names and fingerprints.

Return type:	`list` of `dict`

ex_list_security_groups()[source]¶

List existing Security Groups.

@note: This is a non-standard extension API, and only works for EC2.

Return type:	`list` of `str`

ex_modify_image_attribute(image, attributes)[source]¶

Modify image attributes.

Parameters:	node (`Node`) – Node instance attributes (`dict`) – Dictionary with node attributes
Returns:	True on success, False otherwise.
Return type:	`bool`

ex_modify_instance_attribute(node, attributes)[source]¶

Modify node attributes. A list of valid attributes can be found at http://goo.gl/gxcj8

Parameters:	node (`Node`) – Node instance attributes (`dict`) – Dictionary with node attributes
Returns:	True on success, False otherwise.
Return type:	`bool`

ex_release_address(elastic_ip_address)[source]¶

Release an Elastic IP address

Parameters:	elastic_ip_address (`str`) – Elastic IP address which should be used
Returns:	True on success, False otherwise.
Return type:	`bool`

ex_start_node(node)[source]¶

Start the node by passing in the node object, does not work with instance store backed instances

Parameters:	node (`Node`) – Node which should be used
Return type:	`bool`

ex_stop_node(node)[source]¶

Stop the node by passing in the node object, does not work with instance store backed instances

Parameters:	node (`Node`) – Node which should be used
Return type:	`bool`

list_images(location=None, ex_image_ids=None, ex_owner=None)[source]¶

List all images

Ex_image_ids parameter is used to filter the list of images that should be returned. Only the images with the corresponding image ids will be returned.

Ex_owner parameter is used to filter the list of images that should be returned. Only the images with the corresponding owner will be returned. Valid values: amazon|aws-marketplace|self|all|aws id

Parameters:	ex_image_ids (`str`) – List of `NodeImage.id` ex_owner – Owner name
Return type:	`list` of `NodeImage`

list_nodes(ex_node_ids=None)[source]¶

List all nodes

Ex_node_ids parameter is used to filter the list of nodes that should be returned. Only the nodes with the corresponding node ids will be returned.

Parameters:	ex_node_ids (`list` of `str`) – List of `node.id`
Return type:	`list` of `Node`

list_snapshots(snapshot=None, owner=None)[source]¶

Describe all snapshots.

Parameters:	snapshot – If provided, only return snapshot information for the provided snapshot. owner (`str`) – Owner for snapshot: self\|amazon\|ID
Return type:	`list` of `VolumeSnapshot`

wait_until_running(nodes, wait_period=3, timeout=600, ssh_interface='public_ips', force_ipv4=True)¶

Block until the given nodes are fully booted and have an IP address assigned.

Parameters:	nodes (`List` of `Node`) – list of node instances. wait_period (`int`) – How many seconds to between each loop iteration (default is 3) timeout (`int`) – How many seconds to wait before timing out (default is 600) ssh_interface (`str`) – The interface to wait for. Default is ‘public_ips’, other option is ‘private_ips’. force_ipv4 (`bool`) – Ignore ipv6 IP addresses (default is True).
Returns:	`[(Node, ip_addresses)]` list of tuple of Node instance and list of ip_address on success.
Return type:	`list` of `tuple`