aliyun.ecs.connection module

class aliyun.ecs.connection.EcsConnection(region_id, access_key_id=None, secret_access_key=None)

Bases: aliyun.connection.Connection

A connection to Aliyun ECS service.

Parameters:

• region_id (str) – The id of the region to connect to.
• access_key_id (str) – The access key id.
• secret_access_key (str) – The secret access key.

add_disk(instance_id, size=None, snapshot_id=None, name=None, description=None, device=None, delete_with_instance=None)

Create and attach a non-durable disk to an instance.

This is convenience method, combining create_disk and attach_disk.

A new disk will be allocated for the instance and attached as the next available disk letter to the OS. The disk is a plain block device with no partitions nor filesystems.

Either size or snapshot_id must be specified, but not both. If snapshot_id is specified, the size will be taken from the snapshot.

If the snapshot referenced was created before 15 July, 2013, the API will throw an error of InvalidSnapshot.TooOld.

Parameters:

• instance_id (str) – ID of the instance to add the disk to.
• size (int) – Size of the disk in GB. Must be in the range [5-2048].
• snapshot_id (str) – The snapshot ID to create a disk from. If used, the size will be taken from the snapshot and the given size will be disregarded.
• name (str) – A short name for the disk.
• description (str) – A longer description of the disk.
• device (str) – The full device path for the attached device. E.g. /dev/xvdb. Valid values: /dev/xvd[b-z].
• delete_with_instance (bool) – Whether to delete the disk when its

Returns:

the ID to reference the created disk.

Return type:

disk_id (str)

Raises:

• Error – if size and snapshot_id are used.
• Error – InvalidSnapshot.TooOld if referenced snapshot is too old.

add_external_cidr_ip_rule(security_group_id, ip_protocol, port_range, source_cidr_ip, policy=None)

Add a rule for an external CidrIp to a security group.

Parameters:

• security_group_id (str) – The id of the security group.
• ip_protocol (str) – TCP, UDP, ICMP, GRE or ALL
• port_range (str) – For tcp/udp range is 1 to 65535. Else -1/-1.
• source_cidr_ip (str) – Source IP address range.
• policy (str) – Accept, Drop or Reject. Default: Accept.

add_group_rule(security_group_id, ip_protocol, port_range, source_group_id, policy=None)

Add a rule for one security group to access another security group.

Parameters:

• security_group_id (str) – The id of the security group.
• ip_protocol (str) – TCP, UDP, ICMP, GRE or ALL
• port_range (str) – For tcp/udp range is 1 to 65535. Else -1/-1.
• source_group_id (str) – Source security group.
• policy (str) – Accept, Drop or Reject. Default: Accept.

add_internal_cidr_ip_rule(security_group_id, ip_protocol, port_range, source_cidr_ip, policy=None)

Add a rule for an internal CidrIp to a security group.

Parameters:

• security_group_id (str) – The id of the security group.
• ip_protocol (str) – TCP, UDP, ICMP, GRE or ALL
• port_range (str) – For tcp/udp range is 1 to 65535. Else -1/-1.
• source_cidr_ip (str) – Source IP address range.
• policy (str) – Accept, Drop or Reject. Default: Accept.

allocate_public_ip(instance_id)

Allocate and assign a public IP address to an instance.

Parameters:instance_id (str) – instance ID to add a public IP to. Returns:the public IP allocated to the instance.

attach_disk(instance_id, disk_id, device=None, delete_with_instance=None)

Attach an existing disk to an existing instance. The disk and instance must already exist. The instance must be in the Stopped state, or the disk will be attached at next reboot.

The disk will be attached at the next available drive letter (e.g. in linux, /dev/xvdb if only /dev/xvda exists). It will be a raw and un-formatted block device.

Parameters:

• instance_id (str) – ID of the instance to add the disk to.
• disk_id (str) – ID of the disk to delete.
• device (str) – The full device path for the attached device. E.g. /dev/xvdb. Valid values: /dev/xvd[b-z].
• delete_with_instance (bool) – Whether to delete the disk when its associated instance is deleted.

create_and_start_instance(image_id, instance_type, initial_security_group_id, additional_security_group_ids=[], instance_name=None, internet_max_bandwidth_in=None, internet_max_bandwidth_out=None, hostname=None, password=None, system_disk_type=None, internet_charge_type=None, assign_public_ip=True, block_till_ready=True, data_disks=None, description=None, zone_id=None)

