Aliyun(AliCloud) ECS Driver Documentation

Aliyun(AliCloud) Elastic Compute Service (ECS) is a simple and efficient computing service, whose processing capacity is scalable. It can help you quickly build a more stable and secure application. It helps you improve the efficiency of operation and maintenance, and reduce the cost of IT. ECS enables you to focus on core business innovation.

Regions

The Aliyun supports mutiple regions, which indicates the distinct physical location all over the world. The current available regions in China are Hangzhou, Qingdao, Beijing, and Shenzhen. Other regions available outside of Chinese Mainland are Hong Kong, Singapore, and United States.

You can select the AliCloud region according to the customer base, cost effectiveness, disaster recovery site, or any compliance requirements. ECS instances in the same region can communicate with each other over intranet, whereas cross-region ECS communication requires the internet connection.

A region equals to NodeLocation in libcloud. Users can list all available regions, for example:

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

ECSDriver = get_driver(Provider.ALIYUN_ECS)

region = "cn-hangzhou"
access_key_id = "CHANGE IT"
access_key_secret = "CHANGE IT"

driver = ECSDriver(access_key_id, access_key_secret, region=region)

locations = driver.list_locations()
for each in locations:
    print("id: {0:>16s}".format(each.id))

ECS Instance Types

An instance type defines some computing capabilities, including CPU, memory, associated with a set of ECS instances.

Aliyun provides two generations, three instance type families, and more than ten instance types to support different usecases.

For more information, please refer to the Instance Generations section, Instance Type Families section and Instance Type section of the official documentation.

An instance type equals to the NodeSize in libcloud. Users can list all available instance types, for example:

import pprint

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

ECSDriver = get_driver(Provider.ALIYUN_ECS)

region = "cn-hangzhou"
access_key_id = "CHANGE IT"
access_key_secret = "CHANGE IT"

driver = ECSDriver(access_key_id, access_key_secret, region=region)

sizes = driver.list_sizes()
pprint.pprint(sizes)

Security Groups

A security group is a logical grouping which groups instances in the same region with the same security requirements and mutual trust. Security groups, like firewalls, are used to configure network access controls for one or more ECS instances.

Each instance belongs to at least one security group and this must be specified at the time of creation.

Users can list all defined security groups, for example:

import pprint

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

ECSDriver = get_driver(Provider.ALIYUN_ECS)

region = "cn-hangzhou"
access_key_id = "CHANGE IT"
access_key_secret = "CHANGE IT"

driver = ECSDriver(access_key_id, access_key_secret, region=region)

sec_groups = driver.ex_list_security_groups()
pprint.pprint(sec_groups)

For more information, please refer to the Security Groups section of the official documentation.

Images

An image is an ECS instance operating environment template. It generally includes the operating system and preloaded software. It equals to NodeImage in libcloud.

Users can list all available images, for example:

import pprint

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

ECSDriver = get_driver(Provider.ALIYUN_ECS)

region = "cn-hangzhou"
access_key_id = "CHANGE IT"
access_key_secret = "CHANGE IT"

driver = ECSDriver(access_key_id, access_key_secret, region=region)

images = driver.list_images()
pprint.pprint(images)

Storage

Aliyun ECS provides multiple types of storage disks for instances to meet the requirements of different application scenarios. An instance can use all these types of volumes independently.

There are three types of disks: general cloud disk, SSD cloud disk and ephemeral SSD disk.

Aliyun provides the snapshot mechanism. This creates a snapshot that retains a copy of the data on a disk at a certain time point manually or automatically.

Aliyun storage disks equal to StorageVolume in libcloud. Users can manage volumes and snapshots, for example:

import time

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

ECSDriver = get_driver(Provider.ALIYUN_ECS)

region = "cn-hangzhou"
access_key_id = "CHANGE IT"
access_key_secret = "CHANGE IT"

driver = ECSDriver(access_key_id, access_key_secret, region=region)

