All Products
Search
Document Center

Elastic Compute Service:Create and run commands

Last Updated:Sep 12, 2025

Manually performing repetitive tasks (such as installing software, updating configurations, and collecting logs) across multiple Elastic Compute Service (ECS) instances is inefficient. Cloud Assistant securely and reliably executes scripts (such as Shell and PowerShell) across multiple instances.

Procedure

Console

  1. Go to ECS console - ECS Cloud Assistant.

  2. In the top navigation bar, select the region and resource group of the resource that you want to manage. 地域

  3. In the upper-right corner of the ECS Cloud Assistant page, click Create/Run Command.

  4. In the Command Information section, configure the following settings:

    • Command content: You can enable Use Parameters.

      The Base64-encoded command payload cannot exceed 18 KB when select Run And Save, and 24 KB when select Run.
      • Custom parameters: Use the {{parameter}} format to define parameters and assign values manually to support dynamic values and reuse.

      • Built-in parameters: Cloud Assistant provides built-in parameters that are automatically replaced at runtime, such as {{ACS::RegionId}} (Region ID) and {{ACS::InstanceId}} (Instance ID).

      #!/bin/bash
      # Example
      # {{name}} is a custom parameter that you must assign a value to.
      echo {{name}}
      
      # {{ACS::RegionId}} is a built-in parameter that does not require a value to be assigned.
      echo {{ACS::RegionId}}
    • Execution Plan:

      • Perform Only Dry Run: The command is not executed. Only pre-check such as request parameters, the instance environment, and the Cloud Assistant Agent status.

      • Run on Schedule:

        • Run at Fixed Interval: Runs the command at a fixed interval defined by a rate expression.

          The interval must be between 60 seconds and 7 days, and must be longer than the command timeout.
        • Run on Clock-based Schedule: Use cron expression for flexible scheduling of complex tasks.

    • Username: Defaults to root (Linux) or System (Windows). For security, we recommend using a non-root user that follows the principle of least privilege.

    • Execution Path: The default script working directory is /root (Linux) and C:\Windows\system32 (Windows). To ensure execution in the intended path, using cd command at the start of the script.

    • Timeout: Defaults to 60 seconds. You can set the timeout to a value between 10 and 86,400 seconds (24 hours).

    • Task Stop Scope:

      • Command Process: Stops only the script process when the task is terminated.

      • Command Process Tree: Stops the entire process tree (the script process and all its child processes) when the task is terminated.

  5. In the Select Instance or Select Managed Instances section, select the target instances for the command.

    You can select up to 100 instances.
  6. To start the task, click Run and Save or Run.

CLI

  1. Preparation

    The RunCommand API accepts CommandContent parameter as plaintext or Base64-encoded content. If you use Base64-encoded content, you must set ContentEncoding to Base64. Use the following commands to Base64-encode the script content:

    Linux / macOS

    # Encode the string "hello world"
    # Use -n to avoid encoding the trailing line feed
    echo -n "hello world" | base64
    # Output: aGVsbG8gd29ybGQ=

    Windows (PowerShell)

    # Encode the string "hello world"
    [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("hello world"))
    # Output: aGVsbG8gd29ybGQ=
  2. Run the command

    To run the command, use the aliyun ecs RunCommand command. For parameter details, see RunCommand.

    • Example 1: Run a command immediately on a single instance

      # The Base64-encoded string for "yum -y update" is "eXVtIC15IHVwZGF0ZQ=="
      aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
        --Type 'RunShellScript' \
        --ContentEncoding 'Base64' \
        --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
        --InstanceId.1 'i-bp1************de01' \
    • Example 2: Run a command on multiple instances

      # Use the --InstanceId.N parameter multiple times to specify multiple instances
      aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
        --Type 'RunShellScript' \
        --ContentEncoding 'Base64' \
        --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
        --InstanceId.1 'i-bp1************de01' \
        --InstanceId.2 'i-bp1************de02' \
        --InstanceId.3 'i-bp1************de03'
    • Example 3: Create a cron scheduled task

      # The Frequency parameter uses a cron expression and a time zone
      # Example: Run at 12:00 PM every day in 2024 in the Asia/Shanghai time zone
      aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
        --Type 'RunShellScript' \
        --ContentEncoding 'Base64' \
        --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
        --RepeatMode 'Period' \
        --Frequency '0 0 12 * * ? 2024 Asia/Shanghai' \
        --InstanceId.1 'i-bp1************de01'
  3. Query the execution result

    RunCommand returns an InvokeId. Query the execution results by using the aliyun ecs DescribeInvocationResults command with the returned InvokeId. For parameter details, see DescribeInvocationResults.

    # Replace <invoke_id> with your InvokeId
    aliyun ecs DescribeInvocationResults --RegionId 'cn-hangzhou' --InvokeId '<invoke_id>'

    In the response, the Output field contains the script's standard output (STDOUT), and the ErrorInfo or ErrorMsg fields contain error details.

Limitations

  • Number of instances: The maximum number of instances you can target with a single API call is 100. To increase this limit, see Manage quotas.

  • Number of saved commands: By default, you can save up to 500 Cloud Assistant commands in a single Alibaba Cloud Region. This quota may increase based on your ECS usage. To increase this limit, see Manage quotas.

    If you run a command immediately without saving it, the command does not count against your saved command quota.
  • Feature and client version dependencies: Some advanced features depend on specific versions of the Cloud Assistant Agent. For more information, see Features and versions.

Recommendations for production use

  • Ensure idempotence

    When calling the RunCommand API via the CLI or an SDK, we recommend setting the ClientToken parameter to ensure idempotence. This prevents duplicate command executions caused by network retries.

  • Monitoring and alerting

    Monitor the execution status of Cloud Assistant, especially for failed tasks. You can subscribe to Cloud Assistant events through EventBridge or CloudMonitor to set up alerts for command failures. This helps you detect and resolve issues promptly.

FAQ

Q: How can I check the Cloud Assistant Agent version on an ECS instance?

A: You can check the version via the console or by logging in to the instance. For detailed steps, see Install Cloud Assistant Agent.

Q: For a scheduled task with Run at Fixed Interval, does it run immediately after creation or only after the first interval?

A: It does not run immediately. The first run occurs after the specified interval has passed. The schedule only follows the fixed interval. For example, if you create a 10-minute interval task at 10:00, it will run at 10:10, 10:20, and so on.

Q: My command failed to run. How can I troubleshoot it?

A: 1. View the detailed Output log on the execution results page in the console to analyze error messages.

2. Verify that the executing user has read, write, and execute permissions for the relevant files and directories.

3. Validate the script syntax and confirm it can run successfully when executed manually.

4. Ensure the instance is in the Running state and that network connectivity is normal.

5. If the command returns the ClientNeedUpgrade error, check and upgrade the Cloud Assistant Agent.

For more information, see Check execution results and troubleshoot common issues.