All Products
Search
Document Center

Resource Orchestration Service:ALIYUN::ECS::RunCommand

Last Updated:Jan 03, 2024

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,
    "Timed": Boolean,
    "ContentEncoding": String,
    "Name": String,
    "WorkingDir": String,
    "CommandContent": String,
    "Type": String,
    "Frequency": String,
    "EnableParameter": Boolean,
    "InstanceIds": List,
    "KeepCommand": Boolean,
    "Sync": Boolean,
    "Tags": List,
    "RunAgainOn": List
  }
}

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 the Cloud Assistant client does not exist. If a timeout error occurs, the command process is forcefully terminated.

Timed

Boolean

No

No

Specifies whether to periodically run the command.

Valid values:

  • true: runs the command based on the interval that is specified by Frequency. The result of a command execution does not affect the next command execution.

  • false (default): runs the command only once.

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 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.

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 {{}}, the spaces and line feeds before and after the parameter names 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 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.

This property must be specified when Timed is set to true. The interval between two consecutive command executions must be at least 10 seconds. For more information about the valid values of Frequency, see CRON expressions.

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. You can call the InvokeCommand operation to run the command again. The retained command counts against the quota of Cloud Assistant commands.

  • false (default): does not retain the command. The command is automatically deleted after it is run and does not count against 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

No

The tags of the command.

You can add up to 20 tags. For more information, see Tags properties.

RunAgainOn

List

No

No

The stage of running the command again.

None.

Tags syntax

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

Tags properties

Property

Type

Required

Editable

Description

Constraint

Key

String

Yes

No

The key of the tag.

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 value of the tag.

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 result of command execution.

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