CloudOps Orchestration Service:タスクループ

制限事項

ループの Items リストには、最大 1,000 個の項目を含めることができます。

構文

• YAML 構造

---
Tasks:
  - Name: TaskName1 # 必須。タスクの名前。有効な文字は、英字、数字、アンダースコア (_)、ハイフン (-) です。名前は最大 200 文字です。StartInstance のようにキャメルケースを使用します。
    Action: TaskType # 必須。タスクのタイプであり、アクションとも呼ばれます。詳細については、アクションに関するドキュメントをご参照ください。
    Description: description # オプション。タスクの説明。
    Properties: # プロパティリストは、使用するアクションによって異なります。詳細については、アクションに関するドキュメントをご参照ください。
      Property1: Value1 # アクションで必要なプロパティと値。
    Outputs: # 現在のタスクのレスポンスパラメーター。後続タスクの入力や、テンプレートの出力として使用できます。
      OutputParameterName1:
        Type: TypeName # オプション。レスポンスパラメーターのタイプ。デフォルトは String です。
        ValueSelector: "jq selector" # タスクが OpenAPI 呼び出しの場合、呼び出し結果は JSON 入力として扱われます。jq 式を使用して、JSON から必要な値を抽出します。詳細については、クラウド製品アクションやパブリックテンプレートの例をご参照ください。
    Loop:
      Items: [i-id1,i-id2,i-id3,i-id4] # 必須。ループ要素。項目のリストを指定します。各項目は、ループタスク実行のパラメーターとして使用されます。{{describeInstance.InstanceIds}} のように、リストを返すパラメーター名も使用できます。
      RateControl:
          MaxErrors: 0 # オプション。許容される最大エラー数。10 や 10% のように、数値またはパーセンテージで指定できます。デフォルトは 0 です。
          Mode: "Batch/Concurrency" # 必須。ループの実行レートを制御するモード。指定可能な値は Concurrency または Batch です。Concurrency は同時実行、Batch はバッチ実行を意味します。
          Batch:  [1, 2, 3] # オプション。このパラメーターは、Mode が Batch に設定されている場合に有効です。バッチ制御を指定します。バッチの定義方法については、後述の「バッチ制御」セクションをご参照ください。
          ConcurrencyInBatches: [1, 1, 1]  # オプション。このパラメーターは、Mode が Batch に設定されている場合に有効です。各バッチの同時実行数を制御します。デフォルトは 20 です。定義するには、[] 内に各バッチの同時実行数を入力します。
          Concurrency: 1 # オプション。このパラメーターは、Mode が Concurrency に設定されている場合に有効です。すべての実行の同時実行数を制御します。数値またはパーセンテージで指定できます。デフォルトは 1 です。
          BatchPauseOption: "FirstBatchPause/Automatic/EveryBatchPause" # オプション。このパラメーターは、Mode が Batch に設定されている場合に有効です。各バッチ完了後の停止オプションを指定します。指定可能な値は FirstBatchPause、Automatic、EveryBatchPause です。FirstBatchPause は最初のバッチ後に停止し、Automatic は停止せずに実行し、EveryBatchPause は各バッチ後に停止します。
      Outputs:
        FinalOutputParameterName1: # ループタスクが関数で処理された後に出力されるパラメーターの名前。
          AggregateType: BuiltInFunctionName1 # Fn::Sum、Fn::Max、Fn::ListJoin などの組み込み関数を選択し、出力を集約します。
          AggregateField: OutputParameterName1 # ループ要素の実行から返されるレスポンスパラメーターの名前。

• JSON 構造 (詳細は YAML 例のコメントをご参照ください)

{
  "Tasks": [
    {
      "Name": "TaskName1",
      "Action": "TaskType",
      "Description": "description",
      "Properties": {
        "Property1": "Value1"
      },
      "Outputs": {
        "OutputParameterName1": {
          "Type": "TypeName",
          "ValueSelector": "jq selector"
        }
      },
      "Loop": {
        "Items": [
          "i-id1",
          "i-id2",
          "i-id3",
          "i-id4"
        ],
        "RateControl": {
          "MaxErrors": 0,
          "Mode": "Concurrency/Batch",
          "Batch": [
            1,
            2,
            3
          ],
          "ConcurrencyInBatches": [
            1,
            1,
            1
          ],
          "Concurrency": 1,
          "BatchPauseOption": "FirstBatchPause/Automatic/EveryBatchPause"
        },
        "Outputs": {
          "FinalOutputParameterName1": {
            "AggregateType": "BuiltInFunctionName1",
            "AggregateField": "OutputParameterName1"
          }
        }
      }
    }
  ]
}

