Elastic Compute Service:RunCommand

The region ID. You can call the DescribeRegions operation to query the most recent region list.

The ID of the resource group to which the command execution belongs. When you specify this parameter:

• 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 specify this parameter to filter the corresponding command execution results by calling the DescribeInvocations or DescribeInvocationResults operation.

The command name. It supports all character sets and can be up to 128 characters in length.

The command description. It supports all character sets and can be up to 512 characters in length.

The command type. Valid values:

• RunBatScript: Bat commands for Windows instances.

• RunPowerShellScript: PowerShell commands for Windows instances.

• RunShellScript: Shell commands for Linux instances.

The command content. The command content can be plaintext or Base64-encoded. Take note of the following items:

• The size of the Base64-encoded command content cannot exceed 24 KB. You can use KeepCommand to specify whether to retain the command.

• If the command content is Base64-encoded, you must set ContentEncoding to Base64.

• If you set EnableParameter to true, the custom parameter feature is enabled in the command content:

  • Use {{}} to enclose custom parameters. Spaces and line breaks before and after the parameter names within {{}} are ignored.

  • You can define up to 20 custom parameters.

  • A custom parameter name can contain letters, digits, hyphens (-), and underscores (_). The acs:: prefix is not supported for specifying non-built-in environment variables. Other characters are not supported. Parameter names are not case-sensitive.

  • A single custom parameter name cannot exceed 64 bytes in length.

• You can specify built-in environment variables as custom parameters. When you execute the command, you do not need to manually assign values to the parameters. Cloud Assistant automatically replaces them with the corresponding values in the environment. The following built-in environment variables are supported:

  • {{ACS::RegionId}}: the region ID.

  • {{ACS::AccountId}}: the UID of the Alibaba Cloud account.

  • {{ACS::InstanceId}}: the instance ID. If the command is sent to multiple instances and you want to specify {{ACS::InstanceId}} as a built-in environment variable, make sure that the Cloud Assistant Agent is of the following versions or later:

    • Linux: 2.2.3.309

    • Windows: 2.1.3.309

  • {{ACS::InstanceName}}: the instance name. If the command is sent to multiple instances and you want to specify {{ACS::InstanceName}} as a built-in environment variable, make sure that the Cloud Assistant Agent is of the following versions or later:

    • Linux: 2.2.3.344

    • Windows: 2.1.3.344

  • {{ACS::InvokeId}}: the invocation ID. If you want to specify {{ACS::InvokeId}} as a built-in environment variable, make sure that the Cloud Assistant Agent is of the following versions or later:

    • Linux: 2.2.3.309

    • Windows: 2.1.3.309

  • {{ACS::CommandId}}: the command ID. If you call this operation to execute a command and want to specify {{ACS::CommandId}} as a built-in environment variable, make sure that the Cloud Assistant Agent is of the following versions or later:

    • Linux: 2.2.3.309

    • Windows: 2.1.3.309

The running directory of the command on the ECS instance. It can be up to 200 characters in length.

Default value:

• For Linux instances, the default directory is the home directory of the root user, which is /root.

• For Windows instances, the default directory is the directory where the Cloud Assistant Agent process resides, such as C:\Windows\System32.

The timeout period for command execution. Unit: seconds.

If the command cannot be run due to process issues, missing modules, or a missing Cloud Assistant Agent, a timeout occurs. After a timeout, the command process is forcibly terminated.

Default value: 60.

Specifies whether the command contains custom parameters.

Default value: false.

The execution mode of the command. Valid values:

• Once: executes the command immediately.

• 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 prechecks the request. The command execution does not take effect. The check items include request parameters, instance execution environment, and Cloud Assistant Agent running status.

Default value:

• If you do not specify the Frequency parameter, the default value is Once.

• If you specify the Frequency parameter, the value is processed as Period regardless of whether this parameter is set.

Precautions:

• You can call the StopInvocation operation to stop a pending command or a scheduled command.

• If you set this parameter to Period or EveryReboot, you can call the DescribeInvocationResults operation and set IncludeHistory=true to view the historical records of the scheduled command execution.

[Deprecated] This parameter is deprecated and does not take effect even if it is specified.

The execution time of the scheduled command. Three scheduled execution modes are supported: execution at fixed intervals (based on Rate expressions), one-time execution at a specified time, and clock-based scheduled execution (based on Cron expressions).

• Execution at fixed intervals: executes the command at the specified time interval based on a Rate expression. The time interval can be specified in seconds (s), minutes (m), hours (h), or days (d). This mode is suitable for scenarios where tasks are executed at fixed intervals. The format is rate(<interval value><interval unit>). For example, to execute the command every 5 minutes, the format is rate(5m). The following limits apply to execution at fixed intervals:

  • The specified time interval must not exceed 7 days, must not be less than 60 seconds, and must be greater than the timeout period of the scheduled task.

  • The execution interval is based only on the fixed frequency and is independent of the actual time required to execute the task. For example, if you set the command to be executed every 5 minutes and the task takes 2 minutes to complete, the next execution starts 3 minutes after the task is completed.

  • The task is not executed immediately upon creation. For example, if you set the command to be executed every 5 minutes, the command is not executed immediately upon task creation. Instead, the execution starts 5 minutes after the task is created.

