Use InvokeCommand to run commands on instances - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Triggers a Cloud Assistant command on one or more ECS instances by specifying parameters such as CommandId, InstanceId, and ResourceGroupId.

Operation description

The following limits apply to the target ECS instances. If you select multiple ECS instances and one of them does not meet the execution conditions, you must call the operation again.
- Target instance must be in the Running state. You can call DescribeInstances to query target instance status.
- Cloud Assistant Agent must be pre-installed on target instance.
- To run a PowerShell command, target instance must have the PowerShell module configured.
One-time execution: The command is executed only once.
Scheduled execution:
- The command is executed at the frequency specified by the Frequency parameter. The result of the previous execution does not affect the next execution.
- When you run a scheduled task based on a Cron expression and specify a time zone, the scheduled execution time is based on the specified time zone. If you do not specify a time zone, the scheduled execution time is based on the system time zone of the ECS instance, and the execution time is determined by the system time of target instance. Make sure that the time or time zone of the ECS instance is consistent with your expected time. For more information about time zones, see Manage time synchronization services.
Cloud Assistant Agent must be at or later than the following versions to support new features of scheduled tasks (execution at fixed intervals, one-time execution at a specified time, and specifying a year or time zone for Cron expression-based scheduled execution). If the ClientNeedUpgrade error code is returned, see Upgrade or disable upgrades for Cloud Assistant Agent to update the agent to the latest version.
- Linux: 2.2.3.282
- Windows: 2.1.3.282
A command may fail to be executed due to abnormal instance status, network exceptions, or Cloud Assistant Agent exceptions. No execution information is generated when execution fails. For more information, see Common errors and solutions for execution failures.
If you enabled the custom parameter feature when you created the command, you must pass in custom parameters (Parameters) when you execute the command.
Call DescribeCloudAssistantStatus to query the Cloud Assistant status of target instance first. Execute the command only when CloudAssistantStatus is true, especially for newly purchased instances.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:InvokeCommand

update

*Command