Create and start an instance.

This is a convenience method that does more than just create_instance. You can specify a list of security groups (5 total) and the method also starts the instance. It can optionally block for the instance to be running - by default it does block.

Specifying additional data disks is covered in create_instance().

Parameters:

• image_id (str) – Which image id to use.
• instance_type (str) – The type of the instance. To see options use describe_instance_types.
• initial_security_group_id (str) – The security group id on creation.
• additional_security_group_ids (list) – Additional security groups to use. Note: Max size 4.
• instance_name (str) – The name to use for the instance.
• internet_max_bandwidth_in (int) – Max bandwidth in.
• internet_max_bandwidth_out (int) – Max bandwidth out.
• hostname (str) – The hostname to assign.
• password (str) – The root password to assign.
• system_disk_type (str) – cloud, ephemeral or ephemeral_hio. Default: cloud.
• internet_charge_type (str) – PayByBandwidth or PayByTraffic. Default: PayByBandwidth.
• assign_public_ip (bool) – Whether the instance should get assigned a public ip address. Default: True.
• block_till_ready (bool) – Whether to block till the instance is running. Default: True.
• data_disks (list) – List of dictionaries defining additional data disk device mappings. Minimum example: [{‘category’: ‘cloud’, ‘size’: 1024}]
• description (str) – A long description of the instance.
• zone_id (str) – An Availability Zone in the region to put the instance in. E.g. ‘cn-hangzhou-b’

Returns:

The id of the instance created.

Raises:

• Error – if more then 4 additional security group ids specified.
• Error – if timeout while waiting for instance to be running.

The data_disks device mapping dictionary describes the same Disk attributes as create_disk():

[{
   'category': 'ephemeral',
   'size': 200,
   'name': 'mydiskname',
   'description': 'my disk description',
   'device': '/dev/xvdb'
},
{
   'category': 'ephemeral',
   'snapshot_id': 'snap-1234',
   'name': 'mydiskname',
   'description': 'my disk description',
   'device': '/dev/xvdb'
}]

The API supports up to 4 additional disks, each up to 1TB, so to get the maximum disk space at instance creation, this should do the trick:

[
    {'category': 'cloud', 'size': 1024},
    {'category': 'cloud', 'size': 1024},
    {'category': 'cloud', 'size': 1024},
    {'category': 'cloud', 'size': 1024}
]

create_disk(zone_id, name=None, description=None, size=None, snapshot_id=None)

Create a non-durable disk. A new disk will be created and can be managed independently of instance.

Either size or snapshot_id must be specified, but not both. If snapshot_id is specified, the size will be taken from the snapshot.

If the snapshot referenced was created before 15 July, 2013, the API will throw an error of InvalidSnapshot.TooOld.

Parameters:

• zone_id (str) – the Availability Zone to create the disk in. This is required and cannot be changed. E.g. cn-hangzhou-a.
• name (str) – A short name for the disk.
• description (str) – A longer description of the disk.
• size (int) – Size of the disk in GB. Must be in the range [5-2048].
• snapshot_id (str) – The snapshot ID to create a disk from. If used, the size will be taken from the snapshot and the given size will be disregarded.

Returns:

The ID to reference the created disk.

Return type:

(str)

create_image(snapshot_id, image_version=None, description=None, os_name=None)

Create an image.

Parameters:

• snapshot_id (str) – The id of the snapshot to create the image from.
• image_version (str) – The version of the image.
• description (str) – The description of the image.
• os_name (str) – The os name.

Returns:

The image id.

create_image_from_instance(instance_id, image_version=None, description=None, os_name=None, timeout_secs=600)

Create an image from an instance.

This is a convenience method that handles creating the snapshot from the system disk and then creates the image.

Parameters:

• instance_id (str) – The id of the instance.
• image_version (str) – The version of the image.
• description (str) – The description.
• os_name (str) – The os name.
• timeout_secs (int) – How long to wait for the snapshot to be created. Default: 600.

Returns:

The (snapshot id, image id) pair.

Raises:

Error – if the system disk cannot be found or if the snapshot creation process times out.

create_instance(image_id, instance_type, security_group_id, instance_name=None, internet_max_bandwidth_in=None, internet_max_bandwidth_out=None, hostname=None, password=None, system_disk_type=None, internet_charge_type=None, data_disks=None, description=None, zone_id=None)

