CLI integration example

This topic uses the Auto Scaling (ESS) DescribeScalingActivities operation as an example to explain how to call Auto Scaling OpenAPI operations with the Alibaba Cloud CLI.

Background

The Alibaba Cloud Command Line Interface (CLI) is a general-purpose Auto Scaling built on OpenAPI. You can use the Alibaba Cloud CLI to automate the management and maintenance of Auto Scaling. For more information, see What is Alibaba Cloud CLI.

Step 1: Install Alibaba Cloud CLI

The CLI can be installed on Windows, Linux, and macOS. Select the installation method for your operating system.

Windows: Install Alibaba Cloud CLI on Windows.
Linux: Install Alibaba Cloud CLI on Linux.
macOS: Install Alibaba Cloud CLI on macOS.

Cloud Shell comes with the Alibaba Cloud CLI pre-installed and your Cloud Shell automatically configured, eliminating the need for manual setup. You can debug Alibaba Cloud CLI commands directly in Cloud Shell. For more information, see What is Cloud Shell?.

Step 2: Configure Alibaba Cloud CLI

Important

An Alibaba Cloud account has full management and access permissions for the OpenAPI of all products, which poses a high security risk. We strongly recommend that you create a RAM user, grant permissions to the RAM user based on the principle of least privilege, and then use the RAM user to access OpenAPI. For more information about the policies supported by Auto Scaling, see System policies for Auto Scaling and Custom policies for Auto Scaling.

Before you use Alibaba Cloud CLI, you must configure information such as your identity credentials and a region ID. Alibaba Cloud CLI supports multiple types of identity credentials. For more information, see Identity credential types. You can use the AccessKey of a RAM user to configure an AK-type identity credential. The steps are as follows:

Create a RAM user and an AccessKey to configure an identity credential. For more information, see Create a RAM user and Create an AccessKey.
Grant the RAM user the AliyunESSReadOnlyAccess permission for read-only access to Auto Scaling. For more information, see Manage RAM user permissions.
Obtain an available region ID. Alibaba Cloud CLI uses the specified region to make OpenAPI calls. For the available regions for Auto Scaling, see Endpoints.
Note
In Alibaba Cloud CLI, use the --region option to specify a region for a command call. This option overrides the region specified in the default identity credential configuration and in environment variables. For more information, see Command-line options.
Use the RAM user's AccessKey to configure an AK-type credential. Name the configuration file AkProfile. For more information, see Configuration example.

Step 3: Generate a CLI command example

In OpenAPI Explorer, go to the DescribeScalingActivities debug page.
In the Parameter Configuration section, enter the request parameters. Click the CLI Example tab to view the generated CLI example.
Copy the CLI example or run it in Cloud Shell:
- Click the Run Command button to open Cloud Shell and debug the command.
- Click the Copy button to copy the CLI example to the clipboard. Paste the example into a local shell tool to run it, or use it to edit an automated command-line script.
Note
When copying the CLI example to a local shell tool for debugging, note the parameter format. For more information about the parameter format for Alibaba Cloud CLI commands, see Parameter format.
OpenAPI Explorer adds the --region option to the generated example by default. When you copy the command to run it locally, Alibaba Cloud CLI ignores the region information in the default identity credential configuration and environment variables. It preferentially uses the specified region to run the command. You can delete or keep this option as needed.

Step 4: Call the Auto Scaling OpenAPI

Note

The Alibaba Cloud CLI integrates an earlier version of the Auto Scaling OpenAPI. Use the --force and --version options to call the 2022-02-22 version of the Auto Scaling OpenAPI. For more information, see Force an API call.
OpenAPI Explorer automatically adds the --force and --version options when it generates command examples for the 2022-02-22 version of the Auto Scaling OpenAPI. No manual changes are required.
For more information about available APIs, see API overview.

The following example shows how to use the Alibaba Cloud CLI to call the Auto Scaling DescribeScalingActivities API and view the details of a specific scaling activity. For more information about the API, see DescribeScalingActivities - Query scaling activities.

Run the command.

aliyun ess DescribeScalingActivities --RegionId 'cn-hangzhou' --ScalingGroupId 'asg-bp18p2yfxow2dloq****' --version 2022-02-22 --method POST --force

The following output is returned.

{
  "RequestId": "CC107349-57B7-4405-B1BF-9BF5AF7F****",
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 1,
  "ScalingActivities": [
    {
      "Progress": 100,
      "ScalingInstanceNumber": 1,
      "AttachedCapacity": "0",
      "TotalCapacity": "2",
      "ScalingGroupId": "asg-bp18p2yfxow2dloq****",
      "AutoCreatedCapacity": "2",
      "EndTime": "2020-09-10T09:54Z",
      "StartTime": "2020-09-10T09:54Z",
      "Description": "Add \\\"1\\\" ECS instance",
      "StatusCode": "Successful",
      "Cause": "A user requests to execute scaling rule \\\"asr-bp12tcnol686y1ik****\\\", changing the Total Capacity from \\\"1\\\" to \\\"2\\\".",
      "ScalingActivityId": "asa-bp161xudmuxdzofe****",
      "StatusMessage": "\\\"1\\\" ECS instances are added",
      "CreatedCapacity": 1,
      "DestroyedCapacity": 1,
      "StartedCapacity": 1,
      "StoppedCapacity": 1,
      "CreatedInstances": [
        "[\"i-abc1\",\"i-abc2\"]"
      ],
      "DestroyedInstances": [
        "[\n      \"i-abc1\",\n      \"i-abc2\"\n]"
      ],
      "StartedInstances": [
        "[\n      \"i-abc1\",\n      \"i-abc2\"\n]"
      ],
      "StoppedInstances": [
        "[\n      \"i-abc1\",\n      \"i-abc2\"\n]"
      ],
      "ErrorCode": "OperationDenied.NoStock",
      "ErrorMessage": "The specified ECS resource is out of stock in this region. Please try again later.",
      "Detail": "\"new ECS instances \"i-j6c8ilerw, i-j6c8iler4mx\" are created.\"",
      "TriggerSourceType": "Api",
      "TriggerSourceId": "2346366580*****",
      "LifecycleHookContext": {
        "DisableLifecycleHook": false,
        "IgnoredLifecycleHookIds": [
          "ash-bp14zolna43z266bq***\n"
        ]
      },
      "ActivityMetadata": "{\\\"goatscaler.io/managed\\\":\\\"true\\\"}",
      "InstanceRefreshTaskId": "ir-asdf12adsxg*****"
    }
  ]
}

Note

If an error is returned after calling the Auto Scaling OpenAPI, check the request parameters and their values based on the returned error code.

Record the RequestID or SDK error message returned from the call. Use the Alibaba Cloud OpenAPI Diagnostic Platform to run a self-diagnosis.