Items リスト

Items プロパティには、[item1, item2, item3] のようなリテラルリストを指定します。

または、Items プロパティでは、前のタスクの Outputs など、リスト型のパラメーター名を参照することもできます。

• リストとしての Items

  • YAML

  Loop:
    Items: [item1, item2, item3, item4] # [i-id1,i-id2,i-id3,i-id4] のような項目のリスト。各項目は、ループを含むタスク実行のパラメーターとして使用されます。					

  • JSON (詳細は YAML 例のコメントをご参照ください)

  {
    "Items": [
      "item1",
      "item2",
      "item3",
      "item4"
    ]
  }		

• リスト型のパラメーター名としての Items

  • YAML

  Items: '{{ParameterName1}}' # describeInstance.InstanceIds のように、リストを返すパラメーター名。各項目は、ループを含むタスク実行のパラメーターとして使用されます。	

  • JSON (詳細は YAML 例のコメントをご参照ください)

  {
    "Items": "{{ParameterName1}}"
  }		

ループ実行レートの制御

2つのモードがあります。

1. 同時実行制御：すべての項目が処理されるまで、指定されたレートで項目を同時に実行します。

2. バッチ制御：項目を指定されたサイズのバッチに分割します。次のバッチは、前のバッチが完了してから開始されます。

同時実行制御 (Concurrency)

• たとえば、Items に 10 個の項目が含まれ、Concurrency が 3 の場合、システムはすべての項目が処理されるまで 3 個の項目を同時に実行します。

  • YAML

  Concurrency: 3 # 3 のように、同時実行制御に数値またはパーセンテージを指定できます。
  Mode: Concurrency

  • JSON (詳細は YAML 例のコメントをご参照ください)

  {
    "Concurrency": 3,
    "Mode": "Concurrency"
  }

• たとえば、Items に 10 個の項目が含まれ、Concurrency が 20% の場合、同時実行数は 2 (10 の 20%) になります。システムはすべての項目が処理されるまで 2 個の項目を同時に実行します。

  • YAML

  Concurrency: 20% # オプション。20% のように、数値またはパーセンテージで指定できます。
  Mode: Concurrency

  • JSON (詳細は YAML 例のコメントをご参照ください)

  {
    "Concurrency": "20%",
    "Mode": "Concurrency"
  }

バッチ制御 (Batch)

• たとえば、Items に 10 個の項目が含まれ、Batch が [3] の場合、項目は 3 個ずつのバッチに分割されます。すべての項目の実行が成功すると仮定すると、結果としてサイズがそれぞれ 3、3、3、1 の 4 つのバッチが作成されます。

  • YAML

  Batch: [1, 2, 3] # オプション。[3] のように、数値またはパーセンテージのリストを使用してバッチ制御を定義できます。
  Mode: Batch

  • JSON (詳細は YAML 例のコメントをご参照ください)

  {
    "Batch": [
      1,
      2,
      3
    ],
    "Mode": "Batch"
  }

• たとえば、Items に 10 個の項目が含まれ、Batch が [30%] の場合、バッチサイズは 3 (10 の 30%) になります。すべての項目の実行が成功すると仮定すると、結果としてサイズがそれぞれ 3、3、3、1 の 4 つのバッチが作成されます。

  • YAML

  Batch: [30%] # オプション。[30%] のように、数値またはパーセンテージのリストを使用してバッチ制御を定義できます。
  Mode: Batch
  					

  • JSON (詳細は YAML 例のコメントをご参照ください)

  {
    "Batch": [
      "30%"
    ],
    "Mode": "Batch"
  }

• たとえば、Items に 10 個の項目が含まれ、Batch が [3, 10%, 30%] の場合、最初のバッチサイズは 3、2 番目は 1 (10 の 10%)、3 番目以降のバッチは 3 (10 の 30%) になります。すべての項目の実行が成功すると仮定すると、結果としてサイズがそれぞれ 3、1、3、3 の 4 つのバッチが作成されます。

  • YAML

  Mode: Batch
  Batch: [3, 10%, 30%] # オプション。[3, 10%, 30%] のように、複数の数値またはパーセンテージを含むリストを使用してバッチ制御を定義できます。
  					

  • JSON (詳細は YAML 例のコメントをご参照ください)

  {
    "Mode": "Batch",
    "Batch": [
      3,
      "10%",
      "30%"
    ]
  }

MaxErrors によるエラー制御

ループでは MaxErrors プロパティを定義できます。このプロパティは次のように機能します。

