Features, scenarios, and common operations of Cloud Assistant - Elastic Compute Service

Cloud Assistant is a native operations tool for Elastic Compute Service (ECS). It runs Shell, PowerShell, and Bat commands across multiple instances without SSH keys, RDP passwords, or bastion hosts. Use it from the ECS console, API, or SDK to automate deployments, apply security patches, collect diagnostics, and manage instance configurations at scale. Cloud Assistant is available in all Alibaba Cloud regions at no additional cost. You pay only for the underlying ECS resources consumed during task execution.

Key features

Batch operations: Run commands on multiple instances simultaneously. Execution is isolated per instance -- a failure on one does not affect others.
File upload: Send configuration files, scripts, or other assets directly to instances through Cloud Assistant.
Public commands: Choose from a library of pre-built scripts and plugins for common tasks such as security audits, OS patching, and application installation. These vetted templates reduce manual scripting and improve consistency.
Parameterized commands: Define custom or built-in parameters to create reusable command templates. A single template can serve multiple scenarios by injecting different values at runtime.
Security and control: Cloud Assistant operates on a user-driven model. It never initiates actions on its own -- you retain full control over every operation.

Use cases

Software deployment: Push application code, configuration updates, or hotfixes to a fleet of instances in a single operation.
Security patching: Roll out OS patches or security updates across all instances without logging in to each one individually.
Software lifecycle management: Manage the software development life cycle across instances.
Instance configuration: Modify hostnames or reset user credentials in batch.
Process monitoring: Poll process status or service health across a group of instances and collect the results centrally.
Package management: Fetch and install updates from Object Storage Service (OSS) or YUM repositories.

Get started

Interact with Cloud Assistant through the ECS console, API, or SDK. The following table maps common tasks to their documentation and API references.

Task	Documentation	API
Install the agent	Install Cloud Assistant Agent	InstallCloudAssistant, DescribeCloudAssistantStatus
Use the SDK	Run commands using an SDK	--
Create a command	Create a command	RunCommand, CreateCommand
Run a command	Run a command	RunCommand, InvokeCommand
Check results	View execution results and troubleshoot common issues	DescribeInvocations, DescribeInvocationResults
Modify a command	Modify a command	--
Clone a command	Clone a command	--
Stop a command	Stop a command	StopInvocation
Delete a command	Delete a command	DeleteCommand

Note

Cloud Assistant Agent is pre-installed by default on ECS instances created from public images after December 1, 2017.

Instance requirements

Instances must be in the Running state.
Cloud Assistant Agent must be installed. The agent is pre-installed by default on instances created from public images after December 1, 2017. For instances created from custom images or Alibaba Cloud Marketplace images, verify compatibility and install the agent manually if needed. For details, see Install Cloud Assistant Agent.

Supported operating systems

Linux

Alibaba Cloud Linux
CentOS 6, 7, 8, and later
CoreOS
Debian 8, 9, 10, and later
OpenSUSE
Red Hat 5, 6, 7, and later
Note
Red Hat requires manual RPM installation. For details, see Install Cloud Assistant Agent.
SUSE Linux Enterprise Server 11, 12, 15, and later
Ubuntu 12, 14, 16, 18, and later
FreeBSD 11, 12, 13, 14, and later

Windows

Windows Server 2012, 2016, 2019, and later

Payload and parameter limits

All sizes refer to the Base64-encoded payload.

Operation	Max size
Create command	18 KB
Run immediately (save command)	18 KB
Run immediately (do not save)	24 KB
Upload file	32 KB

Each command supports up to 20 custom parameters.

Feature compatibility matrix

Some features require a minimum Cloud Assistant Agent version. The following table lists each feature and the required version.

Feature	Min version (Linux)	Min version (Windows)
Agent heartbeat reporting	1.0.2.458	1.0.0.149
File distribution	1.0.2.569	1.0.0.149
Run as specific user	2.2.0.106	2.1.0.50
Run on next boot	2.2.0.46	2.1.0.50
Run on every boot	2.2.0.46	2.1.0.50
Session Manager support	2.2.3.196	2.1.3.196
Scheduled tasks (Rate/At expressions)	2.2.3.282	2.1.3.282
Scheduled tasks (Cron with year/timezone)	2.2.3.282	2.1.3.282
Built-in environment parameters	2.2.3.309	2.1.3.309
Instance names as parameter	2.2.3.344	2.1.3.344
Stop or restart via exit code	2.2.3.317	2.1.3.317
Container execution (by name)	2.2.3.344	2.1.3.344
Container execution (by ID)	2.2.3.344	2.1.3.344

