ECS インスタンスでコマンドを実行するための呼び出しで ALIYUN::ECS::RunCommand を使用します - Resource Orchestration Service

ALIYUN::ECS::RunCommand は、Elastic Compute Service (ECS) インスタンスでシェル、PowerShell、またはバッチコマンドを実行するために使用されます。

構文

{
  "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"} キーと値のペアを渡すことができます。 echo {{name}} の name 変数の値は、ペアの Jack 値に自動的に置き換えられ、新しいコマンドが生成されます。その結果、echo Jack コマンドが実行されます。	最大 10 個のカスタムパラメータを指定できます。カスタムパラメータのキーは最大 64 文字で、空の文字列にすることはできません。カスタムパラメータの値は空の文字列にすることができます。カスタムパラメータと元のコマンドコンテンツが Base64 でエンコードされた後、合計サイズは最大 16 KB になります。 Parameters プロパティの値で指定されたカスタムパラメータ名は、コマンドの作成時に構成したカスタムパラメータ設定に含まれている必要があります。空の文字列を使用して、指定されていないパラメータを表すことができます。
Description	String	いいえ	いいえ	コマンドの説明。	説明はすべての文字セットをサポートし、最大 512 文字まで入力できます。
Timeout	Integer	いいえ	はい	コマンドを実行するためのタイムアウト期間。	単位：秒。デフォルト値：60。コマンドプロセスが遅くなったり、特定のモジュールまたは Cloud Assistant エージェントが存在しないためにコマンドを実行できない場合、タイムアウトエラーが発生します。タイムアウトエラーが発生すると、コマンドプロセスは強制的に終了します。
ContentEncoding	String	いいえ	はい	CommandContent で指定されたコマンドコンテンツのエンコードモード。	有効な値： Base64 (デフォルト)：コマンドコンテンツを Base64 でエンコードします。 PlainText：コマンドコンテンツをエンコードしません。説明このプロパティに無効な値を指定すると、Base64 を使用してコマンドコンテンツがエンコードされます。
Name	String	いいえ	いいえ	コマンド名。	名前はすべての文字セットをサポートし、最大 128 文字まで入力できます。
WorkingDir	String	いいえ	はい	ECS インスタンス上のコマンドの作業ディレクトリ。	デフォルト値： Linux インスタンスのデフォルト値：/root Windows インスタンスのデフォルト値：C:\Windows\System32\
CommandContent	String	はい	はい	コマンドコンテンツ。コマンドコンテンツはプレーンテキストまたは Base64 エンコードにすることができます。	コマンドコンテンツが Base64 でエンコードされた後、コンテンツのサイズは最大 16 KB になります。 EnableParameter を true に設定すると、カスタムパラメータ機能が有効になります。次のルールに基づいてカスタムパラメータを構成できます。 {{}} 形式でカスタムパラメータを指定します。 {{}} 内では、パラメータ名の前後にあるスペースと改行は無視されます。最大 10 個のカスタムパラメータを指定できます。カスタムパラメータ名には、文字、数字、ハイフン (-)、アンダースコア (_) を使用できます。カスタムパラメータ名は最大 64 文字まで入力できます。
Type	String	はい	はい	コマンドの言語タイプ。	有効な値： RunBatScript：バッチコマンド。バッチコマンドは Window インスタンスに適用できます。 RunPowerShellScript：PowerShell コマンド。 PowerShell コマンドは Window インスタンスに適用できます。 RunShellScript：シェルコマンド。シェルコマンドは Linux インスタンスに適用できます。
Frequency	String	いいえ	いいえ	コマンドを実行する間隔。	なし。
EnableParameter	Boolean	いいえ	はい	コマンドにカスタムパラメータを含めるかどうかを指定します。	有効な値： true false (デフォルト)
InstanceIds	List	はい	はい	ECS インスタンスの ID。	最大 20 個の ECS インスタンスを指定できます。 ECS インスタンスは Running 状態である必要があります。
KeepCommand	Boolean	いいえ	いいえ	コマンドの実行後もコマンドを保持するかどうかを指定します。	有効な値： true：コマンドの実行後もコマンドを保持します。 InvokeCommand オペレーションを呼び出して、コマンドを再実行できます。保持されたコマンドは、Cloud Assistant コマンドのクォータを消費します。 false (デフォルト)：コマンドの実行後、コマンドを保持しません。コマンドは実行後に自動的に削除され、Cloud Assistant コマンドのクォータを消費しません。
Sync	Boolean	いいえ	いいえ	コマンドを同期モードで実行するかどうかを指定します。	有効な値： true false
Tags	List	いいえ	はい	タグ。	最大 20 個のタグを追加できます。詳細については、タグのプロパティをご参照ください。
RunAgainOn	List	いいえ	いいえ	コマンドを再実行するステージ。	なし。
WindowsPasswordName	String	いいえ	いいえ	Windows インスタンスでコマンドを実行するために使用するパスワードの名前。	名前は最大 255 文字まで入力できます。 Windows インスタンスでデフォルトの System ユーザーを使用してコマンドを実行したくない場合は、WindowsPasswordName と `Username` の両方を指定します。パスワード漏洩のリスクを軽減するため、パスワードは CloudOps Orchestration Service (OOS) のパラメータリポジトリにプレーンテキストでホストされます。 WindowsPasswordName を使用して渡されるのは、パスワードの名前だけです。詳細については、暗号化パラメータおよびCloud Assistant コマンドを一般ユーザーとして実行するをご参照ください。説明 Linux インスタンスの root ユーザーまたは Windows インスタンスの System ユーザーを使用してコマンドを実行する場合は、WindowsPasswordName を空のままにすることができます。
RepeatMode	String	いいえ	いいえ	コマンドを実行するモード。	有効な値： Once：コマンドをすぐに実行します。 Period：スケジュールに従ってコマンドを実行します。このプロパティを `Period` に設定する場合は、`Frequency` を指定する必要があります。 NextRebootOnly：次回インスタンスが起動されたときにコマンドを実行します。 EveryReboot：インスタンスが起動されるたびにコマンドを実行します。デフォルト値： `Frequency` を指定しない場合、RepeatMode のデフォルト値は `Once` です。 `Frequency` を指定した場合、RepeatMode が Period に設定されているかどうかに関係なく、`Period` が RepeatMode の値として使用されます。次の項目に注意してください。 StopInvocation オペレーションを呼び出して、コマンドの保留中またはスケジュールされた実行を停止できます。このプロパティを `Period` または `EveryReboot` に設定した場合、DescribeInvocationResults オペレーションを呼び出して `IncludeHistory` を true に設定することで、コマンドの過去のスケジュールされた実行結果をクエリできます。
ResourceGroupId	String	いいえ	いいえ	コマンド実行が属するリソースグループの ID。	次の項目に注意してください。 InstanceId で指定された ECS インスタンスは、リソースグループに属している必要があります。コマンドの実行後、DescribeInvocations または DescribeInvocationResults オペレーションを呼び出し、ResourceGroupId を指定して、指定されたリソースグループのコマンド実行結果をフィルタリングできます。
ContainerName	String	いいえ	いいえ	コンテナ名。	次の項目に注意してください。このプロパティが指定されている場合、Cloud Assistant はインスタンスの指定されたコンテナでコマンドを実行します。このプロパティが指定されている場合、コマンドは、Cloud Assistant エージェントのバージョンが 2.2.3.344 以降の Linux インスタンスでのみ実行できます。このプロパティが指定されている場合、指定された `Username` と `WorkingDir` は有効になりません。コンテナのデフォルトユーザーを使用してのみ、コンテナのデフォルトの作業ディレクトリでコマンドを実行できます。詳細については、Cloud Assistant を使用してコンテナでコマンドを実行するをご参照ください。このプロパティが指定されている場合、Linux コンテナではシェルスクリプトのみを実行できます。スクリプトインタープリタを指定するために、`#!/usr/bin/python` に似た形式のコマンドをスクリプトの先頭に追加することはできません。詳細については、Cloud Assistant を使用してコンテナでコマンドを実行するをご参照ください。
ContainerId	String	いいえ	いいえ	コンテナ ID。	64 ビットの 16 進数文字列のみがサポートされています。 `docker://`、`containerd://`、または `cri-o://` がプレフィックスとして付いたコンテナ ID を使用して、コンテナランタイムを指定できます。次の項目に注意してください。このプロパティが指定されている場合、Cloud Assistant はインスタンスの指定されたコンテナでコマンドを実行します。このプロパティが指定されている場合、コマンドは、Cloud Assistant エージェントのバージョンが 2.2.3.344 以降の Linux インスタンスでのみ実行できます。このプロパティが指定されている場合、指定された `Username` と `WorkingDir` は有効になりません。コンテナのデフォルトユーザーを使用してのみ、コンテナのデフォルトの作業ディレクトリでコマンドを実行できます。詳細については、Cloud Assistant を使用してコンテナでコマンドを実行するをご参照ください。このプロパティが指定されている場合、Linux コンテナではシェルスクリプトのみを実行できます。スクリプトインタープリタを指定するために、`#!/usr/bin/python` に似た形式のコマンドをスクリプトの先頭に追加することはできません。詳細については、Cloud Assistant を使用してコンテナでコマンドを実行するをご参照ください。
Username	String	いいえ	はい	ECS インスタンスでコマンドを実行するために使用するユーザー名。	ユーザー名は最大 255 文字まで入力できます。 ECS Linux インスタンスの場合、デフォルトでは root ユーザー名が使用されます。 ECS Windows インスタンスの場合、デフォルトでは System ユーザー名が使用されます。コマンドを実行するために、ECS インスタンスに既に存在する他のユーザー名を指定することもできます。セキュリティ上の理由から、Cloud Assistant コマンドを一般ユーザーとして実行することをお勧めします。詳細については、Cloud Assistant コマンドを一般ユーザーとして実行するをご参照ください。

