ALIYUN::ECS::RunCommand is used to run a Shell, PowerShell, or batch script on one or more ECS instances.
Syntax
{
"Type": "ALIYUN::ECS::RunCommand",
"Properties": {
"Parameters": Map,
"Description": String,
"Timeout": Integer,
"Timed": Boolean,
"ContentEncoding": String,
"Name": String,
"WorkingDir": String,
"CommandContent": String,
"Type": String,
"Frequency": String,
"EnableParameter": Boolean,
"InstanceIds": List,
"KeepCommand": Boolean
}
}
Properties
Property | Type | Required | Editable | Description | Constraint |
---|---|---|---|---|---|
Parameters | Map | No | No | The key-value pairs of custom parameters that are specified when the script contains custom parameters. For example, if the script content is echo {{name}, you can use the Parameters parameter to specify the target key-value pair {"name":"Jack"}. The variable of the custom parameter is automatically replaced with the variable name to generate a new script. The script that executes the custom parameter is echo Jack. | You can specify a maximum of 10 custom parameters.
The key cannot be an empty string. It can be up to 64 characters in length. The value can be an empty string. After the custom parameters and the original script content are Base64 encoded, the total size cannot exceed 16 KB.The set of custom parameter names must be a subset of the parameter set that is defined when you created the script. For unspecified parameters, you can use an empty string instead. |
Description | String | No | No | The description of the script. | Supports all character sets and cannot exceed 512 characters in length. |
Timeout | String | No | No | The timeout period for script execution. | Unit: seconds.
Default value: 60. A timeout error occurs when a script cannot be run because the process slows down, a specific module or the Cloud Assistant client does not exist. When the script times out, the script process is forcibly terminated. |
Timed | Boolean | No | No | Specifies whether to periodically run the script. | Valid values:
|
ContentEncoding | String | No | No | The encoding type of the script content. | Valid values:
|
Name | String | No | No | The name of the command. | Supports all character sets and cannot exceed 128 characters in length. |
WorkingDir | String | No | No | The running directory of the script in the ECS instance. | Default value:
|
CommandContent | String | Yes | No | The plaintext content or the Base64-encoded content of the script. | The Base64-encoded script content cannot exceed 16 KB.
EnableParameter the value is true, you can enable the custom parameter function in the script content: the custom parameter is written in two braces ({{}}), and the spaces and line breaks before and after the parameter names in the two braces ({{}}) are ignored. The number of custom parameters cannot exceed 20. The custom parameter name can contain English letters, numbers, dashes (-) and underscores (_). A single custom parameter name cannot exceed 64 characters. |
Type | String | Yes | No | The language type of the O&M script. | Valid values:
|
Frequency | String | No | No | The frequency at which the command is invoked. | When the Timed parameter is set to true, the Frequency parameter is required. The interval between two recurring tasks cannot be less than 10 seconds. For more information about the parameter value, see Cron expression. |
EnableParameter | Boolean | No | No | Specifies whether the script contains custom parameters. | Valid values:
|
InstanceIds | List | Yes | No | The IDs of the ECS instances. | You can specify up to 20 ECS instances. The ECS instances must be in the running state. |
KeepCommand | Boolean | No | No | Whether to retain the script after it is run. | Valid values:
|
Response parameters
Fn::GetAtt
- CommandId: the ID of the script.
- InvokeId: the ID of script execution.
Examples
JSON
format
{
"ROSTemplateFormatVersion": "2015-09-01",
"Parameters": {
"Parameters": {
"Type": "Json",
"Description": "The key-value pairs of custom parameters passed in when the script contains custom parameters.\nNumber of custom parameters: 0 to 10.\nThe key cannot be an empty string. It can be up to 64 characters in length.\nThe value can be an empty string.\nAfter the custom parameters and the original script content are Base64 encoded, the total size cannot exceed 16 KB.\nThe set of custom parameter names must be a subset of the parameter set that is defined when you created the script. You can use an empty string to represent the parameters that are not passed in.\nDefault value: null, indicating that this parameter is canceled and customer parameters are disabled.",
"MaxLength": 10
},
"Description": {
"Type": "String",
"Description": "The description of the script, which supports all character sets. It can be up to 512 characters in length."
},
"Timeout": {
"Type": "Number",
"Description": "The timeout period for script execution. Unit: seconds. A timeout error occurs when a script cannot be run because the process slows down, a specific module or the Cloud Assistant client does not exist. When the script times out. the script process is forcibly terminated.\nDefault value: 60."
},
"Timed": {
"Type": "Boolean",
"Description": "Specifies whether to periodically run the script. Valid values:\ntrue: runs the script on a regular basis based on the value set for the Frequency parameter. The result of the previous execution task does not affect the next execution task.\nfalse: runs once only.\nDefault value: false",
"AllowedValues": [
"true",
"false"
]
},
"ContentEncoding": {
"Type": "String",
"Description": "The encoding mode of script content (CommandContent). Valid values (case insensitive):\nPlainText: The script content is not encoded, and transmitted in plaintext.\nBase64: base64-encoded.\nDefault value: PlainText. If the specified value of this parameter is invalid, PlainText is used by default."
},
"Name": {
"Type": "String",
"Description": "The name of the script, which supports all character sets. It can be up to 128 characters in length."
},
"WorkingDir": {
"Type": "String",
"Description": "The running directory of the script in the ECS instance.\nDefault value:\nLinux instances: under the home directory of the administrator (root user): /root.\nWindows instances: under the directory where the process of the Cloud Assistant client is located, such as C:\\ProgramData\\aliyun\\assist\\$(version)."
},
"CommandContent": {
"Type": "String",
"Description": "The plaintext content or the Base64-encoded content of the script. The Base64-encoded script content cannot exceed 16 KB.\nYou can enable the custom parameter function by setting EnableParameter=true in the script content:\nDefine custom parameters in the {{}} format. Within {{}}, the spaces and line breaks before and after the name of the parameter are ignored.\nThe number of custom parameters cannot exceed 20.\nA custom parameter name can contain only letters, digits, underscores (_), and hyphens (-). It is case insensitive.\nEach custom parameter key cannot exceed 64 bytes."
},
"Type": {
"Type": "String",
"Description": "The language type of the OM script. Valid values:\nRunBatScript: batch scripts for Windows instances\nRunPowerShellScript: PowerShell scripts for Windows instances\nRunShellScript: shell scripts for Linux instances"
},
"Frequency": {
"Type": "String",
"Description": "The execution period of recurring tasks. If the Timed parameter is set to True, you must specify the Frequency parameter. The interval between two recurring tasks cannot be less than 10 seconds.\nThe parameter value follows the cron expression. For more information, see Configure scheduled commands."
},
"EnableParameter": {
"Type": "Boolean",
"Description": "Specifies whether the script contains custom parameters.\nDefault value: false",
"AllowedValues": [
"true",
"false"
]
},
"InstanceIds": {
"Type": "Json",
"Description": "The instance id list. Select up to 20 instances at a time.Instances status must be running.",
"MinLength": 1,
"MaxLength": 20
},
"KeepCommand": {
"Type": "Boolean",
"Description": "Specifies whether to retain the script after it is run. Valid values:\ntrue: The script is retained. You can call the InvokeCommand operation to run the script again, call the DescribeCommands operation to query the script, and call the DeleteCommands operation to delete the script. The retained script takes up the quota of Cloud Assistant scripts.\nfalse: The script is not retained. It is automatically deleted after running, without taking up the quota of Cloud Assistant scripts.\nDefault value: false",
"AllowedValues": [
"true",
"false"
]
}
},
"Resources": {
"RunCommand": {
"Type": "ALIYUN::ECS::RunCommand",
"Properties": {
"Parameters": {
"Ref": "Parameters"
},
"Description": {
"Ref": "Description"
},
"Timeout": {
"Ref": "Timeout"
},
"Timed": {
"Ref": "Timed"
},
"ContentEncoding": {
"Ref": "ContentEncoding"
},
"Name": {
"Ref": "Name"
},
"WorkingDir": {
"Ref": "WorkingDir"
},
"CommandContent": {
"Ref": "CommandContent"
},
"Type": {
"Ref": "Type"
},
"Frequency": {
"Ref": "Frequency"
},
"EnableParameter": {
"Ref": "EnableParameter"
},
"InstanceIds": {
"Ref": "InstanceIds"
},
"KeepCommand": {
"Ref": "KeepCommand"
}
}
}
},
"Outputs": {
"CommandId": {
"Description": "The id of command created.",
"Value": {
"Fn::GetAtt": [
"RunCommand",
"CommandId"
]
}
},
"InvokeId": {
"Description": "The invoke id of command.",
"Value": {
"Fn::GetAtt": [
"RunCommand",
"InvokeId"
]
}
}
}
}
YAML
format
ROSTemplateFormatVersion: '2015-09-01'
Parameters:
Parameters:
Type: Json
Description: >-
The key-value pairs of custom parameters passed in when the script
contains custom parameters.
Number of custom parameters: 0 to 10.
The key cannot be an empty string. It can be up to 64 characters in
length.
The value can be an empty string.
After the custom parameters and the original script content are Base64
encoded, the total size cannot exceed 16 KB.
The set of custom parameter names must be a subset of the parameter set
that is defined when you created the script. You can use an empty string
to represent the parameters that are not passed in.
Default value: null, indicating that this parameter is canceled and
customer parameters are disabled.
MaxLength: 10
Description:
Type: String
Description: >-
The description of the script, which supports all character sets. It can
be up to 512 characters in length.
Timeout:
Type: Number
Description: >-
The timeout period for script execution. Unit: seconds. A timeout error
occurs when a script cannot be run because the process slows down, a
specific module or the Cloud Assistant client does not exist. When the
script times out, the script process is forcibly terminated.
Default value: 60.
Timed:
Type: Boolean
Description: >-
Specifies whether to periodically run the script. Valid values:
true: runs the script on a regular basis based on the value set for the
Frequency parameter. The result of the previous execution task does not
affect the next execution task.
false: runs once only.
Default value: false
AllowedValues:
- 'true'
- 'false'
ContentEncoding:
Type: String
Description: >-
The encoding mode of script content (CommandContent). Valid values (case
insensitive):
PlainText: The script content is not encoded, and transmitted in
plaintext.
Base64: base64-encoded.
Default value: PlainText. If the specified value of this parameter is
invalid, PlainText is used by default.
Name:
Type: String
Description: >-
The name of the script, which supports all character sets. It can be up to
128 characters in length.
WorkingDir:
Type: String
Description: >-
The running directory of the script in the ECS instance.
Default value:
Linux instances: under the home directory of the administrator (root
user): /root.
Windows instances: under the directory where the process of the Cloud
Assistant client is located, such as
C:\ProgramData\aliyun\assist\$(version).
CommandContent:
Type: String
Description: >-
The plaintext content or the Base64-encoded content of the script. The
Base64-encoded script content cannot exceed 16 KB.
You can enable the custom parameter function by setting
EnableParameter=true in the script content:
Define custom parameters in the {{}} format. Within {{}}, the spaces and
line breaks before and after the name of the parameter are ignored.
The number of custom parameters cannot exceed 20.
A custom parameter name can contain only letters, digits, underscores (_),
and hyphens (-). It is case insensitive.
Each custom parameter key cannot exceed 64 bytes.
Type:
Type: String
Description: |-
The language type of the OM script. Valid values:
RunBatScript: batch scripts for Windows instances
RunPowerShellScript: PowerShell scripts for Windows instances
RunShellScript: shell scripts for Linux instances
Frequency:
Type: String
Description: >-
The execution period of recurring tasks. If the Timed parameter is set to
True, you must specify the Frequency parameter. The interval between two
recurring tasks cannot be less than 10 seconds.
The parameter value follows the cron expression. For more information, see
Configure scheduled commands.
EnableParameter:
Type: Boolean
Description: |-
Specifies whether the script contains custom parameters.
Default value: false
AllowedValues:
- 'true'
- 'false'
InstanceIds:
Type: Json
Description: >-
The instance id list. Select up to 20 instances at a time.Instances status
must be running.
MinLength: 1
MaxLength: 20
KeepCommand:
Type: Boolean
Description: >-
Specifies whether to retain the script after it is run. Valid values:
true: The script is retained. You can call the InvokeCommand operation to
run the script again and call the DescribeCommands operation to query the
script, and call the DeleteCommands operation to delete the script. The
retained script takes up the quota of Cloud Assistant scripts.
false: The script is not retained. It is automatically deleted after
running, without taking up the quota of Cloud Assistant scripts.
Default value: false
AllowedValues:
- 'true'
- 'false'
Resources:
RunCommand:
Type: 'ALIYUN::ECS::RunCommand'
Properties:
Parameters:
Ref: Parameters
Description:
Ref: Description
Timeout:
Ref: Timeout
Timed:
Ref: Timed
ContentEncoding:
Ref: ContentEncoding
Name:
Ref: Name
WorkingDir:
Ref: WorkingDir
CommandContent:
Ref: CommandContent
Type:
Ref: Type
Frequency:
Ref: Frequency
EnableParameter:
Ref: EnableParameter
InstanceIds:
Ref: InstanceIds
KeepCommand:
Ref: KeepCommand
Outputs:
CommandId:
Description: The id of command created.
Value:
'Fn::GetAtt':
-RunCommand
-CommandId
InvokeId:
Description: The invoke id of command.
Value:
'Fn::GetAtt':
-RunCommand
-InvokeId