Elastic Compute Service:Stop or restart an instance by using a Cloud Assistant command

Exit codes

To stop an instance:

To restart an instance:

Practical example

The exit code goes at the end of your script. A minimal example is exit 194, but a more realistic pattern checks a condition first and only triggers the restart when needed:

#!/bin/bash
# Run updates and restart only if required
yum -y update
needs-restarting -r
if [ $? -eq 1 ]; then
    # Kernel or service update requires a restart
    exit 194
else
    exit 0
fi

For scripts that must continue after a restart, design them to be idempotent: check whether each step has already completed before running it, so the script can resume safely after the instance comes back up.

Steps

1. Go to ECS console - ECS Cloud Assistant.

2. In the top navigation bar, select the region and resource group of the instance.

   

3. In the upper-right corner, click Create/Run Command.

4. In the Command Information section, configure the command parameters. For details, see Create and run a command.

5. At the end of the Command content, add the exit code for the action you want — see the exit codes table above.

6. In the Select Instance or Select Managed Instances section, select the target instances. > Tip: If an instance you expect to see is not listed, check that the Cloud Assistant Agent is running on that instance. See Check the status of Cloud Assistant.

   A managed instance is a server not provisioned by Alibaba Cloud but managed through Cloud Assistant. For details, see Managed instances.

7. Click Run and Save or Run.

Set up the environment

1. Get the AccessKey pair for the Resource Access Management (RAM) user. For details, see Create an AccessKey pair.

2. Use DescribeRegions to retrieve your region ID. For parameter details, see DescribeRegions.

3. Use DescribeInstances to get the IDs of the instances to target. For parameter details, see DescribeInstances.

4. Install the SDK:

   sudo pip install --upgrade alibabacloud_ecs20140526

Run the sample code

Create a .py file with the following code, then run it.

<details> <summary>View sample code</summary>

# coding=utf-8
# Install the SDK: sudo pip install --upgrade alibabacloud_ecs20140526

import base64
import logging
import os
import sys
import time

from alibabacloud_ecs20140526.client import Client as Ecs20140526Client
from alibabacloud_ecs20140526.models import (
    DescribeInvocationResultsRequest,
    DescribeInstancesRequest,
    RunCommandRequest,
    RebootInstancesRequest
)
from alibabacloud_tea_openapi.models import Config

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(name)s [%(levelname)s]: %(message)s",
    datefmt='%m-%d %H:%M'
)
logger = logging.getLogger()

# Load credentials from environment variables — avoid hardcoding AccessKey pairs in source code.
# For production workloads, use STS tokens instead.
access_key = os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID']
access_key_secret = os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET']
region_id = '<yourRegionId>'  # Replace with your region ID

ecs_config = Config(
    access_key_id=access_key,
    access_key_secret=access_key_secret,
    endpoint=f'ecs.{region_id}.aliyuncs.com'
)
client = Ecs20140526Client(ecs_config)


def base64_decode(content, code='utf-8'):
    if sys.version_info.major == 2:
        return base64.b64decode(content)
    else:
        return base64.b64decode(content).decode(code)


def get_invoke_result(invoke_id):
    request = DescribeInvocationResultsRequest(
        region_id=region_id,
        invoke_id=invoke_id
    )
    response = client.describe_invocation_results(request)
    response_details = response.body.invocation.invocation_results.invocation_result
    return {
        detail.instance_id: {
            "status": detail.invocation_status,
            "output": base64_decode(detail.output)
        }
        for detail in response_details
    }


def get_instances_status(instance_ids):
    request = DescribeInstancesRequest(
        region_id=region_id,
        instance_ids=str(instance_ids)
    )
    response = client.describe_instances(request)
    response_details = response.body.instances.instance
    return {detail.instance_id: {"status": detail.status} for detail in response_details}


def run_command(cmdtype, cmdcontent, instance_ids, timeout=60):
    """
    cmdtype: Command type. Valid values: RunBatScript, RunPowerShellScript, RunShellScript.
    cmdcontent: Command content.
    instance_ids: List of instance IDs.
    timeout: Execution timeout in seconds (default: 60).
    """
    try:
        request = RunCommandRequest(
            region_id=region_id,
            type=cmdtype,
            command_content=cmdcontent,
            instance_id=instance_ids,
            timeout=timeout
        )
        response = client.run_command(request)
        return response.body.invoke_id
    except Exception as e:
        logger.error("run command failed", exc_info=True)


