CloudOps Orchestration Service:Loop

Limit

The maximum number of loop Items is 1,000.

Syntax

• YAML format

---
Tasks:
  - Name: TaskName1 # Required. The name of the task. The name can contain lowercase letters, uppercase letters, digits, underscores (_), and hyphens (-). It can be up to 200 characters in length. We recommend that you use the camel case for a name. Example: StartInstance.
    Action: TaskType # Required. The type of the task or action. For more information, see the relevant documentation.
    Description: description # Optional. The description of the task, such as the purpose of the task.
    Properties: # The attributes of the task. The attribute list varies depending on the action used. For more information, see the relevant documentation.
      Property1: Value1 # The attribute that the action depends on.
    Outputs: # The output parameters of the task. These parameters can be used as the input of subsequent tasks or the output of the template.
      OutputParameterName1:
        Type: TypeName # Optional. The type of the output parameter. Default value: String.
        ValueSelector: "jq selector" # The jQuery selector for selecting the required JSON data. For example, when you call an API operation for a task, the jQuery selector extracts the required information from the returned JSON data. For more information, see the examples of cloud product actions and public templates.
    Loop:
      Items: [i-id1,i-id2,i-id3,i-id4] # Required. A list that contains items, such as [i-id1,i-id2,i-id3,i-id4], or a parameter of the List type, such as {{describeInstance.InstanceIds}}. The items obtained by traversing the list act as the input for executing the next iteration of the loop task.
      RateControl:
          MaxErrors: 0 # Optional. The error limit. You can set this attribute to a number or a percentage, such as 10 or 10%. Default value: 0.
          Mode: "Batch/Concurrency" # Required. The mode for controlling the loop execution rate. Valid values: Concurrency and Batch. Concurrency indicates concurrent execution and Batch indicates batch execution.
          Batch: [1, 2, 3] # Optional. The batch control mode. This parameter is valid when the Mode parameter is set to Batch. For more information, see the "Control the batch size" section.
          ConcurrencyInBatches: [1, 1, 1] # Optional. The maximum number of concurrent items of each batch. Default value: 20. This parameter is valid when the Mode parameter is set to Batch. Enter the number of concurrent items of each batch in brackets ([]).
          Concurrency: 1 # Optional. The maximum number of concurrent items. This parameter is valid when the Mode parameter is set to Concurrency. You can set this attribute to a number or a percentage. Default value: 1.
          BatchPauseOption: "FirstBatchPause/Automatic/EveryBatchPause" # Optional. Specify whether to suspend the batch execution when each batch is completed. This parameter is valid when the Mode is set to Batch. Valid values: FirstBatchPause, Automatic, and EveryBatchPause. FirstBatchPause indicates execution suspension after the first batch is completed. Automatic indicates automatic execution without suspension. FirstBatchPause indicates execution suspension after each batch is completed.
      Outputs:
        FinalOutputParameterName1: # The name of the output parameter after the loop task is processed by a function.
          AggregateType: BuiltInFunctionName1 # The built-in function for aggregating the outputs, such as Fn::Sum, Fn::Max, and Fn::ListJoin.
          AggregateField: OutputParameterName1 # The output parameter of the loop task.

• JSON format (For more information, see the parameter description for the YAML format.)

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

The Items attribute can be of the List type, such as List: [item1, item2, item3].

It can also be set to a parameter of the List type, such as the output parameter of the previous task, which is of the List type.

• Items as a list
  • YAML format

  Loop:
    Items: [item1,item2,item3,item4] # A list that contains multiple items, such as [i-id1,i-id2,i-id3,i-id4]. The items returned for each iteration of the loop act as the input for executing the next iteration.					

  • JSON format (For more information, see the parameter description for the YAML format.)

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

• Items as a parameter of the List type
  • YAML format

  Items: '{{ParameterName1}} ' # A parameter of the List type, such as describeInstance.InstanceIds. The parameter values returned for each iteration of the loop act as the input for executing the next iteration.	

  • JSON format (For more information, see the parameter description for the YAML format.)

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