Billing

Cloud Assistant itself is free. You are billed only for the ECS resources (compute, network, storage) consumed during task execution. For details, see Billing overview.

Resource overhead

The Cloud Assistant Agent is lightweight and has minimal impact on instance performance.

Resource	Linux	Windows
CPU	< 1% average utilization	< 1% average utilization
Physical memory	~20 MB	~30 MB
Disk I/O	Negligible (peaks only during upgrades or script saving)	Negligible (peaks only during upgrades or script saving)
Network I/O	Minimal (heartbeat traffic)	Minimal (heartbeat traffic)

Command execution status

Cloud Assistant tracks command execution at two levels: the instance level (status of the command on a single instance) and the invocation level (aggregated status across all targeted instances in a batch execution). Understanding this hierarchy helps you interpret results correctly when running commands across multiple instances.

Relationship between invocation status and instance-level status

Instance-level status

The following statuses describe what happens on a single instance. These correspond to the InvocationStatus field under InvokeInstance in DescribeInvocations, or the InvocationStatus field in DescribeInvocationResults.

Status code	Description
`Pending`	The system is verifying or sending the command.
`Invalid`	The command type or parameter is invalid. Verification failed.
`Aborted`	Failed to send. The instance must be in the `Running` state and the command must be delivered within 1 minute.
`Running`	The command is being executed on the instance.
`Success`	Execution finished with exit code 0. For scheduled tasks, this means the last execution finished with exit code 0 and the schedule has ended.
`Failed`	Execution finished with a non-zero exit code. For scheduled tasks, a non-zero exit code on the last execution aborts the task.
`Error`	An exception occurred during execution.
`Timeout`	Execution exceeded the specified timeout period.
`Cancelled`	Execution was cancelled before it started.
`Stopping`	A stop request has been sent and execution is being stopped.
`Stopped`	Execution was manually stopped.
`Terminated`	Execution was terminated during runtime.
`Scheduled`	The scheduled command is waiting for its next execution window.

Invocation-level status (batch aggregation)

When a command targets multiple instances, Cloud Assistant aggregates individual instance statuses into a single invocation status. This status is returned in the InvocationStatus field of the DescribeInvocations API response.

Status code	Aggregation rule
`Pending`	At least one instance is in the `Pending` state.
`Scheduled`	At least one instance is in the `Scheduled` state.
`Running`	At least one instance is in the `Running` state.
`Success`	All instances have finished. At least one reported `Success`. For immediate tasks, finished with exit code 0. For scheduled tasks, the last execution finished with exit code 0 and the schedule has ended.
`Failed`	All instances have finished, but none succeeded. An instance is considered failed if it reported `Invalid`, `Aborted`, `Failed`, `Timeout`, or `Error`.
`Stopping`	At least one instance is in the `Stopping` state.
`Stopped`	All instances report `Stopped`. This occurs when all tasks were explicitly cancelled (`Cancelled`) or terminated (`Terminated`).
`PartialFailed`	All instances have finished, but results are mixed -- some succeeded and some failed or stopped.

Permissions (RAM)

By default, the Alibaba Cloud account has full access to Cloud Assistant. For production use, create a Resource Access Management (RAM) user and grant only the permissions required for the intended operations. For instructions, see Grant permissions to a RAM user to use Cloud Assistant.

Agent architecture and directory structure

Linux

The Cloud Assistant Agent is installed at /usr/local/share/aliyun-assist/. The following describes the directory layout and key components.

