Use Alibaba Cloud CLI to execute rolling update tasks - Auto Scaling

Background information

Rolling update tasks allow you to update the configurations of multiple ECS instances at the same time. For more information, see Use the rolling update feature.

Procedure

The following procedure shows you how to use Alibaba Cloud CLI to update images of, run scripts on, and install OOS packages on ECS instances in a scaling group.

Step 1: Create a Resource Access Management (RAM) user and grant permissions to the user
Step 2: Configure and verify Alibaba Cloud CLI
Step 3: Use Alibaba Cloud CLI to execute a rolling update task
Execute rollback tasks to handle exceptions in rolling update tasks

Step 1: Create a Resource Access Management (RAM) user and grant permissions to the user

Log on to the RAM console.

Create a RAM user.

In this example, a RAM user named clitest is created. For more information, see Create a RAM user.

In the left-side navigation pane, choose Identities > Users.
Click Create User.

On the Create User page, configure the parameters, and then click OK.

The following table describes the parameters.


Parameter	Example
Logon Name	example@sample.com
Display Name	example
Access Mode	Select Open API Access. An AccessKey pair is automatically created for the RAM user. The RAM user can call API operations or use SDKs to access Alibaba Cloud resources.

On the Basic Information page, click Download CSV File.

Note The AccessKey secret is displayed only when you create an AccessKey pair, and cannot be queried. We recommend that you save the AccessKey secret for subsequent use. If an AccessKey pair is leaked or lost, you must create a new AccessKey pair.

Grant the RAM user permissions to manage resources.

In the left-side navigation pane, choose Identities > Users.
Find the example user that you created. Click Add Permissions in the Actions column.

In the Add Permissions panel, select the policies that contain the permissions required to execute the rolling update task, and then click OK.

The following table describes the parameters in the Add Permissions panel.


Parameter	Example
Authorized Scope	Alibaba Cloud Account
Principal	example@sample.com
Select Policy	Select the following system policies: AliyunECSFullAccess: contains permissions to manage ECS resources such as ECS instances. AliyunESSFullAccess: contains permissions to manage Auto Scaling resources such as scaling groups. AliyunOOSFullAccess: contains permissions to manage OOS resources such as executions. AliyunOSSFullAccess: contains permissions to manage Object Storage Service (OSS) resources such as buckets.

Step 2: Configure and verify Alibaba Cloud CLI

For information about the configuration parameters, see Configure Alibaba Cloud CLI.

Open Alibaba Cloud CLI on your local computer.
Configure Alibaba Cloud CLI.
1. Run the following command to open the configuration file:
```
aliyun configure
```
2. Enter the AccessKey ID and AccessKey secret.
Run the following command to check whether Alibaba Cloud CLI is available:
```
aliyun ecs DescribeRegions
```
This command is used to query the regions in which Alibaba Cloud CLI is supported. If region information is returned, the command is successfully run. The following figure shows a sample command output.

Step 3: Use Alibaba Cloud CLI to execute a rolling update task

In this step, sample commands are used to show how to update images of, run scripts on, and install OOS packages on ECS instances in the scaling group.

Run an Alibaba Cloud CLI command to execute a rolling update task.

For information about the OOS template parameters in the code, see OOS template parameters.

The following sample code shows how to update images of ECS instances in the scaling group to Alibaba Cloud Linux 2.1903 LTS 64-bit.

aliyun oos StartExecution --TemplateName ACS-ESS-RollingUpdateByReplaceSystemDiskInScalingGroup --Parameters "{
        \"invokeType\": \"invoke\",
        \"scalingGroupId\": \"asg-bp18p2yfxow2dloq****\",
        \"scalingConfigurationId\": \"asc-bp1bx8mzur534edp****\",
        \"imageId\": \"aliyun_2_1903_x64_20G_alibase_20200529.vhd\",
        \"sourceImageId\": \"centos_7_8_x64_20G_alibase_20200717.vhd\",
        \"OOSAssumeRole\": \"\",
        \"enterProcess\": [
          \"ScaleIn\",
          \"ScaleOut\",
          \"HealthCheck\",
          \"AlarmNotification\",
          \"ScheduledAction\"
        ],
        \"exitProcess\":  [
          \"ScaleIn\",
          \"ScaleOut\",
          \"HealthCheck\",
          \"AlarmNotification\",
          \"ScheduledAction\"
        ],
        \"batchNumber\": 2,
        \"batchPauseOption\": \"Automatic\"
      }"

The following sample code shows how to run the df -h and ifconfig shell commands on ECS instances in the scaling group to view the disks and network configurations of the instances.

