DocsICP FilingConsole
官方文档
首页

CLI integration example

更新时间：
复制 MD 格式
产品详情
我的收藏

This topic describes how to use Alibaba Cloud CLI to call the API operations of Container Service for Kubernetes (ACK). In this example, the DescribeClusterDetail operation is called to query the details of an ACK cluster.ACK

Before you start

Alibaba Cloud CLI is a general-purpose command-line tool that is developed based on APIs. You can use Alibaba Cloud CLI to implement automatic management and maintenance of ACK resources. For more information, see What is Alibaba Cloud CLI?

Step 1: Install Alibaba Cloud CLI

You must install Alibaba Cloud CLI before you can use it. You can install Alibaba Cloud CLI in the Windows, Linux, and macOS operating systems. You must select an installation package of Alibaba Cloud CLI based on the operating system of your device. For more information, see the following topics:

  • Windows operating system: Windows

  • Linux operating system: Linux

  • macOS operating system: macOS

Cloud Shell is pre-installed with Alibaba Cloud CLI. When you use Alibaba Cloud CLI in a Cloud Shell instance, Cloud Shell automatically configures an identity credential for you based on the identity information of the logon account. You can use Cloud Shell to debug the commands that you want to run in Alibaba Cloud CLI. For more information, see What is Cloud Shell?.

Step 2: Configure Alibaba Cloud CLI

Important

An Alibaba Cloud account has the permissions to manage and access the APIs of all Alibaba Cloud services. If you use an Alibaba Cloud account to call API operations, security risks may arise. We recommend that you create a Resource Access Management (RAM) user, grant permissions to the RAM user based on the principle of least privilege, and then use the RAM user to call API operations. For more information about the system policies supported by ACK, see AliyunCSFullAccess and AliyunCSReadOnlyAccess.

Before you use Alibaba Cloud CLI, you must configure an identity credential and a region. Alibaba Cloud CLI supports multiple types of identity credentials. For more information, see Configure and manage credentials. This topic describes how to use the AccessKey of a RAM user to configure an AK-type credential.

  1. Create a RAM user and create an AccessKey pair for the RAM user to configure identity credentials. For more information, see Create a RAM user and Create an AccessKey pair.

  2. Grant the required permissions to the RAM user. In this example, attach the AliyunCSReadOnlyAccess policy to the RAM user. The policy grants the RAM user the read-only permissions on ACK. For more information, see Grant permissions to a RAM user.

  3. Obtain the ID of the region in which you want to configure identity credentials. Alibaba Cloud CLI uses the specified region ID to call API operations. We recommend that you select the ID of the region where the cluster resides. For more information about the regions supported by ACK, see Endpoints.

    Note

    When you use Alibaba Cloud CLI, you can use the --region option to specify the region from which you want to initiate a call. If you use the option to specify a region, Alibaba Cloud CLI ignores the region information in the default credential settings and environment variables. For more information, see Command line options for API calls.

  4. Use the AccessKey pair of the RAM user to configure identity credentials in the configuration file named AkProfile. For more information, see Configuration examples.

Step 3: Generate a CLI command

  1. Go to the DescribeClusterDetail page in OpenAPI Explorer.

    Click the CLI Example tab on the right to view the generated CLI command, such as aliyun cs GET /clusters/{ClusterId} --header "Content-Type=application/json;". Click the action button on the right side of the command area to copy the command.

  2. On the Parameters tab, enter the request parameters. Click the CLI Example tab to view the generated CLI example.

  3. Copy the CLI command or debug the CLI command in Cloud Shell.

    • Click the Run Command buttonimage to open Cloud Shell and debug the command.

    • Click the Copy buttonimage to copy the CLI example to your clipboard. You can then paste it into a local shell tool or use it in automation scripts.

    Note

    • When you paste the CLI command into your on-premises shell for debugging, take note of the parameter formats. For more information about the parameter formats required by Alibaba Cloud CLI, see Parameter formats.

    • By default, OpenAPI Explorer adds the --region option to the generated CLI command. When you copy the command to your shell, Alibaba Cloud CLI ignores the region information in the default identity credential configurations and environment variable settings, and preferentially runs the command in the specified region. You can delete or retain the option based on your business requirements.

Step 4: Call the API operations of ACK

Example 1: Query the supported API operations of ACK by using Alibaba Cloud CLI