/usr/local/share/aliyun-assist/
- 2.x.x.xxx/ -- Version-specific installation directory (for example, 2.2.4.965/).
  - aliyun-service -- Core agent binary.
  - assist_daemon -- Daemon process (watchdog) that monitors aliyun-service and restarts it if it crashes.
  - acs-plugin-manager -- Plugin management utility.
  - aliyun_assist_update -- Auto-update utility.
  - aliyun_installer -- Deprecated. Superseded by acs-plugin-manager.
  - config/
    - GlobalSignRootCA.crt -- Root certificate for HTTPS communication with the Cloud Assistant server.
    - hash_file -- Cryptographic hashes for integrity verification.
  - init/
    - install, uninstall, clean -- Installation, uninstallation, and cleanup scripts.
    - version -- Current agent version.
  - log/
    - aliyun_assist_main.log -- Active log file (current day).
    - aliyun_assist_main.log.YYYYMMDD -- Archived logs (rotated daily).
  - plugin/
    - ACS-ECS-SysInfoGatherer -- Pre-installed system information collection plugin.
- cache/
  - state_configs.json -- Cached configuration for CloudOps Orchestration Service (OOS) inventory collection.
- config/
  - task_sign_certs/ -- Public keys used to verify task digital signatures.
- hybrid/
  - hardwareHash -- Hardware fingerprint file for managed instance registration.
- plugin/
  - installed_plugins.db -- Database of installed plugins.
- work/
  - script/ -- Staging directory for execution scripts.
    Note
    Starting from version 2.x.3.704, Cloud Assistant no longer saves execution scripts to disk by default. Enable the script-saving feature manually to view executed files in this directory.
- region-id -- Region ID where the instance resides.

Windows

The Cloud Assistant Agent is installed at C:\ProgramData\aliyun\assist\. The following describes the directory layout and key components.

C:\ProgramData\aliyun\assist\
- 2.x.x.xxx/ -- Version-specific installation directory (for example, 2.1.4.965).
  - aliyun_assist_service.exe -- Core agent binary.
  - acs-plugin-manager.exe -- Plugin management utility.
  - aliyun_assist_update.exe -- Auto-update utility.
  - aliyun_installer.exe -- Installer program.
  - install.bat, install.exe -- Installation scripts.
  - PatchGo.dll -- Runtime patch for Windows Server 2008 to mitigate Go runtime clock drift.
  - version.ini -- Agent version configuration.
  - config/
    - GlobalSignRootCA.crt -- Root certificate for HTTPS communication with the Cloud Assistant server.
    - hash_file -- Cryptographic hashes for integrity verification.
  - log/
    - aliyun_assist_main.log -- Active log file (current day).
    - aliyun_assist_main.log.YYYYMMDD -- Archived logs (rotated daily).
  - plugin/
    - ACS-ECS-SysInfoGatherer -- System information collection plugin.
    - SessionManager -- Password-free session management plugin.
    - installed_plugins.db -- Database of installed plugins.
- cache/
  - state_configs.json -- Cached configuration for OOS inventory collection.
- config/
  - task_sign_certs/ -- Public keys for task signature verification.
- hybrid/ -- Managed instance registration data.
- plugin/
  - installed_plugins.db -- Plugin database.
- work/
  - script/ -- Staging directory for execution scripts.
    Note
    Starting from version 2.x.3.704, Cloud Assistant no longer saves execution scripts to disk by default. Enable the script-saving feature manually to view executed files in this directory.
- config.ini -- Global configuration settings, including the current agent version.
- region-id -- Region ID where the instance resides.
- version -- Current agent version.

Terms

Term	Description
Cloud Assistant	The service itself. Available in all Alibaba Cloud regions.
Cloud Assistant Agent	The client-side binary running on each instance. The process name is `aliyun-service` on Linux and `aliyun_assist_service` on Windows.
AssistDaemon	A watchdog process that monitors and restarts the agent if it crashes. Linux only. Service name: `AssistDaemon`. Path: `/usr/local/share/assist-daemon/assist_daemon`.
Working directory	The path where scripts are temporarily staged (if script saving is enabled). Linux: `/tmp`. Windows: `<Cloud Assistant installation path>/work/script`.
Command	The operation payload sent to an instance. Supported types: Shell, PowerShell, and Bat.
Custom parameter	A variable defined with `{{key}}` syntax. Values are injected at runtime using `{{"key":"value"}}`. Use custom parameters to build reusable command templates and optimize usage against regional command quotas. Cloud Assistant also provides built-in environment parameters that are populated automatically at runtime.
One-time execution	A single execution event on one or more instances, also called an invocation.
Scheduled execution	A command configured to run periodically using Cron or Rate expressions.