aliyun oos StartExecution --TemplateName ACS-ESS-RollingUpdateByRunCommandInScalingGroup --Parameters "{
        \"invokeType\": \"invoke\",
        \"scalingGroupId\": \"asg-bp18p2yfxow2dloq****\",
        \"commandType\": \"RunShellScript\",
        \"invokeScript\": \"df -h\nifconfig\",
        \"rollbackScript\": \"df -h\nifconfig\",
        \"OOSAssumeRole\": \"\",
        \"exitProcess\": [
          \"ScaleIn\",
          \"ScaleOut\",
          \"HealthCheck\",
          \"AlarmNotification\",
          \"ScheduledAction\"
        ],
        \"enterProcess\": [
          \"ScaleIn\",
          \"ScaleOut\",
          \"HealthCheck\",
          \"AlarmNotification\",
          \"ScheduledAction\"
        ],
        \"batchNumber\": 2,
        \"batchPauseOption\": \"Automatic\"
      }"

The following sample code shows how to install the WordPress package on all ECS instances in the scaling group.

aliyun oos StartExecution --TemplateName ACS-ESS-RollingUpdateByConfigureOOSPackage --Parameters "{
        \"invokeType\": \"invoke\",
        \"scalingGroupId\": \"asg-bp18p2yfxow2dloq****\",
        \"packageName\": \"wordpress\",
        \"packageVersion\": \"v4\",
        \"action\": \"install\",
        \"OOSAssumeRole\": \"\",
        \"enterProcess\": [
          \"ScaleIn\",
          \"ScaleOut\",
          \"HealthCheck\",
          \"AlarmNotification\",
          \"ScheduledAction\"
        ],
        \"exitProcess\": [
          \"ScaleIn\",
          \"ScaleOut\",
          \"HealthCheck\",
          \"AlarmNotification\",
          \"ScheduledAction\"
        ],
        \"batchNumber\": 2,
        \"batchPauseOption\": \"Automatic\"
      }"

View the execution details.
When you run CLI commands to execute rolling update tasks, executions are automatically created in OOS. You can find an execution based on the returned execution ID and view the details about the execution, such as the execution result and output. The following example shows how to obtain the execution ID and view the execution details.
1. Find the execution ID of the rolling update task in the command output.
  The following figure shows a sample execution ID.
2. Run the following Alibaba Cloud CLI command to view the execution details:
```
aliyun oos ListExecutions --ExecutionId exec-40e2e17ef7e04****
```
  The following figure shows the sample execution details.

Execute rollback tasks to handle exceptions in rolling update tasks

If exceptions occur when rolling update tasks are executed, or if you want to use previous configurations after rolling update tasks are executed, you can execute rollback tasks to restore the configurations of the ECS instances. In this section, sample commands are used to show how to roll back rolling update tasks that are executed.

Find the execution ID of the rolling update task in the command output.
The following figure shows a sample execution ID.

Run an Alibaba Cloud CLI command to execute a rollback task.

For information about the OOS template parameters in the code, see OOS template parameters.

Note When you execute a rollback task, OOS automatically finds the ECS instances that need to be rolled back based on the rolling update task, and suspends or resumes scaling processes of the scaling group. Therefore, you may not need to configure some parameters.

The following example shows how to roll the images of ECS instances in the scaling group back to CentOS 7.8 64-bit.

aliyun oos StartExecution --TemplateName ACS-ESS-RollingUpdateByReplaceSystemDiskInScalingGroup --Parameters "{
        \"invokeType\": \"rollback\",
        \"scalingGroupId\": \"asg-bp18p2yfxow2dloq****\",
        \"scalingConfigurationId\": \"asc-bp1bx8mzur534edp****\",
        \"sourceImageId\": \"centos_7_8_x64_20G_alibase_20200717.vhd\",
        \"sourceExecutionId\": \"exec-83dba59be77d430****\",
        \"OOSAssumeRole\": \"\",
        \"batchNumber\": 2,
        \"batchPauseOption\": \"Automatic\"
      }"

The following example shows how to run the rollback script in the ECS instances. The df -h and ifconfig shell commands are still used. You can change the script based on your business requirements.

aliyun oos StartExecution --TemplateName ACS-ESS-RollingUpdateByRunCommandInScalingGroup --Parameters "{
        \"invokeType\": \"rollback\",
        \"commandType\": \"RunShellScript\",
        \"rollbackScript\": \"df -h\nifconfig\",
        \"scalingGroupId\": \"asg-bp18p2yfxow2dloq****\",
        \"sourceExecutionId\": \"exec-40e2e17ef7e046****\",
        \"OOSAssumeRole\": \"\",
        \"batchNumber\": 2,
        \"batchPauseOption\": \"Automatic\"
      }"

The following example shows how to install the previous version of the WordPress package that is created in OOS for the ECS instances in the scaling group.