1. 項目の総数に対する数値またはパーセンテージを指定できます。たとえば、10 や 10% です。デフォルト値は 0 です。これは、いずれかの項目が失敗した場合、ループタスク全体が失敗とマークされることを意味します。

2. ループ内の最初の項目は常に実行されます。

3. 後続の項目が実行されるかどうかは、エラー数 (ErrorCount) が MaxErrors の値を超えるかどうかによって決まります。

   • エラー数が MaxErrors の値を超えると、ループは後続の項目の実行を停止し、ループタスクは失敗とマークされます。

   • エラー数が MaxErrors の値以下の場合、ループは実行を継続します。

4. ループタスクの最終ステータスは、合計 ErrorCount と MaxErrors を比較して決定されます。ErrorCount が MaxErrors より大きい場合、タスクは Failed とマークされます。それ以外の場合は、Success とマークされます。

• 数値として指定

  • YAML

    MaxErrors: 2 # オプション。数値またはパーセンテージで指定できます。たとえば、2 は許容される最大 ErrorCount が 2 であることを意味します。

  • JSON (詳細は YAML 例のコメントをご参照ください)

    {
     "MaxErrors": 2 
    }

• パーセンテージとして指定

  • YAML

    MaxErrors: 25% # オプション。数値またはパーセンテージで指定できます。たとえば、4 個の項目の場合、25% は許容される最大 ErrorCount が 25% * 4 = 1 であることを意味します。

  • JSON (詳細は YAML 例のコメントをご参照ください)

    {
     "MaxErrors": "25%"
    }

ループの出力

タスクまたはテンプレート内のループは出力を生成できます。ループの最終的な出力は、各項目の実行から得られる出力を集約したものです。AggregateType プロパティを定義して、この集約のための組み込み関数を選択できます。

AggregateType プロパティを定義します。

• YAML

AggregateType: Fn::Max # Fn::Max のような組み込み関数を選択して、ループの出力を集約します。これは、すべてのサブタスク出力から得られる Number 型の OutputParameterName1 の最大値が、ループの出力値として使用されることを意味します。

• JSON (詳細は YAML 例のコメントをご参照ください)

{
"AggregateType": "Fn::Max"
}		

例

同時実行モード

• YAML 形式

FormatVersion: OOS-2019-06-01
Description: 1 つ以上の ECS インスタンスを作成します。
Parameters:
  regionId:
    Description: リージョン ID。
    Type: String
    Default: '{{ ACS::RegionId }}'
  imageId:
    Description: インスタンス作成時に指定するイメージリソースの ID。
    Type: String
    AllowedPattern: '[A-Za-z0-9_\-\.]*'
    MinLength: 1
    MaxLength: 100
  instanceType:
    Description: インスタンスのタイプ。
    Type: String
    AllowedPattern: ecs\.[A-Za-z0-9\.\-]*
    MaxLength: 30
    MinLength: 1
  securityGroupId:
    Description: インスタンスが属するセキュリティグループの ID。
    Type: String
    AllowedPattern: sg-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  vSwitchId:
    Description: vSwitch の ID。
    Type: String
    AllowedPattern: vsw-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  amount:
    Description: 作成するインスタンス数。
    Type: Number
    Default: 1
  internetMaxBandwidthIn:
    Description: 最大パブリックインバウンド帯域幅。
    Type: Number
    Default: 200
  internetMaxBandwidthOut:
    Description: 最大パブリックアウトバウンド帯域幅。
    Type: Number
    Default: 0
Tasks:
- Name: runInstances
  Action: ACS::ExecuteAPI
  Description: 1 つ以上のインスタンスを作成します。
  Properties:
    Service: ECS
    API: RunInstances
    Parameters:
      RegionId: '{{ regionId }}'
      Amount: '{{ amount }}'
      ImageId: '{{ imageId }}'
      InstanceType: '{{ instanceType }}'
      SecurityGroupId: '{{ securityGroupId }}'
      VSwitchId: '{{ vSwitchId }}'
      InternetMaxBandwidthIn: '{{ internetMaxBandwidthIn }}'
      InternetMaxBandwidthOut: '{{ internetMaxBandwidthOut }}'
  Outputs:
    instanceIds:
      Type: List
      ValueSelector: InstanceIdSets.InstanceIdSet[]
- Name: untilInstanceReady
  Action: ACS::WaitFor
  Description: 作成されたインスタンスが Running 状態になるまで待機します。
  Properties:
    Service: ECS
    API: DescribeInstances
    Parameters:
      RegionId: '{{ regionId }}'
      InstanceIds:
      - '{{ ACS::TaskLoopItem }}'
    DesiredValues:
    - Running
    PropertySelector: Instances.Instance[].Status
  Loop:
    RateControl:
      Mode: Concurrency
      MaxErrors: 0
      Concurrency: 1
    Items: '{{ runInstances.instanceIds }}'