The following example shows how to use the --help option to query the supported API operations of ACK. For more information, see List of operations by function.

  1. Run the following command: 

    aliyun cs --help

  2. Expected output: 

    Product: CS (Container Service for Kubernetes )
Version: 2015-12-15
Available Api List:
  AttachInstances              : POST /clusters/[ClusterId]/attach
  AttachInstancesToNodePool    : POST /clusters/[ClusterId]/nodepools/[NodepoolId]/attach
  CancelClusterUpgrade         : POST /api/v2/clusters/[ClusterId]/upgrade/cancel
  CancelComponentUpgrade       : POST /clusters/[clusterId]/components/[componentId]/cancel
  CancelOperationPlan          : DELETE /operation/plans/[plan_id]
  CancelTask                   : POST /tasks/[task_id]/cancel
  CancelWorkflow               : PUT /gs/workflow/[workflowName]
  CheckControlPlaneLogEnable   : GET /clusters/[ClusterId]/controlplanelog
  CheckServiceRole             : POST /ram/check-service-role
  CleanClusterUserPermissions  : DELETE /cluster/[ClusterId]/user/[Uid]/permissions

Example 2: Query cluster details

The following example shows how to use Alibaba Cloud CLI to call the DescribeClusterDetail operation of ACK to query the details of an ACK cluster based on the cluster ID. For more information, see DescribeClusterDetail.

  1. Run the following command: 

    aliyun cs GET /clusters/cdde1f21ae22e483ebcb068a6eb7f****

  2. Expected output: 

    {
  "cluster_id": "c82e6987e2961451182edacd74faf****",
  "cluster_type": "Kubernetes",
  "created": "2019-11-25T15:50:20+08:00",
  "init_version": "1.16.6-aliyun.1",
  "current_version": "1.16.6-aliyun.1",
  "next_version": "1.18.8-aliyun.1",
  "deletion_protection": true,
  "docker_version": "19.03.5",
  "external_loadbalancer_id": "lb-2zehc05z3b8dwiifh****",
  "meta_data": "\\\"Addons\\\":***",
  "name": "cluster-demo",
  "network_mode": "vpc",
  "region_id": "cn-beijing",
  "resource_group_id": "rg-acfmyvw3wjm****",
  "security_group_id": "sg-25yq****",
  "container_cidr": "172.20.0.0/16",
  "service_cidr": "172.21.0.0/20",
  "proxy_mode": "ipvs",
  "timezone": "Asia/Shanghai",
  "node_cidr_mask": "26",
  "ip_stack": "ipv4",
  "cluster_domain": "cluster.local",
  "size": 5,
  "state": "running",
  "tags": [
    {
      "key": "env",
      "value": "prod"
    }
  ],
  "updated": "2020-01-13T23:01:03+08:00",
  "vpc_id": "vpc-2zecuu62b9zw7a7qn****",
  "vswitch_id": "vsw-2zete8s4qocqg0mf6****,vsw-2zete8s4qocqg0mf6****",
  "vswitch_ids": [
    "vsw-2zete8s4qocqg0mf6****"
  ],
  "subnet_cidr": "172.20.0.0/16",
  "zone_id": "cn-beijing-a",
  "master_url": "{\\\"intranet_api_server_endpoint\\\":\\\"https://192.168.0.251:6443\\\"***}",
  "private_zone": false,
  "profile": "Default",
  "cluster_spec": "ack.pro.small",
  "worker_ram_role_name": "KubernetesWorkerRole-ec87d15b-edca-4302-933f-c8a16bf0****",
  "maintenance_window": {
    "enable": false,
    "maintenance_time": "2020-10-15T12:31:00.000+08:00",
    "duration": "3h",
    "weekly_period": "Monday,Thursday",
    "recurrence": "FREQ=WEEKLY;INTERVAL=4;BYDAY=MO,TU"
  },
  "parameters": {
    "key": "WorkerImageId"
  },
  "operation_policy": {
    "cluster_auto_upgrade": {
      "enabled": true,
      "channel": "patch"
    }
  }
}
    Note

    • If an error is returned after you call an API operation of ACK, check whether the input parameters and values are valid based on the error code.

    • Alternatively, record the returned RequestID and error information, and use OpenAPI Diagnostic to troubleshoot the issue.

References

Previous：CLI ReferenceNext：View all clusters