DocsICP FilingConsole
Documentation
Home Page Resource Orchestration Service Developer Reference Resource Types ECS ALIYUN::ECS::Invocation

ALIYUN::ECS::Invocation

Updated at:
Copy as MD
Product
My Favorites

The ALIYUN::ECS::Invocation resource runs a Cloud Assistant command on one or more Elastic Compute Service (ECS) instances.

Syntax

{
  "Type": "ALIYUN::ECS::Invocation",
  "Properties": {
    "Frequency": String,
    "CommandId": String,
    "Parameters": Map,
    "InstanceIds": List,
    "Sync": Boolean,
    "CommandName": String,
    "WindowsPasswordName": String,
    "Timeout": Integer,
    "RepeatMode": String,
    "ResourceGroupId": String,
    "ContainerName": String,
    "ContainerId": String,
    "Launcher": String,
    "Username": String,
    "Tags": List
  }
}

Properties

Property name

Type

Required

Update allowed

Description

Constraints

Frequency

String

No

No

The schedule on which to run the auto triggered task. The value must be a valid Cron expression.

None

CommandId

String

No

Yes

The ID of the command.

None

InstanceIds

List

Yes

Yes

A list of instance IDs on which to run the command.

You can specify up to 20 instance IDs.

Parameters

Map

No

Yes

The key-value pairs of the custom parameters to pass to the command when the custom parameter feature is enabled. Example: {"name": "Jack", "accessKey": "LTAI****************"}.

The value of the custom parameter ranges from 0 to 10.

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

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

The set of custom parameter names must be a subset of the parameter set that was defined when the command was created. You can use an empty string for a parameter that is not passed.

Sync

Boolean

No

No

Specifies whether to run the command synchronously.

Valid values:

  • true: Synchronous invocation.

  • false: Asynchronous invocation.

Launcher

String

No

No

The launcher to use for running the script.

The length cannot exceed 1 KB.

CommandName

String

No

No

The name of the command.

None

WindowsPasswordName

String

No

No

The name of the password for the user who runs the command on a Windows instance.

The length cannot exceed 255 characters.

If you want to run a command on a Windows instance as a user other than the default user (System), specify both Username and this parameter. To reduce the threat of password leakage, store the plaintext password in the parameter repository of Operation Orchestration Service (OOS) and specify only the name of the password here. For more information, see Encrypted parameters and Run Cloud Assistant commands as a regular user.

Note

This parameter is not required when you run a command as the `root` user on a Linux instance or as the `System` user on a Windows instance.

Timeout

Integer

No

Yes

The timeout period for running the command.

Unit: seconds.

  • The value cannot be less than 10 seconds.

  • A timeout occurs if the command cannot be run due to issues such as a problematic process, a missing module, or a missing Cloud Assistant Agent. After a timeout, the command process is forcibly stopped.

  • If you do not set this parameter, the timeout period specified when the command was created is used.

  • This value applies only to the current command execution and does not change the timeout period of the command itself.

RepeatMode

String

No

No

The execution mode of the command.

Valid values:

  • Once: Runs the command immediately.

  • Period: Runs the command on a schedule. If you set this parameter to Period, you must also specify the Frequency parameter.

  • NextRebootOnly: Runs the command automatically the next time the instance starts.

  • EveryReboot: Runs the command automatically every time the instance starts.

Default value:

  • If you do not specify the Frequency parameter, the default value is Once.

  • If you specify the Frequency parameter, the value is always treated as Period, regardless of the value you set for this parameter.

Note:

  • You can call StopInvocation to stop a pending or scheduled command.

  • If you set this parameter to Period or EveryReboot, you can call DescribeInvocationResults and set IncludeHistory=true to view the execution history of the scheduled command.

ResourceGroupId

String

No

No

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

If you specify this parameter:

ContainerName

String

No

No

The name of the container.

