ALIYUN::ECS::RunCommand is used to run a shell, PowerShell, or batch command on one or more Elastic Compute Service (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,
    "Sync": Boolean
  }
}

Properties

Property Type Required Editable Description Constraint
Parameters Map No No The key-value pairs of custom parameters. This property is available if the command contains custom parameters. For example, if the command content is echo {{name}}, you can use the Parameters property to specify the {"name":"Jack"} key-value pair. The name variable value of the custom parameter is automatically replaced to generate a new command. In this example, the echo Jack command is actually run. You can specify at most 10 custom parameters.

The key of a custom parameter cannot be an empty string and can be up to 64 characters in length. The value of a custom parameter can be an empty string.

The total size after the custom parameters and the original command content are encoded in Base64 cannot exceed 16 KB.

The custom parameter names specified in the value of Parameters must all be included in the custom parameter settings specified when you created the command.

You can use empty strings to represent the parameters that are not specified.
Description String No No The description of the command. The description supports all character sets and can be up to 512 characters in length.
Timeout Integer No No The timeout period for running the command. Unit: seconds.

Default value: 60.

A timeout error occurs if the command cannot be run because the process slows down or because a specific module or the Cloud Assistant client does not exist. When a timeout error occurs, the command process is forcibly terminated.
Timed Boolean No No Specifies whether to periodically run the command. Valid values:
  • true: periodically runs the command based on the schedule specified by the Frequency property. The results of each execution do not affect the next execution.
  • false: runs the command only once. This is the default value.
ContentEncoding String No No The encoding mode of the command content specified by the CommandContent property. Valid values:
  • PlainText: does not encode the command content. This is the default value.
    Note If you set this property to a value other than PlainText and Base64, the default value PlainText takes effect.
  • Base64: encodes the command content in Base64.
Name String No No The name of the command. The name supports all character sets and can be up to 128 characters in length.
WorkingDir String No No The working directory of the command on the ECS instance. Default value:
  • Default value for Linux instances: /root
  • Default value for Windows instances: C:\Windows\System32\
CommandContent String Yes No The content of the command. The command content can be plaintext or Base64-encoded. If the command content is Base64-encoded, the content cannot exceed 16 KB in size.

If you set the EnableParameter property to true, you can use custom parameters in the command. You must enclose a custom parameter in two pairs of braces ({{}}). In the braces, spaces and line feeds before and after the parameter name are ignored.

You can specify up to 20 custom parameters. A custom parameter name can contain letters, digits, hyphens (-), and underscores (_). A custom parameter name cannot exceed 64 characters in length.
Type String Yes No The language type of the command. Valid values:
  • RunBatScript: batch command for Window instances
  • RunPowerShellScript: PowerShell command for Window instances
  • RunShellScript: shell command for Linux instances
Frequency String No No The frequency at which the system runs the command. This property is required if the Timed property is set to true. The interval between two consecutive executions cannot be less than 10 seconds. For information about the value format of this property, see Cron expressions.
EnableParameter Boolean No No Specifies whether to contain custom parameters in the command. Valid values:
  • true.
  • false. This is the default value.
InstanceIds List Yes No The IDs of ECS instances. You can specify a maximum of 20 ECS instances, and the ECS instances must be in the Running state.
KeepCommand Boolean No No Specifies whether to retain the command after it is run. Valid values:
  • true: retains the command. If you set this property to true, you can call the InvokeCommand operation to run the command again. A retained command takes up the quota of Cloud Assistant commands.
  • false: does not retain the command. If you set this property to false, the command is automatically deleted after it is run. In this case, the command does not take up the quota of Cloud Assistant commands. This is the default value.
Sync Boolean No No Specifies whether to run the command in synchronous mode. Valid values:
  • true: runs the command in synchronous mode.
  • false: runs the command in asynchronous mode.

Response parameters

Fn::GetAtt

  • CommandId: the ID of the command.
  • InvokeId: the ID of the execution.
  • InvokeInstances: the information about the ECS instances on which the command is run.

Example

  • YAMLformat

    ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  InstanceId:
    Type: String
    AssociationProperty: ALIYUN::ECS::Instance::InstanceId
Resources:
  RunCommand:
    Type: ALIYUN::ECS::RunCommand
    Properties:
      CommandContent:
        Fn::Sub:
          - |
            #!/bin/sh
            yum install -y tree
      Type: RunShellScript
      InstanceIds:
        - Ref: InstanceId
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

  • JSONformat

    {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "InstanceId": {
      "Type": "String",
      "AssociationProperty": "ALIYUN::ECS::Instance::InstanceId"
    }
  },
  "Resources": {
    "RunCommand": {
      "Type": "ALIYUN::ECS::RunCommand",
      "Properties": {
        "CommandContent": {
          "Fn::Sub": [
            "#!/bin/sh\nyum install -y tree\n"
          ]
        },
        "Type": "RunShellScript",
        "InstanceIds": [
          {
            "Ref": "InstanceId"
          }
        ]
      }
    }
  },
  "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"
        ]
      }
    }
  }
}