Alibaba Cloud ECS SDK (V1.0)

4.24.82 verified Thu Apr 16 auth: no python maintenance

aliyun-python-sdk-ecs is the Elastic Compute Service (ECS) module of the Alibaba Cloud Python SDK V1.0. This SDK provides an interface to interact with Alibaba Cloud ECS resources. While actively maintained with frequent updates, the V1.0 SDK is in a basic security maintenance phase, and Alibaba Cloud officially recommends migrating to the V2.0 SDK (`alibabacloud-python-sdk`) for new development and improved features.

pip install aliyun-python-sdk-core aliyun-python-sdk-ecs

Common errors

error ModuleNotFoundError: No module named 'aliyunsdkcore' ↓

cause The core SDK (`aliyun-python-sdk-core`) is a mandatory dependency and has not been installed.

fix

Install the core SDK: pip install aliyun-python-sdk-core.

error Command 'python setup.py egg_info' failed with error code 1 in /path/to/package ↓

cause This often indicates an outdated `pip` or Python version, or missing build-time dependencies required for package installation.

fix

Upgrade pip and setuptools: pip install --upgrade pip setuptools. Ensure your Python version meets the SDK requirements (Python 3.7+ for recent aliyunsdkcore).

error The current status of the resource does not support this operation. ↓

cause You are attempting to perform an action (e.g., start, stop, release an instance) on an ECS instance that is not in the required state for that operation.

fix

Before performing state-changing operations, query the instance's current status (e.g., using DescribeInstancesRequest) and wait for it to reach the correct state. For example, an instance must be 'Stopped' to be 'Started', and 'Running' to be 'Stopped'.

error SDK.HttpError: The endpoint is not found. ↓

cause This error typically means the region ID provided during `AcsClient` initialization is invalid or the SDK version is too old to recognize the endpoint for the specified region.

fix

Verify the region_id string format (e.g., 'cn-hangzhou'). Ensure aliyunsdkcore is updated to the latest version: pip install --upgrade aliyun-python-sdk-core.

Warnings

breaking The Alibaba Cloud Python SDK V1.0, which includes `aliyun-python-sdk-ecs`, is officially deprecated and in a basic security maintenance phase. Users are strongly recommended to migrate to the V2.0 SDK (`alibabacloud-python-sdk`) for new projects and actively maintained features. ↓

fix Migrate to `alibabacloud-python-sdk`. The import patterns and client initialization differ significantly. Refer to the official Alibaba Cloud Python SDK 2.0 documentation for migration guides.

gotcha As of `aliyun-python-sdk-core` version 2.16.0, the minimum supported Python version is 3.7. Attempting to use this SDK with older Python versions (e.g., Python 2.7, 3.6) will lead to compatibility issues or installation failures. ↓

fix Ensure your Python environment is version 3.7 or newer. Upgrade Python if necessary, or use a virtual environment with a compatible Python version.

gotcha Many ECS operations (e.g., StartInstance, StopInstance, ReleaseInstance) are asynchronous and require the ECS instance to be in a specific state before the operation can succeed. Failing to check the instance status can lead to API errors. ↓

fix Implement logic to poll the instance status using `DescribeInstancesRequest` or `DescribeInstanceAttributeRequest` and wait for the desired state before proceeding with dependent operations. The V2.0 SDK offers `instance.wait_until(ECSInstanceResource.STATUS_RUNNING)` for this purpose.

gotcha When allocating an EIP (`AllocateEipAddressRequest`), you might encounter an API error if the `InternetChargeType` parameter is not explicitly set, even though it might seem optional in some contexts. ↓

fix Explicitly set `request.set_InternetChargeType('PayByBandwidth')` or `'PayByTraffic'` when calling `AllocateEipAddressRequest` to avoid this known API issue.

Imports

AcsClient

from aliyunsdkcore.client import AcsClient

DescribeInstancesRequest

from aliyunsdkecs.request.v20140526.DescribeInstancesRequest import DescribeInstancesRequest

RunInstancesRequest

wrong

from aliyunsdkecs.request.RunInstancesRequest import RunInstancesRequest

correct

from aliyunsdkecs.request.v20140526.RunInstancesRequest import RunInstancesRequest

Requests are versioned, typically under a 'vYYYYMMDD' path. Omitting the version will cause ModuleNotFoundError.

Quickstart

This quickstart demonstrates how to initialize the V1.0 ECS client using environment variables for credentials and fetch a list of ECS instances. It uses `DescribeInstancesRequest` as a common API call. Remember to replace placeholder values or set environment variables.

import os
from aliyunsdkcore.client import AcsClient
from aliyunsdkecs.request.v20140526.DescribeInstancesRequest import DescribeInstancesRequest

# Configure credentials and region using environment variables
access_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY_ID')
access_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'YOUR_ACCESS_KEY_SECRET')
region_id = os.environ.get('ALIBABA_CLOUD_REGION_ID', 'cn-hangzhou')

if not access_key_id or not access_key_secret:
    raise ValueError("Alibaba Cloud Access Key ID and Secret must be set in environment variables or hardcoded for testing.")

try:
    # Initialize the AcsClient
    client = AcsClient(access_key_id, access_key_secret, region_id)

    # Create a request object for DescribeInstances
    request = DescribeInstancesRequest()
    request.set_PageSize(10)

    # Send the request and get the response
    response = client.do_action_with_exception(request)

    # Process the response (response is a byte string, decode it)
    import json
    response_data = json.loads(response.decode('utf-8'))

    print(f"Successfully queried instances in region {region_id}:")
    for instance in response_data.get('Instances', {}).get('Instance', []):
        print(f"  Instance ID: {instance['InstanceId']}, Status: {instance['Status']}")

except Exception as e:
    print(f"An error occurred: {e}")