def reboot_instances(instance_ids, Force=False):
    """
    instance_ids: List of instance IDs to restart.
    Force: Whether to force-restart. Default: False.
    """
    request = RebootInstancesRequest(
        region_id=region_id,
        instance_id=instance_ids,
        force_reboot=Force
    )
    client.reboot_instances(request)


def wait_invoke_finished_get_out(invoke_id, wait_count, wait_interval):
    # Poll until all invocations leave the transient states
    for i in range(wait_count):
        result = get_invoke_result(invoke_id)
        if set([res['status'] for _, res in result.items()]) & set(["Running", "Pending", "Stopping"]):
            time.sleep(wait_interval)
        else:
            return result
    return result


def wait_instance_reboot_ready(ins_ids, wait_count, wait_interval):
    # Poll until all instances return to Running
    for i in range(wait_count):
        result = get_instances_status(ins_ids)
        if set([res['status'] for _, res in result.items()]) != set(["Running"]):
            time.sleep(wait_interval)
        else:
            return result
    return result


def run_task():
    cmdtype = "RunShellScript"
    cmdcontent = """
    #!/bin/bash
    echo helloworld
    """
    timeout = 60
    # Replace with your instance IDs
    ins_ids = ["i-bp185fcs****", "i-bp14wwh****", "i-bp13jbr****"]

    invoke_id = run_command(cmdtype, cmdcontent, ins_ids, timeout)
    logger.info("run command, invoke_id: %s" % invoke_id)

    if invoke_id is None:
        logger.error("Failed to run command, stopping further execution")
        return

    # Wait for command to finish: poll 10 times at 5-second intervals
    invoke_result = wait_invoke_finished_get_out(invoke_id, 10, 5)
    for ins_id, res in invoke_result.items():
        logger.info("instance %s: status=%s, output=%s" % (ins_id, res['status'], res['output']))

    # Restart all instances
    logger.warning("Restarting instances...")
    reboot_instances(ins_ids)

    time.sleep(5)
    # Wait for instances to reach Running: poll 30 times at 10-second intervals
    reboot_result = wait_instance_reboot_ready(ins_ids, 30, 10)
    logger.warning("Restart complete")
    for ins_id, res in reboot_result.items():
        logger.info("instance %s status: %s" % (ins_id, res['status']))


if __name__ == '__main__':
    run_task()

</details>

Replace the placeholders in the code:

After the script runs, it executes the command on each instance and then restarts all of them automatically.

Create the OOS template

1. Log on to the OOS console.

2. In the navigation pane, click Automated Tasks > Custom Template.

3. Click Create Template.

4. On the Create Template page, keep the default configurations and click Next Step.

5. Click the YAML tab and paste the following template.

<details> <summary>View template YAML</summary>

FormatVersion: OOS-2019-06-01
Description:
  en: Run a Cloud Assistant command on multiple ECS instances in a batch and then restart them.
  name-en: Batch Run Command and Restart ECS Instances
  categories:
    - run_command
