call ALIYUN::ECS::Invocation to trigger a Cloud Assistant command on an ECS instance - Resource Orchestration Service

ALIYUN::ECS::Invocation is used to run a Cloud Assistant command on 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,
    "Username": String,
    "Tags": List
  }
}

Properties

Property	Type	Required	Editable	Description	Constraint
Frequency	String	No	No	The schedule on which the command is run. For information about the value structures, see Cron expression.	None
CommandId	String	No	Yes	The command ID.	None
InstanceIds	List	Yes	Yes	The IDs of the ECS instances on which you want to run the command.	You can specify up to 20 instance IDs.
Parameters	Map	No	Yes	The key-value pairs of the custom parameters that you want to pass to the command when the custom parameter feature is enabled. Example: `{"name": "Jack", "accessKey": "LTAIdyv******aRY"}`.	You can specify up to 10 custom parameters. Each key in a Map collection cannot be an empty string, and can be up to 64 characters in length. Each value in a Map collection can be an empty string. After the custom parameters and the original command content are Base64-encoded, the total size cannot exceed 16 KB. The set of custom parameter names must be a subset of the parameter set that you specify when you create the command. You can use empty strings to represent the parameters that are not passed in.
Sync	Boolean	No	No	Specifies whether to run the command synchronously.	Valid values: true false
CommandName	String	No	No	The command name.	None
WindowsPasswordName	String	No	No	The username of the password that you 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 the WindowsPasswordName and `Username` properties. The password is hosted in plaintext in the parameter repository of CloudOps Orchestration Service (OOS) to mitigate the risk of password leaks. Only the username of the password is passed in by using the WindowsPasswordName property. For more information, see Manage encryption parameters and Run Cloud Assistant commands as a regular user. Note If you use the root user for Linux instances or the System user for Windows instances to run the command, you do not need to specify the WindowsPasswordName property.
Timeout	Integer	No	Yes	The timeout period for command execution. Unit: seconds.	Take note of the following items when you specify this property: The timeout period cannot be less than 10 seconds. A timeout error occurs if the command cannot be run because the process slows down or because a specific module or Cloud Assistant Agent does not exist. When the specified timeout period ends, the command process is forcefully terminated. If you do not specify this property, the timeout period that is specified when the command is created is used. This timeout period is applicable only to the execution. The timeout period of the command is not modified.
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 regular basis. If you set this property to `Period`, you must also specify the `Frequency` property. 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 the `Frequency` property, the default value is `Once`. If you specify the `Frequency` property, `Period` is used as the value of RepeatMode regardless of whether the RepeatMode property is set to Period. Take note of the following items when you specify this property: You can all 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 with `IncludeHistory` set to true to query the results of historical scheduled executions.
ResourceGroupId	String	No	No	The ID of the resource group.	Take note of the following items when you specify this property: 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 when you specify this property: If you specify this property, Cloud Assistant runs scripts in the specified container on 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. For more information about how to view versions of Cloud Assistant Agent, see Install Cloud Assistant Agent. For information about how to upgrade Cloud Assistant Agent, see Upgrade or disable upgrades for Cloud Assistant Agent. 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 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 when you specify this property: If you specify this property, Cloud Assistant runs scripts in the specified container on 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. For more information about how to view versions of Cloud Assistant Agent, see Install Cloud Assistant Agent. For information about how to upgrade Cloud Assistant Agent, see Upgrade or disable upgrades for Cloud Assistant Agent. 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 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 use to run the command on instances.	The username can be up to 255 characters in length. For Linux instances, the root username is used by default. For 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.
Tags	List	No	No	The tags.	You can specify up to 20 tags in the following format: `[{"Key":"tagKey","Value":"tagValue"},{"Key":"tagKey2","Value":"tagValue2"}]`. For more information, see Tags properties.

Tags syntax

"Tags": [
  {
    "Value": String,
    "Key": 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

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

Note

If you want to run the command only once, see ALIYUN::ECS::RunCommand.

Examples

YAML format

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

JSON format

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