Outputs:
  instanceIds:
    Type: List
    Value: '{{ runInstances.instanceIds }}'
			

• JSON 形式

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "1 つ以上の ECS インスタンスを作成します。",
  "Parameters": {
    "regionId": {
      "Description": "リージョン ID。",
      "Type": "String",
      "Default": "{{ ACS::RegionId }}"
    },
    "imageId": {
      "Description": "インスタンス作成時に指定するイメージリソースの ID。",
      "Type": "String",
      "AllowedPattern": "[A-Za-z0-9_\\-\\.]*",
      "MinLength": 1,
      "MaxLength": 100
    },
    "instanceType": {
      "Description": "インスタンスのタイプ。",
      "Type": "String",
      "AllowedPattern": "ecs\\.[A-Za-z0-9\\.\\-]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "securityGroupId": {
      "Description": "インスタンスが属するセキュリティグループの ID。",
      "Type": "String",
      "AllowedPattern": "sg-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "vSwitchId": {
      "Description": "vSwitch の ID。",
      "Type": "String",
      "AllowedPattern": "vsw-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "amount": {
      "Description": "作成するインスタンス数。",
      "Type": "Number",
      "Default": 1
    },
    "internetMaxBandwidthIn": {
      "Description": "最大パブリックインバウンド帯域幅。",
      "Type": "Number",
      "Default": 200
    },
    "internetMaxBandwidthOut": {
      "Description": "最大パブリックアウトバウンド帯域幅。",
      "Type": "Number",
      "Default": 0
    }
  },
  "Tasks": [
    {
      "Name": "runInstances",
      "Action": "ACS::ExecuteAPI",
      "Description": "1 つ以上のインスタンスを作成します。",
      "Properties": {
        "Service": "ECS",
        "API": "RunInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "Amount": "{{ amount }}",
          "ImageId": "{{ imageId }}",
          "InstanceType": "{{ instanceType }}",
          "SecurityGroupId": "{{ securityGroupId }}",
          "VSwitchId": "{{ vSwitchId }}",
          "InternetMaxBandwidthIn": "{{ internetMaxBandwidthIn }}",
          "InternetMaxBandwidthOut": "{{ internetMaxBandwidthOut }}"
        }
      },
      "Outputs": {
        "instanceIds": {
          "Type": "List",
          "ValueSelector": "InstanceIdSets.InstanceIdSet[]"
        }
      }
    },
    {
      "Name": "untilInstanceReady",
      "Action": "ACS::WaitFor",
      "Description": "作成されたインスタンスが Running 状態になるまで待機します。",
      "Properties": {
        "Service": "ECS",
        "API": "DescribeInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "InstanceIds": [
            "{{ ACS::TaskLoopItem }}"
          ]
        },
        "DesiredValues": [
          "Running"
        ],
        "PropertySelector": "Instances.Instance[].Status"
      },
      "Loop": {
        "RateControl": {
          "Mode": "Concurrency",
          "MaxErrors": 0,
          "Concurrency": 1
        },
        "Items": "{{ runInstances.instanceIds }}"
      }
    }
  ],
  "Outputs": {
    "instanceIds": {
      "Type": "List",
      "Value": "{{ runInstances.instanceIds }}"
    }
  }
}

バッチモード

• YAML 形式

FormatVersion: OOS-2019-06-01
Description: 1 つ以上の ECS インスタンスを作成します。
Parameters:
  regionId:
    Description: リージョン ID。
    Type: String
    Default: '{{ ACS::RegionId }}'
  imageId:
    Description: インスタンス作成時に指定するイメージリソースの ID。
    Type: String
    AllowedPattern: '[A-Za-z0-9_\-\.]*'
    MinLength: 1
    MaxLength: 100
  instanceType:
    Description: インスタンスのタイプ。
    Type: String
    AllowedPattern: ecs\.[A-Za-z0-9\.\-]*
    MaxLength: 30
    MinLength: 1
  securityGroupId:
    Description: インスタンスが属するセキュリティグループの ID。
    Type: String
    AllowedPattern: sg-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  vSwitchId:
    Description: vSwitch の ID。
    Type: String
    AllowedPattern: vsw-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  amount:
    Description: 作成するインスタンス数。
    Type: Number
    Default: 1
  internetMaxBandwidthIn:
    Description: 最大パブリックインバウンド帯域幅。
    Type: Number
    Default: 200
  internetMaxBandwidthOut:
    Description: 最大パブリックアウトバウンド帯域幅。
    Type: Number
    Default: 0
