Use ALIYUN::ECS::RunCommand in a call to run a command on ECS instances - Resource Orchestration Service

ALIYUN::ECS::RunCommand is used to run a shell, PowerShell, or batch command on Elastic Compute Service (ECS) instances.

Syntax

{
  "Type": "ALIYUN::ECS::RunCommand",
  "Properties": {
    "Parameters": Map,
    "Description": String,
    "Timeout": Integer,
    "ContentEncoding": String,
    "Name": String,
    "WorkingDir": String,
    "CommandContent": String,
    "Type": String,
    "Frequency": String,
    "EnableParameter": Boolean,
    "InstanceIds": List,
    "KeepCommand": Boolean,
    "Sync": Boolean,
    "Tags": List,
    "RunAgainOn": List,
    "WindowsPasswordName": String,
    "RepeatMode": String,
    "ResourceGroupId": String,
    "ContainerName": String,
    "ContainerId": String,
    "Username": String
  }
}

Properties

Property	Type	Required	Editable	Description	Constraint
Parameters	Map	No	Yes	The key-value pairs of the custom parameters that are passed in if the command includes custom parameters. For example, if the command content is echo {{name}}, you can use the Parameters property to pass in the {"name":"Jack"} key-value pair. The value of the name variable in echo {{name}} is automatically replaced by the paired Jack value to generate a new command. As a result, the echo Jack command is run.	You can specify up to 10 custom parameters. The key of a custom parameter can be up to 64 characters in length, and cannot be an empty string. The value of a custom parameter can be an empty string. After the custom parameters and the original command content are encoded in Base64, the total size can be up to 16 KB. The custom parameter names specified in the value of the Parameters property must be included in the custom parameter settings that you configured 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	Yes	The timeout period for running the command.	Unit: seconds. Default value: 60. A timeout error occurs if a command cannot be run because the command process slows down or because a specific module or Cloud Assistant Agent does not exist. When a timeout error occurs, the command process is forcefully terminated.
ContentEncoding	String	No	Yes	The encoding mode of the command content that is specified by CommandContent.	Valid values: Base64 (default): encodes the command content in Base64. PlainText: does not encode the command content. Note If you specify an invalid value for this property, Base64 is used to encode the command content.
Name	String	No	No	The command name.	The name supports all character sets and can be up to 128 characters in length.
WorkingDir	String	No	Yes	The working directory of the command on the ECS instance.	Default values: Default value for Linux instances: /root Default value for Windows instances: C:\Windows\System32\
CommandContent	String	Yes	Yes	The command content. The command content can be plaintext or Base64-encoded.	After the command content is encoded in Base64, the content can be up to 16 KB in size. If you set EnableParameter to true, the custom parameter feature is enabled. You can configure custom parameters based on the following rules: Specify custom parameters in the {{}} format. Within {{}}, spaces and line feeds before and after the parameter names are ignored. You can specify up to 10 custom parameters. A custom parameter name can contain letters, digits, hyphens (-), and underscores (_). A custom parameter name can be up to 64 characters in length.
Type	String	Yes	Yes	The language type of the command.	Valid values: RunBatScript: batch command. Batch commands are applicable to Window instances. RunPowerShellScript: PowerShell command. PowerShell commands are applicable to Window instances. RunShellScript: shell command. Shell commands are applicable to Linux instances.
Frequency	String	No	No	The interval at which the command is run.	None.
EnableParameter	Boolean	No	Yes	Specifies whether to include custom parameters in the command.	Valid values: true false (default)
InstanceIds	List	Yes	Yes	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	Specifies whether to retain the command after it is run.	Valid values: true: retains the command after it is run. You can call the InvokeCommand operation to run the command again. The retained command consumes the quota of Cloud Assistant commands. false (default): does not retain the command after it is run. The command is automatically deleted after it is run and does not consume the quota of Cloud Assistant commands.
Sync	Boolean	No	No	Specifies whether to run the command in synchronous mode.	Valid values: true false
Tags	List	No	Yes	The tags.	You can add up to 20 tags. For more information, see Tags properties.
RunAgainOn	List	No	No	The stages of running the command again.	None.
WindowsPasswordName	String	No	No	The name of the password that you want to use to run the command on Windows instances.	The name can be up to 255 characters in length. If you do not want to use the default System user to run the command on Windows instances, specify both WindowsPasswordName and `Username`. The password is hosted in plaintext in the parameter repository of CloudOps Orchestration Service (OOS) to mitigate the risk of password leaks. Only the name of the password is passed in by using WindowsPasswordName. For more information, see Encrypted parameters and Run Cloud Assistant commands as a regular user. Note If you use the root user of a Linux instance or the System user of a Windows instance to run the command, you can leave WindowsPasswordName empty.
RepeatMode	String	No	No	The mode in which you want to run the command.	Valid values: Once: runs the command immediately. Period: runs the command on a schedule. If you set this property to `Period`, you must specify `Frequency`. NextRebootOnly: runs the command the next time the instance is started. EveryReboot: runs the command every time the instance is started. Default values: If you do not specify `Frequency`, the default value of RepeatMode is `Once`. If you specify `Frequency`, `Period` is used as the value of RepeatMode regardless of whether RepeatMode is set to Period. Take note of the following items: You can call the StopInvocation operation to stop the pending or scheduled executions of the command. If you set this property to `Period` or `EveryReboot`, you can call the DescribeInvocationResults operation and set `IncludeHistory` to true to query the results of historical scheduled executions of the command.
ResourceGroupId	String	No	No	The ID of the resource group to which the command executions belong.	Take note of the following items: The ECS instance that is specified by InstanceId must belong to the resource group. After the command is run, you can call the DescribeInvocations or DescribeInvocationResults operation and specify ResourceGroupId to filter command execution results in the specified resource group.
ContainerName	String	No	No	The container name.	Take note of the following items: If this property is specified, Cloud Assistant runs the command in the specified container of the instance. If this property is specified, the command can be run only on Linux instances whose Cloud Assistant Agent is of version 2.2.3.344 or later. If this property is specified, the specified `Username` and `WorkingDir` do not take effect. You can run the command in the default working directory of the container only by using the default user of the container. For more information, see Use Cloud Assistant to run commands in containers. If this property is specified, you can run only shell scripts in Linux containers. You cannot add a command in the format similar to `#!/usr/bin/python` at the beginning of a script to specify a script interpreter. For more information, see Use Cloud Assistant to run commands in containers.
ContainerId	String	No	No	The container ID.	Only 64-bit hexadecimal strings are supported. You can use container IDs that are prefixed with `docker://`, `containerd://`, or `cri-o://` to specify container runtimes. Take note of the following items: If this property is specified, Cloud Assistant runs the command in the specified container of the instance. If this property is specified, the command can be run only on Linux instances whose Cloud Assistant Agent is of version 2.2.3.344 or later. If this property is specified, the specified `Username` and `WorkingDir` do not take effect. You can run the command in the default working directory of the container only by using the default user of the container. For more information, see Use Cloud Assistant to run commands in containers. If this property is specified, you can run only shell scripts in Linux containers. You cannot add a command in the format similar to `#!/usr/bin/python` at the beginning of a script to specify a script interpreter. For more information, see Use Cloud Assistant to run commands in containers.
Username	String	No	Yes	The username that you want to use to run the command on ECS instances.	The username can be up to 255 characters in length. For ECS Linux instances, the root username is used by default. For ECS Windows instances, the System username is used by default. You can also specify other usernames that already exist on the ECS instances to run the command. For security purposes, we recommend that you run Cloud Assistant commands as a regular user. For more information, see Run Cloud Assistant commands as a regular user.