タグの構文

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

タグのプロパティ

プロパティ	タイプ	必須	編集可能	説明	制約
Key	String	はい	いいえ	タグキー。	タグキーは 1 ～ 128 文字で、`http://` または `https://` を含めることはできません。 `aliyun` または `acs:` で始めることはできません。
Value	String	いいえ	いいえ	タグ値。	タグ値は最大 128 文字で、`http://` または `https://` を含めることはできません。 `aliyun` または `acs:` で始めることはできません。

戻り値

Fn::GetAtt

CommandId：コマンド ID。
InvokeId：コマンド実行の ID。
InvokeInstances：コマンドが実行される ECS インスタンス。
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: 作成されたコマンドの ID。
    Value:
      Fn::GetAtt:
        - RunCommand
        - CommandId
  InvokeId:
    Description: コマンドの呼び出し ID。
    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"  // シェルスクリプト、tree をインストール
        },
        "Type": "RunShellScript",
        "InstanceIds": [
          {
            "Ref": "InstanceId"
          }
        ]
      }
    }
  },
  "Outputs": {
    "CommandId": {
      "Description": "作成されたコマンドの ID。",
      "Value": {
        "Fn::GetAtt": [
          "RunCommand",
          "CommandId"
        ]
      }
    },
    "InvokeId": {
      "Description": "コマンドの呼び出し ID。",
      "Value": {
        "Fn::GetAtt": [
          "RunCommand",
          "InvokeId"
        ]
      }
    }
  }
}