Create an instance.

Parameters:

• image_id (str) – Which image id to use.
• instance_type (str) – The type of the instance. To see options use describe_instance_types.
• security_group_id (str) – The security group id to associate.
• instance_name (str) – The name to use for the instance.
• internet_max_bandwidth_in (int) – Max bandwidth in.
• internet_max_bandwidth_out (int) – Max bandwidth out.
• hostname (str) – The hostname to assign.
• password (str) – The root password to assign.
• system_disk_type (str) – cloud, ephemeral or ephemeral_hio. Default: cloud.
• internet_charge_type (str) – PayByBandwidth or PayByTraffic. Default: PayByBandwidth.
• data_disks (list) – List of *args or **kwargs to DiskMapping
• description (str) – A long description of the instance.
• zone_id (str) – An Availability Zone in the region to put the instance in. E.g. ‘cn-hangzhou-b’

Returns:

The id of the instance created.

The data_disks argument is passed as *args (if not a dict) or **kwargs (if it is a dict) to create a new model.DiskMapping. To create two fully-specified data disks:

[{
   'category': 'ephemeral',
   'size': 200,
   'name': 'mydiskname',
   'description': 'my disk description',
   'device': '/dev/xvdb'
},
{
   'category': 'ephemeral',
   'snapshot_id': 'snap-1234',
   'name': 'mydiskname',
   'description': 'my disk description',
   'device': '/dev/xvdb'
}]

To create two minimally-specified data disks of 2000GB each::

[('cloud', 2000), ('cloud', 2000)]

The API supports up to 4 additional disks, each up to 2000GB, so to get the maximum disk space at instance creation, this should do the trick:

[
    {'category': 'cloud', 'size': 2000},
    {'category': 'cloud', 'size': 2000},
    {'category': 'cloud', 'size': 2000},
    {'category': 'cloud', 'size': 2000}
]

create_security_group(description)

Create a security group.

Parameters:description (str) – The description. Returns:The security group id.

create_snapshot(instance_id, disk_id, snapshot_name=None, timeout_secs=None, description=None)

Create a snapshot of a disk.

The instance has to be in the running or stopped state.

Parameters:

• instance_id (str) – The id of the instance.
• disk_id (str) – The id of the disk.
• snapshot_name (str) – The name to assign to the snapshot.
• timeout_secs (int) – If you want to block till the snapshot is ready you can specify how long to wait for.
• description (str) – A description of the snapshot.

Returns:

The snapshot id.

Raises:

Error – if a timeout is given and the snapshot is not ready by then.

delete_disk(disk_id)

Delete a disk from an instance.

If the instance state is running, the disk will be removed after reboot. If the instance state is stopped, the disk will be removed immediately.

Parameters:

• instance_id (str) – ID of the instance to delete a disk from.
• disk_id (str) – ID of the disk to delete.

delete_image(image_id)

Delete an image.

Parameters:image_id (str) – The id of the image.

delete_instance(instance_id)

Delete an instance.

Parameters:instance_id (str) – The id of the instance.

delete_security_group(security_group_id)

Delete a security group.

Parameters:security_group_id (str) – The id of the security group.

delete_snapshot(instance_id, snapshot_id)

Delete a snapshot.

Parameters:

• instance_id (str) – The id of the instance.
• snapshot_id (str) – The id of the snapshot.

describe_auto_snapshot_policy()

Describe the Auto-Snapshot policy for both data- and system-disks.

Returns:model.AutoSnapshotPolicyResponse.

describe_disks(zone_id=None, disk_ids=None, instance_id=None, disk_type=None, category=None, status=None, snapshot_id=None, portable=None, delete_with_instance=None, delete_auto_snapshot=None)

List the disks in the region. All arguments are optional to allow restricting the disks retrieved.

Parameters:

• zone_id (str) – Availability Zone of the disks.
• disk_ids (list) – List of disk ids to retrieve.
• instance_id (str) – ID of instance retrieved disks are attached to.
• disk_type (str) – “system”, “data”, or “all” (default).
• category (str) – “cloud”, “ephemeral”, or “all” (default).
• status (str) – Restrict to disks only with this status. “In_use”, “Available”, “Attaching”, “Detaching”, “Creating”, “ReIniting”, or “All” (default).
• snapshot_id (str) – Snapshot used to create the disk.
• portable (bool) – Whether the disk can be detached and re-attached elsewhere.
• delete_with_instance (bool) – Whether the disk will be deleted with its associated instance.
• delete_auto_snapshot (bool) – Whether the AutoSnapshotPolicy will be deleted with the Disk.