Tasks:
- Name: runInstances
  Action: ACS::ExecuteAPI
  Description: 1 つ以上のインスタンスを作成します。
  Properties:
    Service: ECS
    API: RunInstances
    Parameters:
      RegionId: '{{ regionId }}'
      Amount: '{{ amount }}'
      ImageId: '{{ imageId }}'
      InstanceType: '{{ instanceType }}'
      SecurityGroupId: '{{ securityGroupId }}'
      VSwitchId: '{{ vSwitchId }}'
      InternetMaxBandwidthIn: '{{ internetMaxBandwidthIn }}'
      InternetMaxBandwidthOut: '{{ internetMaxBandwidthOut }}'
  Outputs:
    instanceIds:
      Type: List
      ValueSelector: InstanceIdSets.InstanceIdSet[]
- Name: untilInstanceReady
  Action: ACS::WaitFor
  Description: 作成されたインスタンスが Running 状態になるまで待機します。
  Properties:
    Service: ECS
    API: DescribeInstances
    Parameters:
      RegionId: '{{ regionId }}'
      InstanceIds:
      - '{{ ACS::TaskLoopItem }}'
    DesiredValues:
    - Running
    PropertySelector: Instances.Instance[].Status
  Loop:
    RateControl:
      Mode: Batch
      MaxErrors: 0
    Items: '{{ runInstances.instanceIds }}'
Outputs:
  instanceIds:
    Type: List
    Value: '{{ runInstances.instanceIds }}'
			

• JSON 形式

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "1 つ以上の ECS インスタンスを作成します。",
  "Parameters": {
    "regionId": {
      "Description": "リージョン ID。",
      "Type": "String",
      "Default": "{{ ACS::RegionId }}"
    },
    "imageId": {
      "Description": "インスタンス作成時に指定するイメージリソースの ID。",
      "Type": "String",
      "AllowedPattern": "[A-Za-z0-9_\\-\\.]*",
      "MinLength": 1,
      "MaxLength": 100
    },
    "instanceType": {
      "Description": "インスタンスのタイプ。",
      "Type": "String",
      "AllowedPattern": "ecs\\.[A-Za-z0-9\\.\\-]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "securityGroupId": {
      "Description": "インスタンスが属するセキュリティグループの ID。",
      "Type": "String",
      "AllowedPattern": "sg-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "vSwitchId": {
      "Description": "vSwitch の ID。",
      "Type": "String",
      "AllowedPattern": "vsw-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "amount": {
      "Description": "作成するインスタンス数。",
      "Type": "Number",
      "Default": 1
    },
    "internetMaxBandwidthIn": {
      "Description": "最大パブリックインバウンド帯域幅。",
      "Type": "Number",
      "Default": 200
    },
    "internetMaxBandwidthOut": {
      "Description": "最大パブリックアウトバウンド帯域幅。",
      "Type": "Number",
      "Default": 0
    }
  },
  "Tasks": [
    {
      "Name": "runInstances",
      "Action": "ACS::ExecuteAPI",
      "Description": "1 つ以上のインスタンスを作成します。",
      "Properties": {
        "Service": "ECS",
        "API": "RunInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "Amount": "{{ amount }}",
          "ImageId": "{{ imageId }}",
          "InstanceType": "{{ instanceType }}",
          "SecurityGroupId": "{{ securityGroupId }}",
          "VSwitchId": "{{ vSwitchId }}",
          "InternetMaxBandwidthIn": "{{ internetMaxBandwidthIn }}",
          "InternetMaxBandwidthOut": "{{ internetMaxBandwidthOut }}"
        }
      },
      "Outputs": {
        "instanceIds": {
          "Type": "List",
          "ValueSelector": "InstanceIdSets.InstanceIdSet[]"
        }
      }
    },
    {
      "Name": "untilInstanceReady",
      "Action": "ACS::WaitFor",
      "Description": "作成されたインスタンスが Running 状態になるまで待機します。",
      "Properties": {
        "Service": "ECS",
        "API": "DescribeInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "InstanceIds": [
            "{{ ACS::TaskLoopItem }}"
          ]
        },
        "DesiredValues": [
          "Running"
        ],
        "PropertySelector": "Instances.Instance[].Status"
      },
      "Loop": {
        "RateControl": {
          "Mode": "Batch",
          "MaxErrors": 0
        },
        "Items": "{{ runInstances.instanceIds }}"
      }
    }
  ],
  "Outputs": {
    "instanceIds": {
      "Type": "List",
      "Value": "{{ runInstances.instanceIds }}"
    }
  }
}