qcloudcli 1.9.20

Universal Command Line Environment for qcloud

Tencent Cloud (aka QCloud) Command Line Interface qcloudcli is an open source tool built on top of the Tencent Cloud API that provides commands for interacting with Tencent Cloud services.

It works on Python versions:

• 2.7.x and greater

• 3.6.x and greater

Install

The recommended way to install qcloudcli is to use pip:

$ pip install --user qcloudcli

--user option will install qcloudcli to current user path instead of system path, for Linux system, it might be ~/.local, which means it doesn’t require sudo priviledge.

Attention!

If you are in a virtualenv environment, the --user option should be removed.

Get the version of qcloudcli:

$ qcloudcli --version

to upgrade:

$ pip install --user --upgrade qcloudcli

to remove:

$ pip uninstall --yes qcloudcli

Command Completion

On Unix-like systems, the qcloudcli includes a command-completion feature that enables you to use the TAB key to complete a partially typed command. This feature is not automatically installed, so you need to configure it manually.

$ complete -C qcloud_completer qcloudcli

Add it to your ~/.bashrc to enable it by default.

Usage Guide

Configuration

qcloudcli needs account information to interact with Tencent Cloud Services. Log in Tencent Cloud Console, shift to API Credential Management page to view your credentials, if the list is empty, you will need to create a new one. SecretId is used like your account name, SecretKey is used like your password, so keep in mind that never leak your SecretKey to others.

Attention!

You might not be able to have such page in international site or translations in English version for now.

Run qcloudcli congifure to enter interactive mode and provide information like this:

$ qcloudcli configure
Qcloud API SecretId [None]: foo
Qcloud API SecretKey [None]: bar
Region Id(gz,hk,ca,sh,shjr,bj,sg) [None]: gz
Output Format(json,table,text) [None]: json

These information will be stored in files under your home root path, for example, in Linux system, it will be ~/.qcloudcli/configure and ~/.qcloudcli/credentials.

The content of ~/.qcloudcli/configure in last example is:

[default]
output = json
region = gz

The content of ~/.qcloudcli/credentials in last example is:

[default]
qcloud_secretkey = bar
qcloud_secretid = for

Attention!

These information will be stored as plain text, it relies on your correct access control of your private home directory.

In Linux system, the default priviledge is:

$ ls -l ~/.qcloudcli/
total 8
4 -rw-rw-r-- 1 john john 36 Nov 29 23:35 configure
4 -rw------- 1 john john 55 Nov 29 23:35 credentials

Attention!

Currently, these two configure files will not be removed when you uninstall qcloudcli, you will need to manually remove them.

Use Help

To get available module list, including configure command, run:

$ qcloudcli help

To get action list of specific module, for example, cvm (Cloud Virtual Machine), run:

$ qcloudcli cvm help

To get parameter list of specific action, for example, DescribeInstances, run:

$ qcloudcli cvm DescribeInstances help

Specify Complex Object Paramters

To specify base type parameters, like string and int, you can directly use it. For example, to get instance (virtual machine) list, use default API version, limit the return item to 10, run:

$ qcloudcli cvm DescribeInstances --limit 10

For complex object parameters, like array and dictionary, you have to use json format string.

For example, to get instance list, use default API version, only query instances which id are qcvmf4b542ad7b4cd49f2db57a733368d5b1 and qcvmaf636dd06a816765b4f2c51595f2d84d, run:

$ qcloudcli cvm DescribeInstances --instanceIds '["qcvmf4b542ad7b4cd49f2db57a733368d5b1", "qcvmaf636dd06a816765b4f2c51595f2d84d"]'

For example, to get instance list, use API version 2017-03-12, with Filters parameter, only return instances in ap-guangzhou-2 zone, run:

$ qcloudcli cvm DescribeInstances --Filters '[{"Name":"zone","Values":["ap-guangzhou-2"]}]'

For example, to create new instances, use API version 2017-03-12, a complex example might be:

$ qcloudcli cvm RunInstances --Placement '{"Zone":"ap-beijing-3"}' --InstanceChargeType PREPAID --InstanceChargePrepaid '{"Period":1,"RenewFlag":"NOTIFY_AND_AUTO_RENEW"}' --ImageId img-dkwyg6sr --InstanceType S2.SMALL1 --SystemDisk '{"DiskType":"CLOUD_BASIC","DiskSize":50}' --InternetAccessible '{"InternetChargeType":"TRAFFIC_POSTPAID_BY_HOUR","InternetMaxBandwidthOut":2,"PublicIpAssigned":"TRUE"}' --InstanceName prod-jumpserver-01 --EnhancedService '{"SecurityService":{"Enabled":"TRUE"},"MonitorService":{"Enabled":"TRUE"}}' --InstanceCount 1 --VirtualPrivateCloud '{"VpcId":"vpc-njkwg482","SubnetId":"subnet-6rs8ienn"}'

NOTE: Here Placement has specify availability zone to be ap-beijing-3, so the region value in ~/.qcloudcli/configure must be bj, or you can specify global parameter --RegionId ap-beijing to override configured value.

Filter Data

qcloudcli provides --filter option which bases on jmespath to filter returned data, it is pretty useful when you want to get specific data from a bunch of items. However, you need to know the exact structure of returned json format.

For example, to get security groups and only return security gourp id, run:

$ qcloudcli dfw DescribeSecurityGroups --filter data[*].sgId
[
    "sg-icy671l9",
    "sg-o9rfv42p",
    "sg-pknfyaar",
    "sg-2rjokpt7",
    "sg-4ehjaoh3"
]

* means get all elements.

For example, using CVM API version 2017-03-12, to get security groups id of a specific instance ins-od1laqxs, run:

$ qcloudcli cvm DescribeInstances --InstanceIds '["ins-od1laqxs"]' --filter Response.InstanceSet[0].SecurityGroupIds
[
    "sg-4ehjaoh3"
]

The index 0 means get the first instance.

Specify API Version

NOTE: New in version 1.9.0

Some services of Tencent Cloud have multiple API versions, for example, CVM has a API version 2017-03-12, to use it, open ~/.qcloudcli/configure and add the following content in profile section:

api_versions =
    cvm = 2017-03-12

If the specified version doesn’t exist, you will get an error when you run related commands. If the service only has one version, then you don’t need to add such configuration, please remove it. If the service has multiple versions, and there is no such configuration, then the default one will be used.

Use HTTPS Proxy

NOTE: New in version 1.8.9

If you are in an environment behinds a proxy, and *.api.qcloud.com is not in the proxy white list, then you will need to configure HTTPS proxy to get qcloudcli work.

Currently, only verified in Linux and Windows system, with proxy doesn’t require user name and password.

In Linux system, to set your temporary global proxy, run:

$ export https_proxy=YourProxyRealHost:YourProxyRealPort

Please note that replace YourProxyRealHost and YourProxyRealPort with your real proxy information. You can add it to your ~/.bashrc to active it by default.

In Windows system, to set your temporary global proxy, run:

> set https_proxy=YourProxyRealHost:YourProxyRealPort

You can add it to your system environment variables to active it by default.