You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@libcloud.apache.org by to...@apache.org on 2016/03/12 22:52:42 UTC
[08/10] libcloud git commit: [LIBCLOUD-802] Add doc page and examples
for Aliyun ecs
[LIBCLOUD-802] Add doc page and examples for Aliyun ecs
Signed-off-by: Tomaz Muraus <to...@tomaz.me>
Closes #712
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/a8479e18
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/a8479e18
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/a8479e18
Branch: refs/heads/trunk
Commit: a8479e18b288460f64d8b82327d9e11db1abf23d
Parents: ae4c482
Author: xg.song <sa...@gmail.com>
Authored: Sat Mar 12 00:25:43 2016 +0800
Committer: Tomaz Muraus <to...@tomaz.me>
Committed: Sat Mar 12 13:29:01 2016 -0800
----------------------------------------------------------------------
docs/compute/drivers/aliyun_ecs.rst | 101 +++++++++++++++++++
.../compute/ecs/ex_list_security_groups.py | 15 +++
docs/examples/compute/ecs/list_images.py | 15 +++
docs/examples/compute/ecs/list_locations.py | 14 +++
docs/examples/compute/ecs/list_sizes.py | 15 +++
docs/examples/compute/ecs/manage_nodes.py | 56 ++++++++++
.../compute/ecs/manage_volumes_and_snapshots.py | 26 +++++
libcloud/compute/drivers/ecs.py | 75 ++++++++++----
8 files changed, 299 insertions(+), 18 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/docs/compute/drivers/aliyun_ecs.rst
----------------------------------------------------------------------
diff --git a/docs/compute/drivers/aliyun_ecs.rst b/docs/compute/drivers/aliyun_ecs.rst
new file mode 100644
index 0000000..4103c10
--- /dev/null
+++ b/docs/compute/drivers/aliyun_ecs.rst
@@ -0,0 +1,101 @@
+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:
+
+.. literalinclude:: /examples/compute/ecs/list_locations.py
+ :language: python
+
+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:
+
+.. literalinclude:: /examples/compute/ecs/list_sizes.py
+ :language: python
+
+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:
+
+.. literalinclude:: /examples/compute/ecs/ex_list_security_groups.py
+ :language: python
+
+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:
+
+.. literalinclude:: /examples/compute/ecs/list_images.py
+ :language: python
+
+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:
+
+.. literalinclude:: /examples/compute/ecs/manage_volumes_and_snapshots.py
+ :language: python
+
+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
+-----------------------------
+
+.. literalinclude:: /examples/compute/ecs/manage_nodes.py
+ :language: python
+
+API Reference
+-------------
+
+.. autoclass:: libcloud.compute.drivers.ecs.ECSDriver
+ :members:
+ :inherited-members:
+
+.. _`Aliyun(AliCloud) Elastic Compute Service (ECS)`: https://www.aliyun.com/product/ecs/?lang=en
+.. _`Instance Generations`: https://docs.aliyun.com/en#/pub/ecs_en_us/product-introduction/instance&instancegeneration
+.. _`Instance Type Families`: https://docs.aliyun.com/en#/pub/ecs_en_us/product-introduction/instance&instancetypefamily
+.. _`Instance Type`: https://docs.aliyun.com/en#/pub/ecs_en_us/product-introduction/instance&type
+.. _`Security Groups`: https://docs.aliyun.com/en#/pub/ecs_en_us/product-introduction/network&securitygroup
+.. _`Storage`: https://docs.aliyun.com/en#/pub/ecs_en_us/product-introduction/storage&summary
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/docs/examples/compute/ecs/ex_list_security_groups.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/ecs/ex_list_security_groups.py b/docs/examples/compute/ecs/ex_list_security_groups.py
new file mode 100644
index 0000000..554f627
--- /dev/null
+++ b/docs/examples/compute/ecs/ex_list_security_groups.py
@@ -0,0 +1,15 @@
+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)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/docs/examples/compute/ecs/list_images.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/ecs/list_images.py b/docs/examples/compute/ecs/list_images.py
new file mode 100644
index 0000000..e70a99d
--- /dev/null
+++ b/docs/examples/compute/ecs/list_images.py
@@ -0,0 +1,15 @@
+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)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/docs/examples/compute/ecs/list_locations.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/ecs/list_locations.py b/docs/examples/compute/ecs/list_locations.py
new file mode 100644
index 0000000..c824c76
--- /dev/null
+++ b/docs/examples/compute/ecs/list_locations.py
@@ -0,0 +1,14 @@
+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))
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/docs/examples/compute/ecs/list_sizes.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/ecs/list_sizes.py b/docs/examples/compute/ecs/list_sizes.py
new file mode 100644
index 0000000..7df6630
--- /dev/null
+++ b/docs/examples/compute/ecs/list_sizes.py
@@ -0,0 +1,15 @@
+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)
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/docs/examples/compute/ecs/manage_nodes.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/ecs/manage_nodes.py b/docs/examples/compute/ecs/manage_nodes.py
new file mode 100644
index 0000000..7507048
--- /dev/null
+++ b/docs/examples/compute/ecs/manage_nodes.py
@@ -0,0 +1,56 @@
+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()
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/docs/examples/compute/ecs/manage_volumes_and_snapshots.py
----------------------------------------------------------------------
diff --git a/docs/examples/compute/ecs/manage_volumes_and_snapshots.py b/docs/examples/compute/ecs/manage_volumes_and_snapshots.py
new file mode 100644
index 0000000..de5aeb6
--- /dev/null
+++ b/docs/examples/compute/ecs/manage_volumes_and_snapshots.py
@@ -0,0 +1,26 @@
+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')
http://git-wip-us.apache.org/repos/asf/libcloud/blob/a8479e18/libcloud/compute/drivers/ecs.py
----------------------------------------------------------------------
diff --git a/libcloud/compute/drivers/ecs.py b/libcloud/compute/drivers/ecs.py
index 7929720..c9d53f8 100644
--- a/libcloud/compute/drivers/ecs.py
+++ b/libcloud/compute/drivers/ecs.py
@@ -457,6 +457,12 @@ class ECSDriver(NodeDriver):
Aliyun ECS node driver.
Used for Aliyun ECS service.
+
+ TODO:
+ Create public IP address
+ Get guest OS root password
+ Adjust internet bandwidth settings
+ Manage security groups and rules
"""
name = 'Aliyun ECS'
@@ -693,7 +699,10 @@ class ECSDriver(NodeDriver):
def reboot_node(self, node, ex_force_stop=False):
"""
+ Reboot the given node
+
@inherits :class:`NodeDriver.reboot_node`
+
:keyword ex_force_stop: if ``True``, stop node force (maybe lose data)
otherwise, stop node normally,
default to ``False``
@@ -725,7 +734,9 @@ class ECSDriver(NodeDriver):
"""
Start node to running state.
- :param node: ``Node`` object
+ :param node: the ``Node`` object to start
+ :type node: ``Node``
+
:return: starting operation result.
:rtype: ``bool``
"""
@@ -741,10 +752,12 @@ class ECSDriver(NodeDriver):
:param node: The node to stop
:type node: :class:`Node`
+
:keyword ex_force_stop: if ``True``, stop node force (maybe lose data)
otherwise, stop node normally,
default to ``False``
:type ex_force_stop: ``bool``
+
:return: stopping operation result.
:rtype: ``bool``
"""
@@ -761,6 +774,7 @@ class ECSDriver(NodeDriver):
:keyword ex_filters: security group attributes to filter results.
:type ex_filters: ``dict``
+
:return: a list of defined security groups
:rtype: ``list`` of ``ECSSecurityGroup``
"""
@@ -782,8 +796,10 @@ class ECSDriver(NodeDriver):
def ex_list_zones(self, region_id=None):
"""
List availability zones in the given region or the current region.
+
:keyword region_id: the id of the region to query zones from
:type region_id: ``str``
+
:return: list of zones
:rtype: ``list`` of ``ECSZone``
"""
@@ -808,16 +824,17 @@ class ECSDriver(NodeDriver):
@inherits: :class:`NodeDriver.list_volumes`
- :keyword ex_volume_ids: a list of volume's ids used to filter volumes.
- Only the volumes which's id in this list
- will be returned.
- :type ex_volume_ids: ``list`` of ``str``
- :keyword ex_filters: 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.
- :type ex_filters: ``dict``
+ :keyword ex_volume_ids: a list of volume's ids used to filter volumes.
+ Only the volumes which's id in this list
+ will be returned.
+ :type ex_volume_ids: ``list`` of ``str``
+
+ :keyword ex_filters: 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.
+ :type ex_filters: ``dict``
"""
params = {'Action': 'DescribeDisks',
'RegionId': self.region}
@@ -851,15 +868,17 @@ class ECSDriver(NodeDriver):
List snapshots for a storage volume.
@inherites :class:`NodeDriver.list_volume_snapshots`
+
:keyword ex_snapshot_ids: a list of snapshot ids to filter the
snapshots returned.
:type ex_snapshot_ids: ``list`` of ``str``
+
:keyword ex_filters: 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.
- :type ex_filters: ``dict``
+ :type ex_filters: ``dict``
"""
params = {'Action': 'DescribeSnapshots',
'RegionId': self.region}
@@ -888,14 +907,18 @@ class ECSDriver(NodeDriver):
Create a new volume.
@inherites :class:`NodeDriver.create_volume`
+
:keyword ex_zone_id: the availability zone id (required)
:type ex_zone_id: ``str``
+
:keyword ex_description: volume description
:type ex_description: ``unicode``
+
:keyword ex_disk_category: disk category for data disk
:type ex_disk_category: ``str``
+
:keyword ex_client_token: a token generated by client to identify
- each request.
+ each request.
:type ex_client_token: ``str``
"""
params = {'Action': 'CreateDisk',
@@ -927,11 +950,14 @@ class ECSDriver(NodeDriver):
ex_client_token=None):
"""
Creates a snapshot of the storage volume.
+
@inherits :class:`NodeDriver.create_volume_snapshot`
+
:keyword ex_description: description of the snapshot.
:type ex_description: ``unicode``
+
:keyword ex_client_token: a token generated by client to identify
- each request.
+ each request.
:type ex_client_token: ``str``
"""
params = {'Action': 'CreateSnapshot',
@@ -960,8 +986,11 @@ class ECSDriver(NodeDriver):
@inherits :class:`NodeDriver.attach_volume`
+ :keyword device: device path allocated for this attached volume
+ :type device: ``str`` between /dev/xvdb to xvdz,
+ if empty, allocated by the system
:keyword ex_delete_with_instance: if to delete this volume when the
- instance is deleted.
+ instance is deleted.
:type ex_delete_with_instance: ``bool``
"""
params = {'Action': 'AttachDisk',
@@ -1035,16 +1064,19 @@ class ECSDriver(NodeDriver):
def list_images(self, location=None, ex_image_ids=None, ex_filters=None):
"""
List images on a provider.
+
@inherits :class:`NodeDriver.list_images`
+
:keyword ex_image_ids: a list of image ids to filter the images to
be returned.
:type ex_image_ids: ``list`` of ``str``
+
:keyword ex_filters: 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.
- :type ex_filters: ``dict``
+ :type ex_filters: ``dict``
"""
if location and isinstance(location, NodeLocation):
@@ -1075,14 +1107,18 @@ class ECSDriver(NodeDriver):
ex_image_version=None, ex_client_token=None):
"""
Creates an image from a system disk snapshot.
+
@inherits :class:`NodeDriver.create_image`
+
:keyword ex_snapshot_id: the id of the snapshot to create the image.
(required)
:type ex_snapshot_id: ``str``
+
:keyword ex_image_version: the version number of the image
:type ex_image_version: ``str``
+
:keyword ex_client_token: a token generated by client to identify
- each request.
+ each request.
:type ex_client_token: ``str``
"""
params = {'Action': 'CreateImage',
@@ -1130,11 +1166,14 @@ class ECSDriver(NodeDriver):
"""
Copies an image from a source region to the destination region.
If not provide a destination region, default to the current region.
+
@inherits :class:`NodeDriver.copy_image`
+
:keyword ex_destination_region_id: id of the destination region
:type ex_destination_region_id: ``str``
+
:keyword ex_client_token: a token generated by client to identify
- each request.
+ each request.
:type ex_client_token: ``str``
"""
params = {'Action': 'CopyImage',