UpdatePolicy の概要

ALIYUN::ECS::RunCommand を使用して ECS インスタンスのコレクションでコマンドを実行した後、UpdatePolicy プロパティを使用して ECS インスタンスの構成をバッチで更新できます。次の表に、UpdatePolicy プロパティとその構文を示します。

UpdatePolicy 構文

"UpdatePolicy": {
  "RollingUpdate": Map
}

UpdatePolicy プロパティ

プロパティ	タイプ	必須	編集可能	説明	制約
RollingUpdate	Map	いいえ	はい	既存のコマンドの更新ポリシー。	詳細については、RollingUpdate プロパティをご参照ください。

RollingUpdate 構文

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

RollingUpdate プロパティ

プロパティ	タイプ	必須	編集可能	説明	制約
MaxBatchSize	Integer	はい	はい	各バッチでコマンドを実行する ECS インスタンスの数。	有効な値：1 ～ 1000。
PauseTime	Integer	いいえ	はい	2 つのバッチコマンド実行の間隔。デフォルト値：0。単位：秒。	有効な値：0 ～ 3600。

更新前後のテンプレート

次のテンプレートを使用して、3 つの ECS インスタンスで同じコマンドを実行できます。

{
    "ROSTemplateFormatVersion": "2015-09-01",
    "Resources": {
        "RunCommand": {
            "Type": "ALIYUN::ECS::RunCommand",
            "Properties": {
                "CommandContent": "xxx",  // コマンドの内容
                "Type": "RunShellScript",
                "Sync": true,
                "InstanceIds": [
                    "i-2zxxxx",  // ECS インスタンス ID
                    "i-2zxxxx",  // ECS インスタンス ID
                    "i-2zxxxx",  // ECS インスタンス ID
                ]
            }
        }
    }
}

ECS インスタンスを含むスタックが作成された後、テンプレートに UpdatePolicy プロパティを追加して、ECS インスタンスの構成を更新できます。

{
    "ROSTemplateFormatVersion": "2015-09-01",
    "Resources": {
        "RunCommand": {
            "Type": "ALIYUN::ECS::RunCommand",
            "Properties": {
                "CommandContent": "xxx",  // コマンドの内容
                "Type": "RunShellScript",
                "Sync": true,
                "InstanceIds": [
                    "i-2zxxxx",  // ECS インスタンス ID
                    "i-2zxxxx",  // ECS インスタンス ID
                    "i-2zxxxx",  // ECS インスタンス ID
                    "i-2zxxxx",  // ECS インスタンス ID
                    "i-2zxxxx",  // ECS インスタンス ID
                ]
            },
            "UpdatePolicy": {
                "RollingUpdate": {
                    "MaxBatchSize": 2,
                    "PauseTime": 10
                }
            }
        }
    }
}

上記のサンプルコードでは、MaxBatchSize は 2 に設定されています。 InstanceIds で示される ECS インスタンスの数は 3 から 5 に更新されます。スタックの更新プロセス中に、元の 3 つの ECS インスタンスの構成は、指定された順序で 2 つのバッチで更新されます。各バッチには、それぞれ 2 つと 1 つのインスタンスが含まれています。コマンドは、新しい 2 つの ECS インスタンスで同時に実行されます。

構文