All Products
Search
Document Center

Resource Orchestration Service:ALIYUN::ECS::Command

Last Updated:Mar 08, 2024

ALIYUN::ECS::Command is used to create a Cloud Assistant command.

Syntax

{
  "Type": "ALIYUN::ECS::Command",
  "Properties": {
    "Name": String,
    "WorkingDir": String,
    "CommandContent": String,
    "Timeout": Integer,
    "Type": String,
    "Description": String,
    "EnableParameter": Boolean,
    "Username": String,
    "WindowsPasswordName": String,
    "ResourceGroupId": String,
    "ContainerName": String,
    "ContainerId": String,
    "RepeatMode": String
    "Tags": List
  }
}

Properties

Property

Type

Required

Editable

Description

Constraint

Name

String

No

Yes

The command name.

The command name must be 1 to 128 characters in length. All character sets are supported.

WorkingDir

String

No

Yes

The working directory of the command on the Elastic Compute Service (ECS) instance.

Default values:

  • For Linux instances, the default value is /root, which is the home directory of the root user.

  • For Windows instances, the default value is the directory where the process of Cloud Assistant Agent resides, such as C:\Windows\System32.

CommandContent

String

No

No

The Base64-encoded content of the command.

The value of this property must be Base64-encoded and can be up to 16 KB in size.

You can define custom parameters in the command content. To use custom parameters, you must set EnableParameter to true.

  • You can define custom parameters by enclosing them in two nested braces {{ }}. The spaces and line feeds before and after parameter names in {{ }} are ignored.

  • You can specify up to 20 custom parameters.

  • The name of a custom parameter can contain letters and digits. The name is case-insensitive.

  • The name of each custom parameter can be up to 64 characters in length.

Timeout

Integer

No

Yes

The timeout period for running the command on the ECS instance.

If the command fails to run within the specified period, the command times out. When a command execution times out, Cloud Assistant Agent forcefully terminates the command process by canceling the process ID (PID).

Default value: 60.

Unit: seconds.

Type

String

Yes

No

The command type.

Valid values:

  • RunBatScript: batch command. Batch commands are applicable to Windows instances.

  • RunPowerShellScript: PowerShell command. PowerShell commands are applicable to Windows instances.

  • RunShellScript: shell command. Shell commands are applicable to Linux instances.

Description

String

No

Yes

The description of the command.

The description must be 1 to 512 characters in length. All character sets are supported.

EnableParameter

Boolean

No

No

Specifies whether to use custom parameters in the command.

Valid values:

  • true

  • false (default)

Tags

List

No

No

The tags of the instance. You can add up to 20 tags.

For more information, see Tags properties.

RepeatMode

String

No

No

The mode in which you want to run the command.

Valid values:

  • Once: immediately runs the command.

  • 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: automatically runs the command every time the instance is started.

Default values:

  • Default value when you do not specify Frequency: Once.

  • Default value when you specify Frequency: Period. This value is used for 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.

Take note of the following items when you specify ResourceGroupId:

  • 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 query execution results of the command in the specified resource group.

ContainerName

String

No

No

The container name.

Take note of the following items:

  • If you specify this property, Cloud Assistant runs scripts in the specified container of the instance.

  • If you specify this property, you can run scripts only on Linux instances on which Cloud Assistant Agent is installed. The version of Cloud Assistant Agent must be 2.2.3.344 or later.

  • If you specify this property, Username that is specified in a request to call this operation and WorkingDir that is specified in a request to call the CreateCommand operation do not take effect. You can run the command only 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 you specify this property, you can run only shell scripts in Linux containers. You cannot specify a script interpreter by adding a command in a format that is similar to #!/usr/bin/python at the beginning of a script. 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 you specify this property, Cloud Assistant runs scripts in the specified container of the instance.

  • If you specify this property, you can run scripts only on Linux instances on which Cloud Assistant Agent is installed. The version of Cloud Assistant Agent must be 2.2.3.344 or later.

  • If you specify this property, Username that is specified in a request to call this operation and WorkingDir that is specified in a request to call the CreateCommand operation do not take effect. You can run the command only 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 you specify this property, you can run only shell scripts in Linux containers. You cannot specify a script interpreter by adding a command in a format that is similar to #!/usr/bin/python at the beginning of a script. For more information, see Use Cloud Assistant to run commands in containers.

Username

String

No

No

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

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, you must 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 Manage encryption parameters and Run Cloud Assistant commands as a regular user.

Note

You do not need to specify this property when you use the root user of a Linux instance or the System user of a Windows instance to run the command.

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://. The tag key 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://. The tag value cannot start with aliyun or acs:.

Return values

Fn::GetAtt

CommandId: the command ID.

Note

You can run the command only once. For more information, see ALIYUN::ECS::RunCommand.

Examples

  • YAML format

    ROSTemplateFormatVersion: '2015-09-01'
    Parameters: {}
    Resources:
      Command:
        Type: ALIYUN::ECS::Command
        Properties:
          CommandContent:
            Fn::Base64Encode: |
              #!/bin/bash
              echo "hello" >> /root/test.sh
          Type: RunShellScript
          Name:
            Ref: ALIYUN::StackName
    Outputs:
      CommandId:
        Description: The id of command created.
        Value:
          Fn::GetAtt:
            - Command
            - CommandId
  • JSON format

    {
      "ROSTemplateFormatVersion": "2015-09-01",
      "Parameters": {
      },
      "Resources": {
        "Command": {
          "Type": "ALIYUN::ECS::Command",
          "Properties": {
            "CommandContent": {
              "Fn::Base64Encode": "#!/bin/bash\necho \"hello\" >> /root/test.sh\n"
            },
            "Type": "RunShellScript",
            "Name": {
              "Ref": "ALIYUN::StackName"
            }
          }
        }
      },
      "Outputs": {
        "CommandId": {
          "Description": "The id of command created.",
          "Value": {
            "Fn::GetAtt": [
              "Command",
              "CommandId"
            ]
          }
        }
      }
    }