All Products
Search
Document Center

Elastic Compute Service:Release an ECS instance

Last Updated:Sep 19, 2023

ECS resources can be created on demand. You can create custom resources during peak hours and release the resources during off-peak hours. This topic describes how to use ECS SDK for Python to release an Elastic Compute Service (ECS) instance.

Background information

After an ECS instance is released, the physical resources used by the instance, such as disks and snapshots, are reclaimed. The data stored in the physical resources is lost and cannot be restored. To retain the data, we recommend that you create snapshots for the disks on the instance before you release the instance. Then, you can create another instance by using the snapshots.

This topic provides the sample code to show how to release an ECS instance and also the explanation of the sample code. For more information, see the following sections of this topic:

Sample code

This section provides the complete sample code.

Note

Exercise caution when you release ECS instances.

#  coding=utf-8
rr# if the python sdk is not install using 'sudo pip install aliyun-python-sdk-ecs'
# if the python sdk is install using 'sudo pip install --upgrade aliyun-python-sdk-ecs'
# make sure the sdk version is 2.1.2, you can use command 'pip show aliyun-python-sdk-ecs' to check

import json
import logging
import os
from aliyunsdkcore import client
from aliyunsdkecs.request.v20140526.DeleteInstanceRequest import DeleteInstanceRequest
from aliyunsdkecs.request.v20140526.DescribeInstancesRequest import DescribeInstancesRequest
from aliyunsdkecs.request.v20140526.ModifyInstanceAutoReleaseTimeRequest import \
    ModifyInstanceAutoReleaseTimeRequest
from aliyunsdkecs.request.v20140526.StopInstanceRequest import StopInstanceRequest

# configuration the log output formatter, if you want to save the output to file,
# append ",filename='ecs_invoke.log'" after datefmt.
# Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime environment. 
# If the project code is leaked, the AccessKey pair may be leaked and the security of resources within your account may be compromised. The following sample code shows how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. We recommend that you use Security Token Service (STS) tokens, which provide higher security.
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(filename)s[line:%(lineno)d] %(levelname)s %(message)s',
                    datefmt='%a, %d %b %Y %H:%M:%S')
clt = client.AcsClient(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], '<region-Id>')


def stop_instance(instance_id, force_stop=False):
    '''
    stop one ecs instance.
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :param force_stop: if force stop is true, it will force stop the server and not ensure the data
    write to disk correctly.
    :return:
    '''
    request = StopInstanceRequest()
    request.set_InstanceId(instance_id)
    request.set_ForceStop(force_stop)
    logging.info("Stop %s command submit successfully.", instance_id)
    _send_request(request)


def describe_instance_detail(instance_id):
    '''
    describe instance detail
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :return:
    '''
    request = DescribeInstancesRequest()
    request.set_InstanceIds(json.dumps([instance_id]))
    response = _send_request(request)
    if response is not None:
        instance_list = response.get('Instances').get('Instance')
        if len(instance_list) > 0:
            return instance_list[0]


def check_auto_release_time_ready(instance_id):
    detail = describe_instance_detail(instance_id=instance_id)
    if detail is not None:
        release_time = detail.get('AutoReleaseTime')
        return release_time


def release_instance(instance_id, force=False):
    '''
    delete instance according instance id, only support after pay instance.
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :param force:
    if force is false, you need to make the ecs instance stopped, you can
    execute the delete action.
    If force is true, you can delete the instance even the instance is running.
    :return:
    '''
    request = DeleteInstanceRequest();
    request.set_InstanceId(instance_id)
    request.set_Force(force)
    _send_request(request)


def set_instance_auto_release_time(instance_id, time_to_release=None):
    '''
    setting instance auto delete time
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :param time_to_release: if the property is setting, such as '2017-01-30T00:00:00Z'
    it means setting the instance to be release at that time.
    if the property is None, it means cancel the auto delete time.
    :return:
    '''
    request = ModifyInstanceAutoReleaseTimeRequest()
    request.set_InstanceId(instance_id)
    if time_to_release is not None:
        request.set_AutoReleaseTime(time_to_release)
    _send_request(request)
    release_time = check_auto_release_time_ready(instance_id)
    logging.info("Check instance %s auto release time setting is %s. ", instance_id, release_time)


def _send_request(request):
    '''
    send open api request
    :param request:
    :return:
    '''
    request.set_accept_format('json')
    try:
        response_str = clt.do_action(request)
        logging.info(response_str)
        response_detail = json.loads(response_str)
        return response_detail
    except Exception as e:
        logging.error(e)