Note:

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

  • If you specify this parameter, the command can be run only on Linux instances with Cloud Assistant Agent V2.2.3.344 or later.

  • If you specify this parameter, the Username parameter in this operation and the WorkingDir parameter in CreateCommand do not take effect. The command can be run only by the default user of the container in the default working directory of the container. For more information, see Run commands in a container using Cloud Assistant.

  • If you specify this parameter, only Shell scripts can be run in Linux containers. You cannot use commands such as #!/usr/bin/python at the beginning of a script to specify an interpreter for the script content. For more information, see Run commands in a container using Cloud Assistant.

ContainerId

String

No

No

The ID of the container.

Only 64-bit hexadecimal strings are supported. You can use the docker://, containerd://, or cri-o:// prefix to specify the container runtime.

Note:

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

  • If you specify this parameter, the command can be run only on Linux instances with Cloud Assistant Agent V2.2.3.344 or later.

  • If you specify this parameter, the Username parameter in this operation and the WorkingDir parameter in CreateCommand do not take effect. The command can be run only by the default user of the container in the default working directory of the container. For more information, see Run commands in a container using Cloud Assistant.

  • If you specify this parameter, only Shell scripts can be run in Linux containers. You cannot use commands such as #!/usr/bin/python at the beginning of a script to specify an interpreter for the script content. For more information, see Run commands in a container using Cloud Assistant.

Username

String

No

No

The name of the user who runs the command on the ECS instance.

The length cannot exceed 255 characters.

  • On Linux ECS instances, commands are run as the `root` user by default.

  • On Windows ECS instances, commands are run as the `System` user by default.

You can also specify another existing user on the instance to run the command. Running Cloud Assistant commands as a regular user is more secure. For more information, see Run Cloud Assistant commands as a regular user.

Tags

List

No

No

The tags.

You can specify up to 20 tags. The format is: [{"Key":"tagKey","Value":"tagValue"},{"Key":"tagKey2","Value":"tagValue2"}].

For more information, see Tags.

Tags syntax

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

Tags properties

Property name

Type

Required

Update allowed

Description

Constraints

Key

String

Yes

No

The key of the tag.

The key can be 1 to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://.

Value

String

No

No

The value of the tag.

The value can be 0 to 128 characters in length. It cannot start with aliyun or acs: and cannot contain http:// or https://.

Return values

Fn::GetAtt

  • InvokeId: The ID of the command execution process.

  • InvokeInstances: A list of instances on which the command was run.

  • InvokeResults: The results of the command execution.

Note

To run a one-time command, see ALIYUN::ECS::RunCommand.

Examples

ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  CommandId:
    Type: String
    Description: The id of command.
  InstanceId:
    Type: String
    AssociationProperty: ALIYUN::ECS::Instance::InstanceId
Resources:
  Invocation:
    Type: ALIYUN::ECS::Invocation
    Properties:
      CommandId:
        Ref: CommandId
      InstanceIds:
        - Ref: InstanceId
Outputs:
  InvokeId:
    Description: The id of command execution.
    Value:
      Fn::GetAtt:
        - Invocation
        - InvokeId                   
{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "CommandId": {
      "Type": "String",
      "Description": "The id of command."
    },
    "InstanceId": {
      "Type": "String",
      "AssociationProperty": "ALIYUN::ECS::Instance::InstanceId"
    }
  },
  "Resources": {
    "Invocation": {
      "Type": "ALIYUN::ECS::Invocation",
      "Properties": {
        "CommandId": {
          "Ref": "CommandId"
        },
        "InstanceIds": [
          {
            "Ref": "InstanceId"
          }
        ]
      }
    }
  },
  "Outputs": {
    "InvokeId": {
      "Description": "The id of command execution.",
      "Value": {
        "Fn::GetAtt": [
          "Invocation",
          "InvokeId"
        ]
      }
    }
  }
}
Previous：ALIYUN::ECS::InstanceGroupCloneNext：ALIYUN::ECS::JoinSecurityGroup