• One-time execution at a specified time: executes the command once at the specified time zone and time point. The format is at(yyyy-MM-dd HH:mm:ss <time zone>), which means at(year-month-day hour:minute:second <time zone>). If you do not specify a time zone, the UTC time zone is used by default. The time zone supports the following three formats:

  • Time zone full name: such as Asia/Shanghai (China/Shanghai time) and America/Los_Angeles (US/Los Angeles time).

  • Time zone offset from Greenwich Mean Time: such as GMT+8:00 (East 8th zone) and GMT-7:00 (West 7th zone). When you use the GMT format, leading zeros are not supported for the hour digit.

  • Time zone abbreviation: only UTC (Coordinated Universal Time) is supported.

  For example, to execute the command once at 13:15:30 on June 6, 2022 in the China/Shanghai time zone, the format is at(2022-06-06 13:15:30 Asia/Shanghai). To execute the command once at 13:15:30 on June 6, 2022 in the West 7th zone, the format is at(2022-06-06 13:15:30 GMT-7:00).

• Clock-based scheduled execution (based on Cron expressions): executes the command based on a Cron expression. The format is <seconds> <minutes> <hours> <day of month> <month> <day of week> <year (optional)> <time zone>, which means <Cron expression> <time zone>. In the specified time zone, the scheduled task execution time is calculated based on the Cron expression and the task is executed. If you do not specify a time zone, the internal system time zone of the instance that executes the scheduled task is used by default. For more information about Cron expressions, see Cron expressions. The time zone supports the following three formats:

  • Time zone full name: such as Asia/Shanghai (China/Shanghai time) and America/Los_Angeles (US/Los Angeles time).

  • Time zone offset from Greenwich Mean Time: such as GMT+8:00 (East 8th zone) and GMT-7:00 (West 7th zone). When you use the GMT format, leading zeros are not supported for the hour digit.

  • Time zone abbreviation: only UTC (Coordinated Universal Time) is supported. For example, to execute the command once at 10:15 every day in 2022 in the China/Shanghai time zone, the format is 0 15 10 ? * * 2022 Asia/Shanghai. To execute the command every half hour from 10:00 to 11:30 every day in 2022 in the East 8th zone, the format is 0 0/30 10-11 * * ? 2022 GMT+8:00. To execute the command every 5 minutes from 14:00 to 14:55 every day in October every two years starting from 2022 in the UTC time zone, the format is 0 0/5 14 * 10 ? 2022/2 UTC.

  Note

  The minimum time interval must be greater than or equal to the timeout period of the scheduled task and must not be less than 10 seconds.

The key-value pairs of custom parameters passed when the command is executed, if the command contains custom parameters. For example, if the command content is echo {{name}}, you can pass the key-value pair {"name":"Jack"} by using the Parameter parameter. The custom parameter automatically replaces the variable value name, resulting in a new command. The actual command executed is echo Jack.

The number of custom parameters ranges from 0 to 10. Take note of the following items:

• The key cannot be an empty string and can be up to 64 characters in length.

• The value can be an empty string.

• After the custom parameters and the original command content are Base64-encoded, the size of the Base64-encoded command content cannot exceed 24 KB. You can use KeepCommand to specify whether to retain the command.

• The set of custom parameter names must be a subset of the parameter set defined when the command is created. For parameters that are not passed, you can use an empty string instead.

Default value: empty. This means the parameter is not set and custom parameters are disabled.

Specifies whether to retain the command after it is executed. Valid values:

• true: retains the command. You can call the InvokeCommand operation to execute it again. This consumes the quota for retained Cloud Assistant commands.

• false: does not retain the command. The command is automatically deleted after execution and does not consume the quota for retained Cloud Assistant commands.

Default value: false.

The encoding mode of the command content (CommandContent). Valid values (case-insensitive):

• PlainText: no encoding. The content is transmitted in plaintext.

• Base64: Base64 encoding.

Default value: PlainText. If an invalid value is specified, it is processed as PlainText.

The username of the user who executes the command on the ECS instance. It can be up to 255 characters in length.

• For Linux ECS instances, the command is executed by the root user by default.

• For Windows ECS instances, the command is executed by 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 execute Cloud Assistant commands.

The password name of the user who executes the command on the Windows instance. It can be up to 255 characters in length.

If you want to execute the command as a non-default user (System) on a Windows instance, you must specify both Username and this parameter. To reduce the risk of password leakage, you must host the plaintext password in the parameter repository of operations management and pass only the password name here. For more information, see Encrypted parameters and Settings for regular users to execute Cloud Assistant commands.

The container ID. Only 64-bit hexadecimal strings are supported. The docker://, containerd://, or cri-o:// prefix is allowed to explicitly specify the container runtime.

Precautions:

• If you specify this parameter, Cloud Assistant executes the script in the specified container on the instance.

• If you specify this parameter, it is only supported on Linux instances where the Cloud Assistant Agent version is 2.2.3.344 or later.

• If you specify this parameter, the specified Username and WorkingDir parameters 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 execute commands in containers.

The container name.

Precautions:

• If you specify this parameter, Cloud Assistant executes the script in the specified container on the instance.

• If you specify this parameter, it is only supported on Linux instances where the Cloud Assistant Agent version is 2.2.3.344 or later.

• If you specify this parameter, the specified Username and WorkingDir parameters 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 execute commands in containers.

The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must make sure that it 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.

The OSS delivery configuration for the command execution output.

• Format: oss://${BucketName}/${Prefix}. ${BucketName} is the name of the OSS bucket to which the output is delivered, and ${Prefix} is the directory prefix to which the output is delivered.

The mode used when the task is stopped (manually stopped or interrupted due to execution timeout). Valid values:

• Process: stops the current script process.

• ProcessTree: stops the current process tree (the script process and all child processes created by it).

The bootstrap program for script execution. It cannot exceed 1 KB in length.