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:
  • true: runs the script on a regular basis based on the Frequency set by the Frequency parameter. The result of the previous execution task does not affect the next execution task.
  • false (default): run the command only once.
ContentEncoding String No No The encoding type of the script content. Valid values:
  • PlainText (default): transmitted in PlainText.
    Note If another value is specified, the value is PlainText.
  • Base64: base64-encoded.
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:
  • Linux instance:/root
  • Windows instance: C:\Windows\System32 \
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:
  • RunBatScript: Bat script for Windows instances.
  • RunPowerShellScript: PowerShell scripts for Windows-based instances.
  • RunShellScript: Shell script for Linux-based instances.
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:
  • true
  • false(default)
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:
  • true: The script is retained. You can execute the script again by using InvokeCommand. The retained script takes up the quota of Cloud Assistant scripts.
  • false (default): The script is not retained. It is automatically deleted after execution. It does not take up the quota of Cloud Assistant scripts.

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