node = driver.list_nodes()[0]
zone = driver.ex_list_zones()[0]

new_volume = driver.create_volume(
    size=5,
    name="data_volume1",
    ex_zone_id=zone.id,
    ex_disk_category=driver.disk_categories.CLOUD,
)
driver.attach_volume(node, new_volume)
# Wait 10s for attaching finished
time.sleep(10)

snapshot = driver.create_volume_snapshot(new_volume, name="data_volume1_snapshot1")

For more information, please refer to the Storage section of the official documentation.

IP Address

IP addresses are an important means for users to access ECS instances and for ECS instances to provide external services. Each instance will be allocated a private network card and bound to a specific private IP and a public network card by default.

Private IPs can be used for SLB load balancing, intranet mutual access between ECS instances or between an ECS instance and another cloud service within the same region. Data traffic through private IPs between instances in the same region is free.

Public IPs are used to access the instance from the internet. Public network traffic is not free.

Users can select different internet charge type and bandwidth limitations.

Instance lifecycle management

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

ECSDriver = get_driver(Provider.ALIYUN_ECS)

region = "cn-hangzhou"
access_key_id = "CHANGE IT"
access_key_secret = "CHANGE IT"

driver = ECSDriver(access_key_id, access_key_secret, region=region)

# Query the size ecs.t1.small
sizes = driver.list_sizes()
t1_small = sizes[1]
# Query the first ubuntu OS image
images = driver.list_images()
for each in images:
    if "ubuntu" in each.id.lower():
        ubuntu = each
        break
else:
    ubuntu = images[0]
# Query the default security group
sg = driver.ex_list_security_groups()[0]

# Create a cloud type data disk which is 5GB and deleted with the node
data_disk = {
    "size": 5,
    "category": driver.disk_categories.CLOUD,
    "disk_name": "data_disk1",
    "delete_with_instance": True,
}

# Set a password to access the guest OS
auth = NodeAuthPassword("P@$$w0rd")

# Create the node
node = driver.create_node(
    image=ubuntu,
    size=t1_small,
    name="test_node",
    ex_security_group_id=sg.id,
    ex_internet_charge_type=driver.internet_charge_types.BY_TRAFFIC,
    ex_internet_max_bandwidth_out=1,
    ex_data_disks=data_disk,
    auth=auth,
)

# Reboot the node
node.reboot()

# Stop the node
driver.ex_stop_node(node)

# Start the node
driver.ex_start_node(node)

# Destroy the node
node.destroy()

API Reference

class libcloud.compute.drivers.ecs.ECSDriver(key, secret=None, secure=True, host=None, port=None, api_version=None, region=None, **kwargs)[source]

Aliyun ECS node driver.

Used for Aliyun ECS service.

TODO: Get guest OS root password Adjust internet bandwidth settings Manage security groups and rules

Parameters
  • key (str) – API key or username to be used (required)

  • secret (str) – Secret password to be used (required)

  • secure (bool) – Whether to use HTTPS or HTTP. Note: Some providers only support HTTPS, and it is on by default.

  • host (str) – Override hostname used for connections.

  • port (int) – Override port used for connections.

  • api_version (str) – Optional API version. Only used by drivers which support multiple API versions.

  • region (str) – Optional driver region. Only used by drivers which support multiple regions.

Return type

None

attach_volume(node, volume, device=None, ex_delete_with_instance=None)[source]

Attaches volume to node.

@inherits NodeDriver.attach_volume

Parameters
  • device (str between /dev/xvdb to xvdz, if empty, allocated by the system) – device path allocated for this attached volume

  • ex_delete_with_instance (bool) – if to delete this volume when the instance is deleted.

connectionCls

alias of ECSConnection

copy_image(source_region, node_image, name, description=None, ex_destination_region_id=None, ex_client_token=None)[source]

Copies an image from a source region to the destination region. If not provide a destination region, default to the current region.

@inherits NodeDriver.copy_image

