命令行工具

概览

CLI是供管理员调用所有ZStack Cloud API的命令行工具。本手册中所有API示例都将用CLI来展示。

ZStack Cloud基于SOA（Service Oriented Architecture，面向服务架构）而设计，所有的操作本质上都是消息。例如，启动云主机的StartVmInstanceCLI命令，可以映射到APIStartVmInstanceMsg的API消息。

ZStack Cloud包含了内置的HTTP服务，将所有API消息封装于HTTP POST请求中，CLI是基于内置的HTTP服务调用API请求进行相应的业务处理。

用法

连接到ZStack Cloud管理节点

默认情况下安装ZStack Cloud管理节点后，CLI会被同步安装，可在shell终端通过命令zstack-cli直接启动：

[root@localhost ~]# zstack-cli

  zstack command line tool
  Type "help" for more information
  Type Tab key for auto-completion
  Type "quit" or "exit" or Ctrl-d to exit

没有指定任何参数时，CLI默认会连接localhost的8080端口；如果要连接远程的ZStack Cloud管理节点, 可以通过选项-H和-p来分别指定IP和端口号。

[root@localhost ~]# zstack-cli --help
Usage: -c [options]

Options:
  -h, --help            show this help message and exit
  -H HOST, --host=HOST  [Optional] IP address or DNS name of a zstack
                        management node. Default value: localhost
  -p PORT, --port=PORT  [Optional] Port that the zstack management node is
                        listening on. Default value: 8080
  -d DEPLOY_CONFIG_FILE, --deploy=DEPLOY_CONFIG_FILE
                        [Optional] deploy a cloud from a XML file.
  -t DEPLOY_CONFIG_TEMPLATE_FILE, --template=DEPLOY_CONFIG_TEMPLATE_FILE
                        [Optional] variable template file for XML file
                        specified in option '-d'
  -D ZSTACK_CONFIG_DUMP_FILE, --dump=ZSTACK_CONFIG_DUMP_FILE
                        [Optional] dump a cloud to a XML file
  -P ADMIN_PASSWORD, --password=ADMIN_PASSWORD
                        [Optional] admin account password for dumping and
                        recovering cloud environment. It can only be used when
                        set -D or -d option. Default is 'password'.
  -s, --no-secure       [Optional] if setting -s, will save password
                        information in command history.
[root@localhost ~]# zstack-cli -H 172.20.16.35

  zstack command line tool
  Type "help" for more information
  Type Tab key for auto-completion
  Type "quit" or "exit" or Ctrl-d to exit


admin >>>

如果有多个管理节点, 可以通过CLI连接到任一个管理节点。

模式（Modes）

命令模式

CLI可从shell接受参数工作在命令模式。在命令模式下，CLI只运行一次，然后输出结果到shell，例如：

[root@localhost ~]# zstack-cli -H 172.20.16.35 QueryZone name=Zone-1
{
    "inventories": [
        {
            "createDate": "Nov 17, 2017 8:27:47 PM",
            "lastOpDate": "Nov 17, 2017 8:27:47 PM",
            "name": "Zone-1",
            "state": "Enabled",
            "type": "zstack",
            "uuid": "c3a228078e8c4f81ba7da0b16fb8d77f"
        }
    ],
    "success": true
}

交互模式

CLI也可工作在交互模式。在交互模式下，CLI会维护一个会话（session）来不断地执行命令，例如：

...

admin >>>query
BatchQuery                                        PrometheusQueryLabelValues
PrometheusQueryMetadata                           PrometheusQueryPassThrough
PrometheusQueryVmMonitoringData                   QueryAccessKey
QueryAccount                                      QueryAccountResourceRef
QueryAffinityGroup                                QueryAlarm
QueryAlert                                        QueryAliyunDiskFromLocal
...
QueryVmCdRom                                      QueryVmInstance
QueryVmNic                                        QueryVmNicInSecurityGroup
QueryVniRange                                     QueryVolume
QueryVolumeBackup                                 QueryVolumeSnapshot
QueryVolumeSnapshotTree                           QueryVpcIkeConfigFromLocal
QueryVpcIpSecConfigFromLocal                      QueryVpcRouter
QueryVpcUserVpnGatewayFromLocal                   QueryVpcVpnConnectionFromLocal
QueryVpcVpnGatewayFromLocal                       QueryVtep
QueryWebhook                                      QueryZone
ZQLQuery