Control the loop execution rate

You can control the loop execution rate in the following ways:

1. Control the number of concurrent items. The items are executed based on the specified number of concurrent items until all items are executed.
2. Control the batch size. All items are divided into multiple batches. The batches are executed one by one. The next batch can be executed only after the previous batch completes execution.

Control the number of concurrent items

• Assume that the list contains 10 items and the concurrency is 3. In this case, three items are executed concurrently each time until all of the items are executed.
  • YAML format

  Concurrency: 3 # The number of concurrent items. Example: 3.
  Mode: Concurrency

  • JSON format (For more information, see the parameter description for the YAML format.)

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

• Assume that the list contains 10 items and the concurrency is 20%. In this case, 20% of the items, namely, two items are executed concurrently each time until all of the items are executed.

  • YAML format

  Concurrency: 20% # Optional. The percentage of the items to be executed concurrently each time to all items. Example: 20%.
  Mode: Concurrency

  • JSON format (For more information, see the parameter description for the YAML format.)

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

Control the batch size

• Assume that the list contains 10 items and the batch size is [3]. In this case, all items are divided into four batches with three items as a batch. The number of items in each of the four batches is respectively 3, 3, 3, and 1 if all items are successfully executed.
  • YAML format

  Batch: [1, 2, 3] # Optional. The number of items in each batch. Example: [3].
  Mode: Batch

  • JSON format (For more information, see the parameter description for the YAML format.)

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

• Assume that the list contains 10 items and the batch size is [30%]. In this case, all items are divided into four batches with 30% of the items, namely, three items as a batch. The number of items in each of the four batches is respectively 3, 3, 3, and 1 if all items are successfully executed.

  • YAML format

  Batch: [30%] # Optional. The percentage of the items in each batch to all items. Example: 30%.
  Mode: Batch
  					

  • JSON format (For more information, see the parameter description for the YAML format.)

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

• Assume that the list contains 10 items and the batch size is [3, 10%, 30%]. In this case, three items are in the first batch. 10% of the items, namely, one item, is in the second batch. [30%] of the items, namely, three items, are in the third batch and each of the subsequent batches. The number of items in each of the four batches is respectively 3, 1, 3, and 3 if all items are successfully executed.

  • YAML format

  Mode: Batch
  Batch: [3, 10%, 30%] # Optional. A list of numbers and percentages that indicate the number of items in each batch. Example: [3, 10%, 30%].
  					

  • JSON format (For more information, see the parameter description for the YAML format.)

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

MaxErrors

You can define MaxErrors for a loop task based on the following description:

1. You can set this attribute to a number or a percentage, such as 10 or 10%. If the attribute is set to a percentage, multiply the total number of items by the percentage to obtain the maximum number of errors allowed. The default value is 0, indicating that the loop task stops once an error occurs.
2. The first item in a loop is always executed.
3. The relationship between MaxErrors and ErrorCount determines whether the second item or subsequent items can be executed.
   • If the value of ErrorCount is greater than that of MaxErrors, the subsequent items cannot be executed and the loop task is marked as failed.
   • If the value of ErrorCount is equal to or smaller than that of MaxErrors, the subsequent items can be executed.

4. The execution status of the loop task is determined based on the comparison condition: ErrorCount > MaxErrors. If the condition is true, the execution status is Failed. If the condition is false, the execution status is Success.

• MaxErrors as a number

  • YAML format

    MaxErrors: 2 # Optional. The maximum number of errors allowed. Example: 2.

  • JSON format (For more information, see the parameter description for the YAML format.)

    {
     "MaxErrors": 2 
    }

• MaxErrors as a percentage

  • YAML format

    MaxErrors: 25% # Optional. The percentage of the maximum number of errors allowed to the total number of items. Assume that you set this attribute to 25% and the list contains 4 items. In this case, the maximum number of errors allowed is 1.

  • JSON format (For more information, see the parameter description for the YAML format.)

    {
     "MaxErrors": "25%"
    }

Loop outputs