Parameters
  • ex_destination_region_id (str) – id of the destination region

  • ex_client_token (str) – a token generated by client to identify each request.

create_image(node, name, description=None, ex_snapshot_id=None, ex_image_version=None, ex_client_token=None)[source]

Creates an image from a system disk snapshot.

@inherits NodeDriver.create_image

Parameters
  • ex_snapshot_id (str) – the id of the snapshot to create the image. (required)

  • ex_image_version (str) – the version number of the image

  • ex_client_token (str) – a token generated by client to identify each request.

create_key_pair(name)

Create a new key pair object.

Parameters

name (str) – Key pair name.

Return type

KeyPair object

create_node(name, size, image, auth=None, ex_security_group_id=None, ex_description=None, ex_internet_charge_type=None, ex_internet_max_bandwidth_out=None, ex_internet_max_bandwidth_in=None, ex_hostname=None, ex_io_optimized=None, ex_system_disk=None, ex_data_disks=None, ex_vswitch_id=None, ex_private_ip_address=None, ex_client_token=None, **kwargs)[source]

@inherits: NodeDriver.create_node

Parameters
  • name (str) – The name for this new node (required)

  • image (NodeImage) – The image to use when creating this node (required)

  • size (NodeSize) – The size of the node to create (required)

  • auth (NodeAuthSSHKey or NodeAuthPassword) – Initial authentication information for the node (optional)

  • ex_security_group_id (str) – The id of the security group the new created node is attached to. (required)

  • ex_description (str) – A description string for this node (optional)

  • ex_internet_charge_type (a str of ‘PayByTraffic’ or ‘PayByBandwidth’) – The internet charge type (optional)

  • ex_internet_max_bandwidth_out (a int in range [0, 100] a int in range [1, 100] for ‘PayByTraffic’ internet charge type) – The max output bandwidth, in Mbps (optional) Required for ‘PayByTraffic’ internet charge type

  • ex_internet_max_bandwidth_in (a int in range [1, 200] default to 200 in server side) – The max input bandwidth, in Mbps (optional)

  • ex_hostname (str) – The hostname for the node (optional)

  • ex_io_optimized (boll) – Whether the node is IO optimized (optional)

  • ex_system_disk (dict) – The system disk for the node (optional)

  • ex_data_disks (a list of dict) – The data disks for the node (optional)

  • ex_vswitch_id (str) – The id of vswitch for a VPC type node (optional)

  • ex_private_ip_address (str) – The IP address in private network (optional)

  • ex_client_token – A token generated by client to keep requests idempotency (optional)

create_public_ip(instance_id)[source]

Create public ip.

Parameters

instance_id (str) – instance id for allocating public ip.

:return public ip :rtype str

create_volume(size, name, location=None, snapshot=None, ex_zone_id=None, ex_description=None, ex_disk_category=None, ex_client_token=None)[source]

Create a new volume.

@inherites NodeDriver.create_volume

Parameters
  • ex_zone_id (str) – the availability zone id (required)

  • ex_description (unicode) – volume description

  • ex_disk_category (str) – disk category for data disk

  • ex_client_token (str) – a token generated by client to identify each request.

create_volume_snapshot(volume, name=None, ex_description=None, ex_client_token=None)[source]

Creates a snapshot of the storage volume.

@inherits NodeDriver.create_volume_snapshot

Parameters
  • ex_description (unicode) – description of the snapshot.

  • ex_client_token (str) – a token generated by client to identify each request.

delete_image(node_image)[source]

Deletes a node image from a provider.

Parameters

node_image (NodeImage) – Node image object.

Returns

True if delete_image was successful, False otherwise.

Return type

bool

delete_key_pair(key_pair)

Delete an existing key pair.

Parameters

key_pair (KeyPair) – Key pair object.

Return type

bool

