文档

ALIYUN::ECS::RunCommand

更新时间:

ALIYUN::ECS::RunCommand类型用于在一台或多台ECS实例中执行一段Shell、PowerShell或者Bat类型的脚本。

语法

{
  "Type": "ALIYUN::ECS::RunCommand",
  "Properties": {
    "Parameters": Map,
    "Description": String,
    "Timeout": Integer,
    "ContentEncoding": String,
    "Name": String,
    "WorkingDir": String,
    "CommandContent": String,
    "Type": String,
    "Frequency": String,
    "EnableParameter": Boolean,
    "InstanceIds": List,
    "KeepCommand": Boolean,
    "Sync": Boolean,
    "Tags": List,
    "RunAgainOn": List,
    "WindowsPasswordName": String,
    "RepeatMode": String,
    "ResourceGroupId": String,
    "ContainerName": String,
    "ContainerId": String,
    "Username": String
  }
}

属性

属性名称

类型

必须

允许更新

描述

约束

Parameters

Map

脚本中包含自定义参数时,执行脚本时指定的自定义参数的键值对。例如:脚本内容为echo {{name}},则可以通过Parameters参数指定键值对{"name":"Jack"}。自定义参数将自动替换变量值name,得到一条新的脚本,实际执行的是echo Jack。

最多支持10个自定义参数。

键不允许为空字符串,最多支持64个字符。 值允许为空字符串。

自定义参数与原始脚本内容在Base64编码后,综合长度不能超过16KB。

设置的自定义参数名集合必须为创建脚本时定义的参数集的子集。

对于未指定的参数,您可以使用空字符串代替。

Description

String

脚本描述。

支持全字符集,长度不超过512个字符。

Timeout

Integer

执行脚本的超时时间。

单位:秒。

默认值:60。

当因为进程原因、缺失模块、缺失云助手客户端等原因无法运行脚本时,会出现超时现象。超时后,会强制终止脚本进程。

ContentEncoding

String

脚本内容(CommandContent)的编码方式。

取值:

  • Base64(默认值):Base64编码。

  • PlainText:不编码,采用明文传输。

说明

当您错填该值,则会被当作Base64处理。

Name

String

脚本名称。

支持全字符集,长度不超过128个字符。

WorkingDir

String

脚本在ECS实例中的运行目录。

默认值:

  • Linux实例:/root

  • Windows实例:C:\Windows\System32\

CommandContent

String

脚本的明文内容或者Base64编码后的内容。

脚本内容Base64编码后不能超过16KB。

EnableParameter取值为true时,可以在脚本内容中启用自定义参数功能:自定义参数写作两个大括号({{}})中,在两个大括号({{}})内参数名前后的空格以及换行符会被忽略。

自定义参数个数不能超过20个。自定义参数名可包含英文字母、数字、短划线(-)和下划线(_)。 单个自定义参数名不能超过64个字符。

Type

String

运维脚本的语言类型。

取值:

  • RunBatScript:适用于Windows实例的Bat脚本。

  • RunPowerShellScript:适用于Windows实例的PowerShell脚本。

  • RunShellScript:适用于Linux实例的Shell脚本 。

Frequency

String

周期任务的执行周期。

EnableParameter

Boolean

脚本中是否包含自定义参数。

取值:

  • true:包含自定义参数。

  • false(默认值):不包含自定义参数。

InstanceIds

List

ECS实例ID列表。

最多指定20台ECS实例,且ECS实例的状态必须是运行中。

KeepCommand

Boolean

执行完该脚本后是否保留。

取值:

  • true:保留。可以通过InvokeCommand再次执行。会占用云助手脚本的保有量配额。

  • false(默认值):不保留,执行完成后自动删除,不占用云助手脚本的保有量配额。

Sync

Boolean

是否同步调用。

取值:

  • true:同步调用。

  • false:异步调用。

Tags

List

标签。

最多支持添加20个标签。更多信息,请参见Tags属性

RunAgainOn

List

再次执行命令的阶段。

WindowsPasswordName

String

在Windows实例中执行命令的用户的密码名称。

长度不得超过 255 个字符。

当您希望以非默认用户(System)在 Windows 实例中执行命令时,需要同时传入Username和该参数。为降低密码泄露的风险,需要将密码明文托管在运维编排服务的参数仓库中,此处仅传入密码的名称。更多信息,请参见加密参数以及设置普通用户执行云助手命令

说明

当您使用 Linux 实例的 root 用户或 Windows 实例的 System 用户执行命令时,不需要传递该参数。

RepeatMode

String

设置命令执行的方式。

取值范围:

  • Once:立即执行命令。

  • Period:定时执行命令。当该参数取值为Period时,必须同时指定Frequency参数。

  • NextRebootOnly:当实例下一次启动时,自动执行命令。

  • EveryReboot:实例每一次启动都将自动执行命令。

默认值:

  • 当不指定Frequency参数时,默认值为Once

  • 当指定Frequency参数时,无论是否已设置了该参数值,都将按照Period处理。