admin >>>QueryZone

手动执行时通常更适合使用交互模式，而脚本集成时通常更适合使用命令模式。

登录（Login）

ZStack Cloud的认证和访问管理系统（IAM，Identity and Access Management）支持三种登录方式：账户登录、用户登录、AD/LDAP登录。

账户分为admin管理员账户和普通账户。admin管理员账户使用默认密码password。

在执行任何命令之前, 需运行登录命令LogInByAccount取得一个会话令牌（session token），这个令牌会被CLI自动保存到~/.zstack/cli/session，需要单独维护。

admin >>>LogInByAccount accountName=admin password=password

登出（LogOut）

一旦工作完成，可以使用LogOut命令结束当前会话：

admin >>>LogOut

LogOut命令可以接受参数sessionUuid, 可选参数，CLI默认会自动读取已保存的session。

执行API命令

每一个API都可拥有多个参数，可通过命令模式或交互模式来执行：

命令模式：

[root@localhost ~]# zstack-cli StartVmInstance uuid=f1bd87fe2a40498db78ee596766f57b0

交互模式：

admin >>>StartVmInstance uuid=f1bd87fe2a40498db78ee596766f57b0

查看命令历史

可以使用more命令来查看命令历史，例如：

命令模式：
```
[root@localhost ~]# zstack-cli more
```
交互模式：
```
admin >>>more
```

结果格式和Linux *more*命令类似，可使用上下键来浏览或者搜索。


[NUM]   COMMAND
------------------------------------------------
[1]      LogInByAccount accountName=admin password=******
[2]      ['LogOut']
[3]      ['QueryVmInstance', 'state=Running']
[4]      ['QueryZone']
[5]      ['QueryVmInstance']
[6]      LogInByAccount accountName=admin password=******
[7]      [u'QueryVmInstance', u'count=True', u'state=Stopped']
[8]      [u'QueryVmInstance', u'count=True', u'state=Running']
[9]      [u'QueryVmInstance', u'count=True']
...

使用more后面跟上命令编号可以查看一个命令的详情：

命令模式：
```
[root@localhost ~]# zstack-cli more 6
```

交互模式：

admin >>>more 6

结果类似于：


Command:
        LogInByAccount accountName=admin password=******
Result:
{
    "inventory": {
        "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
        "createDate": "Dec 28, 2017 5:13:59 PM",
        "expiredDate": "Dec 28, 2017 7:13:59 PM",
        "userUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
        "uuid": "c0488a149e1244799317a84ab3378763"
    },
    "success": true
}
(END)

导出命令结果

可通过save命令导出命令历史，可以一次保存一个历史也可以一次保存多个历史：

一次保存一个历史

命令模式：

[root@localhost ~]# zstack-cli save 1
Saved command: 1 result to file: /root/LogInByAccount-1.json

交互模式：

admin >>>save 1
Saved command: 1 result to file: /root/LogInByAccount-1.json

一次保存多个历史

命令模式：

[root@localhost ~]# zstack-cli save 1,2,3
[u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
Saved command: 1 result to file: /usr/local/CreateDataVolume-1.json
[u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
Saved command: 2 result to file: /usr/local/CreateDataVolume-2.json
[u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
Saved command: 3 result to file: /usr/local/CreateDataVolume-3.json

交互模式：

admin >>>save 1,2,3
[u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
Saved command: 1 result to file: /usr/local/CreateDataVolume-1.json
[u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
Saved command: 2 result to file: /usr/local/CreateDataVolume-2.json
[u'CreateDataVolume', u'primaryStorageUuid=4db283cfa9ac4b0a9994aab52bff4069', u'diskOfferingUuid=7c3ba7609e2e44d2a429e93e2944871e', u'name=volume', u'systemTags=localStorage::hostUuid::37bfae93611541039aec7ae87a204e5a']
Saved command: 3 result to file: /usr/local/CreateDataVolume-3.json

默认情况下结果被保存到当前目录下，也可以通过额外提供一个路径来指定目的文件夹：

save 1 /tmp