Parameters:
  regionId:
    Type: String
    Description:
      en: The ID of the region.
    Label:
      en: Region
    AssociationProperty: RegionId
    Default: '{{ ACS::RegionId }}'
  targets:
    Type: Json
    Label:
      en: Target Instances
    AssociationProperty: Targets
    AssociationPropertyMetadata:
      ResourceType: ALIYUN::ECS::Instance
      RegionId: regionId
  commandType:
    Description:
      en: The type of the command.
    Label:
      en: Command type
    Type: String
    AllowedValues:
      - RunBatScript
      - RunPowerShellScript
      - RunShellScript
    Default: RunShellScript
  commandContent:
    Description:
      en: The command content to execute on the ECS instance.
    Label:
      en: Command content
    Type: String
    MaxLength: 16384
    AssociationProperty: Code
    Default: echo hello
  workingDir:
    Description:
      en: 'The directory where the command runs on the ECS instances. For Linux instances, the default is the home directory of the root user (/root). For Windows instances, the default is the directory where the Cloud Assistant client process is located, such as C:\Windows\System32.'
    Label:
      en: Working directory
    Type: String
    Default: ''
  timeout:
    Description:
      en: The timeout period for command execution on an ECS instance.
    Label:
      en: Timeout
    Type: Number
    Default: 600
  enableParameter:
    Description:
      en: Specifies whether the command contains secret or custom parameters.
    Label:
      en: Enable parameters
    Type: Boolean
    Default: false
  username:
    Description:
      en: The username used to run the command on the ECS instance.
    Label:
      en: Username
    Type: String
    Default: ''
  windowsPasswordName:
    Description:
      en: The name of the password for the user who runs the command on a Windows instance.
    Label:
      en: Windows password name
    Type: String
    Default: ''
    AssociationProperty: SecretParameterName
  rateControl:
    Description:
      en: The concurrency ratio for task execution.
    Label:
      en: Rate control
    Type: Json
    AssociationProperty: RateControl
    Default:
      Mode: Concurrency
      MaxErrors: 0
      Concurrency: 10
  OOSAssumeRole:
    Description:
      en: The RAM role that OOS assumes.
    Label:
      en: OOS assume role
    Type: String
    Default: OOSServiceRole
RamRole: '{{ OOSAssumeRole }}'
Tasks:
  - Name: getInstance
    Description:
      en: Get the ECS instances.
    Action: ACS::SelectTargets
    Properties:
      ResourceType: ALIYUN::ECS::Instance
      RegionId: '{{ regionId }}'
      Filters:
        - '{{ targets }}'
    Outputs:
      instanceIds:
        Type: List
        ValueSelector: Instances.Instance[].InstanceId
  - Name: runCommand
    Action: ACS::ECS::RunCommand
    Description:
      en: Execute the Cloud Assistant command.
    Properties:
      regionId: '{{ regionId }}'
      commandContent: '{{ commandContent }}'
      instanceId: '{{ ACS::TaskLoopItem }}'
      commandType: '{{ commandType }}'
      workingDir: '{{ workingDir }}'
      timeout: '{{ timeout }}'
      enableParameter: '{{ enableParameter }}'
      username: '{{ username }}'
      windowsPasswordName: '{{ windowsPasswordName }}'
    Loop:
      RateControl: '{{ rateControl }}'
      Items: '{{ getInstance.instanceIds }}'
      Outputs:
        commandOutputs:
          AggregateType: Fn::ListJoin
          AggregateField: commandOutput
    Outputs:
      commandOutput:
        Type: String
        ValueSelector: invocationOutput
  - Name: rebootInstance
    Action: ACS::ECS::RebootInstance
    Description:
      en: Restart the ECS instances.
    Properties:
      regionId: '{{ regionId }}'
      instanceId: '{{ ACS::TaskLoopItem }}'
    Loop:
      RateControl: '{{ rateControl }}'
      Items: '{{ getInstance.instanceIds }}'
Outputs:
  instanceIds:
    Type: List
    Value: '{{ getInstance.instanceIds }}'

</details>

1. Click Create Template.

2. In the dialog that appears, enter the template name runcommand_reboot_instances and click OK.

Run the template

1. Find the template you just created and click Create Execution in the Actions column.

2. On the Parameter Settings page, select the target instances and review the rateControl settings: Keep the other settings at their defaults.

   Parameter	Default	Description
   Concurrency	10	Number of instances processed in parallel. Lower this value for large fleets to reduce blast radius if a command fails.
   MaxErrors	0	Number of instance failures allowed before OOS stops the task. Set to a non-zero value if you want the task to continue past individual failures.

   

3. On the OK page, click Create. OOS starts executing the template immediately and redirects you to the Basic Information page. Wait for the Execution Status to change to Successful.

View execution results

1. In the Execution Steps And Results section, click View Execution Flowchart to see the full execution path.

   

2. Click the Cloud Assistant command execution step. On the loop task list tab, view the per-instance execution details.