deploy_node(deploy, ssh_username='root', ssh_alternate_usernames=None, ssh_port=22, ssh_timeout=10, ssh_key=None, ssh_key_password=None, auth=None, timeout=300, max_tries=3, ssh_interface='public_ips', at_exit_func=None, wait_period=5, **create_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 available 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)

  • ssh_key_password (str) – Optional password used for encrypted keys.

  • 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’.

  • at_exit_func (func) –

    Optional atexit handler function which will be registered and called with created node if user cancels the deploy process (e.g. CTRL+C), after the node has been created, but before the deploy process has finished.

    This method gets passed in two keyword arguments:

    • driver -> node driver in question

    • node -> created Node object

    Keep in mind that this function will only be called in such scenario. In case the method finishes (this includes throwing an exception), at exit handler function won’t be called.

  • wait_period (int) – How many seconds to wait between each iteration while waiting for node to transition into running state and have IP assigned. (default is 5)

destroy_node(node)[source]

Destroy a node.

Depending upon the provider, this may destroy all data associated with the node, including backups.

Parameters

node (Node) – The node to be destroyed

Returns

True if the destroy was successful, False otherwise.

Return type

bool

destroy_volume(volume)[source]

Destroys a storage volume.

Parameters

volume (StorageVolume) – Volume to be destroyed

Return type

bool

destroy_volume_snapshot(snapshot)[source]

Destroys a snapshot.

Parameters

snapshot (VolumeSnapshot) – The snapshot to delete

Return type

bool

detach_volume(volume, ex_instance_id=None)[source]

Detaches a volume from a node.

@inherits NodeDriver.detach_volume

Parameters

ex_instance_id (str) – the id of the instance from which the volume is detached.

disk_categories

alias of DiskCategory

ex_create_security_group(description=None, client_token=None)[source]

Create a new security group.

Parameters
  • description (unicode) – security group description

  • client_token (str) – a token generated by client to identify each request.

ex_delete_security_group_by_id(group_id=None)[source]

Delete a new security group.

Parameters

group_id (str) – security group id

ex_join_security_group(node, group_id=None)[source]

Join a node into security group.

Parameters
  • node (Node) – The node to join security group

  • group_id (str) – security group id.

Returns

join operation result.

Return type

bool

ex_leave_security_group(node, group_id=None)[source]

Leave a node from security group.

Parameters
  • node (Node) – The node to leave security group

  • group_id (str) – security group id.

Returns

leave operation result.

Return type

bool

ex_list_security_group_attributes(group_id=None, nic_type='internet')[source]

List security group attributes in the current region.

Parameters
  • group_id (str) – security group id.

  • nic_type (str) – internet|intranet.

Returns

a list of defined security group Attributes

Return type

list of ECSSecurityGroupAttribute

ex_list_security_groups(ex_filters=None)[source]

List security groups in the current region.

Parameters

ex_filters (dict) – security group attributes to filter results.

Returns

a list of defined security groups

Return type

list of ECSSecurityGroup

ex_list_zones(region_id=None)[source]

List availability zones in the given region or the current region.

Parameters

region_id (str) – the id of the region to query zones from

Returns

list of zones

Return type

list of ECSZone

ex_modify_security_group_by_id(group_id=None, name=None, description=None)[source]

Modify a new security group. :keyword group_id: id of the security group :type group_id: str :keyword name: new name of the security group :type name: unicode :keyword description: new description of the security group :type description: unicode

features = {'create_node': ['password']}
List of available features for a driver.
get_image(image_id, ex_region_id=None)[source]

Returns a single node image from a provider.

Parameters

image_id (str) – Node to run the task on.

:rtype NodeImage: :return: NodeImage instance on success.

get_key_pair(name)

Retrieve a single key pair.

Parameters

name (str) – Name of the key pair to retrieve.

Return type

KeyPair

import_key_pair_from_file(name, key_file_path)

Import a new public key from string.

Parameters
  • name (str) – Key pair name.

  • key_file_path (str) – Path to the public key file.

Return type

KeyPair object

import_key_pair_from_string(name, key_material)

Import a new public key from string.