注意事项:

  • 您可以调用StopInvocation停止待执行的命令或定时执行的命令。

  • 当该参数取值Period或者EveryReboot时,您可以调用DescribeInvocationResults,然后指定IncludeHistory=true查看命令定时执行的历史记录。

ResourceGroupId

String

命令执行的资源组ID。

当指定该参数时:

ContainerName

String

容器名称。

注意事项:

  • 如果指定了该参数,云助手将在实例的指定容器内执行脚本。

  • 如果指定了该参数,仅支持在云助手Agent版本不低于 2.2.3.344 的 Linux 实例内运行。

  • 如果指定了该参数,已指定的Username参数和WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。详细信息,请参见使用云助手在容器内执行命令

  • 如果指定了该参数,在Linux容器中只支持执行Shell脚本,不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。详细信息,请参见使用云助手在容器内执行命令

ContainerId

String

容器ID。

仅支持64位16进制字符串,允许存在docker://containerd://或者cri-o://前缀来明确指定的容器运行时。

注意事项:

  • 如果指定了该参数,云助手将在实例的指定容器内执行脚本。

  • 如果指定了该参数,仅支持在云助手Agent版本不低于2.2.3.344的Linux实例内运行。

  • 如果指定了该参数,已指定的Username参数和WorkingDir参数将不会生效。仅支持通过容器默认用户在容器的默认工作目录下执行命令。详细信息,请参见使用云助手在容器内执行命令

  • 如果指定了该参数,在Linux容器中只支持执行Shell脚本,不支持在脚本开头使用类似#!/usr/bin/python命令的形式指定脚本内容的解释器。详细信息,请参见使用云助手在容器内执行命令

Username

String

在ECS实例中执行命令的用户名称。

长度不得超过255个字符。

  • Linux系统的ECS实例,默认以root用户执行命令。

  • Windows系统的ECS实例,默认以System用户执行命令。

您也可以指定实例中已存在的其他用户执行命令,以普通用户执行云助手命令更加安全。更多信息,请参见设置普通用户执行云助手命令

Tags语法

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

Tags属性

属性名称

类型

必须

允许更新

描述

约束

Key

String

标签键。

长度为1~128个字符,不能以aliyunacs:开头,不能包含http://或者https://

Value

String

标签值。

长度为0~128个字符,不能以aliyunacs:开头,不能包含http://或者https://

返回值

Fn::GetAtt

  • CommandId:脚本ID。

  • InvokeId:脚本执行ID。

  • InvokeInstances:执行命令的实例列表。

  • InvokeResults:执行命令的结果。

示例

YAML格式

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格式

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

UpdatePolicy简介

当我们使用ALIYUN::ECS::RunCommand为一组ECS实例执行脚本后,需要对已执行脚本的这组ECS进行配置批量更新时,可以使用UpdatePolicy属性去完成对ECS::RunCommand配置更新策略的控制。UpdatePolicy属性语法参考:

UpdatePolicy语法

"UpdatePolicy": {
  "RollingUpdate": Map
}

UpdatePolicy属性

属性名称

类型

必须

允许更新

描述

约束

RollingUpdate

Map

控制更新已有的Command的策略。

详见RollingUpdate属性

RollingUpdate语法

"RollingUpdate": {
  "MaxBatchSize": Integer,
  "PauseTime": Integer
}

RollingUpdate属性

属性名称

类型

必须

允许更新

描述

约束

MaxBatchSize

Integer

每个批次执行命令的ECS台数。

取值范围:1~1000。

PauseTime

Integer

各个批次执行命令之间暂停的时间(单位:秒)默认为0。

取值范围:0~3600。

示例

使用以下模板为ECS实例执行一组相同配置的Command(包含3台ECS)。

{
    "ROSTemplateFormatVersion": "2015-09-01",
    "Resources": {
        "RunCommand": {
            "Type": "ALIYUN::ECS::RunCommand",
            "Properties": {
                "CommandContent": "xxx",
                "Type": "RunShellScript",
                "Sync": true,
                "InstanceIds": [
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                ]
            }
        }
    }
}

创建资源栈成功后对已执行Command的ECS实例进行配置更新,更新时可以配置UpdatePolicy属性。

{
    "ROSTemplateFormatVersion": "2015-09-01",
    "Resources": {
        "RunCommand": {
            "Type": "ALIYUN::ECS::RunCommand",
            "Properties": {
                "CommandContent": "xxx",
                "Type": "RunShellScript",
                "Sync": true,
                "InstanceIds": [
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                    "i-2zxxxx",
                ]
            },
            "UpdatePolicy": {
                "RollingUpdate": {
                    "MaxBatchSize": 2
                    "PauseTime": 10
                }
            }
        }
    }
}

指定MaxBatchSize=2。 更新前InstanceIds内包含3台ECS实例,更新后InstanceIds内包含5台ECS实例,在更新资源栈的过程中,原有的3台机器,会分2个批次(2/1)进行变配更新(原有的InstanceIds信息会按照传入的顺序划分批次)。新增的2台机器会被一次性统一执行Command。