if __name__ == '__main__':
    logging.info("Release ecs instance by Aliyun OpenApi!")
    stop_instance('i-bp1aet7s13lfpjop****')
    # set_instance_auto_release_time('i-bp1187lghfcy8nnz****', '2020-04-17T06:00:00Z')
    # set_instance_auto_release_time('i-bp1aet7s13lfpjop****')
    # release_instance('i-bp1aet7s13lfpjop****')
    # release_instance('i-bp1aet7s13lfpjop****', True)

Stop an ECS instance

Before you release an instance, put the instance into the Stopped state. If you stop an instance and applications that run on the instance are affected, you can restart the instance.

The method to stop an instance is simple, regardless of whether the instance is a pay-as-you-go or subscription instance. Set the ForceStop parameter to true to forcefully stop an instance. This operation is equivalent to the power-off operation. As a result, data may not be written to the disks on the instance when you perform this operation. For the sole purpose of releasing an instance, you can set this parameter to true.

def stop_instance(instance_id, force_stop=False):
    '''
    stop one ecs instance.
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :param force_stop: if force stop is true, it will force stop the server and not ensure the data
    write to disk correctly.
    :return:
    '''
    request = StopInstanceRequest()
    request.set_InstanceId(instance_id)
    request.set_ForceStop(force_stop)
    logging.info("Stop %s command submit successfully.", instance_id)
    _send_request(request)

Release an ECS instance

If you release an instance without stopping the instance beforehand, the following error may be returned:

{"RequestId":"3C6DEAB4-7207-411F-9A31-6ADE54C268BE","HostId":"ecs-cn-hangzhou.aliyuncs.com","Code":"IncorrectInstanceStatus","Message":"The current status of the resource does not support this operation."}

You can release an instance when the instance is in the Stopped state. The method to release an instance is simple. Configure the following parameters:

  • InstanceId: the ID of the instance.

  • force: specifies whether to forcefully release an instance. If you set this parameter to true, the instance is forcefully released, even if the instance is not in the Stopped state. To prevent accidental instance releases from affecting your business, exercise caution when you set this parameter.

Sample request to release an instance:

def release_instance(instance_id, force=False):
    '''
    delete instance according instance id, only support after pay instance.
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :param force:
    if force is false, you need to make the ecs instance stopped, you can
    execute the delete action.
    If force is true, you can delete the instance even the instance is running.
    :return:
    '''
    request = DeleteInstanceRequest();
    request.set_InstanceId(instance_id)
    request.set_Force(force)
    _send_request(request)

Sample success response:

{"RequestId":"689E5813-D150-4664-AF6F-2A27BB4986A3"}

Set the automatic release time for an ECS instance

To simplify instance management, you can specify a time to release an instance. When the automatic release time is reached, Alibaba Cloud releases the instance for you without the need for manual operation.

Note

Specify the automatic release time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC. If the value of ss is not 00, the time is automatically set to the start of the specified minute. The automatic release time ranges from 30 minutes later than the current time to three years later than the current time.

def set_instance_auto_release_time(instance_id, time_to_release = None):
    '''
    setting instance auto delete time
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :param time_to_release: if the property is setting, such as '2017-01-30T00:00:00Z'
    it means setting the instance to be release at that time.
    if the property is None, it means cancel the auto delete time.
    :return:
    '''
    request = ModifyInstanceAutoReleaseTimeRequest()
    request.set_InstanceId(instance_id)
    if time_to_release is not None:
        request.set_AutoReleaseTime(time_to_release)
    _send_request(request)

Run set_instance_auto_release_time('i-1111', '2017-01-30T00:00:00Z') to set the automatic release time.

After the time is set, you can call the DescribeInstances operation to query the automatic release time:

def describe_instance_detail(instance_id):
    '''
    describe instance detail
    :param instance_id: instance id of the ecs instance, like 'i-***'.
    :return:
    '''
    request = DescribeInstancesRequest()
    request.set_InstanceIds(json.dumps([instance_id]))
    response = _send_request(request)
    if response is not None:
        instance_list = response.get('Instances').get('Instance')
        if len(instance_list) > 0:
            return instance_list[0]
def check_auto_release_time_ready(instance_id):
    detail = describe_instance_detail(instance_id=instance_id)
    if detail is not None:
        release_time = detail.get('AutoReleaseTime')
        return release_time

Cancel the automatic release

If you want to cancel the automatic release due to your business changes, run the following command to set the automatic release time to null:

set_instance_auto_release_time('i-1111')