Returns:

List of model.Disk objects.

describe_images(image_ids=None, owner_alias=None, snapshot_id=None)

List images in the region matching params.

Parameters:

• image_ids (list) – List of image ids to filter on.
• owner_alias (list) – List of owner alias to filter on. Can be values: system, self, others or marketplace.
• snapshot_id (str) – List images only based off of this snapshot.

Returns:

class`.model.Image` objects.

Return type:

List of

describe_instance_disks(instance_id)

List the disks associated with an instance. This is now only a helper method which calls describe_disks with an ID.

Parameters:instance_id (str) – The id of the instance. Returns:List of model.Disk.

describe_instance_types()

List the instance types available.

Returns:List of model.InstanceType.

describe_security_groups()

List all the security groups in the region.

Returns:List of model.SecurityGroupInfo.

describe_snapshot(snapshot_id)

Describe a snapshot.

Parameters:snapshot_id (str) – The id of the snapshot. Returns:model.Snapshot.

describe_snapshots(instance_id=None, disk_id=None, snapshot_ids=None)

Describe snapshots, filtering by ids or originating disk.

Parameters:

• instance_id (str) – Instance ID.
• disk_id (str) – The originating disk ID to get snapshots for.
• snapshot_ids (list) – Filter to up to 10 specific snapshot IDs

Returns:

A list of model.Snapshot.

detach_disk(instance_id, disk_id)

Detach an existing disk from an existing instance.

Parameters:

• instance_id (str) – ID of the instance to add the disk to.
• disk_id (str) – ID of the disk to delete.

get_all_clusters()

Get a list of ECS clusters in the region.

Returns:List of cluster IDs.

get_all_instance_ids(zone_id=None)

Get all the instance ids in a region.

Parameters:zone_id (str, optional) – The Zone ID to get instance ids from. Returns:The list of instance ids.

get_all_instance_status(zone_id=None)

Get the instance statuses.

Parameters:zone_id (str, optional) – A specific zone id to get instances from. Returns:The list of model.InstanceStatus.

get_all_region_ids()

Get all the region ids.

Returns:List of region ids.

get_all_regions()

Get all regions.

Returns:A list of aliyun.ecs.model.Region Return type:list

get_all_zone_ids()

Get all availability zone ids in the region.

Returns:List of zone id strings.

get_all_zones()

Get all availability zones in the region.

Returns:List of model.Zone.

get_instance(instance_id)

Get an instance.

Parameters:instance_id (str) – The id of the instance. Returns:model.Instance if found. Raises:Error – if not found.

get_security_group(security_group_id)

Get a security group.

Parameters:security_group_id (str) – The id of the security group. Returns:The model.SecurityGroup object.

get_security_group_ids()

List all the security group ids in the region.

Returns:List of security group ids.

join_security_group(instance_id, security_group_id)

Add an instance to a security group.

Parameters:

• instance_id (str) – The id of the instance.
• security_group_id (str) – The id of the security_group.

leave_security_group(instance_id, security_group_id)

Remove an instance from a security group.

Parameters:

• instance_id (str) – The id of the instance.
• security_group_id (str) – The id of the security_group.

modify_auto_snapshot_policy(system_disk_policy_enabled, system_disk_policy_time_period, system_disk_policy_retention_days, system_disk_policy_retention_last_week, data_disk_policy_enabled, data_disk_policy_time_period, data_disk_policy_retention_days, data_disk_policy_retention_last_week)

Modify the account’s auto-snapshot policy.

Parameters:

• system_disk_policy_enabled (bool) – Enable/Disable for system disks.
• system_disk_policy_time_period (int) – Time period for system disk auto snapshots.
• system_disk_policy_retention_days (int) – Number of days to retain.
• system_disk_policy_retention_last_week (bool) – Keep/Discard Sunday’s auto-snapshot.
• data_disk_policy_enabled (bool) – Enable/Disable for data disks.
• data_disk_policy_time_period (int) – Time period for data disk auto snapshots.
• data_disk_policy_retention_days (int) – Number of days to retain.
• data_disk_policy_retention_last_week (bool) – Keep/Discard Sunday’s auto-snapshot.

