:Use Alibaba Cloud CLI to call API operations of OOS

What is Alibaba Cloud CLI?

Alibaba Cloud CLI is an open source tool that is built based on Alibaba Cloud SDK for Go. You can use the aliyun commands to interact with Alibaba Cloud services and manage your Alibaba Cloud resources. For more information, see What is Alibaba Cloud CLI?

Installation guide

Alibaba Cloud CLI can be installed on multiple operating systems:

Linux

Windows

macOS

Credential configuration and debugging

Before you use Alibaba Cloud CLI, you must configure the information that is required to use Alibaba Cloud services. The information includes the credential, region, and language. Alibaba Cloud CLI supports multiple types of credentials, such as AccessKey pair, Security Token Service (STS) token, RamRoleArn, and EcsRamRole. For more information, see Non-interactive configuration.

In CloudOps Orchestration Service (OOS), most O&M tasks are automatically executed. In this example, the EcsRamRole credential for non-interactive configuration is used. This type of credential is easy to get started.

In most cases, a RAM role is used to grant permissions in automation scenarios. Therefore, you can attach a RAM role to the ECS instance on which you want to use Alibaba Cloud CLI. For more information, see Grant ECS access to other Alibaba Cloud services by using instance RAM roles.

In this example, a RAM role named InstanceRole is attached to an ECS instance that runs a Linux operating system.

After you attach the InstanceRole role to the ECS instance, you can install and configure Alibaba Cloud CLI on the instance. The following script provides an example on how to install and configure Alibaba Cloud CLI:

mkdir -p  $HOME/aliyun
cd $HOME/aliyun
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-3.0.51-amd64.tgz
tar xzvf aliyun-cli-linux-3.0.51-amd64.tgz
cp $HOME/aliyun/aliyun /usr/bin/
ramRoleName="InstanceRole"
regiond_id=cn-zhangjiakou
aliyun configure set --profile ecsRamRoleProfile --mode EcsRamRole --region $regiond_id --ram-role-name $ramRoleName

In the preceding script, Alibaba Cloud CLI is installed, the region ID is set to cn-zhangjiakou, and the InstanceRole role that has been attached to the ECS instance is specified as the permission source of Alibaba Cloud CLI.

Then, you can check whether the configuration of Alibaba Cloud CLI takes effect. You can run the aliyun OOS command to query the available API operations of OOS. If the result shown in the following figure is returned, the configuration of Alibaba Cloud CLI takes effect. After that, you can test Alibaba Cloud CLI by calling API operations of OOS in the specified region.

aliyun OOS

API call reference

You can run the aliyun oos ApiName --help command to query the request parameters of an API operation. For example, you can run the following command to query the usage of the ListTemplates operation:

aliyun oos ListTemplates --help

Then, you can call the ListTemplates operation of OOS to query templates. The following figure shows the result.

aliyun OOS ListTemplates  --MaxResults 10

You can also call the CreateTemplate operation to create an OOS template in the JSON or YAML format. The following scripts show the template content and the command:

FormatVersion: OOS-2019-06-01
Description: Views the ECS instances by specifying instance status.
Parameters:
  regionId:
    Description: The ID of region.
    Type: String
    Default: '{{ ACS::RegionId }}'
  status:
    Description: The ECS instances status for query instances.
    Type: String
Tasks:
  - Name: describeInstances
    Action: 'ACS::ExecuteAPI'
    Description: Views the ECS instances by specifying instance status.
    Properties:
      Service: ECS
      API: DescribeInstances
      Parameters:
        RegionId: '{{ regionId }}'
        Status: '{{ status }}'
    Outputs:
      instanceIds:
        Type: List
        ValueSelector: 'Instances.Instance[].InstanceId'
Outputs:
  instanceIds:
    Type: List
    Value: '{{ describeInstances.instanceIds }}'

{
  "FormatVersion": "OOS-2019-06-01",
  "Description": "Views the ECS instances by specifying instance status.",
  "Parameters": {
    "regionId": {
      "Description": "The ID of region.",
      "Type": "String",
      "Default": "{{ ACS::RegionId }}"
    },
    "status": {
      "Description": "The ECS instances status for query instances.",
      "Type": "String"
    }
  },
  "Tasks": [
    {
      "Name": "describeInstances",
      "Action": "ACS::ExecuteAPI",
      "Description": "Views the ECS instances by specifying instance status.",
      "Properties": {
        "Service": "ECS",
        "API": "DescribeInstances",
        "Parameters": {
          "RegionId": "{{ regionId }}",
          "Status": "{{ status }}"
        }
      },
      "Outputs": {
        "instanceIds": {
          "Type": "List",
          "ValueSelector": "Instances.Instance[].InstanceId"
        }
      }
    }
  ],
  "Outputs": {
    "instanceIds": {
      "Type": "List",
      "Value": "{{ describeInstances.instanceIds }}"
    }
  }
}

# Enclose the JSON or YAML code of the template in single quotation marks (').
content='{ "FormatVersion": "OOS-2019-06-01", "Description": "Views the ECS instances by specifying instance status.", "Parameters": { "regionId": { "Description": "The ID of region.", "Type": "String", "Default": "{{ ACS::RegionId }}" }, "status": { "Description": "The ECS instances status for query instances.", "Type": "String" } }, "Tasks": [ { "Name": "describeInstances", "Action": "ACS::ExecuteAPI", "Description": "Views the ECS instances by specifying instance status.", "Properties": { "Service": "ECS", "API": "DescribeInstances", "Parameters": { "RegionId": "{{ regionId }}", "Status": "{{ status }}" } }, "Outputs": { "instanceIds": { "Type": "List", "ValueSelector": "Instances.Instance[].InstanceId" } } } ], "Outputs": { "instanceIds": { "Type": "List", "Value": "{{ describeInstances.instanceIds }}" } } }'
aliyun oos CreateTemplate --TemplateName template01 --Content  "$content"

Call the StartExecution operation to create an execution for an existing custom template.

regionId="cn-zhangjiakou" # The region in which the execution task is run.
status="Running"
parameters="{
  \"regionId\": \"$regionId\",
  \"status\": \"$status\"
}"
aliyun oos StartExecution --TemplateName template01 --Parameters "${parameters}"

Call the StartExecution operation to create an execution for an existing public template.

regionId="cn-zhangjiakou" # The region in which the execution task is run.
securityGroupId="sg-8vb*********xwvnuqy6" # The security group that is used to create a temporary instance.
vSwitchId="vsw-8*******0z9ykpzv01c" # The vSwitch that is used to create a temporary instance.
instanceType="ecs.g5.large" # The instance type of the temporary instance.
sourceImageId="centos_7_8_x64_20G_alibase_20200622.vhd" # The source image to be updated.
commandType="RunShellScript" # The type of the script.
commandContent='ls\npwd\n'
parameters="{
  \"securityGroupId\": \"$securityGroupId\",
  \"commandType\": \"$commandType\",
  \"sourceImageId\": \"$sourceImageId\",
  \"regionId\": \"$regionId\",
  \"vSwitchId\": \"$vSwitchId\",
  \"instanceType\": \"$instanceType\",
  \"commandContent\": \"$commandContent\"
}"
aliyun oos StartExecution --TemplateName ACS-ECS-UpdateImage --Parameters "${parameters}"

Summary

If you attach a RAM role to an ECS instance and the RAM role is authorized to access other Alibaba Cloud services, you can use Alibaba Cloud CLI to call API operations of these Alibaba Cloud services on the ECS instance. You can also write a Cloud Assistant script in OOS to run Alibaba Cloud CLI commands. Use these commands as regular commands.