Tags syntax

"Tags": [
  {
    "Key": String,
    "Value": String
  }
]

Tags properties

Property	Type	Required	Editable	Description	Constraint
Key	String	Yes	No	The tag key.	The tag key must be 1 to 128 characters in length, and cannot contain `http://` or `https://`. It cannot start with `aliyun` or `acs:`.
Value	String	No	No	The tag value.	The tag value can be up to 128 characters in length, and cannot contain `http://` or `https://`. It cannot start with `aliyun` or `acs:`.

Return values

Fn::GetAtt

CommandId: the command ID.
InvokeId: the ID of the command execution.
InvokeInstances: the ECS instances on which the command is run.
InvokeResults: the execution results of the command.

Examples

`YAML` format

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

`JSON` format

{
  "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"
        ]
      }
    }
  }
}

UpdatePolicy overview

After you use ALIYUN::ECS::RunCommand to run a command on a collection of ECS instances, you can use the UpdatePolicy property to update the configurations of the ECS instances in batches. The following tables describe the UpdatePolicy property and its syntax.

UpdatePolicy syntax

"UpdatePolicy": {
  "RollingUpdate": Map
}

UpdatePolicy property

Property	Type	Required	Editable	Description	Constraint
RollingUpdate	Map	No	Yes	The update policy for the existing command.	For more information, see RollingUpdate properties.

RollingUpdate syntax

"RollingUpdate": {
  "MaxBatchSize": Integer,
  "PauseTime": Integer
}

RollingUpdate properties

Property	Type	Required	Editable	Description	Constraint
MaxBatchSize	Integer	Yes	Yes	The number of ECS instances on which you want to run the command in each batch.	Valid values: 1 to 1000.
PauseTime	Integer	No	Yes	The interval between two batch command executions. Default value: 0. Unit: seconds.	Valid values: 0 to 3600.

Templates before and after the update

You can use the following template to run the same command on three ECS instances:

{
    "ROSTemplateFormatVersion": "2015-09-01",
    "Resources": {
        "RunCommand": {
            "Type": "ALIYUN::ECS::RunCommand",
            "Properties": {
                "CommandContent": "xxx",
                "Type": "RunShellScript",
                "Sync": true,
                "InstanceIds": [
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                ]
            }
        }
    }
}

After the stack that contains the ECS instances is created, you can add the UpdatePolicy property to the template to update the configurations of the ECS instances:

{
    "ROSTemplateFormatVersion": "2015-09-01",
    "Resources": {
        "RunCommand": {
            "Type": "ALIYUN::ECS::RunCommand",
            "Properties": {
                "CommandContent": "xxx",
                "Type": "RunShellScript",
                "Sync": true,
                "InstanceIds": [
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                ]
            },
            "UpdatePolicy": {
                "RollingUpdate": {
                    "MaxBatchSize": 2
                    "PauseTime": 10
                }
            }
        }
    }
}

In the preceding sample code, MaxBatchSize is set to 2. The number of ECS instances indicated by InstanceIds is updated from 3 to 5. During the stack update process, the configurations of the original three ECS instances are updated in two batches in the specified sequence. Each batch separately contains two and one instances. The command is run on the new two ECS instances at a time.