modify_disk(disk_id, name=None, description=None, delete_with_instance=None)

Modify information about a disk.

Parameters:

• disk_id (str) – The Disk to modify/update.
• name (str) – The new disk name.
• description (str) – The new disk description.
• delete_with_instance (str) – Change whether to delete the disk with its associated instance.

modify_instance(instance_id, new_instance_name=None, new_password=None, new_hostname=None, new_security_group_id=None, new_description=None)

Modify certain attributes of an instance.

Only attributes that you want to modify should be specified. If you want to associated multiple security groups with an instance use the join_security_group method.

Parameters:

• instance_id (str) – The id of the instance.
• new_instance_name (str) – The new instance name.
• new_password (str) – The new root password for the instance. This requires a reboot to take effect.
• new_hostname (str) – The new hostname for the instance.
• new_security_group_id (str) – A single security group id.
• new_description (str) – The new description for the instance.

modify_instance_spec(instance_id, instance_type=None, internet_max_bandwidth_out=None, internet_max_bandwidth_in=None)

NOT PUBLICLY AVAILABLE: Modify instance specification

Modify an existing instance’s instance type or in/out bandwidth limits. This API Action is restricted, so you may get an error when calling this method.

Parameters:

• instance_id (str) – The id fo the instance.
• instance_type (str) – Use describe_instance_types for valid values.
• internet_max_bandwidth_out (int) – Outbound bandwdith limit in Mbps. between 1 and 200, inclusive.
• internet_max_bandwidth_in (int) – Inbound bandwdith limit in Mbps. between 1 and 200, inclusive.

reboot_instance(instance_id, force=False)

Reboot an instance.

Parameters:

• instance_id (str) – The id of the instance.
• force (bool) – Whether to force reboot the instance.

reinit_disk(disk_id)

Re-initialize a disk to it’s original Image.

Parameters:disk_id (str) – ID of the Disk to re-initialize.

remove_external_cidr_ip_rule(security_group_id, ip_protocol, port_range, source_cidr_ip, policy=None)

Remove a rule for an external CidrIp from a security group.

Parameters:

• security_group_id (str) – The id of the security group.
• ip_protocol (str) – TCP, UDP, ICMP, GRE or ALL
• port_range (str) – For tcp/udp range is 1 to 65535. Else -1/-1.
• source_cidr_ip (str) – Source IP address range.
• policy (str) – Accept, Drop or Reject. Default: Accept.

remove_group_rule(security_group_id, ip_protocol, port_range, source_group_id, policy=None)

Remove a rule for a security group to access another security group.

Parameters:

• security_group_id (str) – The id of the security group.
• ip_protocol (str) – TCP, UDP, ICMP, GRE or ALL
• port_range (str) – For tcp/udp range is 1 to 65535. Else -1/-1.
• source_group_id (str) – Source security group.
• policy (str) – Accept, Drop or Reject. Default: Accept.

remove_internal_cidr_ip_rule(security_group_id, ip_protocol, port_range, source_cidr_ip, policy=None)

Remove a rule for an internal CidrIp from a security group.

Parameters:

• security_group_id (str) – The id of the security group.
• ip_protocol (str) – TCP, UDP, ICMP, GRE or ALL
• port_range (str) – For tcp/udp range is 1 to 65535. Else -1/-1.
• source_cidr_ip (str) – Source IP address range.
• policy (str) – Accept, Drop or Reject. Default: Accept.

replace_system_disk(instance_id, image_id)

Replace an Instance’s system disk to the given Image.

Parameters:

• instance_id (str) – ID of the Instance to replace.
• image_id (str) – ID of the Image to use for the new system disk.

Returns:

ID of the new disk.

reset_disk(disk_id, snapshot_id)

Reset a disk to its snapshot.

Parameters:

• disk_id (str) – Disk ID to reset.
• snapshot_id (str) – ID of snapshot to reset the disk to.

start_instance(instance_id)

Start an instance.

Parameters:instance_id (str) – The id of the instance.

stop_instance(instance_id, force=False)

Stop an instance.

Parameters:

• instance_id (str) – The id of the instance.
• force (bool) – Whether to force stop the instance.

exception aliyun.ecs.connection.Error

Bases: exceptions.Exception

Base exception class for this module.