In a template, not only each loop task but also each iteration of a loop task generates outputs. The actual loop outputs contain the outputs of multiple items. Therefore, you need aggregate the outputs of multiple child tasks to obtain the final loop outputs. You can set AggregateType to a built-in function to aggregate the loop outputs.

Define AggregateType.

• YAML format

AggregateType: Fn::Max # A built-in function for aggregating the loop outputs, such as Fn::Max, which selects the largest OutputParameterName1 value of all child tasks as the output value of the loop.

• JSON format (For more information, see the parameter description for the YAML format.)

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

Examples

Concurrency mode

• YAML format

FormatVersion: OOS-2019-06-01
Description: Creates one or more ECS instances.
Parameters:
  regionId:
    Description: The ID of region.
    Type: String
    Default: '{{ ACS::RegionId }}'
  imageId:
    Description: The ID of the image resource that you specify when you create the
      instance.
    Type: String
    AllowedPattern: '[A-Za-z0-9_\-\.] *'
    MinLength: 1
    MaxLength: 100
  instanceType:
    Description: The type of the instance.
    Type: String
    AllowedPattern: ecs\.[ A-Za-z0-9\. \-]*
    MaxLength: 30
    MinLength: 1
  securityGroupId:
    Description: The ID of the security group to which the instance belongs.
    Type: String
    AllowedPattern: sg-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  vSwitchId:
    Description: The ID of the VSwitch.
    Type: String
    AllowedPattern: vsw-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  amount:
    Description: The specified number of instances you want to create.
    Type: Number
    Default: 1
  internetMaxBandwidthIn:
    Description: The maximum inbound public bandwidth.
    Type: Number
    Default: 200
  internetMaxBandwidthOut:
    Description: The maximum outbound public bandwidth.
    Type: Number
    Default: 0
Tasks:
- Name: runInstances
  Action: ACS::ExecuteAPI
  Description: Creates one or more instances.
  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: Waits for the created instances to be 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 f format

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "Creates one or more ECS instances.",
  "Parameters": {
    "regionId": {
      "Description": "The ID of region.",
      "Type": "String",
      "Default": "{{ ACS::RegionId }}"
    },
    "imageId": {
      "Description": "The ID of the image resource that you specify when you create the instance.",
      "Type": "String",
      "AllowedPattern": "[A-Za-z0-9_\\-\\.] *",
      "MinLength": 1,
      "MaxLength": 100
    },
    "instanceType": {
      "Description": "The type of the instance.",
      "Type": "String",
      "AllowedPattern": "ecs\\.[ A-Za-z0-9\\. \\-]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "securityGroupId": {
      "Description": "The ID of the security group to which the instance belongs.",
      "Type": "String",
      "AllowedPattern": "sg-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "vSwitchId": {
      "Description": "The ID of the VSwitch.",
      "Type": "String",
      "AllowedPattern": "vsw-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "amount": {
      "Description": "The specified number of instances you want to create.",
      "Type": "Number",
      "Default": 1
    },
    "internetMaxBandwidthIn": {
      "Description": "The maximum inbound public bandwidth.",
      "Type": "Number",
      "Default": 200
    },
    "internetMaxBandwidthOut": {
      "Description": "The maximum outbound public bandwidth.",
      "Type": "Number",
      "Default": 0
    }
  },
  "Tasks": [
    {
      "Name": "runInstances",
      "Action": "ACS::ExecuteAPI",
      "Description": "Creates one or more instances.",
      "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": "Waits for the created instances to be 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 }}"
    }
  }
}

Batch mode

• YAML format