acs:ecs:{#regionId}:{#accountId}:command/{#commandId}

*Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

ecs:CommandRunAs

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID. You can call DescribeRegions to query the most recent region list.	cn-hangzhou
ResourceGroupId	string	No	The resource group ID for the command execution. When this parameter is specified: If the ECS instance specified by InstanceId belongs to a non-default resource group, the ECS instance must belong to this resource group. You can filter command execution results by specifying this parameter (by calling DescribeInvocations or DescribeInvocationResults).	rg-bp67acfmxazb4p****
CommandId	string	Yes	The command ID. You can call DescribeCommands to query all available command IDs. Note For public commands, you can run them by command name. For more information, see View and run Cloud Assistant public commands.	c-e996287206324975b5fbe1d****
RepeatMode	string	No	The execution mode of the command. Valid values: Once: immediately executes the command. Period: executes the command on a schedule. If you set this parameter to `Period`, you must also specify the `Frequency` parameter. NextRebootOnly: automatically executes the command the next time the instance starts. EveryReboot: automatically executes the command every time the instance starts. DryRun: only performs a dry run of the request. The command is not actually executed. Checks include request parameters, instance execution environment, and Cloud Assistant Agent running status. Default value: If the `Frequency` parameter is not specified, the default value is `Once`. If the `Frequency` parameter is specified, the command is processed as `Period` regardless of whether this parameter is set. Precautions: You can call StopInvocation to stop a pending or scheduled command. If this parameter is set to `Period` or `EveryReboot`, you can call DescribeInvocationResults and specify `IncludeHistory=true` to view the execution history of the scheduled command.	Once
Timed	boolean	No	[Deprecated] This parameter is deprecated. Specifying this parameter has no effect.	true
Frequency	string	No	The schedule on which the command is executed. Three types of scheduled execution are supported: execution at fixed intervals (based on a Rate expression), one-time execution at a specified time, and clock-based scheduled execution (based on a Cron expression). Execution at fixed intervals: Based on a Rate expression, the command is executed at the specified interval. The interval can be specified in seconds (s), minutes (m), hours (h), or days (d). This is applicable to scenarios where tasks are executed at fixed intervals. Format: `rate(<interval value><interval unit>)`. For example, to execute every 5 minutes, use `rate(5m)`. The following limits apply to execution at fixed intervals: The interval must be no greater than 7 days, no less than 60 seconds, and greater than the timeout period of the scheduled task. The execution interval is based on a fixed frequency and is not related to the actual execution time of the task. For example, if the command is set to execute every 5 minutes and the task takes 2 minutes to complete, the next round of execution starts 3 minutes after the task is completed. The task is not executed immediately upon creation. For example, if the command is set to execute every 5 minutes, the command is not executed immediately when the task is created. Instead, execution starts 5 minutes after the task is created. One-time execution at a specified time: The command is executed once at the specified time zone and time point. Format: `at(yyyy-MM-dd HH:mm:ss <time zone>)`. If no time zone is specified, UTC is used by default. The time zone supports the following three formats: Full time zone name: For example, `Asia/Shanghai` (China/Shanghai time) or `America/Los_Angeles` (US/Los Angeles time). Time zone offset from Greenwich Mean Time: For example, `GMT+8:00` (East 8th time zone) or `GMT-7:00` (West 7th time zone). When using the GMT format, leading zeros are not supported for the hour value. Time zone abbreviation: Only UTC (Coordinated Universal Time) is supported. For example, to execute once at 13:15:30 on June 6, 2022 in China/Shanghai time, use: `at(2022-06-06 13:15:30 Asia/Shanghai)`. To execute once at 13:15:30 on June 6, 2022 in the West 7th time zone, use: `at(2022-06-06 13:15:30 GMT-7:00)`. Clock-based scheduled execution (based on a Cron expression): Based on a Cron expression, the command is executed according to the scheduled task settings. Format: `<seconds> <minutes> <hours> <day of month> <month> <day of week> <year (optional)> <time zone>`, that is, `<Cron expression> <time zone>`. The scheduled task execution time is calculated based on the Cron expression in the specified time zone. If no time zone is specified, the system time zone of the instance running the scheduled task is used. For more information about Cron expressions, see Cron expressions. The time zone supports the following three formats: Full time zone name: For example, `Asia/Shanghai` (China/Shanghai time) or `America/Los_Angeles` (US/Los Angeles time). Time zone offset from Greenwich Mean Time: For example, `GMT+8:00` (East 8th time zone) or `GMT-7:00` (West 7th time zone). When using the GMT format, leading zeros are not supported for the hour value. Time zone abbreviation: Only UTC (Coordinated Universal Time) is supported. For example, to execute once at 10:15 AM every day in 2022 in China/Shanghai time, use `0 15 10 ? * * 2022 Asia/Shanghai`. To execute every 30 minutes from 10:00 AM to 11:30 AM every day in 2022 in the East 8th time zone, use `0 0/30 10-11 * * ? 2022 GMT+8:00`. To execute every 5 minutes from 2:00 PM to 2:55 PM every day in October every two years starting from 2022 in UTC, use `0 0/5 14 * 10 ? 2022/2 UTC`. Note The minimum interval must be greater than or equal to the timeout period of the scheduled task and no less than 10 seconds.	0 /20 * * ?
Parameters	object	No	The key-value pairs of custom parameters to pass in when executing the command with the custom parameter feature enabled. The number of custom parameters ranges from 0 to 10. Map keys cannot be empty strings and can contain up to 64 characters. Map values can be empty strings. After Base64 encoding, the total length of custom parameters and the original command content cannot exceed 24 KB. The set of custom parameter names must be a subset of the parameter set defined when the command was created. For parameters that are not passed in, you can use an empty string as a substitute. You can disable custom parameters by not setting this parameter.	{"name":"Jack", "accessKey":"LTAI************"}
Username	string	No	The username used to execute the command on the ECS instance. The length cannot exceed 255 characters. For Linux instances, the command is executed as the root user by default. For Windows instances, the command is executed as the System user by default. You can also specify another existing user on the instance to execute the command. Executing Cloud Assistant commands as a regular user is more secure. For more information, see Configure a regular user to run Cloud Assistant commands.	test
WindowsPasswordName	string	No	The name of the password for the user who executes the command on a Windows instance. The length cannot exceed 255 characters. When you want to execute a command on a Windows instance as a non-default user (System), you must pass in both `Username` and this parameter. To reduce the risk of password leaks, the plaintext password must be hosted in the parameter repository of operations management. Only the password name is passed in here. For more information, see Encryption parameters and Settings for a regular user to run Cloud Assistant commands. Note This parameter is not required when you execute a command as the root user on a Linux instance or the System user on a Windows instance.	axtSecretPassword
InstanceId	array	No	The list of instances on which to execute the command. You can specify up to 100 instance IDs. Valid values of N: 1 to 100. You can also apply for a quota increase in Quota Center (quota name: Maximum number of instances supported for command execution).	i-bp185dy2o3o6n****
	string	No	The instance ID on which to execute the command.	i-bp185dy2o3o6n****
ContainerId	string	No	The container ID. Only 64-bit hexadecimal strings are supported. You can use the `docker://`, `containerd://`, or `cri-o://` prefix to specify the container runtime. Precautions: If this parameter is specified, Cloud Assistant executes the script in the specified container of the instance. If this parameter is specified, the command can only run on Linux instances with Cloud Assistant Agent version 2.2.3.344 or later. To view the Cloud Assistant Agent version, see Install Cloud Assistant Agent. To upgrade the Cloud Assistant Agent version, see Upgrade or disable upgrades for Cloud Assistant Agent. If this parameter is specified, the `Username` parameter specified in this operation and the `WorkingDir` parameter specified in CreateCommand do not take effect. The command can only be executed by the default user of the container in the default working directory of the container. For more information, see Use Cloud Assistant to run commands in containers. If this parameter is specified, only Shell scripts can be executed in Linux containers. You cannot use a format such as `#!/usr/bin/python` at the beginning of the script to specify the interpreter for the script content. For more information, see Use Cloud Assistant to run commands in containers.	ab141ddfbacfe02d9dbc25966ed971536124527097398d419a6746873fea****
ContainerName	string	No	The container name. Precautions: If this parameter is specified, Cloud Assistant executes the script in the specified container of the instance. If this parameter is specified, the command can only run on Linux instances with Cloud Assistant Agent version 2.2.3.344 or later. To view the Cloud Assistant Agent version, see Install Cloud Assistant Agent. To upgrade the Cloud Assistant Agent version, see Upgrade or disable upgrades for Cloud Assistant Agent. If this parameter is specified, the `Username` parameter specified in this operation and the `WorkingDir` parameter specified in CreateCommand do not take effect. The command can only be executed by the default user of the container in the default working directory of the container. For more information, see Use Cloud Assistant to run commands in containers. If this parameter is specified, only Shell scripts can be executed in Linux containers. You cannot use a format such as `#!/usr/bin/python` at the beginning of the script to specify the interpreter for the script content. For more information, see Use Cloud Assistant to run commands in containers.	test-container
Timeout	integer	No	The timeout period for the command execution. Unit: seconds. The value cannot be less than 10 seconds. If the command cannot run due to process issues, missing modules, or missing Cloud Assistant Agent, a timeout occurs. When a timeout occurs, the command process is forcefully terminated. If this value is not set, the timeout period specified when the command was created is used. This value only serves as the timeout period for this command execution and does not change the timeout period of the command itself.	60
Tag	array<object>	No	The tags.
	object	No	The tags.
Value	string	No	The tag value of the command execution. Valid values of N: 1 to 20. The value can be an empty string. The tag value can be up to 128 characters in length and cannot contain `http://` or `https://`.	TestValue
Key	string	No	The tag key of the command execution. Valid values of N: 1 to 20. The tag key cannot be an empty string once specified. If you use a single tag to filter resources, the resource count under that tag cannot exceed 1,000. If you use multiple tags to filter resources, the number of resources that are attached to all specified tags cannot exceed 1,000. If the resource count exceeds 1,000, use the ListTagResources operation to execute the query. The tag key can be up to 64 characters in length and cannot start with `aliyun` or `acs:`, or contain `http://` or `https://`.	TestKey
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. You can use the client to generate the token, but make sure that the token is unique among different requests. The ClientToken value can contain only ASCII characters and cannot exceed 64 characters in length. For more information, see How to ensure idempotence.	123e4567-e89b-12d3-a456-42665544****
ResourceTag	array<object>	No	The tags used to filter instances. You can execute commands in batches on instances that have the same tag without specifying InstanceId.
	object	No	The tag used to filter instances. You can execute commands in batches on instances that have the same tag without specifying InstanceId.
Value	string	No	The tag value used to filter instances. Precautions: Valid values of N: 1 to 10. The value can be an empty string. The tag value can be up to 128 characters in length and cannot contain http:// or https://.	TestValue
Key	string	No	The tag key used to filter instances. Precautions: This parameter conflicts with the InstanceId parameter. You cannot specify both parameters at the same time. Valid values of N: 1 to 10. The tag key cannot be an empty string once specified. The number of instances under the tag cannot exceed the limit of InstanceId.N. If the number of instances exceeds the limit, control the number of instances by adding batch tags, such as batch: b1. The tag key can be up to 64 characters in length and cannot start with aliyun or acs:, or contain http:// or https://.	TestKey
TerminationMode	string	No	The mode for stopping the task (manual stop or timeout interruption). Valid values: Process: stops the current script process. ProcessTree: stops the current process tree (the collection of the script process and all child processes it created).	ProcessTree
Launcher	string	No	The bootstrap program for script execution. The length cannot exceed 1 KB.	python3 -u {{ACS::ScriptFileName\|Ext(".py")}}
WorkingDir	string	No	The directory in which the command is executed on the ECS instance. The length cannot exceed 200 characters. If this value is not set, the working directory specified when the command was created is used. This value only serves as the working directory for this command execution and does not change the working directory of the command itself.	/home/user
OssOutputDelivery	string	No	The OSS delivery configuration for command execution output. Format: oss://${BucketName}/${Prefix}, where ${BucketName} is the name of the OSS bucket to deliver to, and ${Prefix} is the directory prefix to deliver to.	oss://testBucket/testPrefix

Response elements

Element	Type	Description	Example
	object
InvokeId	string	The command execution ID.	t-7d2a745b412b4601b2d47f6a768d****
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****

Examples

Success response

JSON format

{
  "InvokeId": "t-7d2a745b412b4601b2d47f6a768d****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****"
}

Error codes

HTTP status code	Error code	Error message	Description
400	ResourceBusy.SlrCreation	The ServiceLinkedRole is still being created or has not taken effect yet. Please try again later.
400	RegionId.ApiNotSupported	The api is not supported in this region.	The API operation cannot be called in the specified region. Check whether the specified RegionId parameter is valid.
400	InvalidParameter.WorkingDir	The specified parameter WorkingDir is not valid.	The specified WorkingDir parameter is invalid.
400	MissingParam.InstanceId	The parameter instanceId is missing or empty.	The instance ID is empty.
400	InvalidContainerId.Malformed	The specified parameter ContainerId is not valid.	The specified container ID is invalid.
400	InvalidContainerName.Malformed	The specified parameter ContainerName is not valid.	The specified container name is invalid.
400	InvalidClientToken.Malformed	The specified parameter clientToken is not valid.	The specified ClientToken parameter does not meet the format requirements. The parameter must contain only ASCII characters and cannot exceed 64 characters in length.
400	InvalidInstance.NotMatch	The specified instance type does not match the command.
400	MissingParam.Frequency	The frequency must be specified when you create a timed task.
400	InvalidParam.Frequency	The specified frequency is invalid.
400	Parameter.MissingValue	The parameter value of this command is required.
400	Parameter.Disabled	Parameters cannot be passed in when the command customization function is disabled.
400	InvalidParameter.Parameters	The specified parameter Parameters is not valid.	The specified Parameters parameter is invalid.
400	NumberExceed.ResourceTags	The maximum number of ResourceTags is exceeded.
400	MissingParameter.ResourceTagKey	You must specify ResourceTag.N.Key.
400	InvalidResourceTagKey.Malformed	The specified ResourceTag key is not valid.
400	InvalidResourceTagValue.Malformed	The specified ResourceTag value is not valid.
400	Duplicate.ResourceTagKey	The ResourceTag contains duplicate keys.
400	InvalidResourceTag.InstanceNotFound	InstanceIds are not found by the specified ResourceTag.
400	InvalidResourceTag.ConflictWithInstanceIds	The specified param ResourceTag conflicts with InstanceId.
400	InvalidOssOutputDelivery.BucketInOtherRegion	The OSS bucket specified in the parameter OssOutputDelivery is in another region.	The OSS bucket specified in the parameter OssOutputDelivery is in another region.
400	InvalidParameter.OssOutputDelivery	The specified parameter OssOutputDelivery is not valid.	The specified parameter OssOutputDelivery is not valid.
400	InvalidOssOutputDelivery.KeyPrefixMalformed	The prefix of the OSS key specified in the parameter OssOutputDelivery is not valid.	The prefix of the OSS key specified in the parameter OssOutputDelivery is not valid.
500	InternalError.Dispatch	An error occurred when you dispatched the request.	An error occurred while the request is being sent. Try again later.
403	InvalidOssOutputDelivery.BucketAccessDenied	The error message returned by the OSS API is: %s
403	InstanceIds.ExceedLimit	The number of instance IDs exceeds the upper limit.	The number of specified instance IDs exceeds the upper limit.
403	Invocation.ExceedQuota	The invocation quota in the current region has been reached for today.	The maximum daily number of commands that can be run in the specified region has been reached.
403	ParameterCount.ExceedLimit	The maximum number of parameters is exceeded.	The number of specified custom parameters exceeds the upper limit.
403	ParameterKey.ExceedLimit	The maximum length of a parameter name is exceeded.	The key length of a custom parameter exceeds the upper limit.
403	CmdContent.ExceedLimit	The maximum length of a command is exceeded.	The length of the command content exceeds the upper limit. Shorten your command.
403	ParameterKey.Duplicate	Parameter names cannot be duplicated.	A parameter that has the same name already exists. Parameter names must be unique.
403	Parameter.NotMatched	The passed-in parameters do not match the parameters defined when you created the command.	The custom parameters passed in do not match those specified when the command was created.
403	ParameterType.NotSupported	The type of parameter value is not supported.
403	Username.ExceedLimit	The length of the username exceeds the upper limit.	The length of the username exceeds the upper limit.
403	WindowsPasswordName.ExceedLimit	The length of the WindowsPasswordName exceeds the upper limit.	The length of the specified WindowsPasswordName parameter exceeds the upper limit.
403	WindowsPasswordName.Missed	WindowsPasswordName must be specified when you create a Windows task.	The value of the request parameter WindowsPasswordName is not provided.
403	ParameterStore.NotSupported	Parameter Store is not supported in this region.
403	TemporaryAccessKey.Error	The temporary accessKey is invalid.
403	ParameterStore.InvalidParameters	The parameter is invalid in Parameter Store.	The parameter specified by {{oos:?}} in the command content was not found.
403	ParameterStore.NoPermission	You have no access to Parameter Store.
403	Operation.Forbidden	The operation is not permitted.	The operation is not supported.
403	IdempotentParameterMismatch	The specified parameter has changed while using an already used clientToken.	The specified client token has already been used.
403	IdempotentProcessing	The previous idempotent request(s) is still processing.	A previous idempotent request is being processed. Try again later.
403	InvalidLauncher.LengthLimitExceeded	The length of the parameter Launcher exceeds the limit of 1 KB characters.	The length of the argument Launcher exceeds the limit of 1 KB characters.
403	InvalidParameterCharset.Parameters	The parameter Parameters contains illegal charset.	The command parameter contains an illegal character set.
403	CreateServiceLinkedRole.NoPermission	You do not have permission to create ServiceLinkedRole for output delivery.	You do not have permission to create ServiceLinkedRole for output delivery.
403	InvalidTimeout.ExceedLimit	The specified parameter Timeout exceeds the upper limit.
404	InvalidRepeatMode.NotFound	The specified repeat mode does not exist.	The specified command execution mode does not exist.
404	InvalidRegionId.NotFound	The RegionId provided does not exist in our records.	Region information error
404	InvalidInstance.NotFound	The specified instance does not exist.	The specified instance does not exist.
404	InvalidCmdId.NotFound	The specified command ID does not exist.	The specified CommandId parameter is invalid. Check the parameter value. You can call the DescribeCommands operation to query all available command IDs.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	The specified resource group does not exist.
404	InvalidTerminationMode.NotFound	The specified parameter TerminationMode does not exist.	The specified parameter TerminationMode does not exist.
404	InvalidOssOutputDelivery.BucketNotFound	The OSS bucket specified in the parameter OssOutputDelivery does not exist.	The OSS bucket specified in the parameter OssOutputDelivery does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.