aliyun oos StartExecution --TemplateName ACS-ESS-RollingUpdateByConfigureOOSPackage --Parameters "{
        \"invokeType\": \"rollback\",
        \"scalingGroupId\": \"asg-bp18p2yfxow2dloq****\",
        \"packageVersion\": \"v3\",
        \"packageName\": \"wordpress\",
        \"sourceExecutionId\": \"exec-f4e61f2f21fe490****\",
        \"OOSAssumeRole\": \"\",
        \"batchNumber\": 2,
        \"batchPauseOption\": \"Automatic\"
      }"

View the execution details.
When you run CLI commands to execute a rollback task, executions are also automatically created in OOS. You can also use the methods in Step 3 to view the details about an execution, such as the execution result and output.

OOS template parameters

The following tables describe the parameters of the OOS public templates that are used in the preceding examples.

Table 1. Parameters in the ACS-ESS-RollingUpdateByReplaceSystemDiskInScalingGroup template
Parameter	Description
invokeType	The type of the task. Valid values: invoke: rolling update task rollback: rollback task
scalingGroupId	The ID of the scaling group in which you want to execute the task.
scalingConfigurationId	The ID of the active scaling configuration in the scaling group.
imageId	The ID of the image that you want to use to replace the current image.
sourceImageId	The ID of the image that you want to use for the rollback task.
OOSAssumeRole	The RAM role that you want to use to execute the task. Default value: OOSServiceRole.
enterProcess	The scaling process that you want to suspend before the task is executed.
exitProcess	The scaling process that you want to resume when the task is complete.
batchNumber	The number of batches into which the ECS instances in the scaling group are divided. The task is executed in these batches. Each batch contains at least one ECS instance.
batchPauseOption	Specifies whether and how to suspend the task. Valid values: Automatic: The task is executed without interruptions. FirstBatchPause: The task is suspended when the first batch of executions is complete. EveryBatchPause: The task is suspended when each batch of executions is complete.
sourceExecutionId	The execution ID of the source rolling update task when a rollback task is executed.

Note You can log on to the OOS console to view more parameter descriptions. For example, to view the parameter descriptions for the China (Hangzhou) region, see ACS-ESS-RollingUpdateByReplaceSystemDiskInScalingGroup.

Table 2. Parameters in the ACS-ESS-RollingUpdateByRunCommandInScalingGroup template
Parameter	Description
invokeType	The type of the task. Valid values: invoke: rolling update task rollback: rollback task
scalingGroupId	The ID of the scaling group in which you want to execute the task.
commandType	The type of the script that you want to execute. A value of RunShellScript specifies a shell script.
invokeScript	The script that is executed on ECS instances during a rolling update task.
rollbackScript	The script that is executed on ECS instances during a rollback task.
OOSAssumeRole	The RAM role that you want to use to execute the task. Default value: OOSServiceRole.
enterProcess	The scaling process that you want to suspend before the task is executed.
exitProcess	The scaling process that you want to resume when the task is complete.
batchNumber	The number of batches into which the ECS instances in the scaling group are divided. The task is executed in these batches. Each batch contains at least one ECS instance.
batchPauseOption	Specifies whether and how to suspend the task. Valid values: Automatic: The task is executed without interruptions. FirstBatchPause: The task is suspended when the first batch of executions is complete. EveryBatchPause: The task is suspended when each batch of executions is complete.
sourceExecutionId	The execution ID of the source rolling update task when a rollback task is executed.

Note You can log on to the OOS console to view more parameter descriptions. For example, to view the parameter descriptions for the China (Hangzhou) region, see ACS-ESS-RollingUpdateByRunCommandInScalingGroup.

Table 3. Parameters in the ACS-ESS-RollingUpdateByConfigureOOSPackage template
Parameter	Description
invokeType	The type of the task. Valid values: invoke: rolling update task rollback: rollback task
scalingGroupId	The ID of the scaling group in which you want to execute the task.
packageName	The name of the software package.
packageVersion	The version of the software package.
action	The action to be taken on the software package. Valid values: install uninstall Default value: install.
OOSAssumeRole	The RAM role that you want to use to execute the task. Default value: OOSServiceRole.
enterProcess	The scaling process that you want to suspend before the task is executed.
exitProcess	The scaling process that you want to resume when the task is complete.
batchNumber	The number of batches into which the ECS instances in the scaling group are divided. The task is executed in these batches. Each batch contains at least one ECS instance.
batchPauseOption	Specifies whether and how to suspend the task. Valid values: Automatic: The task is executed without interruptions. FirstBatchPause: The task is suspended when the first batch of executions is complete. EveryBatchPause: The task is suspended when each batch of executions is complete.
sourceExecutionId	The execution ID of the source rolling update task when a rollback task is executed.

Note You can log on to the OOS console to view more parameter descriptions. For example, to view the parameter descriptions for the China (Hangzhou) region, see ACS-ESS-RollingUpdateByConfigureOOSPackage.

Auto Scaling:Use Alibaba Cloud CLI to execute rolling update tasks

Prerequisites