All Products
Search
Document Center

Resource Orchestration Service:ALIYUN::ECS::Command

Last Updated:Jul 02, 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,
    "Tags": List,
    "ResourceGroupId": String,
    "ContentEncoding": String
  }
}

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.

Note

If you set WorkingDir to a value other than default ones, make sure that the directory exists on the instance.

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 18 KB in size.

  • You can use custom parameters in the command content. To enable the custom parameter feature, you must set EnableParameter to true.

    • Custom parameters are defined 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 only letters, digits, hyphens (-), and underscores (_). The name is case-insensitive. You cannot use the ACS:: prefix to specify non-built-in environment parameters.

    • Each custom parameter name can be up to 64 bytes in length.

  • You can specify built-in environment parameters as custom parameters in a command. When you run the command, Cloud Assistant automatically uses the environment parameter values for the custom parameters. You can specify the following built-in environment variables:

    • {{ACS::RegionId}}: the region ID.

    • {{ACS::AccountId}}: the unique identifier (UID) of the Alibaba Cloud account.

    • {{ACS::InstanceId}}: the instance ID. If you want to specify {{ACS::InstanceId}} as a built-in environment variable when the command is run on multiple instances, make sure that the version of Cloud Assistant Agent is not earlier than the following versions:

      • Linux: 2.2.3.309

      • Windows: 2.1.3.309

    • {{ACS::InstanceName}}: the instance name. If you want to specify {{ACS::InstanceName}} as a built-in environment variable when the command is run on multiple instances, make sure that the version of Cloud Assistant Agent is not earlier than the following versions:

      • Linux: 2.2.3.344

      • Windows: 2.1.3.344

    • {{ACS::InvokeId}}: the ID of the command task. If you want to specify {{ACS::InvokeId}} as a built-in environment variable, make sure that the version of Cloud Assistant Agent is not earlier than the following versions:

      • Linux: 2.2.3.309

      • Windows: 2.1.3.309

    • {{ACS::CommandId}}: the command ID. If you want to specify {{ACS::CommandId}} as a built-in environment variable when you run the command by calling the RunCommand operation, make sure that the version of Cloud Assistant Agent is not earlier than the following versions:

      • Linux: 2.2.3.309

      • Windows: 2.1.3.309

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. You can add up to 20 tags.

For more information, see Tags properties.

ContentEncoding

String

No

No

The encoding mode of the command content.

Valid values:

  • PlainText: does not encode the command content.

  • Base64 (default): encodes the command content in Base64.

Note

If you specify an invalid value, Base64 is used for this property.

ResourceGroupId

String

No

Yes

The ID of the resource group to which the command belongs.

None.

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.

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