Run a saved Cloud Assistant command on one or more Elastic Compute Service (ECS) instances. Each instance runs the command independently — the result on one instance does not affect others.
Prerequisites
Before you begin, make sure that:
The target instances are in the Running state
Cloud Assistant Agent is installed on the instances. See Install Cloud Assistant Agent
(For scheduled tasks) Cloud Assistant Agent is at least the following version:
Linux: 2.2.3.282
Windows: 2.1.3.282
If the ClientNeedUpgrade error appears, upgrade Cloud Assistant Agent to the latest version. See Upgrade or disable upgrades of Cloud Assistant Agent.
Limits
A single API call can target up to 100 instances. This limit is controlled by the Maximum number of instances supported for command execution quota. To increase the quota, see Manage ECS quotas.
In the ECS console, selecting more than 100 instances causes the system to run the command in batches.
Procedure
Run a command in the ECS console
In the top navigation bar, select the region and resource group of the instances you want to target.
On the My Commands tab, find the command you want to run and click Run in the Actions column.
In the Run Command panel, configure the following settings.
Command Information section
Parameter Description Command content Click View command content to inspect the command before running it. Execution Plan Select when to run the command. See Execution plan options below. Username The OS user that runs the command. Default: rooton Linux,systemon Windows. Run commands as a low-privilege user to follow the principle of least privilege. See Run Cloud Assistant commands as a regular user.Timeout How long (in seconds) Cloud Assistant waits before force-stopping the command process. Defaults to the timeout value saved with the command. Changing this value does not affect the saved command's timeout. Tag Add Tag key and Tag value pairs to label the execution task. In the Select Instance and Select Managed Instances sections, select the target instances. You can select instances by:
Searching by instance ID, name, or tag
Filtering by Cloud Assistant Agent status
A managed instance is a non-Alibaba Cloud server managed through Cloud Assistant. See Alibaba Cloud managed instances.
Click Run.
Execution plan options
Choose the option that matches how often and when the command should run.
| Option | When to use |
|---|---|
| Immediate execution | Run once, right now. |
| After the next startup of the system | Run once the next time each target instance starts. |
| After each system startup | Run every time each target instance starts. |
| Perform Only Dry Run | Validate the request parameters, execution environment, and Cloud Assistant Agent status without running the actual command. Use this to check configuration before the first real run. |
| Run on Schedule | Run on a recurring or one-time schedule. Choose a sub-option below. |
Run on Schedule has three sub-options:
Run at Fixed Interval — Use a rate expression to run at a fixed interval (60 seconds to 7 days). Use this when you need predictable gaps between executions rather than a clock-based schedule. How the interval works: the interval is the gap between when one execution ends and the next begins — it does not account for the command's own run time. For example, if you set a 5-minute interval and the command takes 2 minutes to run, the next execution starts 3 minutes after the previous one finishes. The first run starts one full interval after you create the task.
The interval must be longer than the task's timeout period.
Run Only Once at Specified Time — Specify a date, time, and time zone to run the command exactly once. For example, set Execution time to
May 17, 2022, 17:30:50and Time Zone to(GMT+08:00) Asia/Shanghaito run at 17:30:50 on May 17, 2022 (UTC+8).Run on Clock-based Schedule Cron Expression — Use a cron expression (accurate to seconds, minutes, hours, day of month, month, day of week, and year) with a selected time zone. Use this for complex schedules, such as "every Wednesday at noon." The minimum interval between runs is 10 seconds and must be longer than the task's timeout period. For cron expression syntax, see Cron expressions.
Run a command using Alibaba Cloud CLI
Before you begin, install Alibaba Cloud CLI on your machine:
Step 1. (Optional) Start the instance if it is not in the Running state.
aliyun ecs StartInstance --InstanceId 'i-bp1f4f6o8lv0wqof****'For parameter details, see StartInstance.
Step 2. (Optional) Confirm Cloud Assistant Agent is installed on the instances.
aliyun ecs DescribeCloudAssistantStatus --RegionId 'cn-hangzhou' \
--InstanceId.1 'i-bp1f4f6o8lv0wqof****'If CloudAssistantStatus is true in the response, the agent is installed. Otherwise, install it with InstallCloudAssistant. See DescribeCloudAssistantStatus and InstallCloudAssistant.
Step 3. Run the command with InvokeCommand.
aliyun ecs InvokeCommand --RegionId 'cn-hangzhou' \
--InstanceId.1 'i-bp1f4f6o8lv0wqof****' \
--InstanceId.2 'i-bp137qu6142s3mhm****' \
--CommandId 'c-hz018qp243j****'| Parameter | Example | Description |
|---|---|---|
RegionId | cn-hangzhou | The region where the instances are located. |
InstanceId.1 | i-bp1f4f6o8lv0wqof**** | The ID of the first target instance. |
InstanceId.2 | i-bp137qu6142s3mhm**** | The ID of the second target instance. Add more InstanceId.N parameters for additional instances. |
CommandId | c-hz018qp243j**** | The ID of the Cloud Assistant command to run. |
For all available parameters, see InvokeCommand.
What's next
DescribeAccountAttributes — query ECS resource quotas in a region
InvokeCommand — API reference for triggering a Cloud Assistant command