Parameters
  • name (str) – Key pair name.

  • key_material (str) – Public key material.

Return type

KeyPair object

internet_charge_types

alias of InternetChargeType

list_images(location=None, ex_image_ids=None, ex_filters=None)[source]

List images on a provider.

@inherits NodeDriver.list_images

Parameters
  • ex_image_ids (list of str) – a list of image ids to filter the images to be returned.

  • ex_filters (dict) – image attribute and value pairs to filter images. Only the image which matchs all the pairs will be returned. If the filter attribute need a json array value, use list object, the driver will convert it.

list_key_pairs()

List all the available key pair objects.

Return type

list of KeyPair objects

list_locations()[source]

List data centers for a provider

Returns

list of node location objects

Return type

list of NodeLocation

list_nodes(ex_node_ids=None, ex_filters=None)[source]

List all nodes.

@inherits: NodeDriver.create_node

Parameters
  • ex_node_ids (list of str) – a list of node’s ids used to filter nodes. Only the nodes which’s id in this list will be returned.

  • ex_filters (dict) – node attribute and value pairs to filter nodes. Only the nodes which matchs all the pairs will be returned. If the filter attribute need a json array value, use list object, the driver will convert it.

list_sizes(location=None)[source]

List sizes on a provider

Parameters

location (NodeLocation) – The location at which to list sizes

Returns

list of node size objects

Return type

list of NodeSize

list_volume_snapshots(volume, ex_snapshot_ids=[], ex_filters=None)[source]

List snapshots for a storage volume.

@inherites NodeDriver.list_volume_snapshots

Parameters
  • ex_snapshot_ids (list of str) – a list of snapshot ids to filter the snapshots returned.

  • ex_filters (dict) – snapshot attribute and value pairs to filter snapshots. Only the snapshot which matchs all the pairs will be returned. If the filter attribute need a json array value, use list object, the driver will convert it.

list_volumes(ex_volume_ids=None, ex_filters=None)[source]

List all volumes.

@inherits: NodeDriver.list_volumes

Parameters
  • ex_volume_ids (list of str) – a list of volume’s ids used to filter volumes. Only the volumes which’s id in this list will be returned.

  • ex_filters (dict) – volume attribute and value pairs to filter volumes. Only the volumes which matchs all will be returned. If the filter attribute need a json array value, use list object, the driver will convert it.

reboot_node(node, ex_force_stop=False)[source]

Reboot the given node

@inherits NodeDriver.reboot_node

Parameters

ex_force_stop (bool) – if True, stop node force (maybe lose data) otherwise, stop node normally, default to False

start_node(node)[source]

Start node to running state.

Parameters

node (Node) – the Node object to start

Returns

starting operation result.

Return type

bool

stop_node(node, ex_force_stop=False)[source]

Stop a running node.

Parameters
  • node (Node) – The node to stop

  • ex_force_stop (bool) – if True, stop node force (maybe lose data) otherwise, stop node normally, default to False

Returns

stopping operation result.

Return type

bool

wait_until_running(nodes, wait_period=5, timeout=600, ssh_interface='public_ips', force_ipv4=True, ex_list_nodes_kwargs=None)

Block until the provided nodes are considered running.

Node is considered running when it’s state is “running” and when it has at least one IP address assigned.

Parameters
  • nodes (list of Node) – List of nodes to wait for.

  • wait_period (int) – How many seconds to wait between each loop iteration. (default is 3)

  • timeout (int) – How many seconds to wait before giving up. (default is 600)

  • ssh_interface (str) – Which attribute on the node to use to obtain an IP address. Valid options: public_ips, private_ips. Default is public_ips.

  • force_ipv4 (bool) – Ignore IPv6 addresses (default is True).

  • ex_list_nodes_kwargs (dict) – Optional driver-specific keyword arguments which are passed to the list_nodes method.

Returns

[(Node, ip_addresses)] list of tuple of Node instance and list of ip_address on success.

Return type

list of tuple