FormatVersion: OOS-2019-06-01
Description: Creates one or more ECS instances.
Parameters:
  regionId:
    Description: The ID of region.
    Type: String
    Default: '{{ ACS::RegionId }}'
  imageId:
    Description: The ID of the image resource that you specify when you create the
      instance.
    Type: String
    AllowedPattern: '[A-Za-z0-9_\-\.] *'
    MinLength: 1
    MaxLength: 100
  instanceType:
    Description: The type of the instance.
    Type: String
    AllowedPattern: ecs\.[ A-Za-z0-9\. \-]*
    MaxLength: 30
    MinLength: 1
  securityGroupId:
    Description: The ID of the security group to which the instance belongs.
    Type: String
    AllowedPattern: sg-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  vSwitchId:
    Description: The ID of the VSwitch.
    Type: String
    AllowedPattern: vsw-[A-Za-z0-9]*
    MaxLength: 30
    MinLength: 1
  amount:
    Description: The specified number of instances you want to create.
    Type: Number
    Default: 1
  internetMaxBandwidthIn:
    Description: The maximum inbound public bandwidth.
    Type: Number
    Default: 200
  internetMaxBandwidthOut:
    Description: The maximum outbound public bandwidth.
    Type: Number
    Default: 0
Tasks:
- Name: runInstances
  Action: ACS::ExecuteAPI
  Description: Creates one or more instances.
  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: Waits for the created instances to be Running.
  Properties:
    Service: ECS
    API: DescribeInstances
    Parameters:
      RegionId: '{{ regionId }}'
      InstanceIds:
      - '{{ ACS::TaskLoopItem }}'
    DesiredValues:
    - Running
    PropertySelector: Instances.Instance[].Status
  Loop:
    RateControl:
      Mode: Batch
      MaxErrors: 0
      Batch: [1, 2, 3]
      BatchPauseOption: Automatic
      ConcurrencyInBatches: [1, 2, 3]
    Items: '{{ runInstances.instanceIds }}'
Outputs:
  instanceIds:
    Type: List
    Value: '{{ runInstances.instanceIds }}'
            

• JSON format

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "Creates one or more ECS instances.",
  "Parameters": {
    "regionId": {
      "Description": "The ID of region.",
      "Type": "String",
      "Default": "{{ ACS::RegionId }}"
    },
    "imageId": {
      "Description": "The ID of the image resource that you specify when you create the instance.",
      "Type": "String",
      "AllowedPattern": "[A-Za-z0-9_\\-\\.] *",
      "MinLength": 1,
      "MaxLength": 100
    },
    "instanceType": {
      "Description": "The type of the instance.",
      "Type": "String",
      "AllowedPattern": "ecs\\.[ A-Za-z0-9\\. \\-]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "securityGroupId": {
      "Description": "The ID of the security group to which the instance belongs.",
      "Type": "String",
      "AllowedPattern": "sg-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "vSwitchId": {
      "Description": "The ID of the VSwitch.",
      "Type": "String",
      "AllowedPattern": "vsw-[A-Za-z0-9]*",
      "MaxLength": 30,
      "MinLength": 1
    },
    "amount": {
      "Description": "The specified number of instances you want to create.",
      "Type": "Number",
      "Default": 1
    },
    "internetMaxBandwidthIn": {
      "Description": "The maximum inbound public bandwidth.",
      "Type": "Number",
      "Default": 200
    },
    "internetMaxBandwidthOut": {
      "Description": "The maximum outbound public bandwidth.",
      "Type": "Number",
      "Default": 0
    }
  },
  "Tasks": [
    {
      "Name": "runInstances",
      "Action": "ACS::ExecuteAPI",
      "Description": "Creates one or more instances.",
      "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": "Waits for the created instances to be Running.",
      "Properties": {
        "Service": "ECS",
        "API": "DescribeInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "InstanceIds": [
            "{{ ACS::TaskLoopItem }}"
          ]
        },
        "DesiredValues": [
          "Running"
        ],
        "PropertySelector": "Instances.Instance[].Status"
      },
      "Loop": {
        "RateControl": {
          "Mode": "Batch",
          "MaxErrors": 0,
          "Batch": [
            1,
            2,
            3
          ],
          "BatchPauseOption": "Automatic",
          "ConcurrencyInBatches": [
            1,
            2,
            3
          ]
        },
        "Items": "{{ runInstances.instanceIds }}"
      }
    }
  ],
  "Outputs": {
    "instanceIds": {
      "Type": "List",
      "Value": "{{ runInstances.instanceIds }}"
    }
  }
}