ZStack用户手册¶

介绍¶

ZStack是一个开源的基础架构即服务的软件，用于管理数据中心中的计算、网络、存储等资源。目前ZStack的核心代码主要用Java和Python编写。

本文档主要介绍ZStack的各个功能模块以及相关的API手册。如果你还没有安装ZStack，可以参考`ZStack官网<http://zstack.org/cn>` 来安装和使用ZStack。

用户手册里会详细介绍ZStack的各个功能模块。每个功能是一章，每一章还会划分为以下几个部分：

简介: 简单介绍一下该功能的背景。
清单（Inventory）: 介绍该功能各种资源(例如主机区域（zone）, 虚拟机（virtual machine）)的清单，也就是在使用各种Query API得到的返回结果。我们会使用表格来展示清单，表格的左边是资源的名字，右侧会介绍该资源的用途。
操作: 介绍和该功能有关的API操作。我们还将结合ZStack的命令行工具`zstack-cli`来介绍每个API的使用方法。
全局配置（Global Configurations）: 介绍和该功能有关的全局配置参数。
系统标签（System Tags）: 介绍和该功能有关的系统标签。

我们推荐用户从:ref:Introduction`开始，然后至少阅读:ref:`Resource Model <resource>, Command Line Tool, 和:ref:Query <query> 。这些将会对日常使用ZStack非常关键。对于其他章节，你可以按需阅读。例如，当你需要创建虚拟机的时候，再来阅读 Virtual Machine 。

目录¶

前言 ¶

前言
- 概览

概览 ¶

根据云的规模，ZStack可以部署在一台独立的Linux机器上，也可以是运行多个ZStack管理节点的Linux服务器集群.

单一管理节点部署 ¶

在最简单的情况下，所有的ZStack软件组件和第三方依赖都安装在一个单独的Linux服务器上。一个典型的安装中包含五个部分:

RabbitMQ 消息服务器: ZStack服务用作通信的核心消息总线.
MySQL数据库: ZStack通过数据库存储云资源的后台数据.
Ansible: ZStack使用配置管理工具进行远程部署和代理程序升级.
ZStack管理节点: 包含所有ZStack服务的主进程.
ZStack用户界面服务: 提供给最终用户界面的网路服务器.

除此以外，一些需要在运行时部署到本地或远程的Python代理程序（Agent）被打包成ZStack管理节点的WAR文件，并通过Ansible部署.

因为ZStack基于异步架构，通常一个独立的管理节点可以处理数万条并发的API访问请求，这可以满足同时管理数万台服务器和数十万台虚拟机（云主机，在后面的章节讲直接简称为VM）的需求。然而，需要高可用性或者需要扩展至超大规模的云时，就需要部署多个管理节点.

多管理节点的部署 ¶

在多管理节点部署中，RabbitMQ服务和MySQL数据库服务都被独立出来放到独立的服务器上；ZStack管理节点和Ansible被安装在所有的Linux管理服务器上；多个管理节点分享同一个RabbitMQ消息服务器和MySQL数据库。ZStack用户界面服务,也通过RabbitMQ发送API请求至管理节点，它被部署在负载均衡后面，而后者会分发用户的访问请求.

对于RabbitMQ和MySQL集群而言, 管理员可以部署两个RabbitMQ服务器和一个额外的MySQL从数据库服务器.

ZStack云架构 ¶

IaaS软件通常使用诸如’zone’, ‘cluster’来描述数据中心中设施的构成，ZStack也采取同样的方式. 为了便于理解和减少误解，ZStack尽可能的使用已有的IaaS和数据中心的术语.

下图示例说明了ZStack如何定义数据中心的设施.

一个数据中心, 在ZStack的定义中按以下方式组织:

区域（Zone）:

一个区域是一些资源的逻辑组合，例如集群（clusters)，L2网络，主存储（primary storage）. ZStack使用区域来定义资源的访问边界. 例如, 一个区域B中的集群不能访问在区域A中的一个主存储. 实践中，区域也可以用来划分域以达到容错的目的, 例如 Amazon EC2中的可用性区域（availability zones）.
集群（Cluster）:

一个集群是一组物理主机的逻辑集合. 一个集群中的主机必须有相同的操作系统(hypervisor)和网络配置. 集群在其他一些IaaS软件中也被称为主机聚合或主机池.
主机（Host）:

一个主机是一个安装了操作系统（或者hypervisor）的物理服务器，其上面运行虚拟机.
L2网络:

一个L2网络是二层广播域的一个抽象. 任何提供二层广播域的技术都可以是ZStack中的L2网络。例如，VLAN, VxLan, 或者基于三层网络创建二层叠加（overlay）网络的SDN技术.
主存储（Primary Storage）:

主存储为虚拟机运行时会访问的云盘（volume）提供磁盘存储. 主存储可以是类似NFS的文件系统也可以是类似ISCSI的块存储。
备份存储（Backup Storage）:

备份存储为存储映像（images）和云盘快照（volume snapshots）提供磁盘存储，两者都可以用于创建云盘. 备份存储上的文件并不被虚拟机直接访问; 在被使用之前，他们需要被下载到主存储。备份存储可以基于文件系统或者对象存储（object storage）.

ZStack使用一种称为挂载策略（attaching strategy）来描述资源之间的关系, 例如, 一个集群可以被挂载于多个主存储和L2网络，反之亦然. 相关章节(主存储, L2网络)有更详细的介绍.

一个数据中心可以有一个或者多个区域。多个区域的图如下:

除以上描述数据中心设施的术语外，还有其他一些术语诸如虚拟机（VM），实例方案（instance offering）, 云盘规格（disk offering）, 他们描述虚拟资源；在相关章节中有更详细的描述.

资源模型 ¶

资源模型

ZStack本质上是一个云资源的配置管理系统. 资源可以是物理资源（例如，主机，网络，存储）也可以是虚拟资源（例如，虚拟机）. 在当前版本中, 所有的资源如图所示:

资源之间的关系 ¶

资源之间有四种关系:

父子关系（Parent - Child）:

一个资源可以是另一个资源的父亲或孩子. 例如, 一个集群是一个区域的子资源，而一个区域是一个集群的父资源.
祖先后裔关系（Ancestor - Descendant）:

一个资源可以是另一个资源的直系祖先（lineal ancestor）或者直系后裔（lineal descendant）. 例如, 一个区域是虚拟机的祖先资源; 一个虚拟机是一个区域的直系后裔资源.
兄弟关系（Sibling）:

拥有同样父资源的资源为兄弟关系. 例如, 集群, 主机，主存储, L2网络是兄弟资源因为他们都是区域的子资源.
朋友关系（Friend）:

一些资源资源之间没有以上三种关系，但是这些资源在某些情境下需要分工合作，这时他们是朋友关系. 例如, 主存储和备份存储是朋友关系, 因为在创建虚拟机时主存储需要从备份存储下载镜像.

没有关系的资源是无关资源; 例如, 安全组和集群是无关资源.

资源属性 ¶

绝大多数资源都有四个公共属性:

通用唯一识别码（UUID）:

ZStack使用通用唯一识别码`UUIDv4 (Universally Unique Identifier) <http://en.wikipedia.org/wiki/Universally_unique_identifier>`_ 来唯一的标识一个资源. 不同于普通的UUID，ZStack去掉了字符串中的连字符。例如, 80b5ca2c76154da298a1a248b975372a.
名字（Name）:

名字是最长255个字符组成的可读字符串. 由于ZStack不使用名字作为资源标识符，所以名字可以重复. 名字可以包含任何可见的ASCII字符（例如，%，#，^，空格）; 然而, 在名字中放置一些字符可能导致查询API很难使用 . 最佳做法是只用字母，数字，连字符（’-‘）, 和下划线(‘_’)来命名资源.
描述（Description）:

描述是最长2048个可读字符组成的字符串. 同样ZStack没有对描述可以使用的字符集施加任何限制.
创建日期（Created Date）:

一个不变的日期标明资源创建时间.
上次操作时间（Last Operation Date）:

资源上次被更新的时间. 每次资源被更新，这个时间都会被更新; 更新操作可以是用户操作，也可以是ZStack内部操作.

每个资源都可能有他特有的属性, 例如, 虚拟机可能有属性’hostUuid’. ZStack在API中使用JSON, 因此资源的属性在大多数API响应中通常被包括在JSON映射中。在ZStack中，JSON映射被称为清单（inventory). 在随后的章节中, 档提到资源清单时, 通常是指包含资源属性的JSON映射. 下面是一个虚拟机清单实例:

{
  "inventory": {
    "uuid": "94d991c631674b16be65bfdf28b9e84a",
    "name": "TestVm",
    "description": "Test",
    "zoneUuid": "acadddc85a604db4b1b7358605cd6015",
    "clusterUuid": "f6cd5db05a0d49d8b12721e0bf721b4c",
    "imageUuid": "061141410a0449b6919b50e90d68b7cd",
    "hostUuid": "908131845d284d7f821a74362fff3d19",
    "lastHostUuid": "908131845d284d7f821a74362fff3d19",
    "instanceOfferingUuid": "91cb47f1416748afa7e0d34f4d0731ef",
    "rootVolumeUuid": "19aa7ec504a247d89b511b322ffa483c",
    "type": "UserVm",
    "hypervisorType": "KVM",
    "createDate": "Jun 1, 2015 6:11:47 PM",
    "lastOpDate": "Jun 1, 2015 6:11:47 PM",
    "state": "Running",
    "vmNics": [
      {
        "uuid": "6b58e6b2ba174ef4bce8a549de9560e8",
        "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a",
        "usedIpUuid": "4ecc80a2d1d93d48b32680827542ddbb",
        "l3NetworkUuid": "55f85b8fa9a647f1be251787c66550ee",
        "ip": "10.12.140.148",
        "mac": "fa:f0:08:8c:20:00",
        "netmask": "255.0.0.0",
        "gateway": "10.10.2.1",
        "deviceId": 0,
        "createDate": "Jun 1, 2015 6:11:47 PM",
        "lastOpDate": "Jun 1, 2015 6:11:47 PM"
      },
      {
        "uuid": "889cfcab8c08409296c649611a4df50c",
        "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a",
        "usedIpUuid": "8877537e11783ee0bfe8af0fcf7a6388",
        "l3NetworkUuid": "c6134efd3af94db7b2928ddc5deba540",
        "ip": "10.4.224.72",
        "mac": "fa:e3:87:b1:71:01",
        "netmask": "255.0.0.0",
        "gateway": "10.0.0.1",
        "deviceId": 1,
        "createDate": "Jun 1, 2015 6:11:47 PM",
        "lastOpDate": "Jun 1, 2015 6:11:47 PM"
      },
      {
        "uuid": "cba0da7a12d44b2e878dd5803d078337",
        "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a",
        "usedIpUuid": "f90d01a098303956823ced02438ae3ab",
        "l3NetworkUuid": "c7e9e14f2af742c29c3e25d58f16a45f",
        "ip": "10.29.42.155",
        "mac": "fa:2d:31:08:da:02",
        "netmask": "255.0.0.0",
        "gateway": "10.20.3.1",
        "deviceId": 2,
        "createDate": "Jun 1, 2015 6:11:47 PM",
        "lastOpDate": "Jun 1, 2015 6:11:47 PM"
      }
    ],
    "allVolumes": [
      {
        "uuid": "19aa7ec504a247d89b511b322ffa483c",
        "name": "ROOT-for-TestVm",
        "description": "Root volume for VM[uuid:94d991c631674b16be65bfdf28b9e84a]",
        "primaryStorageUuid": "24931b95b45e41fb8e41a640302d4c00",
        "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a",
        "rootImageUuid": "061141410a0449b6919b50e90d68b7cd",
        "installUrl": "/opt/zstack/nfsprimarystorage/prim-24931b95b45e41fb8e41a640302d4c00/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-19aa7ec504a247d89b511b322ffa483c/19aa7ec504a247d89b511b322ffa483c.qcow2",
        "type": "Root",
        "format": "qcow2",
        "size": 3.221225472E10,
        "deviceId": 0,
        "state": "Enabled",
        "status": "Ready",
        "createDate": "Jun 1, 2015 6:11:47 PM",
        "lastOpDate": "Jun 1, 2015 6:11:47 PM"
      }
    ]
  }
}

资源操作（Resource Operations）¶

资源支持完全的（full）或部分的（partial) CRUD（创建, 读, 更新, 删除）操作.

创建（Create Resources）¶

每个资源都有自己的创建API. 所有的创建API都有一个公共参数 ‘resourceUuid’. 当’resourceUuid’不等于null, ZStack使用这个值作为被创建资源的UUID; 否则ZStack会自动生成一个UUID.

下面是一个创建集群的示例:

CreateCluster name=cluster1 description='awesome cluster' hypervisorType=KVM zoneUuid=061141410a0449b6919b50e90d68b7cd

或者:

CreateCluster resourceUuid=f31e38309e2047beac588e111fa2051f name=cluster1 description='awesome cluster' hypervisorType=KVM zoneUuid=061141410a0449b6919b50e90d68b7cd

读取资源（Read Resources）¶

每个资源都有自己的查询API返回资源清单. 详细信息, 请查看 Query. 这里是一个查询虚拟机的示例:

QueryVmInstance allVolumes.type=Data allVolumes.size>1099511627776

示例中: 找出所有拥有一个或多个大于1099511627776字节(1T)数据云盘的虚拟机

删除资源（Delete Resources）¶

资源可以被删除. ZStack中资源被删除的哲学是: 每个资源都应该可以被删除; 删除资源应该总是可以成功的除非用户允许某种失败; 例如, 一个插件允许用户在虚拟机上设置’none-deletable’标签, 当这个虚拟机被删除时一个错误就会被抛出.

在IaaS中删除资源通常不是那么容易, 尤其是当资源有很多后裔资源; 一些软件方案通过不灵活的代码来删除所有后裔资源; 一些软件方案在删除还有后裔资源在线的资源时通过简单的抛出错误来处理.

ZStack使用一种优雅的方式来处理资源删除. 当一个资源被删除时, 一个被称为瀑布框架的组件`Cascade Framework <http://zstack.org/blog/cascade.html>`_ 将会计算被删资源和云中其他资源的关系, 必要时合适的操作会被扩散至相关的资源. 例如, 删除一个区域时, 删除操作会被散布至所有的这个区域的后裔资源，也就是说所有的这个区域中的虚拟机，主机，集群，L2网络都在区域被删除前会被删除 ; 同时挂载到这个区域的备份存储也会被卸载. 使用这个瀑布框架, 在ZStack中删除资源变得简单和可靠.

每个资源都有自己的删除API. 所有的删除API都有一个公共参数*deleteMode*，这个参数有两个选项 Permissive 和 Enforcing. 当*deleteMode*设置成Permissive时, 如果删除过程中发生错误或者删除不被允许ZStack会停止删除操作; 在这种情况下, 包含失败原因的错误代码会被返回.当*deleteMode*被设置成Enforcing, ZStack会忽略所有错误和权限而直接删除资源; 在这种情况下, 删除操作总是会成功.

下面是一个删除虚拟机的示例:

DestroyVmInstance uuid=94d991c631674b16be65bfdf28b9e84a

命令行工具 ¶

命令行工具
- 概览
- 用法

概览 ¶

zstack-cli是供用户调用所有ZStack API的命令行工具. 本手册中所有API示例都将用zstack-cli来展示.

由于ZStack是基于面向服务架构（SOA，Service Oriented Architecture）, 所有的ZStack本质上都是消息; 例如, 你将会在虚拟机相关的章节中看到一个叫做*StartVmInstance*的CLI命令, 它实际上映射到这个API消息: APIStartVmInstanceMsg; 然而，相对于消息大家对HTTP调用更加熟悉，因此ZStack包含了一个内置HTTP服务将所有API消息封装于HTTP POST请求中. zstack-cli就是基于这个内置HTTP服务调用API的.

用法 ¶

链接到ZStack管理节点 ¶

默认情况下安装ZStack管理节点后zstack-cli就会被安装. 你可以在shell终端简单的通过命令’zstack-cli’来启动它:

在没有参数指定的情况下, zstack-cli会连接到localhost的8080端口; 如果要连接远程的ZStack管理节点, 你可以通过选项’-s’和’-p’来分别指定IP和端口号:

如果你有多个管理节点, 你可以通过zstack-cli连接到任一个管理节点.

模式（Modes）¶

zstack-cli可以从shell接受参数工作在命令模式, 在这种模式下，他只运行一次, 然后从shell输出结果, 例如:

ztack-cli也可以工作在交互模式，在这种模式下，他会维护一个会话(session)来不断的执行命令, 例如:

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

登陆（LogIn）¶

在当前ZStack版本(0.6), 认证和访问管理系统（IAM，Identity and Access Management)还没就绪; 唯一的账户是’admin’，它使用默认密码(‘password’). 在执行任何命令之前, 你需要运行登陆命令’LogInByAccount’取得一个会话令牌（session token），这个令牌会被zstack-cli自动保存到~/.zstack/cli/session，所以你需要单独维护它:

>>> LogInByAccount accountName=admin password=password

登出（LogOut）¶

一旦你的工作已完成, 你可以使用’LogOut’命令来结束当前会话:

>>> LogOut

LogOut命令接受一个参数’sessionUuid’, 但你并不需要指定它，因为zstack-cli会自动从它所保存的位置获取.

执行API命令 ¶

每一个API都是一个拥有多个参数的命令, 你可以通过命令模式或者交互模式来执行他们:

>>> StartVmInstance uuid=11be8ac6adad44c68ae02493cba29846

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

查看命令历史 ¶

你可以使用’more’命令来查看命令历史, 例如:

>>> more

或者:

[root@localhost ~]# zstack-cli more

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

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

>>> more 6

或者:

[root@localhost ~]# zstack-cli more 6

结果类似于:

导出命令结果 ¶

你可以通过’save’命令导出命令历史, 可以一次保存一个历史也可以一次保存多个历史:

>>> save 1
Saved command: 1 result to file: /home/root/QueryZone-1.json

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

或者:

>>>save 1,2,3
Saved command: 1 result to file: /home/root/QueryZone-1.json
Saved command: 2 result to file: /home/root/CreateZone-2.json
Saved command: 3 result to file: /home/root/LogInByAccount-3.json

[root@localhost ~]# zstack-cli -s 192.168.0.212 save 1,2,3
Saved command: 1 result to file: /home/root/QueryZone-1.json
Saved command: 2 result to file: /home/root/CreateZone-2.json
Saved command: 3 result to file: /home/root/LogInByAccount-3.json

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

>>> save 1 /tmp
save history command 1 result to /tmp/COMMAND-1.json

查询 ¶

查询

概览 ¶

对于运营大规模云的用户来说，最大的挑战是快速精准的找到所需要的资源. 例如, 要从100000个虚拟机中找到拥有EIP（17.12.53.8)的虚拟机. ZStack提供了丰富全面的API可以用来查询所有资源的每一个域。请参看`查询API <http://zstack.org/blog/query.html>`来了解设计架构.

架构（Arhitect）¶

每个ZStack资源都将他的属性（properties）组织成一个JSON格式的清单（inventory）; 例如, 一个区域（zone）清单:

{
  "uuid": "b729da71b1c7412781d5de22229d5e17",
  "name": "TestZone",
  "description": "Test",
  "state": "Enabled",
  "type": "zstack",
  "createDate": "Jun 1, 2015 6:04:52 PM",
  "lastOpDate": "Jun 1, 2015 6:04:52 PM"
}

一个资源清单可以包含其他资源的清单; 例如, 一个L3网络清单包含IP范围（IP Range）清单:

{
    "createDate": "Nov 10, 2015 7:52:57 PM",
    "dns": [
        "8.8.8.8"
    ],
    "ipRanges": [
        {
            "createDate": "Nov 10, 2015 7:52:58 PM",
            "endIp": "192.168.0.190",
            "gateway": "192.168.0.1",
            "l3NetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
            "lastOpDate": "Nov 10, 2015 7:52:58 PM",
            "name": "ipr-mmbj",
            "netmask": "255.255.255.0",
            "startIp": "192.168.0.180",
            "uuid": "13238c8e0591444e9160df4d3636be82"
        }
    ],
    "l2NetworkUuid": "33107835aee84c449ac04c9622892dec",
    "lastOpDate": "Nov 10, 2015 7:52:57 PM",
    "name": "L3-SYSTEM-PUBLIC",
    "networkServices": [],
    "state": "Enabled",
    "system": true,
    "type": "L3BasicNetwork",
    "uuid": "95dede673ddf41119cbd04bcb5d73660",
    "zoneUuid": "3a3ed8916c5c4d93ae46f8363f080284"
}

清单中的域（field）分为两类: 原生域（primitive field) and 嵌套域（nested field）; 原生域是由一个基本类型（primitive type）构成的域，如数字（number）, 字符串（string）, 布尔（boolean）或者日期（date）; 在上述例子中, uuid, name, system都是原生域; 一个嵌套域通常是由代表其他资源数据类型组合而成的; 在上述例子中, ipRanges就是一个嵌套域.

除非特别声明，所有清单的所有域都是可以被查询的; 对于一个清单, 通常都有对应的查询API, 例如, QueryZone, QueryHost, QueryVmInstance; 查询API通常返回一个清单列表, 或者在没有匹配结果时返回一个空列表. 一个查询的结果类似于:

{
  "inventories": [
      {
          "availableCpuCapacity": 13504,
          "availableMemoryCapacity": 16824565760,
          "clusterUuid": "b429625fe2704a3e94d698ccc0fae4fb",
          "createDate": "Nov 10, 2015 6:32:43 PM",
          "hypervisorType": "KVM",
          "lastOpDate": "Nov 10, 2015 6:32:43 PM",
          "managementIp": "192.168.0.212",
          "name": "U1404-192.168.0.212",
          "state": "Enabled",
          "status": "Connected",
          "totalCpuCapacity": 14400,
          "totalMemoryCapacity": 16828235776,
          "uuid": "d07066c4de02404a948772e131139eb4",
          "zoneUuid": "3a3ed8916c5c4d93ae46f8363f080284"
      }
  ],
  "success": true
}

查询API由一个查询条件(query conditions)的列表和一些辅助参数(helper parameters)构成:

查询API的参数（Parameters）¶

名字	描述	此参数可选	可选参数值	起始支持版本
conditions	:ref:`QueryCondition <QueryCondition>`组成的列表			0.6
limit	允许查询API返回清单的最大数量; 默认为1000	true		0.6
start	返回清单的起始编号; 默认为0	true		0.6
count	如果为true, 查询响应只返回清单数量; 默认为false		true false	0.6
replyWithCount	如果为true, 查询响应会同时返回清单及其数量; 默认为false		true false	0.6
sortBy	指定的域被作为排序依据. 这个域必须是原生域	true		0.6
sortDirection	如果’sortBy’不等于null, 这个域指定排序方向; 默认为’asc’		asc desc	0.6
fields	原生域组成的一个列表; 指定时, 查询返回的清单只会包含这些域.	true		0.6

查询条件（Query Condition）¶

查询API接受查询条件组成的列表，这些查询条件包含以下这些属性:

名字	描述	可选的参数值	起始支持版本
name	域名		0.6
op	比较操作符（comparison operator）	= != > >= < <= in not in is null is not null like not like	0.6
value	查询值		0.6

域名可以是原生域的名字, 也可以是嵌套域的子域的名字, 或者是扩展域（expanded field）的子域（sub-field）名字(请参看:ref:Join <query join>); ‘op’是SQL语言中的比较操作符.

操作符	CLI格式	描述
=	=	等于操作符; 字符串比较区分大小写
!=	!=	不等于操作符; 字符串比较区分大小写
>	>	大于操作符; 字符串比较请参看MySQL的规范
>=	>=	大于等于操作符; 字符串比较请参看MySQL的规范
<	<	小于; 字符串比较请参看MySQL的规范
<=	<=	小于或等于操作符; 字符串比较请参看MySQL的规范
in	?=	检查一个值是否在一个集合内
not in	!?=	检查值是否不在在一个集合内
is null	=null	NULL值测试
is not null	!=null	非NULL值测试
like	~=	简单模式匹配. 用%匹配任一数量的字符, 甚至零个字符; 用_匹配单个字符
not like	!~=	简单模式匹配的反式. 用%匹配任一数量的字符, 甚至零个字符; 用_匹配单个字符

查询条件之间的关系是逻辑与（logical AND）, 当前版本只支持这种关系. 例如:

QueryL3Network ipRanges.name=range1 name=L3Network1

用来查找名字为’L3Network1’的L3网络，并且这个网络有一个或多个IP范围的名字是’range1’.

CLI查询条件 ¶

有两种方式可以在CLI中使用查询条件, 一种是查询API的原始形式:

QueryHost conditions='[{"name":"name", "op":"=", "value":"KVM1"}]'

另一种是CLI格式:

QueryHost name=KVM1

我肯定你会更喜欢CLI格式因为它更直观更容易理解. CLI格式通常使用下面的格式来表示查询条件:

condition_name(no_space)CLI_comparison_operator(no_space)condition_value

在CLI中键入命令时, 你可以使用*Tab*来自动补全或者提示包括原生域，嵌套域以及扩展域在内的可以被查询的域:

联接（Join）扩展查询（expanded query）¶

在ZStack中联结（Join）被称为扩展查询（expanded query）; 这种查询允许用户通过其他和要查询的目标资源有关系的资源的域来查询; 在ZStack的术语中这些域被称为扩展域.

例如, 要查找一个虚拟机的L3网络，这个虚拟机的网卡（nic）拥有EIP的VIP为17.16.0.53:

QueryL3Network vmNic.eip.vipIp=17.16.0.53

在这里L3网络的清单没有称为’vmNic.eip.vipIp’的域; 然而, 它和虚拟机的网卡nic清单有关系，而后者又和EIP清单有关系; 因为我们可以构造一个跨越三个清单的扩展查询: L3网络清单, 虚拟机nic清单, 和EIP清单. 拥有了这个核武器, ZStack可以提供将近400万种查询条件以及无穷无尽的组合条件. 让我们看一个人为构造的复杂例子:

QueryVolumeSnapshot volume.vmInstance.vmNics.l3Network.l2Network.attachedClusterUuids?=13238c8e0591444e9160df4d3636be82

这个复杂的查询用来查找创建自虚拟机云盘的云盘镜像，这些虚拟机所在的L3网络的L2网络被挂载在一个uuid为13238c8e0591444e9160df4d3636be82的集群上. 虽然用户几乎不会用到这样的查询，但他展示了查询API的强大查询能力.

查询列表（Query List）¶

当一个域是列表的时候, 他可以包含类似int，long，string的基本类型或者嵌套清单. 查询列表并不特殊; 我们只是用这个章节来提醒你不要误认为只能用’in’(?=)和’not in’(!?=)来查询一个列表域; 实际上, 你可以使用所有的比较操作符; 例如:

QueryL3Network dns~=72.72.72.%

用来查找所有的拥有类似72.72.72.*的DNS的L3网络:

QueryL3Network ipRanges.startIp=192.168.0.10

用来查找所有的IP范围从192.168.0.10开始的L3网络.

查询标签（Query Tags）¶

在这一节中:ref:`tags <tag>`你会看到所有的资源都可以用用户标签（user tags)和系统标签（system tags)，他们都可以作为查询条件. ZStack使用两个特别的域: *__userTag__*和*__systemTag__*来做查询; 例如:

QueryVmInstance __userTag__?=web-tier-VMs

QueryHost __systemTag__?=os::distribution::Ubuntu managementIp=192.168.0.212

操作符>， >=， <， <= 只会返回用有满足条件的标签的资源; ‘is not null’会返回所有拥有标签的资源; ‘is null’会返回所有没有标签的资源; !=， ‘not in’， ‘not like’会返回拥有的标签不满足条件的以及没有标签的所有资源.

避免循环查询（Avoid Loop Query）¶

大多数ZStack资源拥有双向的扩展查询, 例如, 主机拥有扩展至集群的扩展查询而集群也拥有扩展至主机的扩展查询. 这使得从任意方向查询资源成为可能，但同时也可能导致查询循环. 例如:

QueryHost vmInstance.vmNics.eip.vmNic.vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2

就是一个循环查询, 它和下面的查询作用相同:

QueryHost vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2

循环查询的行为是未定义的; 你有可能得到也有可能得不到正确的结果. 所以请你避免使用循环查询.

有效的使用查询 ¶

查询API很强大，所以你可以通过不同的查询方式得到相同的结果. 例如, 要查找运行在UUID为e497e90ab1e64db099eea93f998d525b的主机上的虚拟机，你可以使用:

QueryVmInstance hostUuid=e497e90ab1e64db099eea93f998d525b

也可以使用:

QueryVmInstance host.uuid=e497e90ab1e64db099eea93f998d525b

第一种方式更高效, 因为它只是用了VM表的原生域进行查询; 第二种方式使用了联结VM表和host表的扩展查询. 当你的查询条件是UUID的时候，总是建议使用原生域而不是扩展域的子域进行查询.

示例 ¶

普通查询 ¶

QueryL3Network name=L3-SYSTEM-PUBLIC

查询计数（Query Count）¶

QueryL3Network name=L3-SYSTEM-PUBLIC count=true

带计数的普通查询 ¶

QueryL3Network name=L3-SYSTEM-PUBLIC replyWithCount=true

设置限制 ¶

QueryL3Network name=public-l3 limit=10

设置起始 ¶

QueryVmInstance name=centos6 start=10 limit=100

选择域 ¶

QueryL3Network fields=name,uuid l2NetworkUuid=33107835aee84c449ac04c9622892dec

排序（Sort）¶

QueryL3Network l2NetworkUuid=33107835aee84c449ac04c9622892dec sortBy=createDate sortDirection=desc

全局配置（Global Configurations）¶

全局配置（Global Configurations）

概览 ¶

管理员可以使用全局配置（global configurations）来对很多特性（feature）进行配置; 所有的全局配置都有一个默认值; 更新全局配置并不需要重启管理节点.

对于资源相关的全局配置都被安排在相关章节中，对于那些不能归类到任何资源的配置都被列举在本章节中.

清单（Inventory）¶

名字	描述	起始支持版本
category	配置类别	0.6
description	配置描述	0.6
name	配置名字	0.6
defaultValue	默认值	0.6
value	当前值	0.6

示例 ¶

{
    "category": "identity",
    "defaultValue": "500",
    "description": "管理服务器可以接受的最大会话数量. 达到这个限制值时，新的会话会被拒绝",
    "name": "session.maxConcurrent",
    "value": "500"
}

操作（Operations）¶

更新全局配置 ¶

管理员可以使用UpdateGlobalConfig来更新一个全局配置. 例如:

UpdateGlobalConfig category=host name=connection.autoReconnectOnError value=true

其他配置 ¶

不能归类到单独一个章节的一些配置.

statistics.on ¶

名字	类别	默认值	可选参数值
statistics.on	cloudBus	false	true false

开启或关闭通过JMX统计的每个消息消耗的时间.

node.heartbeatInterval ¶

名字	类别	默认值	可选参数值
node.heartbeatInterval	managementServer	5	> 0

管理节点向数据库写心跳（heartbeat)的间隔时间, 单位是秒.

node.joinDelay ¶

名字	类别	默认值	可选参数值
node.joinDelay	managementServer	0	>= 0

当值为非0时，每个管理节点在消息总线上发布加入事件(join event)之前会延迟0到’node.joinDelay’秒. 这是为了避免当有大量的管理节点同时上线时会产生加入事件风暴.

key.public ¶

名字	类别	默认值	可选参数值
key.public	configuration	请查看你的数据库

ZStack会把这个SSH公钥（public SSH key）注入到需要部署代理（agent）的Linux服务器上; 在当前版本中, Linux服务器包含KVM主机, 虚拟路由器虚拟机（virtual router VMs）, SFTP备份存储（SFTP backup storage）. 成功注入后, ZStack在需要SSH登陆时会使用:ref:key.private <configuration.key.private>.

key.private ¶

名字	类别	默认值	可选参数值
key.private	configuration	请查看你的数据库

Zstack用来SSH登陆远程Linux服务器的SSH私钥（private SSH key）; 请参看:ref:key.public <configuration.key.public>.

标签（Tags）¶

标签（Tags）

概览 ¶

ZStack提供两类标签来帮助用户和插件管理资源，引入额外的资源属性，以及指挥ZStack执行特殊的业务逻辑. 对于标签的架构设计请参见`The Tag System <http://zstack.org/blog/tag.html>`_.

用户标签（User Tags）¶

用户可以在他们所拥有的资源上创建用户标签，这对于管理相似资源的聚集特别有用; 例如, 用户可以为作为网页服务器(Web Server)的虚拟机设置一个标签’web’:

CreateUserTag resourceType=VmInstanceVO resourceUuid=613af3fe005914c1643a15c36fd578c6 tag=web

CreateUserTag resourceType=VmInstanceVO resourceUuid=5eb55c39db015c1782c7d814900a9609 tag=web

CreateUserTag resourceType=VmInstanceVO resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag=web

之后, 可以通过:ref:`Query API with tags <query with tags>`来获取这些虚拟机:

QueryVmInstance __userTag__=web

用户也可以通过用户标签和系统标签（system tags）合作来改变ZStack的业务逻辑; 例如, 用户可能想在所有作为网页服务器的虚拟机上在一个特定的通过SSD提高IO性能的主存储上创建他们的根存储云盘（root volumes）; 要达到这个目的, 用户可以在主存储上创建一个用户标签’forWebTierVM’:

CreateUserTag tag=forWebTierVM resourceType=PrimaryStorageVO resourceUuid=6572ce44c3f6422d8063b0fb262cbc62

然后在计算规格(instance offering)上创建一个系统标签:

CreateSystemTag tag=primaryStorage::allocator::userTag::forWebTierVM resourceType=InstanceOfferingVO resourceUuid=8f69ef6c2c444cdf8c019fa0969d56a5

这样, 当用户创建通过计算规格[uuid:8f69ef6c2c444cdf8c019fa0969d56a5]创建虚拟机的, ZStack会保证虚拟机的根存储云盘都会被创建在拥有用户标签’forWebTierVM’的主存储上，在这个例子中, 这个主存储的UUID为6572ce44c3f6422d8063b0fb262cbc62.

系统标签（System Tags）¶

系统标签相比用户标签有更广泛的用途; 就像上一节中的例子一样，用户可以使用它们来指导ZStack执行特殊的业务逻辑. 扩展ZStack功能的插件（Plugins）可以通过使用系统标签来引入额外的资源属性, 或记录和资源紧密相关的元数据.

例如, 要想在KVM主机上实施在线迁移（live migration）或者在线快照（live snapshot）, ZStack需要知道KVM主机的libvirt版本和QEMU版本，这些信息都是元数据因此ZStack将他们作为主机的系统标签存储起来. 例如, 管理员可以通过下面的命令查看一个KVM主机的系统标签:

QuerySystemTag fields=tag resourceUuid=d07066c4de02404a948772e131139eb4

*d07066c4de02404a948772e131139eb4*是某个云主机的UUID, 查询结果为:

{
  "inventories": [
      {
          "tag": "capability:liveSnapshot"
      },
      {
          "tag": "qemu-img::version::2.0.0"
      },
      {
          "tag": "os::version::14.04"
      },
      {
          "tag": "libvirt::version::1.2.2"
      },
      {
          "tag": "os::release::trusty"
      },
      {
          "tag": "os::distribution::Ubuntu"
      }
  ],
  "success": true
}

这一类的系统标签, 被称为内部系统标签（inherent system tags）; 内部系统标签只能被ZStack的服务（services）或插件（plugins）创建, 并且不能被DeleteTag API删除.

为了增加新的功能, 插件通常需要为一个资源添加新的属性; 虽然插件不能通过改变一个资源的数据库模式（database schema）来增加一个新的列（column） , 但它可以为一个资源创建作为系统标签的新属性. 例如, 当创建一个虚拟机时, 用户可以为云主机某L3网络上的网卡绑定一个可以通过网络访问的机器名（hostname）:

CreateVmInstance name=testTag systemTags=hostname::web-server-1 l3NetworkUuids=6572ce44c3f6422d8063b0fb262cbc62 instanceOfferingUuid=04b5419ca3134885be90a48e372d3895 imageUuid=f1205825ec405cd3f2d259730d47d1d8

这个机器名被实现为一个系统标签; 如果你查看 VM inventory in chapter ‘Virtual Machine’, 那里没有叫做’hostname’的属性; 然而, 你可以在虚拟机的系统标签中发现它:

QuerySystemTag fields=tag,uuid resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7

{
  "inventories": [
      {
          "tag": "hostname::web-server-1",
          "uuid": "596070a6276746edbf0f54ef721f654e"
      }
  ],
  "success": true
}

这类系统标签就是非内部的（non-inherent）, 用户可以通过DeleteTag删除它; 例如, 如果用户想把一个之前的虚拟机的机器名更改为 ‘web-server-nginx’, 可以这样做:

DeleteTag uuid=596070a6276746edbf0f54ef721f654e

CreateSystemTag resourceType=VmInstanceVO tag=hostname::web-server-nginx resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7

停止和启动虚拟机之后, 虚拟机中的系统（guest operating system）会接受到’web-server-nginx’作为新的机器名.

命名约定（Name Convention）¶

用户标签和系统标签最多都只能有2048个字符.

对于用户标签, 没有强制的命名约定, 但推荐使用可读的有意义的字符串.

对于系统标签, 和ZStack中服务和插件定义的一样, 他们使用 :: 作为分隔符（delimiters）.

资源类型（Resource Type）¶

当创建一个标签时, 用户必须制定标签所关联的资源类型(resource type). 在当前版本中, 资源类型被列在下表中:

ZoneVO

ClusterVO

HostVO

PrimaryStorageVO

BackupStorageVO

ImageVO

InstanceOfferingVO

DiskOfferingVO

VolumeVO

L2NetworkVO

L3NetworkVO

IpRangeVO

VipVO

EipVO

VmInstanceVO

VmNicVO

SecurityGroupRuleVO

SecurityGroupVO

PortForwardingRuleVO

VolumeSnapshotTreeVO

VolumeSnapshotVO

衍生出的资源使用他们的父类型; 例如, SftpBackupStorage的资源类型是’BackupStorageVO’. 在每个资源的对应*Tags*章节中, 我们有解释需用用什么资源类型来创建对应的标签.

操作（Operations）¶

创建标签（Create Tags）¶

有两种创建标签的方式; 对于已经创建的资源, 用户可以使用命令 CreateUserTag 或者 CreateSystemTag来创建用户标签或系统标签. 例如:

CreateUserTag resourceType=DiskOfferingVO resourceUuid=50fcc61947f7494db69436ebbbefda34 tag=for-large-DB

CreateSystemTag resourceType=HostVO resourceUuid=50fcc61947f7494db69436ebbbefda34 tag=reservedMemory::1G

对于一个将要被创建的资源, 因为它还没有被创建, 所以没有UUID可以被CreateUserTag和CreateSystemTag命令引用; 在这种情况下, 用户可以使用每个“创建类型的API命令”（creational API command）的*userTags*和*systemTags*域, 在创建时，用户可以通过传递列表的形式定义多个标签; 例如:

CreateVmInstance name=testTag systemTags=hostname::web-server-1
userTags=in-super-data-center,has-public-IP,hot-fix-applied-2015-5-1
l3NetworkUuids=6572ce44c3f6422d8063b0fb262cbc62
instanceOfferingUuid=04b5419ca3134885be90a48e372d3895 imageUuid=f1205825ec405cd3f2d259730d47d1d8

参数（Parameters）¶

CreateUserTag和CreateSystemTag有相同的API参数:

名字	描述	起始支持版本
resourceUuid	资源UUID; 例如, 虚拟机的UUID, 计算规格的UUID	0.6
resourceType	资源类型; 参见 resource type	0.6
tag	标签字符串	0.6

删除（Delete Tag）¶

用户可以使用DeleteTag来删除一个用户标签或者一个非内部的系统标签. 例如:

DeleteTag uuid=7813d03bb85840c489789f8df3a5915b

参数（Parameters）¶

名字	描述	可选的	可选的参数值	其实支持版本
deleteMode	参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	标签的UUID			0.6

查询标签（Query Tags）¶

用户可以使用QueryUserTag来查询用户标签, 例如:

QueryUserTag resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag~=web-server-%

或使用QuerySystemTag来查询系统标签, 例如:

QuerySystemTag resourceUuid=50fcc61947f7494db69436ebbbefda34

区域（Zone）¶

概览（Overview）¶

一个区域是由类似主存储，集群，L2网络的资源组成的逻辑组; 它定义一个可见的边界，在相同区域中的资源互相可见并且可以形成某种关系，但在不同区域中的资源是不行的. 例如, 区域A中的一个主存储可以挂载到区域A中的一个集群，但不能挂载到区域B的集群上.

区域的子资源，包括集群，L2网络和主存储，以下面的形式组织:

区域中的后裔资源没有在上图中列举出来。例如, 一个集群中的主机是集群的父区域的一个后裔资源.

作为逻辑资源（logic resource）, 区域将数据中心中的设备映射为逻辑组（logic groups）. 虽然没有强制要求这些设备需要如何做映射, 下面这些建议可以使事情变得简单:

同一个物理二层广播域中的主机应该在同一个区域中, 被划分为一个或多个集群.
物理二层广播域不应该跨域多个区域, 而应该映射为单个区域中的L2网络.
为虚拟机存储云盘提供磁盘空间的物理存储，也就是主存储，不应该跨越多个区域, 而应该被映射为单个区域中的主存储.
一个数据中心可以有多个区域.

一个区域可以有一个或多个备份存储（备份存储（Backup Storage））挂载. 一个区域中的资源, 例如主存储, 只能访问挂载在同一区域中的备份存储。同时，一个备份存储可以从一个区域中卸载; 在卸载后, 区域中的资源就不能再看见这个备份存储了. 当数据中心中的网络拓扑改变导致一个备份存储不能再被一个区域中的资源访问时，可以将备份存储从区域上卸载掉（Detaching backup storage）.

清单（Inventory）¶

属性（Properties):¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
state	请参见 zone state		Enabled Disabled	0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6
type	保留域			0.6

示例 ¶

{
  "uuid": "b729da71b1c7412781d5de22229d5e17",
  "name": "TestZone",
  "description": "Test",
  "state": "Enabled",
  "type": "zstack",
  "createDate": "Jun 1, 2015 6:04:52 PM",
  "lastOpDate": "Jun 1, 2015 6:04:52 PM"
}

可用状态（State）¶

区域拥有两种可用状态: 启用（Enabled）和禁用（Disabled）. 当改变一个区域的可用状态时, 这个操作会被迭代（cascaded）到归属于这个区域的所有的集群和主机. 例如, 禁用一个区域会导致所以这个区域中的集群和主机被禁用. 由于在已经禁用的主机上不能创建或者启动虚拟机, 禁用一个区域可以避免在这个区域中创建或者启动任何虚拟机.但不影响已有的虚拟机正常使用及重启操作。

操作（Operations）¶

创建区域（Create Zone）¶

管理员可以使用CreateZone命令来创建一个新的区域. 例如:

CreateZone name='San Jose Zone' description='this is a zone in San Jose datacenter'

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源名字, 请参见资源属性		0.6
resourceUuid	资源uuid, 请参见创建（Create Resources）	是	0.6
description	资源描述, 请参见资源属性	是	0.6
type	保留域, 请不要使用它	是	0.6
userTags	用户标签, 请参见创建标签（Create Tags）; 资源类型是 ZoneVO	是	0.6
systemTags	系统标签, 请参见创建标签（Create Tags）; 资源类型是 ZoneVO	是	0.6

删除区域（Delete Zone）¶

管理员可以使用DeleteZone命令来删除一个区域. 例如:

DeleteZone uuid=28e94936284b45f99842ababfc3f976d

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	区域 uuid			0.6
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6

改变可用状态（Change State）¶

管理员可以使用ChangeZoneState命令来改变区域的可用状态. 例如:

ChangeZoneState stateEvent=enable uuid=737896724f2645de9372f11b13a48223

参数（Parameters）¶

名字

描述

可选的

可选的参数值

起始支持版本

uuid

区域 uuid

0.6

stateEvent

状态触发事件.

enable: 改变可用状态为启用（Enabled）
disable: 改变可用状态为禁用（Disabled）

enable
disable

0.6

挂载备份存储（Attach Backup Storage）¶

请参见 attach backup storage to zone.

卸载备份存储（Detach Backup Storage）¶

请参见 detach backup storage from zone.

查询区域（Query Zone）¶

管理员可以使用QueryZone来查询区域. 例如:

QueryZone name=zone1

QueryZone vmInstance.uuid=13238c8e0591444e9160df4d3636be82

原生域查询（Primitive Fields of Query）¶

请参见 zone inventory

嵌套域和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	其实支持版本
vmInstance	vm inventory	属于这个区域的虚拟机	0.6
cluster	cluster inventory	属于这个区域的集群	0.6
host	host inventory	属于这个区域的主机	0.6
primaryStorage	primary storage inventory	属于这个区域的主存储	0.6
l2Network	L2 network inventory	属于这个区域的L2网络	0.6
l3Network	L3 network inventory	属于这个区域的L3网络	0.6
backupStorage	backup storage inventory	属于这个区域的备份存储	0.6

标签（Tags）¶

管理员可以在一个区域上用resourceType=ZoneVO创建用户标签. 例如:

CreateUserTag resourceType=ZoneVO resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag=privateZone

系统标签（System Tags）¶

保留容量（Reserved Capacity）¶

标签（Tag）	描述	示例	起始支持版本
host::reservedMemory::{capacity}	请参见主机容量保留（Host Capacity Reservation）	host::reservedMemory::1G	0.6

集群（Cluster）¶

集群（Cluster）

概览（Overview）¶

一个集群是类似主机（Host）组成的逻辑组. 在同一个集群中的主机必须安装相同的操作系统(虚拟机管理程序,hypervisor), 拥有相同的二层网络连接, 可以访问相同的主存储. 在实际的数据中心, 一个集群通常对应一个机架（rack）.

下图展示了一个典型的集群,以及它和主存储,L2网络之间的关系.

一个集群可以挂载一个或者多个主存储, 只要这些主存储可以被这个集群中的所有主机访问. 同时, 主存储也可以从集群卸载; 在数据中心的网络拓扑发生改变导致主存储不能被集群中的主机继续访问的时候,这非常有用.

只要集群中的主机都在所挂载的L2网络所代表的物理二层广播域中,一个集群可以挂载一个或多个L2网络. 同时,如果数据中心的网络拓扑发生改变导致集群中的主机不再在L2网络所代表的物理二层广播域中,L2网络也可以从集群卸载.

集群的规模,也就是每个集群中可以包含主机的最大数量,没有限制.

清单（Inventory)¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
hypervisorType	请参见 cluster hypervisor type		KVM	0.6
state	请参见 cluster state		Enabled Disabled	0.6
zoneUuid	包含集群的区域uuid. 请参见 zone.			0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6
type	保留域			0.6
userTags	用户标签, 请参见创建标签（Create Tags）	是		0.6
systemTags	系统标签, 请参见创建标签（Create Tags）	是		0.6

示例 ¶

{
  "inventory": {
    "uuid": "c1bd173d5cd84f0e9e7c47195ae27ec6",
    "name": "cluster1",
    "description": "test",
    "state": "Enabled",
    "zoneUuid": "1b830f5bd1cb469b821b4b77babfdd6f"
    "hypervisorType": "KVM",
    "lastOpDate": "Jun 1, 2015 5:54:09 PM",
    "createDate": "Jun 1, 2015 5:54:09 PM",
    "type": "zstack",
  }
}

虚拟机管理程序类型（Hypervisor Type）¶

虚拟机管理程序类型指明了哪种虚拟机管理程序（操作系统, operating system）被安装在集群中的主机上. 在当前ZStack版本中, 仅支持KVM管理程序.

可用状态（State）¶

集群有两种可用状态: 启用（Enabled）和禁用（Disabled）, 类似于 zone. 当改变集群的可用状态时, 操作会被迭代到集群中的所有主机; 例如, 禁用一个集群也会禁用集群中的所有主机.

操作（Operations）¶

创建集群（Create Cluster)¶

管理员可以使用CreateCluster命令来创建一个集群. 例如:

CreateCluster name=cluster1 hypervisorType=KVM zoneUuid=1b830f5bd1cb469b821b4b77babfdd6f

参数（Parameters）¶

名字	描述	可选的	起始支持版本
zoneUuid	父区域的uuid		0.6
name	资源名字, 请参见资源属性		0.6
resourceUuid	资源uuid, 请参见创建（Create Resources）	是	0.6
description	资源描述description, 请参见资源属性	是	0.6
hypervisorType	请参见 cluster hypervisor type		0.6
type	保留域, 请不要使用	是	0.6

删除集群（Delete Cluster）¶

管理员可以使用DeleteCluster命令来删除一个集群. 例如:

DeleteCluster uuid=c1bd173d5cd84f0e9e7c47195ae27ec6

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	集群的uuid			0.6
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6

改变可用状态（Change State）¶

管理员可以使用ChangeClusterState来改变一个集群的可用状态. 例如:

ChangeClusterState uuid=c1bd173d5cd84f0e9e7c47195ae27ec6 stateEvent=disable

参数（Parameters）¶

名字

描述

可选的

可选的参数值

起始支持版本

uuid

集群的uuid

0.6

stateEvent

可用状态触发事件

启用: 改变可用状态为启用（Enabled）
禁用: 改变可用状态为禁用（Disabled）

enable
disable

0.6

挂载主存储（Attach Primary Storage）¶

管理员可以使用AttachPrimaryStorageToCluster命令来挂载主存储到集群. 例如:

AttachPrimaryStorageToCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 primaryStorageUuid=1b830f5bd1cb469b821b4b77babfdd6f

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
clusterUuid	集群的uuid			0.6
primaryStorageUuid	主存储的uuid			0.6

卸载主存储（Detach Primary Storage）¶

管理员可以使用DetachPrimaryStorageFromCluster命令从集群卸载一个主存储. 例如:

DetachPrimaryStorageFromCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 primaryStorageUuid=1b830f5bd1cb469b821b4b77babfdd6f

当管理员需要让一个主存储不能再被集群访问,可以卸载主存储. 例如, 当需要将虚拟机从一个配置较低的主机的集群中迁移到一个配置更新更高的主机的集群时,管理员可以将这些虚拟机的根存储云盘所在的主存储从老的集群卸载,并将主存储挂载到新的集群,之后就可以启动这些停止虚拟机; 由于老的集群已经不能再访问主存储, ZStack会选择新的集群启动这些虚拟机.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
clusterUuid	集群的uuid			0.6
primaryStorageUuid	主存储的uuid			0.6

挂载（Attach L2 Network）¶

管理员可以使用AttachL2NetworkToCluster来挂载一个L2网络到集群. 例如:

AttachL2NetworkToCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 l2NetworkUuid=1b830f5bd1cb469b821b4b77babfdd6f

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
clusterUuid	集群的uuid			0.6
l2NetworkUuid	L2网络的uuid			0.6

卸载L2网络（Detach L2 Network)¶

管理员可以使用DetachL2NetworkFromCluster来从集群卸载一个L2网络. 例如:

DetachL2NetworkFromCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 l2NetworkUuid=1b830f5bd1cb469b821b4b77babfdd6f

当管理员需要在数据中心改变网络拓扑结构的时候可以利用卸载L2网络. 当集群中没有主机还连在物理二层网络时,管理员可以从集群中卸载代表这个物理二层网络的L2网络.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
clusterUuid	集群的uuid			0.6
l2NetworkUuid	L2网络的uuid			0.6

查询集群（Query Cluster——¶

管理员可以使用QueryCluster命令来查询集群. 例如:

QueryCluster hypervisorType=KVM

QueryCluster primaryStorage.availableCapacity>100000000

原生域查询（Primitive Fields of Query）¶

请参见 cluster inventory

嵌套和扩展查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
zone	请参见 zone inventory	父区域（parent zone）	0.6
host	请参见 host inventory	属于这个集群的主机	0.6
vmInstance	请参见 vm inventory	属于这个集群的虚拟机	0.6
l2Network	请参见 L2 network inventory	这个集群挂载的L2网络	0.6
primaryStorage	请参见 primary storage inventory	这个集群挂载的主存储	0.6

标签（Tags）¶

管理员可以使用resourceType=ClusterVO在集群上创建用户标签. 例如:

CreateUserTag resourceType=ClusterVO resourceUuid=80a979b9e0234564a22a4cca8c1dff43 tag=secureCluster

系统标签（System Tags）¶

保留的容量（Reserved Capacity）¶

标签（Tag）	描述	示例	起始支持版本
host::reservedMemory::{capacity}	请参见主机容量保留（Host Capacity Reservation）	host::reservedMemory::1G	0.6

主机（Host）¶

主机（Host）

概览（Overview）¶

主机是一个安装有操作系统（虚拟机管理系统，hypervisor)的物理服务器.

在ZStack中, 主机是提供虚拟机运行所需计算资源（computing resources）的最小单元. 区域（Zones）和集群（clusters）通常包含成组的主机，它们是更大的单元. 相较他的父亲资源和先驱资源都是逻辑资源, 主机是物理资源; 很多看似应用到区域和集群上的操作，实际都被指派到对应的主机上了. 例如, 在挂载一个主存储到集群的时候, 实际的操作是在集群中所有的主机上挂载这个主存储.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
zoneUuid	所在区域的uuid. 请参见 zone			0.6
clusterUuid	父集群的uuid. 请参见 cluster			0.6
managementIp	请参见 management ip			0.6
hypervisorType	请参见 cluster hypervisor type			0.6
state	请参见 state		Enabled Disabled PreMaintenance Maintenance	0.6
status	请参见 status		Connecting Connected Disconnected	0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
  "inventory": {
    "zoneUuid": "2893ce85c43d4a3a8d78f414da39966e",
    "name": "host1-192.168.0.203",
    "uuid": "43673938584447b2a29ab3d53f9d88d3",
    "clusterUuid": "8524072a4274403892bcc5b1972c2576",
    "description": "Test",
    "managementIp": "192.168.0.203",
    "hypervisorType": "KVM",
    "state": "Enabled",
    "status": "Connected",
    "createDate": "Jun 1, 2015 6:49:24 PM",
    "lastOpDate": "Jun 1, 2015 6:49:24 PM"
  }
}

管理IP（Management IP)¶

ZStack管理节点（ZStack management nodes）使用管理IP访问主机操作系统（虚拟机管理系统）; 根据虚拟机管理系统类型的不同,可以有或者没有管理IP. 例如, 在VMWare中, 访问ESXi主机的官方途径是使用VCenter服务器（VCenter Server）, 在这种情况下就没有使用管理IP的必要; 然而, 在KVM主机中, ZStack需要通过管理IP来部署代理程序（agent）到Linux操作系统中.

管理网络（Management Network）¶

虽不做强制限定, 推荐使用一个或者多个专用的子网（dedicated subnets）作为管理网络. 由于管理节点需要通过管理网络发送命令到主机和其他的装置, 运行ZStack管理节点的Linux服务器必须能够访问管理网络. 在以后的章节中, 当谈到特殊应用虚拟机（appliance VMs）的时候，我们会将再次看到管理网络, 在ZStack当前版本中这个特殊应用虚拟机是:ref:virtual router <virtual router>.

可用状态（State）¶

主机有四种可用状态:

Enabled:

在这种状态下，允许在该主机上创建，启动虚拟机，或迁移虚拟机到该主机上
Disabled:

在这种状态下，不允许在该主机上创建，启动虚拟机，或迁移虚拟机到该主机上
PreMaintenance:

指示主机即将进入维护状态的中间状态(intermediate state). 请参见 maintenance mode.
Maintenance:

该状态表明该主机在维护状态中.

主机的可用状态转换图如下:

维护模式（Maintenance Mode）¶

当管理员需要实施一些维护工作时可以将主机设置为维护模式, 例如, 安装更多的内存. 当主机在维护模式中, 不管是API操作还是ZStack内部任务都不会再在主机上执行任何操作. 也就是说, 类似启动虚拟机（API）, 停止虚拟机(API), 挂载主存储(内部)的任务都不能在该主机上进行. ZStack将维护模式设计为两个可用模式: PreMaintenance和Maintenance. 主机进入维护模式的顺序如下:

改变host的可用状态为PreMaintenance. 在这个阶段, ZStack会尝试将所有运行在该主机上的虚拟机迁移到其他合适的主机上. 如果迁移失败, ZStack将停止这些虚拟机.
当所有虚拟机都被迁移或者停止后, ZStack会将主机的可用状态改变为Maintenance. 这时, 管理员就可以开始在主机上实施维护工作.

维护工作结束后，管理员可以通过将主机设置为Enabled或Disabled，以使主机退出维护模式.

连接状态（Status）¶

连接状态反应了主机和管理节点之间命令通道（command channel）的状态. 命令通道是ZStack管理节点和主机通信并只会其执行操作的途径. 例如, 在KVM管理节点中, 命令通道是ZStack管理节点和运行在主机上的Python代理（agents）之间的HTTP连接; 在VMWare管理节点中, 命令通道是VCenter服务器和 ESXi主机之间的连接.

主机有三种连接状态:

Connecting:

在这种状态时，一个ZStack管理节点正在尝试建立自己和主机之间的命令通道. 这时还不能再主机上执行任何操作.
Connected

在这种状态时，ZStack管理节点和主机之间的命令通道已经被成功建立. 可以在主机上执行操作. 只有在这个状态下主机才能创建和启动虚拟机.
Disconnected

在这种状态时，ZStack管理节点和主机之间的命令通道丢失. 这时不能在主机上执行任何操作.

在ZStack管理节点启动过程中会开始和所有他所管理的主机建立命令通道; 在这个阶段, 主机的状态是Connecting; 命令通道建立完成后, 主机的连接状态会变为Connected; 如果管理节点建立命令通道失败, 或者之后某个时候命令通道丢失了, 命令通道所对应的主机连接状态会变为Disconnected.

ZStack管理节点会周期性的向主机发送ping命令（ping commands）以检查命令通道的健康状态; 一旦某个主机响应失败, 或者ping命令超时，主机的连接状态就会变为Disconnected.

主机的连接状态转换图如下:

可用状态（State）和连接状态（Status）¶

可用状态和连接状态之间没有直接关系. 可用状态代表了管理员针对主机的意愿, 而连接状态代表了主机的通信状况.

操作（Operations）¶

添加主机（Add Host）¶

不同虚拟机管理程序添加主机的命令不同.

添加KVM主机（Add KVM Host）¶

管理员可以使用AddKVMHost来添加一个KVM主机. 例如:

AddKVMHost clusterUuid=8524072a4274403892bcc5b1972c2576 managementIp=192.168.10.10 name=kvm1 username=root password=password

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6
clusterUuid	父集群的uuid, 请参见 cluster		0.6
managementIp	请参见 management ip		0.6
username	请参见 kvm credentials		0.6
password	请参见 kvm credentials		0.6

KVM证书（KVM Credentials）¶

ZStack使用一个叫做kvmagent的Python代理(agent)来管理KVM主机. ZStack使用`Ansible <http://www.ansible.com/home>`_ 来配置目标Linux操作系统并部署kvmagents，以实现完全的自动化; 为了在目标Linux操作系统上启动Ansible, ZStack需要KVM主机的SSH **root**用户名和密码来注入SSH公钥（public keys），目的是为了让Ansible可以不需要输入用户名密码就可以工作. 需要**root**是因为Ansible和kvmagent都需要对系统有完整的控制权限.

删除主机（Delete Host）¶

管理员可以使用DeleteHost命令来删除一个主机. 例如:

DeleteHost uuid=2893ce85c43d4a3a8d78f414da39966e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	主机的uuid			0.6

改变主机可用状态（Change Host State）¶

管理员可以使用ChangeHostState命令来改变一个主机的可用状态. 例如:

ChangeHostState stateEvent=preMaintain uuid=2893ce85c43d4a3a8d78f414da39966e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	主机的uuid			0.6
stateEvent	可用状态触发事件. 请参见 state		enable disable preMaintain	0.6

重连主机（Reconnect Host）¶

管理员可以使用ReconnectHost来重新建立ZStack管理节点和主机间的命令通道. 例如:

ReconnectHost uuid=2893ce85c43d4a3a8d78f414da39966e

请参见 status for details.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	其实支持版本
uuid	主机的uuid			0.6

查询主机（Query Host）¶

管理员可以使用QueryHost来查询主机. 例如:

QueryHost managementIp=192.168.0.100

QueryHost vmInstance.vmNics.ip=10.21.100.2

原生域查询（Primitive Fields of Query）¶

请参见 host inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
zone	zone inventory	所在区域	0.6
cluster	cluster inventory	父集群	0.6
vmInstance	VM inventory	这个主机上运行的所有虚拟机	0.6

全局配置（Global Configurations)¶

load.all ¶

名字	类别	默认值	可选的参数值
load.all	主机	true	true false

配置管理节点启动时是否要连接所有的主机. 如果设置为true, 管理节点会在启动时同时连接所有的主机, 如果云中有数量巨大的主机，这可能会导致运行管理节点的主机资源耗尽; 如果设置为false, 配合 load.parallelismDegree, 管理节点在启动时每次只会连接一部分主机，然后重复这个操作直到所有的主机都连上.

load.parallelismDegree ¶

名字	类别	默认值	可选的参数值
load.parallelismDegree	主机	100	> 0

当 load.all 被设置为false, 这个配置定义了管理节点启动时同时连接主机的数目.

ping.timeout ¶

名字	类别	默认值	可选参数值
ping.interval	主机	60	> 0

为了检查主机的连接状态, 管理节点周期性的向主机发送ping命令的间隔时间, 单位是秒.

ping.parallelismDegree ¶

名字	类别	默认值	可选的参数值
ping.parallelismDegree	主机	100	> 0

管理节点发送ping命令的并发度（parallel degree）. 如果主机的数目大于这个值, 管理节点会重复操作指导所有的主机都被ping过. 例如, 先ping前100个主机, 再ping后100个主机 ...

connection.autoReconnectOnError ¶

名字	类别	默认值	可选的参数值
connection.autoReconnectOnError	主机	true	true false

设置当主机的链接状态从Connected变为Disconnected时是否重连. 如果设置为true, 管理节点会通过ping命令重新连接状态从Connected变为Disconnected的主机, 从而让主机完成它在disconnected时错过的操作, 例如, 主机可能disconnected时错过了主机上代理（agent）的升级; 如果设置为false, 管理员根据需要必须手动重连这些主机，管理节点不会自动重连这些主机.

maintenanceMode.ignoreError ¶

名字	类别	默认值	可选的参数值
maintenanceMode.ignoreError	host	false	true false

设置是否在主机进入维护模式时忽略发生的错误. 如果设置为true, 错误将会被忽略，因此主机总是能成功进入维护模式; 如果设置为false, 主机会因为任何错误的发生而不能进入维护模式, 例如, 虚拟机迁移失败.

reservedCapacity.zoneLevel ¶

名字	类别	默认值	可选的参数值
reservedCapacity.zoneLevel	hostAllocator	true	true false

设置是否要在区域级别（zone level）启用主机容量预留; 请参见 host capacity reservation.

reservedCapacity.clusterLevel ¶

名字	类别	默认值	可选的参数值
reservedCapacity.clusterLevel	hostAllocator	true	true false

设置是否要在集群级别（cluster level）启用主机容量预留; 请参见 host capacity reservation.

reservedCapacity.hostLevel ¶

名字	类别	默认值	可选的参数值
reservedCapacity.hostLevel	hostAllocator	true	true false

设置是否要在集群级别（host level）启用主机容量预留; 请参见 host capacity reservation.

vm.migrationQuantity ¶

名字	类别	默认值	可选的参数值
vm.migrationQuantity	kvm	2	> 0

设置当KVM主机进入维护模式时，同时进行迁移的虚拟机数量.

reservedMemory ¶

名字	类别	默认值	可选的参数值
reservedMemory	kvm	512M	>= 0

当:ref:`reservedCapacity.hostLevel <reservedCapacity.hostLevel>`设置为true的时候，这个字符串存储了KVM主机上预留的内存容量. 这个数值是由一个数字后跟上一个单位组成的，这些表示单位的字符可以是B/K/M/G/T; 如果没有指定表示单位的字符, 这个数字被当成字节计算.

dataVolume.maxNum ¶

名字	类别	默认值	可选的参数值
dataVolume.maxNum	kvm	24	0 - 24

设置KVM虚拟机管理程序中虚拟机可以挂在的数据云盘（data volumes）的最大数量.

host.syncLevel ¶

名字	类别	默认值	可选的参数值
host.syncLevel	kvm	10	> 2

设置能在KVM主机上同时执行命令的最大并发数量.

标签（Tags）¶

管理员可以使用resourceType=HostVO在主机上创建用户标签. 例如:

CreateUserTag tag=largeMemoryHost resourceUuid=0a9f95a659444848846b5118e15bff32 resourceType=HostVO

系统标签（System Tags）¶

主机容量保留（Host Capacity Reservation）¶

管理员可以使用系统标签在主机上保留一部分内存供系统软件使用. ZStack提供了各种系统标签和全局配置，以达到更好粒度的内存保留策略控制:

Hypervisor Global Level:

如果没有其他层次的配置，全局等级配置(global level) :ref:`kvm.reservedMemory`会应用到所有的KVM主机.
Zone Level:

请参见 zone host::reservedMemory; 如果没有其他层次的配置，这个系统标签的值会应用到所有这个区域中的主机上. 这个值覆盖全局配置等级(global level).
Cluster Level:

请参见 cluster host::reservedMemory; 如果没有主机层次的配置，这个系统标签的值会应用到所有这个集群中的主机上. 这个值覆盖区域等级配置（zone level)和全局等级配置（global level）.
Host Level:

标签描述示例起始支持版本

reservedMemory::{capacity} 这个主机上保留的内存. reservedMemory::1G 0.6

这个配置覆盖所有上面的配置等级.

例如, 假设你还有三个KVM主机zone1->cluster1->{host1, host2, host3}; 默认的内存保留被默认为512M的全局配置（global configuration）:ref:`kvm.reservedMemory`控制; 这时如果在zone1上创建一个系统标签 host::reservedMemory::1G, 所有3个主机的内存保留都会被变成1G; 这时如果再在cluster1 上创建一个系统标签*host::reservedMemory::2G*, 所有3个主机的内存保留都会变成2G; 最后, 如果你在host1上创建一个系统标签*reservedMemory::3G*, 这时host1的内存保留将变成3G，但host2和host3还是2G.

主机元数据信息（Host Meta Data Information）¶

标签	描述	示例	起始支持版本
capability:liveSnapshot	如果标签存在, 主机上的虚拟机管理程序支持在线云盘快照（live volume snapshot）	capability:liveSnapshot	0.6
os::distribution::{distribution}	主机的操作系统提供商	os::distribution::Ubuntu	0.6
os::release::{release}	主机的操作系统发布版本	os::release::trusty	0.6
os::version::{version}	主机的操作系统版本	os::version::14.04	0.6

KVM主机元数据信息（KVM Host Meta Data Information）¶

标签	描述	示例	起始支持版本
qemu-img::version::{version}	qemu-img 版本	qemu-img::version::2.0.0	0.6
libvirt::version::{version}	libvirt 版本	libvirt::version::1.2.2	0.6
hvm::{flag}	主机硬件虚拟化标识（host hardware virtualization flag）; vmx表示Intel CPU; svm表示AMD CPU	hvm::vmx	0.6

主存储（Primary Storage）¶

主存储（Primary Storage）

概览（Overview）¶

主存储是数据中心里为虚拟机提供磁盘云盘的存储系统. 主存储可以是本地磁盘（local disks，例如主机的硬盘) 或者网络共享存储（network shared storage, 例如NAS, SAN ).

挂载了主存储的集群中的虚拟机的云盘存储在该主存储上.

主存储只能挂载到同一个区域（zone）中的集群上.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
zoneUuid	父区域的uuid, 请参见 zone			0.6
totalCapacity	磁盘总容量, 单位为字节, 请参见 capacity			0.6
availableCapacity	可用磁盘空间, 单位为字节, 请参见 capacity			0.6
url	请参见 url			0.6
type	主存储类型		NFS	0.6
state	请参见 state		Enabled Disabled	0.6
status	请参见 status		Connecting Connected Disconnected	0.6
attachedClusterUuids	主存储已经挂载了的集群uuid列表, 请参见 attach cluster			0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
  "inventory": {
    "uuid": "f4ac0a3119c94c6fae844c2298615d27",
    "zoneUuid": "f04caf351c014aa890126fc78193d063",
    "name": "nfs",
    "url": "192.168.0.220:/storage/nfs",
    "description": "Test Primary Storage",
    "totalCapacity": 10995116277768819,
    "availableCapacity": 10995162768,
    "type": "NFS",
    "state": "Enabled",
    "mountPath": "/opt/zstack/f4ac0a3119c94c6fae844c2298615d27",
    "createDate": "Jun 1, 2015 2:42:51 PM",
    "lastOpDate": "Jun 1, 2015 2:42:51 PM",
    "attachedClusterUuids": [
      "f23e402bc53b4b5abae87273b6004016",
      "4a1789235a86409a9a6db83f97bc582f",
      "fe755538d4e845d5b82073e4f80cb90b",
      "1f45d6d6c02b43bfb6196dcacb5b8a25"
    ]
  }
}

容量（Capacity）¶

为了方便选择合适的主存储创建云盘, ZStack会监控主存储的容量. 不同的主存储插件可能会汇报不同的磁盘容量; 例如, 对于支持超分（over-provisioning）的主存储, 汇报的存储容量会比实际的大; 对于不支持超分的主存储, 汇报的存储容量可能会小于或等于实际的大小.

NFS容量（NFS Capacity）¶

NFS不支持超分, 因此它的容量是用云盘的虚拟大小（volumes’ virtual sizes）根据以下公式计算出来的:

总容量 = NFS的总容量
可用容量 = 总容量 - sum(云盘的虚拟大小)

云盘的虚拟大小会在 :ref:`volume <volume>`章节中介绍; 简单的说, 云盘的虚拟大小就是当云盘被完全填满时的大小; 例如, 当你创建一个1G容量的云盘时, 在它被真正完全填满数据之前, 可能会因为使用了thin-provisioning技术而实际只占用了10M的容量.

统一资源定位符（URL） +++

主存储需要使用URL字符串存储的信息来控制存储系统. 虽然名字叫URL, 具体的字符串存储格式依据主存储的类型而定，并不完全等同于标准的URL规范, 这样可以给插件更多的灵活性以存储一些不方便以URL格式存储的信息.

NFS主存储URL ¶

对于NFS主存储, URL被编码为下面的格式:

nfs服务器的ip或域名:/目录的绝对路径

例如:

192.168.0.220:/storage/nfs/

可用状态（State）¶

主存储有两种可用状态:

** Enabled**:

启用（Enabled）状态下，允许云盘被创建
Disabled:

禁用（Disabled）状态下，不允许云盘被创建

连接状态（Status）¶

类似于 host status, 主存储的连接状态反应了管理节点和主存储之间的命令通道的状态. 命令通道是管理节点和主存储所代表的存储系统通信的途径; 根据主存储类型的不同命令通道也可以不同, 例如, 命令通道可以是ZStack管理节点和主存储之间的HTTP连接或者存储SDK（storage SDKs）提供的通信方法.

有三种连接状态:

Connecting:

在这种状态时，一个ZStack管理节点正在尝试建立自己和主存储之间的命令通道. 这时还不能在主存储上执行任何操作.
Connected

在这种状态时，ZStack管理节点和主存储之间的命令通道已经被成功建立. 可以在主存储上执行操作.
Disconnected

在这种状态时，ZStack管理节点和主存储之间的命令通道丢失. 这时不能在主存储上执行任何操作.

在ZStack管理节点启动过程中会开始和主存储建立命令通道，并且会在运行中周期性的向主存储发送ping命令（ping commands）以检查命令通道的健康状态; 一旦某个主存储响应失败, 或者ping命令超时，主存储的连接状态就会变为Disconnected.

主存储的连接状态转换图如下:

可用状态（State）和连接状态（Status）¶

可用状态和连接状态之间没有直接关系. 可用状态代表了管理员针对主存储的意愿, 而连接状态代表了主存储的通信状况.

挂载集群（Attaching Cluster）¶

挂载集群是将主存储和兄弟集群（sibling clusters）关联, 从而提供了一种灵活的方式维护主机和存储系统在实际数据中心里的关系. 我们来看一个实际的例子; 假设有一个集群(集群A)挂载了一个NFS主存储 (NFS1), 如下图所示:

一段时间后, 集群A内存耗尽但主存储还有足够的磁盘空间, 所以你决定添加另外一个使用NFS1的集群（集群B）; 那么你可以创建一个集群B, 然后将NFS1挂载在集群B上.

又运行一段时间之后, 集群A的硬件可能开始变得过时，因此你决定停止使用他们; 你添加了一个新的更加强大的集群（集群C）, 挂载到NFS1上, 然后将所有集群A中的主机设置为维护模式（maintenance mode）, 这样所有之前运行在集群A中的虚拟机都会被迁移到集群B或集群C; 最后, 你可以将NFS1从集群A卸载，然后删除集群A.现在，数据中心看起来像这样:

最后如果NFS1容量不够用了, 你可以添加另外一个主存储（NFS2）, 并加载到集群B和集群C上.

操作（Operations）¶

添加主存储（Add Primary Storage）¶

不同主存储类型，添加的命令不同.

添加NFS主存储（Add NFS Primary Storage）¶

管理员可以使用AddNfsPrimaryStorage添加一个NFS主存储. 例如:

AddNfsPrimaryStorage name=nfs1 zoneUuid=1b830f5bd1cb469b821b4b77babfdd6f url=192.168.0.220:/storage/nfs

属性（Properties）¶

名字	描述	可选的	起始支持版本
name	资源名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6
zoneUuid	父区域的uuid, 请参见 zone		0.6
url	请参见 url		0.6

删除主存储（Delete Primary Storage）¶

管理员可以使用DeletePrimaryStorage来删除一个主存储. 例如:

DeletePrimaryStorage uuid=2c830f5bd1cb469b821b4b77babfdd6f

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	主存储的uuid			0.6

改变主存储的可用状态（Change Primary Storage State）¶

管理员可以使用ChangePrimaryStorageState来改变一个主存储的可用状态. 例如:

ChangePrimaryStorageState stateEvent=enable uuid=2c830f5bd1cb469b821b4b77babfdd6f

属性（Properties）¶

名字

描述

可选的

可选的参数值

起始支持版本

uuid

主存储的uuid

0.6

stateEvent

可用状态触发事件

启用: 改变可用状态为启用（Enabled）
禁用: 改变可用状态为禁用（Disabled）

enable
disable

0.6

挂载集群（Attach Cluster）¶

请参见挂载主存储（Attach Primary Storage）.

卸载集群（Detach Cluster）¶

请参见卸载主存储（Detach Primary Storage）.

查询主存储（Query Primary Storage）¶

管理员可以使用QueryPrimaryStorage来查询主存储. 例如:

QueryPrimaryStorage totalCapacity<100000000000

QueryPrimaryStorage volumeSnapshot.uuid?=13238c8e0591444e9160df4d3636be82,33107835aee84c449ac04c9622892dec

原生域查询（Primitive Fields of Query）¶

请参见 primary storage inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
zone	zone inventory	父区域（parent zone）	0.6
volume	volume inventory	该主存储中的云盘	0.6
volumeSnapshot	volume snapshot inventory	该主存储中的云盘快照	0.6
cluster	cluster inventory	挂载了该主存储的集群	0.6

全局配置（Global Configurations）¶

mount.base ¶

名字	类别	默认值	可选的参数值
mount.base	nfsPrimaryStorage	/opt/zstack/nfsprimarystorage	以’/’开始的绝对路径

NFS主存储在KVM主机上的挂载点（mount point）.

标签（Tags）¶

用户可以使用resourceType=PrimaryStorageVO在主存储上创建用户标签. 例如:

CreateUserTag resourceType=PrimaryStorage tag=SSD resourceUuid=e084dc809fec4092ab0eff797d9529d5

系统标签（System Tags）¶

存储云盘快照（Storage Volume Snapshot）¶

标签	描述	示例	起始支持版本
capability:snapshot	当有该标签时, 主存储支持存储云盘快照	capability:snapshot	0.6

L2网络（L2 Network）¶

L2网络（L2 Network）

概览（Overview）¶

L2网络在数据中心中代表了一个二层广播域（layer2 broadcast domain <http://en.wikipedia.org/wiki/Broadcast_domain>）. 也就是说，除了传统的OSI数据链路层（data link layer）以外所有能提供二层隔离（layer 2 isolation）的技术都可以在ZStack中作为L2网络. 例如, VLAN, VxLAN, 或者SDN可以创建二层叠加网络（layer 2 overlay networks）. 在ZStack中, L2网络负责为L3网络提供二层隔离.

L2网络可以挂载到同一个区域中的集群（sibling clusters）.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
zoneUuid	父区域的uuid, 请参见 zone			0.6
physicalInterface	请参见 physical interface			0.6
type	L2网络类型		L2NoVlanNetwork L2VlanNetwork	0.6
attachedClusterUuids	L2网络挂载的集群的列表, 请参见 attach cluster			0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

物理接口（Physical Interface）¶

物理接口是一个字符串（例如eth0）。它代表了数据中心里二层网络（L2）的信息. 不同L2网络类型和不同虚拟机管理程序类型通常会有不同的物理接口. 这听起来稍有些复杂. 这主要归结于虚拟机管理程序会使用它自己的标记方式（notations）来描述L2网络, 并且L2网络可以被同时挂载到多个拥有不同虚拟机管理系统的集群上. 下面的一个实际可能可以帮助理解.

假设数据中心有一个L2网络(l2Network A)，这个L2网络跨越两个集群, 一个是KVM集群, 另一个是VMWare集群. 在KVM中, L2网络是使用Linux操作系统中的以太网设备（ethernet device）实现的; 在这个例子中，假设每个KVM主机通过eth0连接到L2网络. 在VMWare集群中, L2网络是使用vswitch实现的; 在这个例子中, 假设VMWare集群使用vswitch0连接到L2网络; 这样，整个拓扑结构如下图所示:

_images/l2Network-physical-interface.png

就像:ref:`host <host>`章节中提到的那样, 很多看似应用到区域和集群上的操作，实际都被指派到对应的主机上了; 这里, 当挂载L2网络A到KVM集群和VMWare集群的时候, ZStack必须能够理解在这些集群中虚拟机管理程序是如何使用标记描述L2网络; 在这种情况下, ZStack必须知道在KVM主机上eth0代表了L2网络，而在VMWare主机上vswitch0代表了L2网络. 所以物理接口的名字也反映了不同的虚拟机管理程序.

挂载集群（Attaching Cluster）¶

挂载集群是为了将L2网络和同一个区域中的集群（sibling clusters）关联起来, 它提供了一种灵活的方式来维护数据中心中主机和二层网络（layer 2 networks）之间的关系. 我们来看一个实际的例子.

假设你的数据中心中的网络拓扑结构如上图所示. 所有集群中的主机的eth0都连接在同一个称为L2 Network1的二层网络上; 集群cluster1和cluster3中主机的eth1都连接在另一个称为L2 network2的二层网络上. 为了ZStack中描述这个拓扑结构, 你可以将L2 network1挂载到所有三个集群上，同时只将L2 network2挂载到集群cluster1和cluster3上.

几个月之后, 由于一些业务的需求网络拓扑结构需要作一些改变, 因此你将集群cluster3中的主机上eth1所连接的网线从机架交换机（rack switch）上断开, 这样集群cluster3就不再和L2 network2相连了; 你可以通过将L2 network2从cluster3上卸载来通知ZStack网络拓扑结构发生了改变.

L2NoVlanNetwork ¶

L2NoVlanNetwork是L2网络的基本类型，它的属性被列举在:ref:properties <l2Network properties>. 名字中的’NoVlan’并不表示不可以使用VLAN技术, 它仅仅表示ZStack自己不会主动使用VLAN来创建一个二层广播域. 下面两个图例可以帮助理解:

在上图这个配置中, 交换机的两个端口5和12是不带VLAN 10标签（untagged VLAN 10）的端口(Cisco中的VLAN 10访问端口，即access port), 并且分别连接到host1和host2的eth0. 这对于L2NoVlanNetwork是一个有效的配置. 管理员可以使用’physicalInterface’ = ‘eth0’创建L2NoVlanNetwork，并将它挂载到集群上.

在上图这个配置中, 交换机的两个端口5和12是带VLAN 10标签（tagged VLAN 10）的端口(Cisco中的VLAN 10干线端口，即trunk port), 并且分别连接到host1和host2上预先创建好的VLAN设备eth0.10. 对于L2NoVlanNetwork来说，这同样是一个有效的配置. 管理员可以使用’physicalInterface’ = ‘eth0.10’创建L2NoVlanNetwork，并将它挂载到集群上.

现在大家应该可以理解，一个L2NoVlanNetwork对应了一个预先创建好的二层广播域; ZStack不会为L2NoVlanNetwork创建任何新的广播域.

KVML2NoVlanNetwork注意事项（L2NoVlanNetwork KVM Specific）¶

当挂载一个L2NoVlanNetwork到KVM集群时, :ref:`physicalInterface <l2Network physical interface>`应该是一个Linux操作系统中的以太网设备名（ethernet device name）; 例如, eth0, eth0.10, em1. 当ZStack使用brctl创建网桥（bridge）时会使用’physicalInterface’作为设备名. 伪代码如下:

Assuming physicalInterface = eth0

brctl create br_eth0
brctl addif br_eth0 eth0

L2NoVlanNetwork清单示例（L2NoVlanNetwork Inventory Example）¶

{
  "inventory": {
    "uuid": "f685ff94513542bbb8e814027f8deb13",
    "name": "l2-basic",
    "description": "Basic L2 Test",
    "zoneUuid": "45a2864b6ddf4d2fb9b4c3736a923dcb",
    "physicalInterface": "eth0",
    "type": "L2NoVlanNetwork",
    "createDate": "Jun 1, 2015 12:58:35 PM",
    "lastOpDate": "Jun 1, 2015 12:58:35 PM",
    "attachedClusterUuids": []
  }
}

L2VlanNetwork ¶

L2VlanNetwork是ZStack会为其主动使用VLAN创建二层广播域的L2网络. 根据集群中虚拟机管理程序的不同, ZStack创建L2网络对应的二层广播域的方式也不同. 相比:ref:properties <l2Network properties>, L2VlanNetwork还有一个额外的属性:

名字	描述	可选的	可选的参数值	起始支持版本
vlan	用来创建二层广播域的VLAN号(VLAN id)		[0, 4095]	0.6

当挂载L2VlanNetwork到集群的时候, ZStack会配合使用’vlan’属性和’physicalInterface’属性在集群中的主机上创建vlan设备; 为了使这种方式工作, ‘physicalInterface’所指定的以太网设备所连接的交换机端口必须是带相应’vlan’标签的. 例如:

在上图这个配置中, 交换机的两个端口5和12是带VLAN 10标签（tagged VLAN 10）的端口, 这样管理员就可以使用’physicalInterface’ = ‘eth0’和’vlan’ = 10创建L2VlanNetwork，并将它挂载到集群上.

L2VlanNetwork KVM注意事项（L2VlanNetwork KVM Specific）¶

当挂载L2VlanNetwork到KVM集群时, ZStack会在集群中的所有主机上创建VLAN设备并创建网桥. 伪代码如下:

Assuming physicalInterface = eth0, vlan = 10

vconfig add eth0 10
brctl create br_eth0_10
brctl addif br_eth0_10 eth0.10

L2VlanNetwork清单示例（L2VlanNetwork Inventory Example）¶

{
    "inventory": {
      "vlan": 10,
      "uuid": "14a01b0978684b2ea6e5a355c7c7fd73",
      "name": "TestL2VlanNetwork",
      "description": "Test",
      "zoneUuid": "c74f8ff8a4c5456b852713b82c034074",
      "physicalInterface": "eth0",
      "type": "L2VlanNetwork",
      "createDate": "Jun 1, 2015 4:31:47 PM",
      "lastOpDate": "Jun 1, 2015 4:31:47 PM",
      "attachedClusterUuids": []
    }
}

操作（Operations）¶

创建L2网络（Create L2 Network）¶

两种L2网络创建的命令不同.

创建L2NoVlanNetwork（Create L2NoVlanNetwork）¶

管理员可以使用CreateL2NoVlanNetwork来创建L2NoVlanNetwork. 例如:

CreateL2NoVlanNetwork name=management-network physicalInterface=eth0 zoneUuid=9a94e647a9f64bb392afcdc5396cc1e4

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源名, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6
zoneUuid	父区域的uuid, 请参见 zone		0.6
physicalInterface	请参见 physical interface		0.6

创建L2VlanNetwork（Create L2VlanNetwork）¶

管理员可以使用CreateL2VlanNetwork来创建L2VlanNetwork. 例如:

CreateL2VlanNetwork name=APPLICATION-L2 physicalInterface=eth0 vlan=100 zoneUuid=69b5be02a15742a08c1b7518e32f442a

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
vlan	用来创建二层广播域的VLAN id		[0, 4095]	0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
zoneUuid	父区域的uuid, 请参见 zone			0.6
physicalInterface	请参见 physical interface			0.6

删除L2网络（Delete L2 Network）¶

管理员可以使用DeleteL2Network来删除一个L2网络. 例如:

DeleteL2Network uuid=a5535531eb7346ce89cfd7e643ad1ef8

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	L2网络的uuid			0.6

挂载集群（Attach Cluster）¶

请参见挂载（Attach L2 Network）.

卸载集群（Detach Cluster）¶

请参见卸载L2网络（Detach L2 Network).

查询L2网络（Query L2 Network）¶

管理员可以使用QueryL2Network来查询L2网络. 例如:

QueryL2Network physicalInterface=eth0

QueryL2Network l3Network.ipRanges.startIp=192.168.0.2

原生域查询（Primitive Fields of Query）¶

请参见 L2 network inventory.

嵌套和扩展域查询（Nested and Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
l3Network	L3 network inventory	属于这个L2网络的L3网络	0.6
cluster	cluster inventory	该L2网络挂载的所有集群	0.6
zone	zone inventory	父区域（parent zone）	0.6

标签（Tags）¶

管理员可以使用resourceType=L2NetworkVO在L2网络上创建用户标签. 例如:

CreateUserTag resourceType=L2NetworkVO tag=publicL2 resourceUuid=cff4be8694174b0fb831a9fe53b1d62b

L3网络（L3 Network）¶

L3网络（L3 Network）

概览（Overview）¶

L3网络是由子网（subnet）以及一系列网络服务（network services）组成, :ref:`L2 network <l2Network>`负责为其提供隔离方法. 网络服务提供模块（network service providers）提供的网络服务, 通常是OSI三层到七层协议的软件实现.

子网（Subnet）¶

一个L3网络中的子网可以是一个连续的IP范围（consecutive IP range）或多个分割的IP范围（split IP ranges）. 对于需要保留一部分IP地址的子网，分割的IP地址范围特别有用. 例如, 假设要创建一个拥有子网192.168.0.0/24的L3网络作为管理网络; 但是, IP地址192.168.0.50 ~ 192.168.0.100都已经被一些网络设备占用，因此你不希望ZStack使用这些地址, 所以你创建了两个分割的IP地址范围:

IP Range1

start IP: 192.168.0.2
end IP: 192.168.0.49
gateway: 192.168.0.1
netmask: 255.255.255.0

IP Range2

start IP: 192.168.0.101
end IP: 192.168.0.254
gateway: 192.168.0.1
netmask: 255.255.255.0

分割的IP范围没有数量限制, 只要他们属于同一个`CIDR <http://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>`_.

网络服务（Network Services）¶

为了给L3网络上的虚拟机提供服务，网络服务实现了OSI三层到七层的协议. 和L3网络的父L2网络相关联的网络服务提供模块负责提供网络服务. 单个类型的网络服务可以有多个网络服务提供模块, 同时单个网络服务提供模块可以提供多种类型的服务. 用户可以在创建的L3网络上挂载网络服务并选择网络服务提供模块. 在ZStack当前版本中, 支持的服务/网络服务提供模块如下所示:

网络服务（Network Service）	网络服务提供模块（Provider）	可以挂载的L2网络（Attachable L2 Network）	起始支持版本
DHCP	虚拟路由器（Virtual Router）	L2NoVlanNetwork L2VlanNetwork	0.6
DNS	虚拟路由器（Virtual Router）	L2NoVlanNetwork L2VlanNetwork	0.6
源网络地址翻译（Source NAT，SNAT)	虚拟路由器（Virtual Router）	L2NoVlanNetwork L2VlanNetwork	0.6
端口转发（Port Forwarding）	虚拟路由器（Virtual Router）	L2NoVlanNetwork L2VlanNetwork	0.6
固定IP（Elastic IP，EIP)	虚拟路由器（Virtual Router）	L2NoVlanNetwork L2VlanNetwork	0.6
安全组（Security Group）	安全组（Security Group）	L2NoVlanNetwork L2VlanNetwork	0.6

表中, 可以挂载的L2网络列表明网络服务提供模块可以挂载到哪种L2网络. 网络服务提供模块不能为不可以挂载的L2网络的子L3网络提供服务.

清单（Inventory)¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
zoneUuid	所在区域的uuid, 请参见 zone			0.6
l2NetworkUuid	父L2网络的uuid, 请参见 L2 network			0.6
state	请参见 state		Enabled Disabled	0.6
dnsDomain	请参见 domain	是		0.6
ipRanges	:ref:`IP ranges <l3Network IP range>`列表			0.6
dns	:ref:`DNS <l3Network DNS>`列表			0.6
networkServices	:ref:`network services references <l3Network network service reference>`列表			0.6
type	L3网络类型（L3 network type）		L3BasicNetwork	0.6
createDate	请参见:ref:resource properties			0.6
lastOpDate	请参见:ref:resource properties			0.6

示例 ¶

{
  "inventory": {
    "uuid": "f73926eb4f234f8195c61c33d8db419d",
    "name": "GuestNetwork",
    "description": "Test",
    "type": "L3BasicNetwork",
    "zoneUuid": "732fbb4383b24b019f60d862995976bf",
    "l2NetworkUuid": "f1a092c6914840c9895c564abbc55375",
    "state": "Enabled",
    "createDate": "Jun 1, 2015 11:07:24 PM",
    "lastOpDate": "Jun 1, 2015 11:07:24 PM",
    "dns": [],
    "ipRanges": [
      {
        "uuid": "78b43f4b0a9745fab49c967e1c35beb1",
        "l3NetworkUuid": "f73926eb4f234f8195c61c33d8db419d",
        "name": "TestIpRange",
        "description": "Test",
        "startIp": "10.10.2.100",
        "endIp": "10.20.2.200",
        "netmask": "255.0.0.0",
        "gateway": "10.10.2.1",
        "createDate": "Jun 1, 2015 11:07:24 PM",
        "lastOpDate": "Jun 1, 2015 11:07:24 PM"
      }
    ],
    "networkServices": [
      {
        "l3NetworkUuid": "f73926eb4f234f8195c61c33d8db419d",
        "networkServiceProviderUuid": "bbb525dc4cc8451295d379797e092dba",
        "networkServiceType": "DHCP"
      }
    ]
  }
}

可用状态（State）¶

L3网络有两种可用状态:

Enabled

在这种状态下，允许创建新的虚拟机
Disabled

在这种状态下，不允许创建新的虚拟机

DNS域（DNS Domain）¶

DNS域用来将L3网络中主机的机器名扩展为FQDNs(完全合格的域名，Full Qualified Domain Name); 例如, 如果虚拟机的主机名是’vm1’并且L3网络的DNS域是’zstack.org’, 主机名最终会被展开为’vm1.zstack.org’.

IP地址范围（IP Range)¶

ZStack当前版本仅支持IPv4 IP地址范围.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的参数	起始支持版本
uuid	请参见资源属性		0.6
name	请参见资源属性		0.6
description	请参见资源属性	是	0.6
startIp	地址范围的起始IP		0.6
endIp	地址范围的结束IP		0.6
netmask	子网掩码		0.6
gateway	子网网关		0.6
createDate	请参见资源属性		0.6
lastOpDate	请参见资源属性		0.6

示例 ¶

{
  "inventory": {
    "uuid": "b1cfcdeca4024d13ac82edbe8d959720",
    "l3NetworkUuid": "50e637dc68b7480291ba87cbb81d94ad",
    "name": "TestIpRange",
    "description": "Test",
    "startIp": "10.0.0.100",
    "endIp": "10.10.1.200",
    "netmask": "255.0.0.0",
    "gateway": "10.0.0.1",
    "createDate": "Jun 1, 2015 4:30:23 PM",
    "lastOpDate": "Jun 1, 2015 4:30:23 PM"
  }
}

DNS ¶

当DNS网络服务启用时，一个L3网络可以有一个或多个DNS起作用.

L2网络和L3网络（L2 Networks and L3 Networks）¶

类似于一个二层广播域可以包含多个子网, 你可以在同一个L2网络中创建多个L3网络; 但由于这些L3网络被没有被互相隔离，仍然可以被监听; 这样使用有一定的风险.

网络服务引用（Network Service References）¶

网络服务引用展现了L3网络上启用的网络服务以及他们的提供者.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的参数值	起始支持版本
l3NetworkUuid	L3网络Uuid		0.6
networkServiceProviderUuid	网络服务提供模块的UUID		0.6
networkServiceType	网络服务类型	DHCP DNS SNAT PortForwarding EIP SecurityGroup	0.6

示例 ¶

{
  "l3NetworkUuid": "f73926eb4f234f8195c61c33d8db419d",
  "networkServiceProviderUuid": "bbb525dc4cc8451295d379797e092dba",
  "networkServiceType": "PortForwarding"
}

网络拓扑结构（Network Typology）¶

在Iaas软件管理云中最常见的网络拓扑结构是:

扁平网络或共享网络（Flat Network or Shared Network）:

这种拓扑结构中, 所有的租客（tenants）共享一个子网; IaaS软件只提供DHCP, DNS服务; 数据中心的路由器将负责路由服务
私有网络或隔离网络（Private Network or Isolated Network）:

这种拓扑结构中, 每个租客都有自己的子网; IaaS软件负责为所有子网提供路由服务, 同时通常包含DHCP, DNS, 和NAT等服务.
虚拟专用网络（Virtual Private Network，VPC):

这种拓扑结构中, 每个租客都可以有多个子网; IaaS软件负责提供路由服务协调所有子网; 租客们可以通过配置路由器的路由表（routing table）来控制子网间的连通.

此外，典型的拓扑结构可以组合成新的类型; 例如, 扁平网络和私有网络可以组合在一起, 如下图所示:

在ZStack中, 所有这些拓扑结构都可以通过组合L2网络, L3网络和网络服务来实现. 例如, 用户可以通过创建一个只启用了DHCP和DNS的L3网络来创建一个扁平网络; 用户可以通过在L2VlanNetwork上创建一个启用了DHCP, DNS, SNAT的L3网络来创建一个私有网络.

操作（Operations）¶

创建L3网络（Create L3 Network）¶

用户可以使用CreateL3Network创建L3网络. 例如:

CreateL3Network l2NetworkUuid=f1a092c6914840c9895c564abbc55375 name=GuestNetwork

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
l2NetworkUuid	父L2网络的uuid, 请参见 L2 network			0.6
dnsDomain	一个DNS域, 请参见 domain	是		0.6
type	L3网络类型, 请参见 type	是	L3BasicNetwork	0.6
system	指示这是否是一个系统L3网络(system L3 network), 请参见系统L3网络（System L3 Network）	是	true false	0.6

类型（Type）¶

ZStack当前版本仅支持L3BasicNetwork L3网络类型. 用户调用CreateL3NetworkUsers时可以不填’type’参数.

系统L3网络（System L3 Network）¶

系统L3网络是ZStack保留使用的，用户不能使用它创建虚拟机. 系统L3网络通常被公有网络（public networks）和管理网络（management networks）使用. 通常云中的用户虚拟机不应该有网卡连接在公网或管理网络上, 但特殊应用虚拟机（appliance VMs） (例如路由器虚拟机，router VM)确实需要有网卡连接在这些网络上; 因此系统网络和公有网络可以创建为系统L3网络.

删除L3网络（Delete L3 Network）¶

用户可以使用DeleteL3Network来删除一个L3网络. 例如:

DeleteL3Network uuid=f73926eb4f234f8195c61c33d8db419d

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	L3网络的uuid			0.6
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6

添加IP地址范围（Add IP Ranges）¶

添加分割的地址范围（Add Split Ranges）¶

用户可以使用AddIpRange来添加一个IP地址范围到L3网络; 这个命令也可以用来添加分割的IP地址范围. 例如:

AddIpRange name=ipr1 startIp=192.168.0.2 endIp=192.168.0.100 netmask=255.255.255.0 gateway=192.168.0.1 resourceUuid=50e637dc68b7480291ba87cbb81d94ad

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6
l3NetworkUuid	父L3网络的uuid		0.6
startIp	IP地址范围的起始地址		0.6
endIp	IP地址范围的结束地址		0.6
netmask	子网掩码		0.6
gateway	子网网关		0.6

添加CIDR（Add CIDR）¶

用户可以使用AddIpRangeByNetworkCidr来添加一个IP地址范围. 例如:

AddIpRangeByNetworkCidr name=ipr1 l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad networkCidr=10.0.1.0/24

参数（Parameters）¶

名字	描述	可选的	起始支持版本
uuid	请参见资源属性		0.6
name	请参见资源属性		0.6
description	请参见资源属性	是	0.6
l3NetworkUuid	父L3网络的uuid		0.6
networkCidr	网络CIDR; 必须按照格式: 网络号/前缀长度（network-number/prefix-length)		0.6

删除IP地址范围（Delete IP Range）¶

用户可以使用DeleteIpRange来删除一个IP地址范围. 例如:

DeleteIpRange uuid=b1cfcdeca4024d13ac82edbe8d959720

参数（Parameters）¶

名字	描述	可选的	可选的参数	起始支持版本
uuid	IP地址范围的uuid			0.6
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6

添加DNS（Add DNS）¶

用户可以使用AddDnsToL3Network来在L3网络上添加DNS. 例如:

AddDnsToL3Network l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad dns=8.8.8.8

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
l3NetworkUuid	父L3网络的uuid			0.6
dns	dns的IPv4地址			0.6

挂载网络服务（Attach Network Service）¶

在创建虚拟机之前，用户可以使用AttachNetworkServiceToL3Network来挂载网络服务到创建的L3网络上. 如果在网络服务挂载钱L3网络上已经有虚拟机运行, 这些已有的虚拟机需要重启才能开始使用新挂载的网络服务.

示例:

AttachNetworkServiceToL3Network l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad networkServices='{"1d1d5ff248b24906a39f96aa3c6411dd": ["DHCP", "DNS", "SNAT", "EIP"]}'

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
l3NetworkUuid	L3网络的uuid			0.6
networkServices	网络服务提供模块UUID和网络服务类型列表之前的映射关系 (map)			0.6

查询L3网络（Query L3 Network）¶

用户可以使用QueryL3Network来查询L3网络. 例如:

QueryL3Network dnsDomain=zstack.org

QueryL3Network vmNic.ip=192.168.10.2

原生域查询（Primitive Fields of Query)¶

请参见 L3 network inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query)¶

域（Field）	清单（Inventory）	描述	起始支持版本
ipRanges	IP range inventory	该L3网络包含的所有IP地址范围	0.6
networkServices	l3Network network service reference	该L3网络挂载的所有网络服务	0.6
l2Network	L2 network	父L2网络	0.6
vmNic	VM nic inventory	连在该L3网络上所有虚拟机网卡	0.6
serviceProvider	network service provider inventory	所有该L3网络挂载的服务的提供模块	0.6
zone	zone inventory	所在区域	0.6

L3网络标签（L3 Network Tags）¶

用户可以使用resourceType=L3NetworkVO在L3网络上创建用户标签. 例如:

CreateUserTag resourceType=L3NetworkVO tag=web-tier-l3 resourceUuid=f6be73fa384a419986fc6d1b92f95be9

IP地址范围标签（IP Range Tags）¶

用户可以使用resourceType=IpRangeVO在IP地址范围上创建用户标签. 例如:

CreateUserTag resourceType=IpRangeVO tag=web-tier-IP resourceUuid=8191d946954940428b7d003166fa641e

镜像（Image）¶

镜像（Image）

概览（Overview）¶

镜像为虚拟机文件系统提供模板. 镜像可以是为虚拟机安装操作系统的根云盘（root volume）提供模板的RootVolumeTemplate; 镜像也可以是为虚拟机存储非操作系统数据的数据云盘（data volumes）提供模板的DataVolumeTemplate; 同时镜像也可以是用来在空白根云盘（blank root volumes）上安装操作系统的ISO文件.

镜像存储在:ref:`backup storage <backup storage>`上. 如果在启动虚拟机之前, 用来创建虚拟机根云盘的镜像还不在:ref:`primary storage <primary storage>`的镜像缓存（image cache）中, 镜像会先被下载到缓存中. 因此在首次用一个镜像创建创建虚拟机的时候，通常会由于需要下载而花费更多的时间.

ZStack使用`thin provisioning <http://en.wikipedia.org/wiki/Thin_provisioning>`_创建根云盘. 从相同镜像创建出来的根云盘共享主存储的镜像缓存中同一份基础镜像（base image），对某个虚拟机根云盘的改动不会影响到基础镜像.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
state	请参见 state		Enabled Disabled	0.6
status	请参见 status		Creating Downloading Ready	0.6
size	镜像大小, 单位是字节			0.6
url	镜像注册的url, 请参见 url			0.6
mediaType	镜像的媒介类型, 请参见 media type		RootVolumeTemplate DataVolumeTemplate ISO	0.6
guestOsType	该字符串描述了虚拟机的操作系统类型	是		0.6
platform	虚拟机的操作系统平台, 请参见 platform		Linux Windows Paravirtualization Other	0.6
system	请参见 system image			0.6
format	请参见 format		qcow2 raw	0.6
md5Sum	镜像的md5校验值			0.6
type	保留的域		zstack	0.6
backupStorageRefs	:ref:`backup storage reference <image backup storage reference>`列表			0.6

示例 ¶

{
    "backupStorageRefs": [
        {
            "backupStorageUuid": "8b99641a4d644820932e0ec5ada78eed",
            "createDate": "Jun 1, 2015 6:17:48 PM",
            "imageUuid": "b395386bdb4a4ff1b1850a457c949c5e",
            "installPath": "/export/backupStorage/sftp/templates/acct-36c27e8ff05c4780bf6d2fa65700f22e/b395386bdb4a4ff1b1850a457c949c5e/centos_400m_140925.template",
            "lastOpDate": "Jun 1, 2015 6:17:48 PM"
        }
    ],
    "createDate": "Jun 1, 2015 6:17:40 PM",
    "description": "Test Image Template for network test",
    "format": "qcow2",
    "guestOsType": "unknown",
    "lastOpDate": "Jun 1, 2015 6:17:40 PM",
    "md5Sum": "not calculated",
    "mediaType": "RootVolumeTemplate",
    "name": "image_for_sg_test",
    "platform": "Linux",
    "size": 419430400,
    "state": "Enabled",
    "status": "Ready",
    "system": false,
    "type": "zstack",
    "url": "http://172.16.0.220/templates/centos_400m_140925.img",
    "uuid": "b395386bdb4a4ff1b1850a457c949c5e"
},

可用状态（State）¶

镜像有两种可用状态:

Enabled:

在这种状态下，允许创建基于该镜像的虚拟机
Disabled:

在这种状态下，不允许创建基于该镜像的虚拟机

连接状态（Status）¶

连接状态反应了镜像的生命周期（lifecycle）:

Creating:

正在从云盘或云盘快照（volume snapshot）创建镜像; 未就绪不能使用.
Downloading:

正在从url下载镜像; 未就绪不能使用.
Ready:

镜像已经在备份存储中；已就绪可以使用.

URL ¶

镜像在备份存储中创建的方式不同，url的含义也会不同; 如果镜像是从网页服务器下载的，url就是HTTP/HTTPS链接; 如果镜像是从云盘或者云盘快照创建的, url就是云盘或云盘快照的UUID的字符串编码, 例如:

volume://b395386bdb4a4ff1b1850a457c949c5e
volumeSnapshot://b395386bdb4a4ff1b1850a457c949c5e

媒介类型（Media Type）¶

媒介类型指示了镜像的用途.

RootVolumeTemplate:

镜像被用来创建根云盘.
DataVolumeTemplate:

镜像被用来创建数据云盘.
ISO:

镜像被用来在空白的根云盘上安装操作系统.

平台（Platform）¶

ZStack根据平台来判断从该镜像创建虚拟机是否要使用半虚拟化（paravirtualization）.

使用半虚拟化	Linux Paravirtualization
不使用半虚拟化（虚拟机磁盘使用IDE模式，网卡使用e1000）	Windows Other

系统镜像（System Image）¶

系统镜像仅被用来创建特殊应用虚拟机（appliance VMs），因而不被用户虚拟机使用. ZStack当前版本使用系统镜像创建:ref:virtual router <virtual router>.

格式（Format）¶

格式反映了虚拟机管理程序和镜像之间的关系. 例如, qcow2格式的镜像仅能被KVM虚拟机使用. ZStack当前版本仅支持KVM虚拟机管理程序, 因此关系表如下:

虚拟机管理程序类型	格式
KVM	qcow2 raw

创建的云盘会从其所基于的镜像继承格式信息; 例如, 从qcow2格式的镜像创建的根云盘同样会是qcow2格式. ‘raw’格式是个特例, 从’raw’格式的镜像创建的云盘会使用qcow2格式，因为ZStack会通过qcow2格式使用thin-clone.

备份存储引用（Backup Storage Reference）¶

一个镜像可以存储在一个或多个备份存储中. 对于所存储的每个备份存储, 镜像都有一个包含了备份存储UUID以及镜像安装路径的备份存储引用.

名字	描述	起始支持版本
imageUuid	镜像的uuid	0.6
backupStorageUuid	备份存储的uuid, 请参见 backup storage	0.6
installPath	在备份存储上的安装路径	0.6
createDate	请参见资源属性	0.6
lastOpDate	请参见资源属性	0.6

示例 ¶

{
    "backupStorageUuid": "8b99641a4d644820932e0ec5ada78eed",
    "imageUuid": "b395386bdb4a4ff1b1850a457c949c5e",
    "installPath": "/export/backupStorage/sftp/templates/acct-36c27e8ff05c4780bf6d2fa65700f22e/b395386bdb4a4ff1b1850a457c949c5e/centos_400m_140925.template",
    "createDate": "Jun 1, 2015 6:17:48 PM",
    "lastOpDate": "Jun 1, 2015 6:17:48 PM"
}

操作（Operations）¶

添加镜像（Add Image）¶

管理员可以使用AddImage来添加镜像. 例如:

AddImage name=CentOS7 format=qcow2 backupStorageUuids=8b99641a4d644820932e0ec5ada78eed url=http://172.16.0.220/templates/centos7_400m_140925.img mediaType=RootVolumeTemplate platform=Linux

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
url	HTTP/HTTPS url, 请参见 url			0.6
mediaType	镜像媒介类型, 请参见 media type. 默认为RootVolumeTemplate	是	RootVolumeTemplate DataVolumeTemplate ISO	0.6
guestOsType	指示虚拟机操作系统类型的字符串, 例如, CentOS7	是		0.6
system	指示是否为系统镜像, 请参见 system image. 默认为false	是	true false	0.6
format	镜像格式, 请参见 format		qcow2 raw	0.6
platform	镜像的平台, 请参见 platform. 默认为Linux	是	Linux Windows Other Paravirtualization	0.6
backupStorageUuids	镜像将要挂载的备份存储uuid列表			0.6
type	保留的域, 请勿使用	是	zstack	0.6

可以通过在’backupStorageUuids’参数中提供一个备份存储UUID列表，将一个镜像添加到多个备份存储; 只要镜像被成功加载到一个备份存储AddImage命令就会返回成功, 只有当其在所有备份存储上失败时才返回失败. 成功将镜像添加的备份存储可以从API返回的镜像清单中的:ref:`image backup storage reference <image backup storage reference>`获得.

删除镜像（Delete Image）¶

管理员可以使用DeleteImage从指定的或全部的备份存储中删除一个镜像. 例如:

DeleteImage uuid=b395386bdb4a4ff1b1850a457c949c5e backupStorageUuids=c310386bdb4a4ff1b1850a457c949c5e,f295386bdb4a4ff1b1850a457c949c5e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	镜像的uuid			0.6
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
backupStorageUuids	存储该镜像的备份存储列表; 如果不指定该参数，该镜像会从所有的备份存储中删除.			0.6

仅当从所有备份存储中删除后，镜像才被认为是被删除了; 否则，镜像只是从部分备份存储中被删除.

改变可用状态（Change State）¶

管理员可以使用ChangeImageState来改变镜像的可用状态. 例如:

ChangeImageState stateEvent=enable uuid=b395386bdb4a4ff1b1850a457c949c5e

参数（Parameters）¶

名字

描述

可选的

可选的参数值

起始支持版本

uuid

镜像的uuid

0.6

stateEvent

状态触发事件（state trigger event）

启用: 改变可用状态为启用（Enabled）
禁用: 改变可用状态为禁用（Disabled）

enable
disable

0.6

从根云盘创建RootVolumeTemplate（Create RootVolumeTemplate From Root Volume）¶

用户可以从根云盘创建RootVolumeTemplate镜像. 例如:

CreateRootVolumeTemplateFromRootVolume name=CentOS7 rootVolumeUuid=1ab2386bdb4a4ff1b1850a457c949c5e backupStorageUuids=backupStorageUuids,f295386bdb4a4ff1b1850a457c949c5e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
backupStorageUuids	该备份存储uuid列表选择镜像将在哪些备份存储上创建, 请参见 backup storage uuids	是		0.6
rootVolumeUuid	即将用于创建该镜像的根云盘的uuid			0.6
platform	镜像的平台, 请参见 platform; 默认为Linux	是	Linux Windows Other Paravirtualization	0.6
guestOsType	该字符串存储了虚拟机的操作系统类型, 例如, CentOS7	是		0.6
system	指示该镜像是否为系统镜像, 请参见 system image; 默认为false	是	true false	0.6

备份存储UUID（Backup Storage UUIDs）¶

当调用CreateRootVolumeTemplateFromRootVolume时, 用户可以提供一个备份存储UUID里列表来指定在哪里创建镜像; 如果忽略这个域, 会随机选择一个备份存储创建镜像.

从云盘快照创建RootVolumeTemplate（Create RootVolumeTemplate From Volume Snapshot）¶

用户可以使用CreateRootVolumeTemplateFromVolumeSnapshot从云盘快照创建一个RootVolumeTemplate. 例如:

CreateRootVolumeTemplateFromVolumeSnapshot name=CentOS7 snapshotUuid=1ab2386bdb4a4ff1b1850a457c949c5e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
snapshotUuid	云盘快照的uuid, 请参见 volume snapshot			0.6
backupStorageUuids	该备份存储uuid列表选择镜像将在哪些备份存储上创建, 请参见 backup storage uuids	是		0.6
platform	镜像平台, 请参见 platform. 默认为Linux	是	Linux Windows Other Paravirtualization	0.6
guestOsType	该字符串指示了虚拟机的操作系统类型, 例如, CentOS7	是		0.6
system	指示该镜像是否为系统镜像, 请参见 system image. Default is false	是	true false	0.6

备份存储uuid（Backup Storage Uuids）¶

当调用CreateRootVolumeTemplateFromVolumeSnapshot时, 用户可以提供一个备份存储UUID里列表来指定在哪里创建镜像; 如果忽略这个域, 会随机选择一个备份存储创建镜像.

从云盘创建DataVolumeTemplate（Create DataVolumeTemplate From Volume）¶

用户可以使用CreateDataVolumeTemplateFromVolume来从云盘创建一个DataVolumeTemplate. 例如:

CreateDataVolumeTemplateFromVolume name=data volumeUuid=1ab2386bdb4a4ff1b1850a457c949c5e

这里的云盘，可以是根云盘，也可以是数据云盘. 因此这里提供了一种从根云盘创建数据云盘的方法. 用户可以先从根云盘创建一个DataVolumeTemplate, 然后基于该DataVolumeTemplate再创建数据云盘.

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6
volumeUuid	云盘的uuid, 请参见 volume		0.6
backupStorageUuids	该备份存储uuid列表选择镜像将在哪些备份存储上创建, 请参见 backup storage uuids	是	0.6

Backup Storage Uuids ¶

当调用CreateDataVolumeTemplateFromVolume时, 用户可以提供一个备份存储UUID里列表来指定在哪里创建镜像; 如果忽略这个域, 会随机选择一个备份存储创建镜像.

查询镜像（Query Image）¶

用户可以使用QueryImage来查询镜像. 例如:

QueryImage status=Ready system=true

QueryImage volume.vmInstanceUuid=85ab231e392d4dfb86510191278e9fc3

原生域查询（Primitive Fields of Query）¶

请参见 image inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
backupStorage	backup storage inventory	该镜像所在的备份存储	0.6
volume	volume inventory	从该镜像创建的所有云盘	0.6
backupStorageRef	backup storage reference	用来查询备份存储安装路径的引用	0.6

标签（Tags）¶

用户可以使用resourceType=ImageVO在镜像上创建用户标签. 例如:

CreateUserTag resourceType=ImageVO tag=golden-image resourceUuid=ff7c04c4e2874a21a3e795501f1bc516

备份存储（Backup Storage）¶

备份存储（Backup Storage）

概览（Overview）¶

备份存储是保存用于创建云盘的:ref:`images <image>`的存储系统. 备份存储可以是基于存储的文件系统（filesystem based storage，例如NFS），也是可以基于对象的存储（object store based storage，例如OpenStack SWIFT）, 只要该存储系统为网络可共享的存储（network shared storage）. 除了可以为创建云盘提供模板以外, 备份存储也允许用户备份云盘或云盘快照（volume snapshots）.

备份存储必须挂载到:ref:`zone <zone>`之后，区域中的资源才能访问它. 管理员可以利用备份存储在多个区域之间共享镜像, 例如:

在云的初期, 可能只有一个区域(Zone1)以及一个备份存储. 随着业务的发展, 管理员可能会选择创建另一个区域(Zone2)，但使用现有的镜像创建虚拟机; 这时管理员可以将备份存储挂载到区域Zone2, 这样区域Zone1和区域Zone2都可以共享同样的镜像了.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
url	请参见 url			0.6
totalCapacity	字节为单位的磁盘总容量, 请参见 capacity			0.6
availableCapacity	字节为单位的磁盘可用容量, 请参见 capacity			0.6
type	备份存储类型e		SftpBackupStorage	0.6
state	请参见 state		Enabled Disabled	0.6
status	请参见 status		Connecting Connected Disconnected	0.6
attachedZoneUuids	备份存储所挂载的所有区域的UUID			0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
    "attachedZoneUuids": [
        "36de66d82f424639af67215a465418f6"
    ],
    "availableCapacity": 1258407346176,
    "name": "sftp",
    "state": "Enabled",
    "status": "Connected",
    "totalCapacity": 1585341214720,
    "type": "SftpBackupStorage",
    "url": "/export/backupStorage/sftp",
    "uuid": "33a35f75885f45ab96ea2626ce9c05a6",
    "lastOpDate": "Jun 1, 2015 3:42:26 PM",
    "createDate": "Jun 1, 2015 3:42:26 PM"
}

统一资源定位符（URL） +++

备份存储需要使用URL字符串存储的信息来控制存储系统. 虽然名字叫URL, 具体的字符串存储格式依据主存储的类型而定，并不完全等同于标准的URL规范, 这样可以给插件更多的灵活性以存储一些不方便以URL格式存储的信息.

SFTP备份存储URL（SFTP Backup Storage URL）¶

对于SFTP备份存储而言, URL是一个目录在文件系统中的绝对路径. 例如, /storage/sftp.

容量（Capacity）¶

为了方便选择合适的备份存储存放镜像, ZStack会监控备份存储的容量. 备份存储的容量根据下面公式来计算:

总容量 = 备份存储的总容量
可用容量 = 总容量 - sum(镜像的实际大小)

可用状态（State）¶

备份存储有两种可用状态:

Enabled:

启用（Enabled）状态下，允许镜像被注册，备份，和下载
Disabled:

禁用（Disabled）状态下，不允许镜像被注册，备份，和下载. 需要特别注意的是，如果一个镜像只存在于一个禁用了的备份存储中，并且这个镜像还没有被下载到主存储的镜像缓存中，这时不能从这个镜像创建虚拟机.

连接状态（Status）¶

主存储的连接状态反应了管理节点和备份存储之间的命令通道的状态.

Connecting:

在这种状态时，一个ZStack管理节点正在尝试建立自己和备份存储之间的命令通道. 这时还不能在备份存储上执行任何操作.
Connected

这种状态时，ZStack管理节点和备份存储之间的命令通道已经被成功建立. 可以在备份存储上执行操作.
Disconnected

在这种状态时，ZStack管理节点和备份存储之间的命令通道丢失. 这时不能在备份存储上执行任何操作.

在ZStack管理节点启动过程中会开始和备份存储建立命令通道，并且会在运行中周期性的向主存储发送ping命令（ping commands）以检查命令通道的健康状态; 一旦某个备份存储响应失败, 或者ping命令超时，备份存储的连接状态就会变为Disconnected.

备份存储的可用状态转换图如下:

SFTP备份存储（SFTP Backup Storage）¶

SFTP备份存储是使用本地文件系统（native filesystem）存储镜像，并使用OpenSSH服务器/客户端传输镜像的Linux服务器. ZStack使用一个python代理(SftpBackupStorageAgent)来管理Linux服务器; 镜像是通过使用`SCP <http://en.wikipedia.org/wiki/Secure_copy>`_从服务器上传/下载. 除了:ref:`backup storage inventory <backup storage inventory>`章节中提到的属性, SFTP备份存储还有一个额外的属性:

名字	描述	可选的	可选的参数值	起始支持版本
hostname	SFTP备份存储的IP地址或DNS域名			0.6

示例 ¶

{
    "attachedZoneUuids": [
        "36de66d82f424639af67215a465418f6"
    ],
    "availableCapacity": 1258407346176,
    "hostname": "172.16.0.220",
    "name": "sftp",
    "state": "Enabled",
    "status": "Connected",
    "totalCapacity": 1585341214720,
    "type": "SftpBackupStorage",
    "url": "/export/backupStorage/sftp",
    "uuid": "33a35f75885f45ab96ea2626ce9c05a6",
    "lastOpDate": "Jun 1, 2015 3:42:26 PM",
    "createDate": "Jun 1, 2015 3:42:26 PM"
}

操作（Operations）¶

添加备份存储（Add Backup Storage）¶

不同的备份存储类型使用不同的添加命令.

添加SFTP备份存储（Add SFTP Backup Storage）¶

管理员可以使用AddSftpBackupStorage来添加一个新的备份存储. 例如:

AddSftpBackupStorage name=sftp1 url=/storage/sftp1 hostname=192.168.0.220 username=root password=password

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
url	请参见 url			0.6
hostname	SFTP备份存储的IP地址或DNS域名			0.6
username	root用户		root	0.6
password	root的SSH密码			0.6

删除备份存储（Delete Backup Storage）¶

管理员可以使用DeleteBackupStorage来删除备份存储. 例如:

DeleteBackupStorage uuid=1613b627cb2e4ffcb30e7e59935064be

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	备份存储的uuid			0.6
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6

改变可用状态（Change State）¶

管理员可以使用ChangeBackupStorageState来改变备份存储的可用状态. 例如:

ChangeBackupStorageState uuid=33a35f75885f45ab96ea2626ce9c05a6 stateEvent=enable

参数（Parameters）¶

名字

描述

可选的

可选的参数值

起始支持版本

uuid

备份存储的uuid

0.6

stateEvent

状态触发事件

启用: 改变可用状态为启用（Enabled）
禁用: 改变可用状态为禁用（Disabled）

enable
disable

0.6

挂载区域（Attach Zone）¶

管理员可以使用AttachBackupStorageToZone将备份存储挂载到区域上. 例如:

AttachBackupStorageToZone backupStorageUuid=d086c30f33914c98a6078269bab7bc8f zoneUuid=d086c30f33914c98a6078269bab7bc8f

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
backupStorageUuid	备份存储的uuid			0.6
zoneUuid	区域的uuid			0.6

卸载区域（Detach Zone）¶

管理员可以使用DetachBackupStorageFromZone从一个区域卸载备份存储. 例如:

DetachBackupStorageFromZone backupStorageUuid=d086c30f33914c98a6078269bab7bc8f zoneUuid=d086c30f33914c98a6078269bab7bc8f

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
backupStorageUuid	备份存储的uuid			0.6
zoneUuid	区域的uuid			0.6

查询备份存储（Query Backup Storage）¶

管理员可以使用QueryBackupStorage来查询备份存储. 例如:

QueryBackupStorage state=Enabled

QueryBackupStorage image.platform=Linux

原生域查询（Primitive Fields of Query）¶

请参见 backup storage inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
zone	zone inventory	该备份存储挂载的所有区域	0.6
image	image inventory	该备份存储包含的所有镜像	0.6
volumeSnapshot	volume snapshot inventory	该备份存储包含的所有云盘快照	0.6

查询SFTP备份存储（Query SFTP Backup Storage）¶

管理员可以使用QuerySftpBackupStorage来查询SFTP备份存储:

QuerySftpBackupStorage name=sftp

原生域查询（Primitive Fields of Query）¶

请参见 SFTP backup storage inventory

嵌套和扩展域查询（Nested and Expanded Fields of Query）¶

请参见 backup storage nested and expanded fields

全局配置（Global Configurations）¶

ping.interval ¶

名字	类别	默认值	可选的参数值
ping.interval	backupStorage	60	> 0

管理节点发送ping命令到备份存储的间隔时间, 单位是秒.

ping.parallelismDegree ¶

名字	类别	默认值	可选的参数值
ping.parallelismDegree	backupStorage	50	> 0

管理节点可以同时ping的最大并行数量.

标签（Tags）¶

管理员可以使用resourceType=BackupStorageVO在备份存储上创建用户标签. 例如:

CreateUserTag tag=lab1 resourceType=BackupStorageVO resourceUuid=2906471068802c501773d3ee55b7766e

云盘（Volume）¶

云盘（Volume）

概览（Overview）¶

云盘为虚拟机提供存储. 根据云盘的作用不同，云盘可以分为两种类型根（root）或数据（data）. 根云盘是安装虚拟机操作系统的磁盘, 例如C:或者sda; 而数据云盘则提供了额外的存储空间, 例如D:或者sdb.

虚拟机管理程序不同，云盘也会有所不同; 也就是说, 不同类型虚拟机管理程序创建的云盘可能不能互相加载; 例如, KVM虚拟机的云盘不能被VMWare虚拟机加载. 类似于:ref:image format <image format>, 虚拟机管理器的信息被隐式包含在域:ref:`format <volume format>`中, 不同的是镜像格式还有一个额外的’ISO’值.

由于使用了`thin provisioning <http://en.wikipedia.org/wiki/Thin_provisioning>`_, 云盘会拥有两种大小: 实际大小（real size）和虚拟大小（virtual size）. 实际大小是指云盘在存储系统上实际占用的大小; 虚拟大小是指云盘声明的大小，也就是云盘完全填满后的大小. 虚拟机大小总是大于或等于实际的大小.

主存储（primary storage）上的云盘可以直接被虚拟机访问. 云盘同一时间只能挂载到一个虚拟机. 根云盘总是被挂载到拥有它的虚拟机上，不能被卸载; 而数据云盘则可以在相同类型虚拟机管理程序管理的不同虚拟机之间挂载和卸载, 只要这些虚拟机可以访问数据云盘所在的主存储.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
primaryStorageUuid	云盘所在的主存储的uuid, 请参见 primary storage			0.6
vmInstanceUuid	云盘所挂载的虚拟机的uuid, 如果没有挂载虚拟机为NULL; 请参见 attach VM	是		0.6
diskOfferingUuid	云盘规格（disk offering）的uuid, 如果云盘是从云盘规格创建出来的	是		0.6
rootImageUuid	镜像（image）的uuid, 如果云盘是从一个镜像创建出来的	是		0.6
installPath	云盘在主存储上的安装路径			0.6
type	云盘的类型		Root Data	0.6
format	请参见 format		qcow2	0.6
size	云盘的虚拟大小, 单位是字节			0.6
deviceId	请参见 device id	是		0.6
state	请参见 state		Enabled Disabled	0.6
status	请参见 status		Creating Ready NotInstantiated	0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
    "description": "Root volume for VM[uuid:1a2b197060eb4593bf5bbf2a83b3d625]",
    "deviceId": 0,
    "format": "qcow2",
    "installPath": "/opt/zstack/nfsprimarystorage/prim-302055ec45794423af7f5d3c5081bc87/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-f7bbb3ae1c674ecda3b0f4c025e333f9/f7bbb3ae1c674ecda3b0f4c025e333f9.qcow2",
    "createDate": "Jun 1, 2015 3:45:44 PM",
    "lastOpDate": "Jun 1, 2015 3:45:44 PM",
    "name": "ROOT-for-virtualRouter.l3.1b7f47f5350c488c99e8f54142ddffbd",
    "primaryStorageUuid": "302055ec45794423af7f5d3c5081bc87",
    "rootImageUuid": "178c662bfcdd4145920682c58ebcbed4",
    "size": 1364197376,
    "state": "Enabled",
    "status": "Ready",
    "type": "Root",
    "uuid": "f7bbb3ae1c674ecda3b0f4c025e333f9",
    "vmInstanceUuid": "1a2b197060eb4593bf5bbf2a83b3d625"
}

挂载的虚拟机（Attached VM）¶

数据云盘可以被挂载到正在运行的（Running）或者已经停止的（Stopped）虚拟机上, 但在同一时间一个云盘只能挂载到一个虚拟机上; 挂载后虚拟机的UUID会出现在’vmInstanceUuid’中. 数据云盘可以从一个虚拟机上卸载，然后挂载到另一个虚拟机上，但是这两个虚拟机需要是相同类型的虚拟机管理程序管理的. 根云盘总是被挂载到拥有它的虚拟机上，不能被卸载.

格式（Format）¶

云盘格式揭示了云盘和虚拟机管理程序之间的关系, 指示了该云盘可以挂载到哪种虚拟机管理程序管理的虚拟机上. 云盘格式和镜像格式（image format）很类似. ZStack当前版本仅支持KVM虚拟机管理程序, 因此云盘格式支持’qcow2’.

设备ID（Device ID）¶

设备号表明了云盘挂载到虚拟机的顺序. 由于第一个被挂载的云盘总是根云盘, 它将有固定的设备ID 0; 数据云盘则可能有1, 2, 3 ... N这样的设备ID, 取决于他们挂载到虚拟机的顺序. 设备ID可以用来识别云盘在客户操作系统（guest operating system）中的盘符（disk letter）; 例如, 在Linux系统中, 0通常代表/dev/xvda, 1通常代表/dev/xvdb，一次类推.

可用状态（State）¶

云盘有两种可用状态:

Enabled:

启用（Enabled）状态下，允许云盘被挂载到虚拟机上.
Disabled:

禁用（Disabled）状态下，不允许云盘被挂载到虚拟机上; 然而, 数据云盘总是可以被卸载，即使已经是禁用状态的数据云盘也可以被卸载.

连接状态（Status）¶

连接状态体现了云盘的生命周期:

NotInstantiated:

数据云盘特有的状态. 在这个连接状态中，数据云盘只是在数据库中分配了还没有在任何主存储上实例化; 也就是说, 他们还只存在于数据库的表记录中. NotInstantiated状态的数据云盘可以挂载到任何类型虚拟机管理程序管理的虚拟机上; 当他们挂载到虚拟机上后，他们会在主存储上被实例化为虚拟机管理程序类型的实际二进制文件. 挂载之后, 数据云盘的hypervisorType域会存储虚拟机对应的虚拟机管理程序类型, 同时连接状态会改为就绪（Ready）; 在这之后，这些数据云盘就只能被重新挂载到相同类型虚拟机管理程序管理的虚拟机上了.
Ready:

在这种状态时，云盘已经在主存储上实例化，已就绪可以使用.

Creating:

在这种状态时，正在从镜像或云盘快照创建云盘; 未就绪不能使用.

连接状态转换图如下所示:

操作（Operations）¶

创建一个数据云盘（Create a Data Volume）¶

从云盘规格创建（From a Disk Offering）¶

用户可以使用CreateDataVolume从云盘规格（disk offering）创建数据云盘. 例如:

CreateDataVolume name=data1 diskOfferingUuid=fea135f1d1de40b4915a19aa155983b3

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6
diskOfferingUuid	云盘规格的uuid, 请参见 disk offering		0.6

从镜像创建（From an Image）¶

用户可以使用CreateDataVolumeFromVolumeTemplate从一个镜像创建数据云盘. 例如:

CreateDataVolumeFromVolumeTemplate name=data1 imageUuid=ee6fa27ade8c42a2bdda8f9b1eee8c93 primaryStorageUuid=302055ec45794423af7f5d3c5081bc87

镜像可以是RootVolumeTemplate或DataVolumeTemplate媒介类型.

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, see 资源属性	true	0.6
imageUuid	镜像的uuid, 请参见 image		0.6
primaryStorageUuid	即将用于创建数据云盘的主存储的uuid; 对于要挂载该数据云盘的虚拟机，该主存储必须能被访问; 否则你可能会创建一个不能被挂载到该虚拟机的悬挂数据云盘（dangling data volume）. 请参见 primary storage.		0.6

从云盘快照创建（From a Volume Snapshot）¶

用户可以使用CreateDataVolumeFromVolumeSnapshot来从:ref:`volume snapshot <volume snapshot>`创建数据云盘. 例如:

CreateDataVolumeFromVolumeSnapshot name=data1 primaryStorageUuid=302055ec45794423af7f5d3c5081bc87 volumeSnapshotUuid=178c662bfcdd4145920682c58ebcbed4

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, see 资源属性	是	0.6
volumeSnapshotUuid	云盘快照的uuid, 请参见 volume snapshot		0.6
primaryStorageUuid	即将用于创建数据云盘的主存储的uuid; 对于要挂载该数据云盘的虚拟机，该主存储必须能被访问; 否则你可能会创建一个不能被挂载到该虚拟机的悬挂数据云盘（dangling data volume）. 请参见 primary storage.		0.6

删除数据云盘（Delete Data Volume）¶

用户可以使用DeleteDataVolume来删除数据云盘. 例如:

DeleteDataVolume uuid=178c662bfcdd4145920682c58ebcbed4

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	云盘的uuid			0.6

改变可用状态（Change State）¶

用户可以使用ChangeVolumeState来改变一个数据云盘的可用状态. 例如:

ChangeVolumeState uuid=be19ce415bbe44539b0bd276633470e0 stateEvent=enable

参数（Parameters）¶

名字

描述

可选的

可选的参数值

起始支持版本

uuid

云盘的uuid

0.6

stateEvent

状态触发事件

启用: 改变可用状态为启用（Enabled）
禁用: 改变可用状态为禁用（Disabled）

enable
disable

0.6

挂载虚拟机（Attach VM）¶

用户可以使用AttachDataVolumeToVm来挂载一个云盘到虚拟机上. 例如:

AttachDataVolumeToVm volumeUuid=178c662bfcdd4145920682c58ebcbed4 vmInstanceUuid=c5b443a20341418b9120c7e3b3cd34f5

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
volumeUuid	云盘的uuid			0.6
vmInstanceUuid	虚拟机的uuid, 请参见 VM			0.6

卸载虚拟机（Detach VM）¶

用户可以使用DetachDataVolumeFromVm从虚拟机卸载一个数据云盘. 例如:

DetachDataVolumeFromVm uuid=178c662bfcdd4145920682c58ebcbed4

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	云盘的uuid			0.6

查询云盘（Query Volume）¶

用户可以使用QueryVolume来查询云盘. 例如:

QueryVolume type=Data vmInstanceUuid=71f5376ef53a46a9abddd59c942cf45f

QueryVolume diskOffering.name=small primaryStorage.uuid=8db7eb2ccdab4c4eb4784e46895bb016

原生域查询（Primitive Fields of Query）¶

请参见 volume inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field)	清单（nventory）	描述	起始支持版本
vmInstance	VM inventory	云盘所挂载的虚拟机	0.6
snapshot	volume snapshot inventory	从该云盘创建出来的所有云盘快照	0.6
diskOffering	disk offering inventory	从该云盘创建出来的所有云盘规格	0.6
primaryStorage	primary storage inventory	该云盘所在的主存储	0.6
image	image inventory	从该云盘创建出来的镜像	0.6

标签（Tags）¶

用户可以使用resourceType=VolumeVO在云盘上创建标签. 例如:

CreateUserTag resourceType=VolumeVO tag=goldenVolume resourceUuid=f97b8cb9bccc4872a723c8b7785d9a12

云盘规格（Disk Offering）¶

概览（Overview）¶

云盘规格是云盘的规格描述（specification）, 其中定义了云盘的大小以及如何创建云盘. 云盘规格可以用来创建根云盘（root volumes）和数据云盘（data volumes）.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
diskSize	单位为字节的云盘大小, 请参见 disk size			0.6
state	请参见 state		Enabled Disabled	0.6
type	保留的域		zstack	0.6
allocatorStrategy	请参见 allocator strategy		DefaultPrimaryStorageAllocationStrategy	0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

云盘大小（Disk Size）¶

DiskSize定义了云盘的虚拟大小（virtual size）. 正如:ref:`volume <volume>`中提到的那样, 虚拟大小是指云盘声明的大小，也就是云盘完全填满后的在存储系统中所占的大小. 简单的说，虚拟大小就是，你希望云盘有多大.

可用状态（State）¶

云盘规格有两种可用状态:

Enabled:

启用（Enabled）状态下，允许从云盘规格创建云盘.
Disabled:

禁用（Disabled）状态下，不允许从云盘规格创建云盘.

分配策略（Allocator Strategy）¶

分配策略定义了ZStack怎么选择用于创建新云盘的主存储. ZStack当前版本仅支持寻找满足下列条件主存储的DefaultPrimaryStorageAllocationStrategy策略:

可用状态为启用（Enabled）
连接状态为已连接（Connected）
可用容量（availableCapacity）比云盘规格的diskSize大
已挂载到云盘将要挂载的虚拟机所在的集群

操作（Operations）¶

创建云盘规格（Create Disk Offering）¶

用户可以使用CreateDiskOffering创建云盘规格. 例如:

CreateDiskOffering name=small diskSize=1073741824

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
diskSize	以字节为单位的云盘大小, 请参见 size			0.6
allocationStrategy	请参见 allocator strategy	是	DefaultPrimaryStorageAllocationStrategy	0.6
type	保留的域, 请勿使用	是		0.6

改变可用状态（Change State）¶

用户可以使用ChangeDiskOfferingState来改变一个云盘规格的可用状态. 例如:

ChangeDiskOfferingState uuid=178c662bfcdd4145920682c58ebcbed4 stateEvent=enable

参数（Parameters）¶

名字

描述

可选的

可选的参数值

起始支持版本

uuid

云盘规格的uuid

0.6

stateEvent

状态触发事件

启用: 改变可用状态为启用（Enabled）
禁用: 改变可用状态为禁用（Disabled）

enable
disable

0.6

删除云盘规格（Delete Disk Offering）¶

用户可以使用DeleteDiskOffering来删除一个云盘规格. 例如:

DeleteDiskOffering uuid=178c662bfcdd4145920682c58ebcbed4

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	云盘规格的uuid			0.6

查询云盘规格（Query Disk Offering）¶

用户可以使用QueryDiskOffering来查询云盘规格. 例如:

QueryDiskOffering diskSize>=10000000

QueryDiskOffering volume.name=data1

原生域查询（Primitive Fields of Query）¶

请参见 disk offering inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
volume	volume inventory	从该云盘规格创建出来的所有云盘	0.6

标签（Tags）¶

用户可以使用resourceType=DiskOfferingVO在云盘规格上创建用户标签. 例如:

CreateUserTag tag=smallDisk resourceType=DiskOfferingVO resourceUuid=d6c49e73927d40abbfcf13852dc18367

系统标签（System Tags）¶

专用主存储（Dedicated Primary Storage）¶

当从云盘规格创建云盘的时候, 用户可以通过系统标签指定从哪个主存储创建云盘.

标签	描述	示例	起始支持版本
primaryStorage::allocator::uuid::{uuid}	如果该标签存在, 从该云盘规格创建的云盘会从uuid指定的主存储分配; 如果指定的主存储不存在或没有足够的容量，会报告分配失败（allocation failure）.	primaryStorage::allocator::uuid::b8398e8b7ff24527a3b81dc4bc64d974	0.6
primaryStorage::allocator::userTag::{tag}::required	如果该标签存在, 从该云盘规格创建的云盘会从带有用户标签tag的主存储分配; 如果指定的主存储不存在或没有足够的容量，会报告分配失败（allocation failure）.	primaryStorage::allocator::userTag::SSD::required	0.6
primaryStorage::allocator::userTag::{tag}	如果该标签存在, 从该云盘规格创建的云盘会首先尝试从带有用户标签tag的主存储分配, 如果找不到带指定标签的主存储或容量不足，ZStack会随机选择一个主存储分配这个云盘.	primaryStorage::allocator::userTag::SSD	0.6

如果在云盘规格上有多个上面提到的系统标签存在, 它们的优先顺序是:

primaryStorage::allocator::uuid::{uuid} > primaryStorage::allocator::userTag::{tag}::required > primaryStorage::allocator::userTag::{tag}

计算规格（Instance Offering）¶

概览（Overview）¶

计算规格定义了虚拟机的内存，CPU和主机分配算法（allocation algorithm）的规范（specification）; 它定义了虚拟机的计算资源容量（volume of computing resource).

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
cpuNum	VCPU数目, 请参见 CPU capacity			0.6
cpuSpeed	VCPU速度, 请参见 CPU capacity			0.6
memorySize	内存大小, 单位是字节			0.6
type	计算规格类型, 默认为UserVm, 请参见 type	是	UserVm VirtualRouter	0.6
allocatorStrategy	主机分配策略, 请参见 allocator strategy		DefaultHostAllocatorStrategy DesignatedHostAllocatorStrategy	0.6
state	请参见 state		Enabled Disabled	0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

CPU容量（CPU Capacity）¶

计算规格使用cpuNum和cpuSpeed来定义虚拟机的CPU容量. cpuNum直接代表了虚拟机所拥有的VCPU数量; cpuSpeed有些特别; 由于虚拟机的VCPU总是和主机上的物理CPU有相同的频率, 这里的cpuSpeed实际上是指在虚拟机管理程序中的VCPU权重（weight）. 虚拟机管理程序不同，对于cpuSpeed的使用和实现也不同.

KVM CPU速度（KVM CPU Speed）¶

在KVM中, ZStack会使用’cpuSpeed * cpuNum’的结果来设置libvirt的虚拟机XML配置:

<cputune>
  <shares>128</shares>
</cputune>

shares = cpuNum * cpuSpeed

类型（Type）¶

计算规格的类型; 当前有两种计算规格类型:

UserVm: 创建用户虚拟机所使用的计算规格.
VirtualRouter: 创建虚拟路由（virtual router）虚拟机所使用的计算规格; 请参见 virtual router.

分配策略（Allocator Strategy）¶

分配策略定义了选择用于创建虚拟机的主机的算法.

DefaultHostAllocatorStrategy ¶

DefaultHostAllocatorStrategy使用下面的算法:

输入参数（Input Parameters） ****************++++++++++++++++++ .. list-table:

:widths: 30 70
:header-rows: 1

* - 名字
  - 描述
* - **image**
  - 用于创建虚拟机的镜像
* - **L3 network**
  - 虚拟机的网卡将连接到的L3网络
* - **instance offering**
  - 计算规格
* - **tags**
  - 用于主机分配的标签

算法（Algorithm） *********+++++++++++++

l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)
host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1)
host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached_to_clusters_of_hosts(image, host_set3)
host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3)
host_set5 = remove_avoided_hosts(host_set4)
host_set6 = call_tag_plugin(tags, host_set5)

return randomly_pick_one_host(host_set6)

DesignatedHostAllocatorStrategy ¶

DesignatedHostAllocatorStrategy使用下面的算法:

输入参数（Input Parameters） ****************++++++++++++++++++ .. list-table:

:widths: 30 60 10
:header-rows: 1

* - 名字
  - 描述
  - 可选的
* - **image**
  - 用于创建虚拟机的镜像
  -
* - **L3 network**
  - 虚拟机的网卡将连接到的L3网络
  -
* - **instance offering**
  - 计算规格
  -
* - **tags**
  - 用于主机分配的标签
  -
* - **zone**
  - 虚拟机想要运行的区域
  - 是
* - **cluster**
  - 虚拟机想要运行的集群
  - 是
* - **host**
  - 虚拟机想要运行的主机
  - 是

算法（Algorithm） *********+++++++++++++

l2_networks = get_parent_l2_networks(l3_networks)
host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks()
check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1)

if host is not null:
   host_set2 = list(find_host_in_host_set1(host))
else if cluster is not null:
   host_set2 = find_host_in_cluster_and_host_set1(cluster)
else if zone is not null:
   host_set2 = find_host_in_zone_and_host_set1(zone)

host_set3 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set2)
host_set4 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set3)
primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached_to_clusters_of_hosts(image, host_set4)
host_set5 = remove_hosts_that_cannot_access_primary_storage(host_set4)
host_set6 = remove_avoided_hosts(host_set5)
host_set7 = call_tag_plugin(tags, host_set6)

return randomly_pick_one_host(host_set7)

可用状态（State）¶

计算规格有两种可用状态:

Enabled:

启用（Enabled）状态下，允许从计算规格创建虚拟机
Disabled:

禁用（Disabled）状态下，不允许从计算规格创建虚拟机

操作（Operations）¶

创建计算规格（Create Instance Offering）¶

用户可以使用CreateInstanceOffering来创建一个计算规格. 例如:

CreateInstanceOffering name=small cpuNum=1 cpuSpeed=1000 memorySize=1073741824

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
cpuNum	VCPU的数量, 请参见 CPU capacity			0.6
cpuSpeed	VCPU的熟读, 请参见 CPU capacity			0.6
memorySize	内存大小, 单位是字节			0.6
type	类型, 默认为UserVm, 请参见 type	是	UserVm VirtualRouter	0.6

删除计算规格（Delete Instance Offering）¶

用户可以使用DeleteInstanceOffering来删除一个计算规格. 例如:

DeleteInstanceOffering uuid=1164a094fea34f1e8265c802a8048bae

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	计算规格的uuid			0.6

改变可用状态（Change State）¶

用户可以使用ChangeInstanceOfferingState来改变一个计算规格的可用状态. 例如:

ChangeInstanceOfferingState uuid=1164a094fea34f1e8265c802a8048bae stateEvent=enable

参数（Parameters）¶

名字

描述

可选的

可选的参数值

起始支持版本

stateEvent

状态触发事件

启用: 改变可用状态为启用（Enabled）
禁用: 改变可用状态为禁用（Disabled）

enable
disable

0.6

uuid

计算规格的uuid

0.6

查询计算规格（Query Instance Offering）¶

用户可以使用QueryInstanceOffering来查询一个计算规格. 例如:

QueryInstanceOffering cpuSpeed=512 cpuNum>2

QueryInstanceOffering vmInstance.state=Stopped

原生域查询（Primitive Fields of Query）¶

请参见 instance offering inventory

嵌套和扩展域查询（Nested and Expanded Fields of Query)¶

域（Field）	清单（Inventory）	描述	起始支持版本
vmInstance	VM inventory	从该计算规格创建的所有虚拟机	0.6

标签（Tags）¶

用户可以使用resourceType=InstanceOfferingVO在计算规格上创建用户标签. 例如:

CreateUserTag resourceType=InstanceOfferingVO tag=web-server-offering resourceUuid=45f909969ce24865b1bbca4adb66710a

系统标签（System Tags）¶

专用主存储（Dedicated Primary Storage）¶

当创建虚拟机的时候, 用户可以通过系统标签指定从哪个主存储创建根云盘.

标签	描述	示例	起始支持版本
primaryStorage::allocator::uuid::{uuid}	如果该标签存在, 虚拟机的根云盘会从uuid指定的主存储分配; 如果指定的主存储不存在或没有足够的容量，会报告分配失败（allocation failure）.	primaryStorage::allocator::uuid::b8398e8b7ff24527a3b81dc4bc64d974	0.6
primaryStorage::allocator::userTag::{tag}::required	如果该标签存在, 虚拟机的根云盘会从带有用户标签tag的主存储分配; 如果指定的主存储不存在或没有足够的容量，会报告分配失败（allocation failure）	primaryStorage::allocator::userTag::SSD::required	0.6
primaryStorage::allocator::userTag::{tag}	如果该标签存在, 虚拟机的根云盘会首相尝试从带有用户标签tag的主存储分配, 如果找不到带指定标签的主存储或容量不足，ZStack会随机选择一个主存储分配这个根云盘;.	primaryStorage::allocator::userTag::SSD	0.6

如果在计算规格上有多个上面提到的系统标签存在, 它们的优先顺序是:

primaryStorage::allocator::uuid::{uuid} > primaryStorage::allocator::userTag::{tag}::required > primaryStorage::allocator::userTag::{tag}

虚拟机（Virtual Machine）¶

虚拟机（Virtual Machine）

概览（Overview）¶

虚拟机(VM)消耗了数据中心里的计算（computing）, 存储（storage）, 以及网络（network）资源.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
zoneUuid	所在区域的uuid, 请参见区域（Zone）和 location	是		0.6
clusterUuid	所在集群的uuid, 请参见集群（Cluster）和 location	是		0.6
hostUuid	运行虚拟机当前的主机uuid, 请参见主机（Host） and location	是		0.6
lastHostUuid	上一次运行虚拟机的主机uuid, 请参见主机（Host） and location	是		0.6
imageUuid	用于创建虚拟机根云盘的镜像uuid, 请参见镜像（Image）			0.6
instanceOfferingUuid	计算规格的uuid, 请参见计算规格（Instance Offering）			0.6
rootVolumeUuid	虚拟机根云盘的uuid, 请参见云盘（Volume）			0.6
defaultL3NetworkUuid	虚拟机默认L3网络的uuid, 请参见 L3 network 和 networks			0.6
type	虚拟机类型 UserVm: 用户创建的虚拟机 ApplianceVm: ZStack创建的帮助管理云的虚拟机		UserVm ApplianceVm	0.6
hypervisorType	虚拟机的虚拟机管理程序类型, 请参见主机（Host）和 hypervisor type		KVM	0.6
state	虚拟机的可用状态, 请参见 state	Created Starting Running Stopping Stopped Rebooting Destroying Destroyed Migrating Unknown		0.6
vmNics	nic inventory			0.6
allVolumes	volume inventory			0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
    "allVolumes": [
        {
            "createDate": "Dec 2, 2015 5:53:42 PM",
            "description": "Root volume for VM[uuid:d92a03ed745a0d32fe63dc30051d3862]",
            "deviceId": 0,
            "format": "qcow2",
            "installPath": "/opt/zstack/nfsprimarystorage/prim-a82b75ee064a48708960f42b800bd910/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-e9555324042542288ec20a67797d476c/e9555324042542288ec20a67797d476c.qcow2",
            "lastOpDate": "Dec 2, 2015 5:53:42 PM",
            "name": "ROOT-for-vm-4-vlan10",
            "primaryStorageUuid": "a82b75ee064a48708960f42b800bd910",
            "rootImageUuid": "f1205825ec405cd3f2d259730d47d1d8",
            "size": 419430400,
            "state": "Enabled",
            "status": "Ready",
            "type": "Root",
            "uuid": "e9555324042542288ec20a67797d476c",
            "vmInstanceUuid": "d92a03ed745a0d32fe63dc30051d3862"
        }
    ],
    "clusterUuid": "b429625fe2704a3e94d698ccc0fae4fb",
    "createDate": "Dec 2, 2015 5:53:42 PM",
    "defaultL3NetworkUuid": "6572ce44c3f6422d8063b0fb262cbc62",
    "hostUuid": "d07066c4de02404a948772e131139eb4",
    "hypervisorType": "KVM",
    "imageUuid": "f1205825ec405cd3f2d259730d47d1d8",
    "instanceOfferingUuid": "04b5419ca3134885be90a48e372d3895",
    "lastHostUuid": "d07066c4de02404a948772e131139eb4",
    "lastOpDate": "Dec 2, 2015 5:53:42 PM",
    "name": "vm-4-vlan10",
    "rootVolumeUuid": "e9555324042542288ec20a67797d476c",
    "state": "Running",
    "type": "UserVm",
    "uuid": "d92a03ed745a0d32fe63dc30051d3862",
    "vmNics": [
        {
            "createDate": "Dec 2, 2015 5:53:42 PM",
            "deviceId": 0,
            "gateway": "10.0.0.1",
            "ip": "10.0.0.218",
            "l3NetworkUuid": "6572ce44c3f6422d8063b0fb262cbc62",
            "lastOpDate": "Dec 2, 2015 5:53:42 PM",
            "mac": "fa:ef:34:5c:6c:00",
            "netmask": "255.255.255.0",
            "uuid": "fb8404455cf84111958239a9ec19ca28",
            "vmInstanceUuid": "d92a03ed745a0d32fe63dc30051d3862"
        }
    ],
    "zoneUuid": "3a3ed8916c5c4d93ae46f8363f080284"
}

位置（Location）¶

由于ZStack通过区域（zones）, 集群（clusters）, 和主机（hosts）组织计算资源（computing resources）, 因此虚拟机的位置可以通过zoneUuid, clusterUuid, 和hostUuid标识. 当虚拟机开始运行后, 这些UUIDs会被设置为标识虚拟机当前位置的值; 当虚拟机停止运行后, hostUuid会被设置为NULL, zoneUuid和clusterUuid会保持不变. lastHostUuid比较特别, 因为它代表了虚拟机上次运行的主机; 对于新创建的虚拟机, lastHostUuid被设置为NULL; 一旦虚拟机停止运行, lastHostUuid就被设置为之前的hostUuid值.

在:ref:`host allocator strategy <instance offering allocator strategy>`章节中已经详细描述了对于新创建虚拟机的主机选择算法. 在本章后面的小节中, 会展示启动和迁移虚拟机的策略.

网络（Networks）¶

虚拟机可以有一个或多个:ref:L3 networks <l3Network>; vm nics 包含了每个L3网络的IP地址, 子网掩码, MAC地址信息. 如果一个虚拟机有不止一个L3网络，那么它必须制定一个默认的L3网络，这个网络提供默认的路由（routing), DNS, 和主机名; 如果一个虚拟机只有一个L3网络, 那么它就自动成为默认的L3网络.

下面的示例会帮助理解什么是默认的L3网络. 假设你有一个如下图所示的用户虚拟机:

虚拟机所连接的三个L3网络都提供SNAT服务, 并且默认的L3网络是10.10.1.0/24:

CIDR: 10.10.1.0/24
Gateway: 10.10.1.1
DNS domain: web.tier.mycompany.com

那么虚拟机的路由表（routing table）将会是这样:

default via 10.10.1.1 dev eth0
10.1.0/24 dev eth0  proto kernel  scope link  src 10.10.1.99
168.0.0/24 dev eth1  proto kernel  scope link  src 192.168.0.10
16.0.0/24 dev eth2  proto kernel  scope link  src 172.16.0.55

可见，默认路由（default routing）指向了**10.10.1.1**，也就是默认L3网络的网关; 同时虚拟机的/etc/resolv.conf如下所示:

search web.tier.mycompany.com
nameserver 10.10.1.1

也就是说DNS域也是来自默认L3网络; DNS域名服务器（DNS name server）也是设置为**10.10.1.1**, 因为默认L3网络提供了DNS服务器; 最终, 虚拟机的FQDN(Full Qualified Domain Name)看起来会像这样:

vm2.web.tier.mycompany.com

它是从DNS域扩展而来的.

虚拟机网络接口清单（VM Nic Inventory）¶

名字	描述	可选的	起始支持版本
uuid	请参见资源属性		0.6
vmInstanceUuid	父虚拟机的uuid		0.6
l3NetworkUuid	网卡所连接的:ref:`l3 network <l3Network>`的uuid		0.6
ip	IP地址		0.6
mac	MAC地址		0.6
netmask	子网掩码		0.6
gateway	网关		0.6
metaData	内部使用的保留域	是	0.6
deviceId	标识网卡在客户操作系统（guest operating system）以太网设备中顺序的整形数字. 例如, 0通常代表eth0, 1通常代表eth1.		0.6

在ZStack当前版本中, 一旦虚拟机的网卡被分配了IP地址, 这个IP地址将一直伴随这个网卡直到虚拟机被删除.

示例 ¶

{
    "createDate": "Dec 2, 2015 5:53:42 PM",
    "deviceId": 0,
    "gateway": "10.0.0.1",
    "ip": "10.0.0.218",
    "l3NetworkUuid": "6572ce44c3f6422d8063b0fb262cbc62",
    "lastOpDate": "Dec 2, 2015 5:53:42 PM",
    "mac": "fa:ef:34:5c:6c:00",
    "netmask": "255.255.255.0",
    "uuid": "fb8404455cf84111958239a9ec19ca28",
    "vmInstanceUuid": "d92a03ed745a0d32fe63dc30051d3862"
}

云盘（Volumes）¶

`allVolumes`域是由:ref:`volume inventory <volume inventory>`组成的列表，其中包含了根云盘（root volume）和数据云盘（data volumes）. 如果要找出其中的根云盘，用户可以通过迭代这个列表，并检查云盘的类型或者使用域’rootVolumeUuid’来匹配云盘的UUID. 根云盘会一直和虚拟机伴随，直到虚拟机被删除.

虚拟机管理程序类型（Hypervisor Type）¶

根据虚拟机创建方式的不同，虚拟机的虚拟机管理程序类型可能是从镜像的虚拟机管理程序类型，或主机的虚拟机管理程序类型继承而来的.

从RootVolumeTemplate创建的虚拟机:

由于镜像中已经安装有操作系统, 虚拟机会被创建在和镜像有相同虚拟机管理程序类型的主机上, 因此虚拟机的虚拟机管理程序类型是从镜像继承而来的.
从ISO文件创建的虚拟机: 由于会使用ISO安装操作系统到虚拟机的空白根云盘上, 虚拟机可能被创建在拥有任何类型的虚拟机管理程序的主机上, 因此虚拟机的虚拟机管理程序类型是从创建的主机上继承而来的.

可用状态（State）¶

虚拟机的生命周期中有10中可用状态.

Created

在这种状态时，虚拟机还只是创建于数据库中的一个记录而已, 并没有在任何的主机上启动. 这个状态仅在创建一个新的虚拟机的时候出现.
Starting

在这种状态时，虚拟机正在一个主机上启动
Running

在这种状态时，虚拟机正运行在一个主机
Stopping

在这种状态时，虚拟机正在一个主机上停止过程中
Stopped

在这种状态时，虚拟机已经停止，没有运行在任何主机上
Rebooting

在这种状态时，虚拟机正在先前运行的主机上重启
Destroying

在这种状态时，虚拟机正在被删除
Migrating

在这种状态时，虚拟机正在被迁移到另一个主机上
Unknown

由于某些原因, 例如, 由于失去和主机的连接, ZStack不能检查虚拟机的可用状态

ZStack会使用VmTracer来周期性的跟踪虚拟机的状态; 默认的间隔时间（interval）是60秒. 虚拟机的状态可能会被ZStack之外的因素影响, 例如, 主机掉电（power outage）会导致所有该主机上运行的虚拟机停止运行; 一旦VmTracer检测到虚拟机的实际状态和数据库中的记录不匹配, 数据库会被更新为实际的状态. 如果VmTracer不能成功检查虚拟机的状态, 例如, 由于ZStack管理节点和主机之间的连接丢失, 虚拟机会被设置为Unknown状态; 一旦VmTracer再次成功检测到虚拟机的状态, 例如, ZStack管理节点和主机之间的连接恢复之后, 虚拟机的状态也会被更新为实际的状态.

操作（Operations）¶

创建虚拟机（Create VM）¶

用户可以使用CreateVmInstance来创建一个虚拟机. 例如:

CreateVmInstance name=vm imageUuid=d720ff0c60ee48d3a2e6263dd3e12c33 instanceOfferingUuid=76789b62aeb542a5b4b8b8488fbaced2 l3NetworkUuids=37d3c4a1e2f14a1c8316a23531e62988,05266285f96245f096f3b7dce671991d defaultL3NetworkUuid=05266285f96245f096f3b7dce671991d

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
instanceOfferingUuid	:ref:`instance offering <instance offering>`的uuid			0.6
imageUuid	:ref:`image <image>`的uuid. 镜像只可以是RootVolumeTemplate或ISO类型			0.6
l3NetworkUuids	:ref:`L3 network <l3Network>`的uuid列表			0.6
type	保留的域, 默认为UserVm		UserVm ApplianceVm	0.6
rootDiskOfferingUuid	根云盘:ref:disk offering <disk offering>`的uuid, 请参见 :ref:`rootDiskOfferingUuid	是		0.6
dataDiskOfferingUuids	disk offering <disk offering>`的uuid列表, 请参见 :ref:`dataDiskOfferingUuids	是		0.6
zoneUuid	如果非null, 虚拟机将在所指定的区域上创建; clusterUuid和hostUuid优先于这个参数的设置	是		0.6
clusterUuid	如果非null, 虚拟机将在所指定的集群上创建; hostUuid优先于这参数的设置	是		0.6
hostUuid	如果非null, 虚拟机将在所指定的主机上创建	是		0.6
defaultL3NetworkUuid	如果l3NetworkUuids包含了多余一个的L3网络的UUID, 这个参数指定哪个L3网络是默认的L3网络. 如果l3NetworkUuids只有一个L3网络UUID，可不设置这个参数.	是		0.6q

rootDiskOfferingUuid ¶

如果虚拟机是从ISO镜像创建的, 用户必须通过rootDiskOfferingUuid指定一个:ref:`disk offering <disk offering>，这样ZStack才能知道根云盘的磁盘大小; 如果虚拟机是从RootVolumeTemplate镜像创建的, 可以忽略这个域.

dataDiskOfferingUuids ¶

通过在dataDiskOfferingUuids指定云盘规格的UUID列表, 用户可以创建一个挂载了多个数据云盘的虚拟机. 如果某个数据云盘创建失败了，整个虚拟机的创建也会失败.

停止虚拟机（Stop VM）¶

用户可以使用StopVmInstance来停止一个虚拟机. 例如:

StopVmInstance uuid=76789b62aeb542a5b4b8b8488fbaced2

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	虚拟机的uid			0.6

启动虚拟机（Start VM）¶

用户可以使用StartVmInstance来启动一个虚拟机. 例如:

StartVmInstance uuid=76789b62aeb542a5b4b8b8488fbaced2

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	虚拟机的uuid			0.6

当启动一个虚拟机的时候, ZStack会使用LastHostPreferredAllocatorStrategy算法尽可能的使用虚拟机之前运行的主机启动虚拟机; 如果用虚拟机之前运行的主机不可用, 会使用:ref:`DesignatedHostAllocatorStrategy`算法在一个新的主机上启动虚拟机.

重启虚拟机（Reboot VM）¶

用户可以使用RebootVmInstance来重启一个虚拟机. 例如:

RebootVmInstance uuid=76789b62aeb542a5b4b8b8488fbaced2

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	虚拟机的uuid			0.6

删除虚拟机（Destroy VM）¶

用户可以使用DestroyVmInstance来删除一个虚拟机. 例如:

DestroyVmInstance uuid=76789b62aeb542a5b4b8b8488fbaced2

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	虚拟机的uuid			0.6

迁移虚拟机（Migrate VM）¶

管理员可以使用MigrateVm来在线迁移（live migrate）一个正在运行的虚拟机，从当前主机到另一个主机. 例如:

MigrateVm vmInstanceUuid=76789b62aeb542a5b4b8b8488fbaced2 hostUuid=37d3c4a1e2f14a1c8316a23531e62988

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
vmInstanceUuid	虚拟机的uuid			0.6
hostUuid	目标主机的uuid; 如果指定这个参数, ZStack会尝试自动选择合适的主机	是		0.6

虚拟机只能在两个拥有完全相同操作系统版本的两个主机之间迁移. 对于KVM而言, 操作系统的版本取决于三个系统标签（system tag): os::distribution, os::release, 和 os::version.

在虚拟机迁移时, *MigrateVmAllocatorStrategy*检查操作系统版本并使用类似于:ref:`DesignatedHostAllocatorStrategy`的算法来选择目标迁移主机.

挂载数据云盘（Attach Data Volume）¶

请参见 attach volume to vm.

卸载数据云盘（Detach Data volume）¶

请参见 detach volume from vm.

查询虚拟机（Query VM）¶

用户可以使用QueryVmInstance来查询虚拟机. 例如:

QueryVmInstance state=Running hostUuid=33107835aee84c449ac04c9622892dec

QueryVmInstance vmNics.eip.guestIp=10.23.109.23

原生域查询（Primitive Fields of Query）¶

请参见 VM inventory

嵌套和扩展域查询（Nested And Expanded Fields of Query）¶

域（Field）	清单（Inventory）	描述	起始支持版本
vmNics	VM nic inventory	虚拟机拥有的所有网卡	0.6
allVolumes	volume inventory	虚拟机拥有的所有云盘	0.6
zone	zone inventory	所在区域	0.6
cluster	cluster inventory	所在集群	0.6
host	host inventory	父主机	0.6
image	image inventory	用于创建该虚拟机的镜像	0.6
instanceOffering	instance offering inventory	用于创建该虚拟机的计算规格	0.6
rootVolume	volume inventory	该虚拟机的根云盘	0.6

查询虚拟机的网卡（Query VM Nic）¶

用户可以使用QueryVmNic来查询虚拟机的网卡. 例如:

QueryVmNic gateway=10.1.1.1

QueryVmNic eip.guestIp=11.168.2.13

网卡原生域查询（Primitive Fields of Query Nic）¶

请参见 VM nic inventory

网卡嵌套和扩展域查询（Nested And Expanded Fields of Query Nic）¶

域（Field）	清单（Inventory）	起始支持版本
vmInstance	VM inventory	0.6
l3Network	L3 network inventory	0.6
eip	EIP inventory	0.6
portForwarding	port forwarding inventory	0.6
securityGroup	security group inventory	0.6

全局配置（Global Configurations）¶

dataVolume.deleteOnVmDestroy ¶

名字	类别	默认值	可选的参数值
dataVolume.deleteOnVmDestroy	vm	false	true false

如果设置为true, 当虚拟机被删除时，虚拟机上挂载的数据云盘也会被删除; 否则, 数据云盘仅会被卸载.

标签（Tags）¶

用户可以使用resourceType=VmInstanceVO在虚拟机上创建用户标签. 例如:

CreateUserTag tag=web-server-vm resourceType=VmInstanceVO resourceUuid=a12b3cc9ee4440dfb00d41c1d2f72d08

系统标签（System Tags）¶

HostName ¶

用户可以为一个虚拟机的默认L3网络指定一个主机名. 这个标签通常在调用CreateVmInstance时在*systemTags*参数中指定; 如果默认的L3网络有DNS域, 虚拟机操作系统收到的主机名会自动使用这个DNS域扩展. 例如, 假设主机名为’web-server’ 并且默认L3网络的DNS域为’zstack.org’, 那么最终的机器名将会是’web-server.zstack.org’.

标签	描述	示例	起始支持版本
hostname::{hostname}	默认L3网络的机器名	hostname::web-server	0.6

例如:

CreateVmInstance name=vm systemTags=hostname::vm1 imageUuid=d720ff0c60ee48d3a2e6263dd3e12c33 instanceOfferingUuid=76789b62aeb542a5b4b8b8488fbaced2 l3NetworkUuids=37d3c4a1e2f14a1c8316a23531e62988,05266285f96245f096f3b7dce671991d defaultL3NetworkUuid=05266285f96245f096f3b7dce671991d

安全组（Security Group）¶

安全组（Security Group）

概览（Overview）¶

安全组就像一个虚拟防火墙（virtual firewall）一样控制虚拟机的网络通信. 根据L2网络采用的隔离方法（isolation method）的不同, 用户可以把安全组作为防火墙或者三层隔离方法使用. 例如, 如果多个租户共享一个L3网络, 每个租户都可以创建一个安全组来保护他们的虚拟机不被其他租户访问. 租户也可以将安全组和:ref:`EIP <eip>`一起使用来控制哪些端口向共有网络开放.

安全组包含了一系列的控制端口可访问性（accessibility）的规则（rules）. 安全组可以挂载到一个或多个L3网络; 虚拟机挂载到L3网络的网卡可以加入这些安全组. 一个虚拟机的网卡可以加入多个安全组, 安全组的规则会合并在一起并应用到该网卡上.

安全组的实现根据虚拟机管理程序的不同而有所不同; 并不是所有的虚拟机管理程序都支持安全组. ZStack当前版本是通过在KVM虚拟机管理程序中使用IPTables来实现安全组的.

要使用安全组, L3网络必须要通过:ref:`AttachNetworkServiceToL3Network <l3Network attach service>`启用安全组服务, 例如:

AttachNetworkServiceToL3Network l3NetworkUuid=50e637dc68b7480291ba87cbb81d94ad networkServices='{"1d1d5ff248b24906a39f96aa3c6411dd": ["SecurityGroup"]}'

对于有多个网卡的虚拟机, 所有的网卡都可以加入安全组.

安全组实际上是一个分布式的防火墙（distributed firewall）; 每次规则变化或者加入或删除网卡都会导致多个主机上的防火墙规则（firewall rules）被更新. 因此, 一些安全组的API使用异步方式实现（asynchronous manner）, 所以在这些API返回之后规则可能不会立即生效. 如果同一个端口指定了多个规则, 只有最宽松的规则（the most permissive rule）会生效. 例如, 如果规则rule1允许从12.12.12.12访问端口22但规则rule2允许所有人访问端口22, 那么规则rule2会优先起作用.

安全组的清单（Security Group Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
state	安全组可用状态; 当前版本ZStack未实现		Enabled Disabled	0.6
rules	:ref:`security group rule inventory <security group rule inventory>`列表			0.6
attachedL3NetworkUuids	安全组挂载的:ref:`L3 networks <l3Network>`的uuid列表			0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

空的安全组会有默认的策略控制进出的流量; 对于进入（Ingress）的流量, 默认的策略是拒绝（deny）, 也就是说对于这个空白安全组的网卡所有的流入流量（inbound traffics）都被阻止（blocked）了; 对于外出（Egress）的流量, 默认的策略是允许（allow）, 也就是说对于这个空白安全组的网卡所有的流出流量都被允许. 管理员可以通过修改全局配置:ref:ingress.defaultPolicy 和 :ref:`egress.defaultPolicy`来改变默认的策略.

示例 ¶

{
    "attachedL3NetworkUuids": [
        "0b48770e593e400c8f54e71fd4e7f514"
    ],
    "createDate": "Nov 16, 2015 1:02:22 AM",
    "lastOpDate": "Nov 16, 2015 1:02:22 AM",
    "name": "sg-in",
    "rules": [
        {
            "allowedCidr": "0.0.0.0/0",
            "createDate": "April 29, 2015 9:57:10 PM",
            "state": "Enabled",
            "endPort": 22,
            "lastOpDate": "Nov 29, 2015 9:57:10 PM",
            "protocol": "TCP",
            "securityGroupUuid": "9e0a72fe64814900baa22f78a1b9d235",
            "startPort": 22,
            "type": "Ingress",
            "uuid": "a338d11be18d4e288223597682964dc8"
        }
    ],
    "state": "Enabled",
    "uuid": "9e0a72fe64814900baa22f78a1b9d235"
}

安全组规则的清单（Security Group Rule Inventory）¶

属性（Properties）¶

名字	描述	可选的参数值	起始支持版本
uuid	请参见资源属性		0.6
securityGroupUuid	父安全组的uuid		0.6
type	请参见 traffic type	Ingress Egress	0.6
protocol	流量协议烈性（traffic protocol type）	TCP UDP ICMP	0.6
startPort	如果协议是TCP/UDP, 它是端口范围（port range）的起始端口号; 如果协议是ICMP, 它是ICMP类型（type）	对于TCP/UDP: 0 - 65535 对于ICMP: 请参见 ICMP type and code , 使用’-1’来表示所有的类型.	0.6
endPort	如果协议是TCP/UDP, 它是端口范围（port range）的起始端口号; 如果协议是ICMP, 它是ICMP代码（code）	对于TCP/UDP: 0 - 65535 对于ICMP: 请参见 ICMP type and code, 使用’-1’来表示所有的类型.	0.6
allowedCidr	请参见 allowedCidr		0.6
state	规则的可用状态, 当前版本未实现	Enabled Disabled	0.6
createDate	请参见资源属性		0.6
lastOpDate	请参见资源属性		0.6

流量类型（Traffic Type）¶

有两种流量类型:

Ingress

访问虚拟机网卡的流入的流量
Egress

离开虚拟机网卡的流出的流量

允许的CIDR（Allowed CIDR）¶

根据流量类型的不同, 允许的CIDR有不同的含义; 格式为:

ipv4地址/网络前缀（network_prefix）

例如: 12.12.12.12/24

如果流量类型是Ingress, 允许的CIDR是允许访问虚拟机网卡的源CIDR（source CIDR）; 例如, 规则:

startPort: 22
endPort: 22
protocol: TCP
type: Ingress
allowedCidr: 12.12.12.12/32

表示只有从IP(12.12.12.12)来的TCP流量允许访问端口22.

如果流量类型是Egress, 允许的CIDR是允许从虚拟机网卡离开并到达的目的地CIDR（destination CIDR）; 例如, 规则:

startPort: 22
endPort: 22
protocol: TCP
type: Egress
allowedCidr: 12.12.12.12/32

表示只允许从目的地为IP为12.12.12.12端口为22的TCP的流量允许流出.

特别的是, CIDR 0.0.0.0/0表示所有IP地址.

示例 ¶

{
     "allowedCidr": "0.0.0.0/0",
     "state": "Enabled",
     "startPort": 22,
     "endPort": 22,
     "protocol": "TCP",
     "type": "Ingress",
     "createDate": "Nov 29, 2015 9:57:10 PM",
     "lastOpDate": "Nov 29, 2015 9:57:10 PM",
     "uuid": "a338d11be18d4e288223597682964dc8"
     "securityGroupUuid": "9e0a72fe64814900baa22f78a1b9d235",
}

安全组和L3网络（Security Group And L3 Network）¶

就像之前提到过的一样, 一个安全组可以被挂载到多个L3网络. 这样设计是考虑到安全组是一系列的防火墙规则，它们可以被应用到任何L3网络上. 例如, 两个不同的L3网络可能有相同的防火墙规则，那么把他们放在同一个安全组中更加合理.

具有相同安全组的不同L3网络上的虚拟机网卡则不相关. 正如在:ref:`Allowed CIDR <allowed cidr>`中提到的那样, 在一个安全组中并且在同一个L3网络的虚拟机网卡不被allowedCIDR规则所影响, 他们总是可以互相访问开放了的端口. 然而, 如果两个网卡在同一个安全组中但来自不同的L3网络, 那么当他们互相访问的时候，会受到allowedCIDR规则的限制.

如果你觉得在多个L3网络上使用同一个安全组会使人困惑, 你总是可以对每一个L3网络创建一个单独的安全组.

操作（Operations）¶

创建安全组（Create Security Group）¶

用户可以使用CreateSecurityGroup来创建一个安全组. 例如:

CreateSecurityGroup name=web

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6

添加规则到安全组（Add Rules To Security Group）¶

用户可以使用AddSecurityGroupRule添加规则到安全组. 例如:

AddSecurityGroupRule securityGroupUuid=29a0f801f77b4b4f866fb4c9503d0fe9 rules="[{'type':'Ingress', 'protocol':'TCP', 'startPort':'22', 'endPort':'22', 'allowedCidr':'0.0.0.0/0'}]"

这个命令是异步执行的, 在它返回后可能规则仍然没有对所有虚拟机网卡生效.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
securityGroupUuid	安全组的uuid			0.6
rules	:ref:`SecurityGroupRuleAO <SecurityGroupRuleAO>`列表			0.6

SecurityGroupRuleAO ¶

名字	描述	可选的	可选的参数值	起始支持版本
type	流量类型, 请参见 traffic type		Ingress Egress	0.6
startPort	起始端口或ICMP类型		port: 0 - 65535 ICMP类型: 请参见 ICMP type and code	0.6
endPort	结束端口或ICMP代码		port: 0 - 65535 ICMP代码: 请参见 ICMP type and code	0.6
protocol	协议类型		TCP UDP ICMP	0.6
allowedCidr	请参见 allowed CIDR; 默认为 0.0.0.0/0	是		0.6

从安全组删除规则（Delete Rules From Security Group）¶

用户可以使用DeleteSecurityGroupRule来从安全组删除规则. 例如:

DeleteSecurityGroupRule ruleUuids=a338d11be18d4e288223597682964dc8,9e0a72fe64814900baa22f78a1b9d235

这个命令是异步执行的, 在它返回后可能规则仍然没有对所有的主机上生效.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
ruleUuids	:ref:`rule inventory <security group rule inventory>`的uuid列表			0.6

添加虚拟机网卡到安全组（Add VM Nics Into Security Group）¶

用户可以使用AddVmNicToSecurityGroup来添加虚拟机网卡到安全组. 例如:

AddVmNicToSecurityGroup securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 vmNicUuids=b429625fe2704a3e94d698ccc0fae4fb,6572ce44c3f6422d8063b0fb262cbc62,d07066c4de02404a948772e131139eb4

这个命令是异步执行的, 在它返回后可能规则仍然没有对所有的网卡生效.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
securityGroupUuid	安全组的uuid			0.6
vmNicUuids	:ref:`vm nic inventory <vm nic inventory>`的uuid列表			0.6

从安全组移除虚拟机网卡（Remove VM Nics from Security Group）¶

用户可以使用DeleteVmNicFromSecurityGroup来从安全组删除虚拟机网卡. 例如:

DeleteVmNicFromSecurityGroup securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 vmNicUuids=b429625fe2704a3e94d698ccc0fae4fb,6572ce44c3f6422d8063b0fb262cbc62,d07066c4de02404a948772e131139eb4

这个命令是异步执行的, 在它返回后可能规则仍然没有对所有虚拟机网卡生效.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
securityGroupUuid	安全组的uuid			0.6
vmNicUuids	:ref:`vm nic inventory <vm nic inventory>`的uuid列表			0.6

挂载安全组到L3网络（Attach Security Group To L3 Network）¶

用户可以使用AttachSecurityGroupToL3Network来挂载一个安全组到L3网络. 例如:

AttachSecurityGroupToL3Network securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 l3NetworkUuid=95dede673ddf41119cbd04bcb5d73660

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
securityGroupUuid	安全组的uuid			0.6
l3NetworkUuid	L3网络的uuid			0.6

从L3网络卸载安全组（Detach Security Group From L3 Network）¶

用户可以使用DetachSecurityGroupFromL3Network来从一个L3网络卸载一个安全组:

DetachSecurityGroupFromL3Network securityGroupUuid=0b48770e593e400c8f54e71fd4e7f514 l3NetworkUuid=95dede673ddf41119cbd04bcb5d73660

卸载后, 所有的规则都会从这个L3网络上的并且在这个安全组中的虚拟机网卡上删除. 这个命令是异步执行的, 在它返回后可能规则仍然没有对所有虚拟机网卡生效.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
securityGroupUuid	安全组的uuid			0.6
l3NetworkUuid	L3网络的uuid			0.6

删除安全组（Delete Security Group）¶

用户可以使用DeleteSecurityGroup来删除安全组. 例如:

DeleteSecurityGroup uuid=0b48770e593e400c8f54e71fd4e7f514

删除后, 所欲规则都会从这个安全组中的虚拟机网卡移除. 这个命令是异步执行的, 在它返回后可能规则仍然没有对所有虚拟机网卡生效.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	安全组的uuid			0.6

查询安全组（Query Security Group）¶

用户可以使用QuerySecurityGroup来查询安全组. 例如:

QuerySecurityGroup rules.startPort=22 rules.type=Ingress rules.protocol=TCP

QuerySecurityGroup vmNic.ip=192.168.0.205

原生域（Primitive Fields）¶

请参见 security group inventory.

嵌套和扩展域（Nested And Expanded Fields）¶

域（Field)	清单（Inventory）	描述	起始支持版本
rules	security group rule inventory	安全组中的规则	0.6
vmNic	VM nic inventory	加入该安全组的虚拟机网卡	0.6
l3Network	L3 network inventory	该安全组挂载的L3网络	0.6

全局配置（Global Configurations）¶

ingress.defaultPolicy ¶

名字	类别	默认值	可选的参数值
ingress.defaultPolicy	securityGroup	deny	deny accept

空白安全组的默认流入策略.

egress.defaultPolicy ¶

名字	类别	默认值	可选的参数值
egress.defaultPolicy	securityGroup	accept	deny accept

空白安全组的默认流出策略.

标签（Tags）¶

用户可以使用resourceType=SecurityGroupVO在安全组上创建标签. 例如:

CreateUserTag tag=web-tier-security-group resourceType=SecurityGroupVO resourceUuid=f25a28fdb21147f8b183296550a98799

网络服务和虚拟路由器（Network Services And Virtual Router）¶

网络服务和虚拟路由器（Network Services And Virtual Router）

概览（Overview）¶

ZStack支持很多OSI　4 ~ 7层的网络服务: DHCP, DNS, SNAT, EIP, 和端口转发（PortForwarding）. L3网络可以启用它所在的L2网络提供的网络服务. 请参考网络服务（Network Services）获取支持的网络服务列表.

ZStack提供了一个内建的（builtin）网络服务模块（network service provider） – 虚拟机路由器模块（Virtual Router Provider）, 它是通过定制的Linux虚拟机来实现的网络服务. 当在一个提供虚拟机路由器模块的L3网络上创建一个新的虚拟机时，如果这个特殊的虚拟机之前还不存在，一个特殊的提供虚拟路由器的虚拟机将被创建.

虚拟路由器的虚拟机的计算容量（Computing capacity, CPU, 内存等）是由一个特殊的称为虚拟路由器规格（virtual router offering）的计算规格（instance offering）定义的. 除了CPU和内存以外, 在虚拟路由器规格中还可以定义许多的额外参数，例如镜像（image）, 管理L3网络（management L3 network）, 共有L3网络（public L3 network）; 详细信息请参见:ref:virtual router offering inventory <virtual router offering inventory>.

虽然在ZStack当前版本中虚拟机路由器模块是唯一的网络服务模块(除了安全组模块), 但网络服务框架（network services framework）是高度可插件扩展的（highly pluggable），第三方可以很容易通过一些小插件实现他们自己的功能.

网络拓扑（Network typology）¶

一个虚拟机路由器通常包含三个L3网络:

管理网络（Management Network）:

ZStack管理节点通过这个网络和虚拟路由器代理（virtual router agents）通信; eth0是连接在管理网络上的网卡.
公有网络（Public Network）:

公有网络提供互联网访问（internet access）, 并且为使用EIP的用户虚拟机提供公有IP地址, 端口转发（port forwarding）, 和源网络地址转换（source NAT）; eth1是连接在公有网络上的网卡.
客户网络（Guest Network）

这个网络用于用户虚拟机连接. eth2是连接在客户网络上的网卡.

在普通的设置中, 所有三个网络应该是不同的L3网络; 然而, 根据你所使用网络拓扑的不同，可以合并为两个或者一个网络.

对于一个:ref:flat network <l3Network typology>, 只有一个虚拟机路由器虚拟机仅仅提供DHCP和DNS服务, 网络拓扑可以是像这样的:

合并公有网络和客户网络; 一个独立的管理网络
合并所有三个网络

对于一个 private network or isolated network, 有一个虚拟机路由器虚拟机提供DHCP, DNS, SNAT; 用户可以选择提供或不提供EI和端口转发; 网络拓扑可以是像这样的:

合并公有网络和管理网络; 一个独立的客户网络
独立的公有网络, 管理网络, 和客户网络

虚拟机路由器网络服务（Virtual Router Network Services）¶

在ZStack当前版本中, 虚拟机路由器模块提供了五种网络服务: DHCP, DNS, SNAT, EIP, 以及端口转发; 由于EIP和端口转发有它们自己的API，我们将在专门的章节中介绍它们.

DHCP

在客户L3网络中, 虚拟机路由器虚拟机可以作为一个DHCP服务器工作; 虚拟路由器DHCP服务器使用静态的IP-MAC映射，因此用户虚拟机将总会获得同一个IP地址.
DNS

无论DNS服务是否启用, 虚拟路由器虚拟机在客户L3网络中总是作为DNS服务器. 如果DNS服务启用, 客户L3网络的DNS会作为虚拟路由器虚拟机的上一级DNS服务器（upstream DNS servers）. 对于如果添加DNS到一个L3网络，请参见 L3 network for how to add DNS to a L3 network.
SNAT

虚拟路由器虚拟机可以作为路由器向用户虚拟机提供原网络地址转换（source NAT）.

清单（Inventory）¶

除了在:ref:`VM instance inventory <vm inventory>`中提供的属性以外, 虚拟路由器虚拟机还有以下一些额外属性.

属性（Properties）¶

名字	描述	可选的参数值	起始支持版本
applianceVmType	特殊虚拟机的类型（appliance VM type）	VirtualRouter	0.6
managementNetworkUuid	管理L3网络的uuid		0.6
defaultRouteL3NetworkUuid	虚拟路由虚拟机提供默认路由（default routing）的L3网络的uuid		0.6
publicNetworkUuid	公有L3网络的uuid		0.6
status	虚拟路由器代理（virtual router agent）的连接状态	Connecting Connected Disconnected	0.6

示例 ¶

{
    "allVolumes": [
        {
            "createDate": "August 2, 2015 5:54:12 PM",
            "description": "Root volume for VM[uuid:f1e76cb2ef0c4dfa87f3b807eb4d7437]",
            "deviceId": 0,
            "format": "qcow2",
            "installPath": "/opt/zstack/nfsprimarystorage/prim-a82b75ee064a48708960f42b800bd910/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-2acccd875e364b53824def6248c94a51/2acccd875e364b53824def6248c94a51.qcow2",
            "lastOpDate": "Dec 2, 2015 5:54:12 PM",
            "name": "ROOT-for-virtualRouter.l3.8db7eb2ccdab4c4eb4784e46895bb016",
            "primaryStorageUuid": "a82b75ee064a48708960f42b800bd910",
            "rootImageUuid": "b4fe2ebbc4522e199d36985012254d7d",
            "size": 462945280,
            "state": "Enabled",
            "status": "Ready",
            "type": "Root",
            "uuid": "2acccd875e364b53824def6248c94a51",
            "vmInstanceUuid": "f1e76cb2ef0c4dfa87f3b807eb4d7437"
        }
    ],
    "applianceVmType": "VirtualRouter",
    "clusterUuid": "b429625fe2704a3e94d698ccc0fae4fb",
    "createDate": "Dec 2, 2015 5:54:12 PM",
    "defaultRouteL3NetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
    "hostUuid": "d07066c4de02404a948772e131139eb4",
    "hypervisorType": "KVM",
    "imageUuid": "b4fe2ebbc4522e199d36985012254d7d",
    "instanceOfferingUuid": "f50a232a1448401cb8d049aad9c3860b",
    "lastHostUuid": "d07066c4de02404a948772e131139eb4",
    "lastOpDate": "Dec 2, 2015 5:54:12 PM",
    "managementNetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
    "name": "virtualRouter.l3.8db7eb2ccdab4c4eb4784e46895bb016",
    "rootVolumeUuid": "2acccd875e364b53824def6248c94a51",
    "publicNetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
    "state": "Running",
    "status": "Connected",
    "type": "ApplianceVm",
    "uuid": "f1e76cb2ef0c4dfa87f3b807eb4d7437",
    "vmNics": [
        {
            "createDate": "Dec 2, 2015 5:54:12 PM",
            "deviceId": 1,
            "gateway": "10.1.1.1",
            "ip": "10.1.1.155",
            "l3NetworkUuid": "8db7eb2ccdab4c4eb4784e46895bb016",
            "lastOpDate": "Dec 2, 2015 5:54:12 PM",
            "mac": "fa:99:e7:31:98:01",
            "metaData": "4",
            "netmask": "255.255.255.0",
            "uuid": "30bd463b926e4299a1326293ee75ae13",
            "vmInstanceUuid": "f1e76cb2ef0c4dfa87f3b807eb4d7437"
        },
        {
            "createDate": "Dec 2, 2015 5:54:12 PM",
            "deviceId": 0,
            "gateway": "192.168.0.1",
            "ip": "192.168.0.188",
            "l3NetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
            "lastOpDate": "Dec 2, 2015 5:54:12 PM",
            "mac": "fa:74:3f:40:cb:00",
            "metaData": "3",
            "netmask": "255.255.255.0",
            "uuid": "dc02fee25e9244ad8cbac151657a7b34",
            "vmInstanceUuid": "f1e76cb2ef0c4dfa87f3b807eb4d7437"
        }
    ],
    "zoneUuid": "3a3ed8916c5c4d93ae46f8363f080284"
}

虚拟路由器规格（Virtual Router Offering）¶

虚拟路由器规格是包含额外属性的一个特殊的:ref:instance offering <instance offering>.

清单（Inventory）¶

除了在:ref:`instance offering inventory <instance offering inventory>`中提到的属性以外, 虚拟路由器规格还有以下额外的属性:

属性（Properties）¶

managementNetworkUuid	管理L3网络的uuid	0.6
publicNetworkUuid	公有L3网络的uuid	0.6
zoneUuid	所在区域的uuid. 虚拟机路由器只能从同一个区域中的虚拟机路由器规格创建出来.	0.6
isDefault	请参见 :default offering	0.6
imageUuid	虚拟路由器镜像的uuid, 请参见 image	0.6

示例 ¶

{
    "allocatorStrategy": "DefaultHostAllocatorStrategy",
    "cpuNum": 1,
    "cpuSpeed": 128,
    "createDate": "Nov 30, 2015 3:31:43 PM",
    "imageUuid": "b4fe2ebbc4522e199d36985012254d7d",
    "isDefault": true,
    "lastOpDate": "Nov 30, 2015 3:31:43 PM",
    "managementNetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
    "memorySize": 536870912,
    "name": "VROFFERING5",
    "publicNetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
    "sortKey": 0,
    "state": "Enabled",
    "type": "VirtualRouter",
    "uuid": "f50a232a1448401cb8d049aad9c3860b",
    "zoneUuid": "3a3ed8916c5c4d93ae46f8363f080284"
}

默认规格（Default Offering）¶

在一个L3网络上创建一个虚拟路由器时, ZStack需要决定使用哪一个虚拟路由器规格; 决定的策略如下:

使用这个规格，如果某个虚拟路由器规格包含系统标签:ref:guestL3Network <vr tag guestL3Network>, 并且这个系统标签中包含了这个L3网络的uuid.
如果没有在步骤1中找到合适的规格, 使用默认的虚拟路由器规格.

每一个区域都必须有一个默认的虚拟路由器规格.

镜像（Image）¶

虚拟路由器虚拟机可以使用从http://download.zstack.org/templates/zstack-virtualrouter-0.6.qcow2下载的定制的Linux镜像. 这个Linux操作系统的root密码是:

username: root
password: password

用户可以通过终端（console）访问虚拟路由器虚拟机，并是用这个用户名和密码登陆.

在创建虚拟路由器规格之前, 用户需要使用:ref:`add image <add image>`将这个镜像添加到备份存储（backup storage）中; 为了避免从这个镜像创建用户虚拟机, 用户可以将参数’system’设置为true.

管理网络和公有网络（Management Network and Public Network）¶

在创建虚拟路由器规格之前, 用户必须首先通过使用:ref:`create L3 network <create L3 network>`创建对应的L3网络. 用户可以把参数’system’设置true, 来避免从这些网络上创建用户虚拟机.

操作（Operations）¶

创建虚拟路由器规格（Create Virtual Router Offering）¶

用户可以使用CreateVirtualRouterOffering来创建一个虚拟路由器规格. 例如:

CreateVirtualRouterOffering name=small cpuNum=1 cpuSpeed=1000 memorySize=1073741824 isDefault=true
managementNetworkUuid=95dede673ddf41119cbd04bcb5d73660 publicNetworkUuid=8db7eb2ccdab4c4eb4784e46895bb016 zoneUuid=3a3ed8916c5c4d93ae46f8363f080284
imageUuid=95dede673ddf41119cbd04bcb5d73660

除了在:ref:`CreateInstanceOffering <CreateInstanceOffering>`中提到的参数以外, 还有以下额外的参数:

参数（Parameters）¶

名字	描述	可选的	起始支持版本
managementNetworkUuid	管理L3网络的uuid		0.6
publicNetworkUuid	公有L3网络的uuid; 默认为managementNetworkUuid.	是	0.6
zoneUuid	所在区域的uuid		0.6
imageUuid	镜像的uuid		0.6

删除虚拟路由器规格（Delete Virtual Router Offering）¶

请参见 DeleteInstanceOffering

重连虚拟路由器代理（Reconnect Virtual Router Agent）¶

正如之前提到的一样, 在虚拟路由器虚拟机上有一个Python虚拟路由器代理（Python virtual router agent）. 用户可以使用ReconnectVirtualRouter来重新初始化从一个ZStack管理节点到一个虚拟路由器虚拟机的连接过程, 这会使得:

如果代理的二进制文件（agent binary）的MD5校验值和管理节点库（repository）中的不一致，更新虚拟路由器代理.
重启代理
重新应用包括DHCP, DNS, SNAT, EIP, 和端口转发在内的所有网络服务配置到虚拟路由器虚拟机.

命令示例:

ReconnectVirtualRouter vmInstanceUuid=bd1652b1e44144e6b9b5b286b82edb69

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
vmInstanceUuid	虚拟路由器虚拟机的uuid			0.6

启动虚拟路由器虚拟机（Start Virtual Router VM）¶

请参见 StartVmInstance. 在启动时, 虚拟路由器虚拟机会执行:ref:`ReconnectVirtualRouter <ReconnectVirtualRouter>`中描述的代理连接过程.

重启虚拟路由器虚拟机（Reboot Virtual Router VM）¶

请参见 RebootVmInstance. 在重启时, 虚拟路由器虚拟机会执行 :ref:`ReconnectVirtualRouter <ReconnectVirtualRouter>`中描述的代理连接过程.

停止虚拟路由器虚拟机（Stop Virtual Router VM)¶

请参见 StopVmInstance.

删除虚拟路由器虚拟机（Destroy Virtual Router VM）¶

请参见 DestroyVmInstance.

迁移虚拟路由器虚拟机（Migrate Virtual Router VM）¶

请参见 MigrateVm.

创建虚拟路由器虚拟机（Create Virtual Router VM）¶

虽然没有现成的API可以手动创建一个虚拟路由器虚拟机, 但是用户在客户L3网络上创建或启动一个虚拟机的时候会自动触发创建一个虚拟路由器虚拟机. 如果该L3网络没有已经在运行的虚拟路由器虚拟机, 创建或停止/启动一个虚拟机的时候会自动触发创建一个虚拟路由器虚拟机.

查询虚拟路由器虚拟机（Query Virtual Router VM）¶

用户可以使用QueryVirtualRouterVm来查询虚拟路由器虚拟机. 例如:

QueryVirtualRouterVm defaultRouteL3NetworkUuid=95dede673ddf41119cbd04bcb5d73660

QueryVirtualRouterVm vmNics.mac=fa:d9:af:a1:38:01

原生域（Primitive Fields）¶

请参见 appliance vm inventory.

嵌套和扩展域（Nested And Expanded Fields）¶

域（Field）	清单（Inventory）	描述	起始支持版本
vmNics	VM nic inventory	虚拟路由器虚拟机的虚拟机网卡	0.6
allVolumes	volume inventory	虚拟路由器虚拟机的云盘	0.6
host	host inventory	运行虚拟路由器虚拟机的主机	0.6
cluster	cluster inventory	虚拟路由器虚拟机所属的集群	0.6
image	image inventory	用于创建虚拟路由器虚拟机的镜像	0.6
zone	zone inventory	虚拟路由器虚拟机所属的区域	0.6
rootVolume	volume inventory	虚拟路由器虚拟机的根云盘	0.6
virtualRouterOffering	virtual router offering inventory		0.6
eip	EIP inventory	虚拟路由器虚拟机提供服务的EIP	0.6
vip	VIP inventory	虚拟路由器虚拟机提供服务的VIP	0.6
portForwarding	port forwarding rule inventory	虚拟路由器虚拟机提供服务的端口转发	0.6

查询虚拟路由器规格（Query Virtual Router Offering）¶

用户可以使用QueryVirtualRouterOffering来查询虚拟路由器规格. 例如:

QueryVirtualRouterOffering managementNetworkUuid=a82b75ee064a48708960f42b800bd910 imageUuid=6572ce44c3f6422d8063b0fb262cbc62

QueryVirtualRouterOffering managementL3Network.name=systemL3Network image.name=newVirtualRouterImage

原生域（Primitive Fields）¶

请参见 virtual router offering inventory.

嵌套和扩展域（Nested And Expanded Fields）¶

域（Field）	清单（Inventory）	描述	起始支持版本
image	image inventory	规格包含的镜像	0.6
managementL3Network	L3 network inventory	规格包含的管理L3网络	0.6
publicL3Network	L3 network inventory	规格包含的公有L3网络	0.6
zone	zone inventory	规格所属的区域	0.6

全局配置（Global Configurations）¶

agent.deployOnStart ¶

名字	类别	默认值	可选的参数值
agent.deployOnStart	virtualRouter	false	true false

是否要在虚拟路由器虚拟机启动/停止/重启的时候部署虚拟路由器代理; 由于虚拟路由器代理是内建在虚拟路由器虚拟机中的，因此这个配置只应在用户想要升级代理的时候设置为true.

command.parallelismDegree ¶

名字	类别	默认值	可选的参数值
command.parallelismDegree	virtualRouter	100	> 0

在虚拟路由器代理上可并行执行命令的最大数目.

connect.timeout ¶

名字	类别	默认值	可选的参数值
connect.timeout	applianceVm	300	> 0

当管理节点连接虚拟路由器代理时的SSH连接超时设置, 单位是秒. 如果在设定的时间限制内管理节点不能和虚拟路由器虚拟机建立SSH连接, 会报告一个错误.

agent.deployOnStart ¶

名字	类别	默认值	可选的额参数值
agent.deployOnStart	applianceVm	false	true false

是否要在虚拟路由器虚拟机启动/停止/重启的时候部署特殊虚拟机代理; 由于虚拟路由器代理是内建在特殊虚拟机中的，因此这个配置只应在用户想要升级代理的时候设置为true.

标签（Tags）¶

用户可以使用计算规格章节中和虚拟机章节中提到的方法分别在虚拟路由器规格或虚拟路由器虚拟机上创建用户标签.

系统标签（System Tags）¶

命令并行度（Parallel Command Level）¶

管理可以限制在一个虚拟路由器虚拟机上并行执行命令的最大数量.

标签	描述	示例	起始支持版本
commandsParallelismDegree::{parallelismDegree}	在一个虚拟路由器虚拟机上并行执行命令的最大数量	commandsParallelismDegree::100	0.6

这个标签既可以在虚拟路由器规格上创建，也可以在虚拟路由器虚拟机上创建; 如果是在虚拟路由器规格上创建的g, 从这个虚拟路由器规格创建的所有虚拟路由器虚拟机都将继承这个标签. 对于虚拟路由器规格请使用resourceType=InstanceOfferingVO创建标签, 对于虚拟路由器虚拟机请使用resourceType=VmInstanceVO创建标签.

客户L3网络（Guest L3 Network）¶

管理员可以将虚拟路由器规格绑定到一个客户L3网络, 以指定在该客户L3网络上创建虚拟路由器虚拟机的时候使用哪一个虚拟路由器规格.

标签	描述	示例	起始支持版本
guestL3Network::{guestL3NetworkUuid}	客户L3网络的uuid	guestL3Network::dd56c5c209a74b669b3fe6115a611d57	0.6

例如:

CreateSystemTag resourceType=InstanceOfferingVO resourceUuid=YOUR_VR_OFFERING_UUID tag=guestL3Network::YOUR_L3_NETWORK_UUID

虚拟IP地址（Virtual IP Address）¶

虚拟IP地址（Virtual IP Address）

概览（Overview）¶

当桥接（bridging）两个网络的通信时, 许多网络服务（network services）都需要虚拟IP地址（virtual Ip addresses, VIP）, 例如端口转发（Port Forwarding）, EIP, VPN, 负载均衡（Load Balancing）; 流入的数据包（incoming packets）被发送到VIP，并被路由到（routed）私有网络IP（private network IPs）.

实际上, VIP通常是可以被internet访问到的公有IP（public IP）, 而路由到背后的私有IP的流量通常都是在对internet来说不可见的私有网络上.

当前ZStack版本中, 必须首先分配一个VIP，才能创建端口转发或EIP. 由于现在虚拟路由器模块（virtual router provider）是唯一的网络服务模块（network service provider）, 因此需要从虚拟路由器虚拟机（virtual router VM）的公有网络创建VIP(请参见 virtual router offering)才能将外部流量路由至客户网络（guest network）.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
ipRangeUuid	分配VIP的IP范围（IP range）的uuid			0.6
l3NetworkUuid	分配VIP的L3网络的uuid			0.6
ip	IP地址			0.6
state	VIP可用状态, 当前版本中未实现		Enabled Disabled	0.6
gateway	网关			0.6
netmask	子网掩码			0.6
serviceProvider	使用该VIP的网络服务模块的名字	是		0.6
peerL3NetworkUuid	该VIP路由流量目的L3网络的uuid			0.6
useFor	使用该VIP的服务名	是	EIP PortForwarding	0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
    "createDate": "Nov 28, 2015 6:52:01 PM",
    "gateway": "192.168.0.1",
    "ip": "192.168.0.189",
    "l3NetworkUuid": "95dede673ddf41119cbd04bcb5d73660",
    "lastOpDate": "Nov 28, 2015 6:52:01 PM",
    "name": "vip-905d8a5c191c6e30173037e9d4c0ec56",
    "netmask": "255.255.255.0",
    "peerL3NetworkUuid": "6572ce44c3f6422d8063b0fb262cbc62",
    "serviceProvider": "VirtualRouter",
    "state": "Enabled",
    "useFor": "Eip",
    "uuid": "429106d5a63a4995911c2c5f14299b85"
}

操作（Operations）¶

创建VIP（Create VIP）¶

用户可以使用CreateVip来创建VIP. 例如:

CreateVip name=vip1 l3NetworkUuid=95dede673ddf41119cbd04bcb5d73660

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
l3NetworkUuid	分配VIP的L3网络的uuid			0.6
requiredIp	打算获得的IP地址, 请参见 requiredIp			0.6
allocatorStrategy	分配VIP的算法		RandomIpAllocatorStrategy	0.6

RequiredIp ¶

用户可以通过指定’requiredIp’来分配特定, 只要这个IP地址在目录L3网络中仍然可用.

删除VIP（Delete VIP）¶

用户可以使用DeleteVip来删除VIP. 例如:

DeleteVip uuid=429106d5a63a4995911c2c5f14299b85

查询VIP（Query VIP）¶

用户可以使用QueryVip来查询VIP. 例如:

QueryVip ip=17.16.89.2 serviceProvider!=null

QueryVip eip.guestIp=10.256.99.2

原生域（Primitive Fields）¶

请参见 VIP inventory

嵌套和扩展域（Nested And Expanded Fields）¶

域（Field）	清单（Inventory）	描述	起始支持版本
eip	EIP inventory	VIP所绑定的EIP	0.6
portForwarding	port forwarding rule inventory	VIP所绑定的端口转发规则	0.6

标签（Tags）¶

用户可以使用resourceType=VipVO来在VIP上创建一个用户标签. 例如:

CreateUserTag tag=web-tier-vip resourceType=VipVO resourceUuid=c3206d0e29074e21984c584074c63920

弹性端口转发（Elastic Port Forwarding）¶

概览（Overview）¶

当用户虚拟机在一个启用了SNAT服务的:ref:`private network or isolated network <l3Network typology>`上时, 他们可以访问外部网络但是不能被外部网络访问到, 这也正是SNAT所定义的功能. 用户可以创建端口转发规则（port forwarding rules）从而允许外部网络访问SNAT后面的虚拟机的某些特定端口. ZStack支持弹性端口转发规则（elastic port forwarding rules）, 也就是说这些规则可以按需的挂载到虚拟机上，或从虚拟机卸载.

由于虚拟路由器模块是当前ZStack版本的唯一一个网络服务模块（network service provider）, 端口转发规则实际上是创建于虚拟路由器虚拟机的公有网络和客户网络之间的.

一个VIP可以在多个端口转发规则中使用, 只要这些规则的端口范围没有重叠; 例如:

端口转发规则清单（Port Forwarding Rule Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
vipIp	VIP的IP地址			0.6
guestIp	虚拟机网卡的IP地址	是		0.6
vipUuid	VIP的uuid			0.6
vipPortStart	VIP的起始端口号		1 ~ 65535	0.6
vipPortEnd	VIP的结束端口号		1 ~ 65535	0.6
privatePortStart	客户IP的起始端口号		1 ~ 65535	0.6
privatePortEnd	客户IP的结束端口号		1 ~ 65535	0.6
vmNicUuid	客户虚拟机网卡的uuid	是		0.6
protocolType	网络流量的协议类型		TCP UDP	0.6
state	规则可用状态, 当前版本中未实现		Enabled Disabled	0.6
allowedCidr	源CIDR; 端口转发规则只作用于源CIDR的流量			0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
    "allowedCidr": "0.0.0.0/0",
    "createDate": "Dec 6, 2015 3:04:34 PM",
    "guestIp": "10.0.0.244",
    "lastOpDate": "Dec 6, 2015 3:04:34 PM",
    "name": "pf-9uf4",
    "privatePortEnd": 33,
    "privatePortStart": 33,
    "protocolType": "TCP",
    "state": "Enabled",
    "uuid": "310a6cd618144ca683d78d74307f16a4",
    "vipIp": "192.168.0.187",
    "vipPortEnd": 33,
    "vipPortStart": 33,
    "vipUuid": "433769b59a7c42199d762af01e08ec16",
    "vmNicUuid": "4b9c27321b794679a9ba8c18239bbb0d"
}

操作（Operations）¶

创建端口转发规则（Create Port Forwarding Rule）¶

用户可以使用CreatePortForwardingRule来创建一个端口转发规则, 并可以同时挂载或者不挂载到虚拟机网卡上. 例如:

CreatePortForwardingRule name=pf1 vipPortStart=22 vipUuid=433769b59a7c42199d762af01e08ec16 protocolType=TCP vmNicUuid=4b9c27321b794679a9ba8c18239bbb0d

一个未被挂载的规则可以稍后再挂载到虚拟机网卡上.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
name	资源的名字, 请参见资源属性			0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是		0.6
description	资源的描述, 请参见资源属性	是		0.6
vipUuid	VIP的UUID			0.6
vipPortStart	VIP的起始端口号		1 - 65535	0.6
vipPortEnd	VIP的结束端口号; 如果忽略不设置, 会默认设置为vipPortStart.	是	1 - 65535	0.6
privatePortStart	客户IP（虚拟机网卡的IP地址）的起始端口号; 如果忽略不设置, 会默认设置为vipPortStart	是	1 - 65535	0.6
privatePortEnd	客户IP（虚拟机网卡的IP地址）的结束端口号; 如果忽略不设置, 会默认设置为vipPortEnd	是	1 - 65535	0.6
protocolType	网络流量协议类型		TCP UDP	0.6
vmNicUuid	该端口转发规则将要挂载的虚拟机网卡的uuid	是		0.6
allowedCidr	源CIDR; 端口转发规则只作用于源CIDR的流量; 如果忽略不设置, 会默认设置为to 0.0.0.0/0	是		0.6

删除端口转发规则（Delete Port Forwarding Rule）¶

用户可以使用DeletePortForwardingRule来删除端口转发规则. 例如:

DeletePortForwardingRule uuid=310a6cd618144ca683d78d74307f16a4

如果没有端口转发规则还绑定在VIP上, VIP将被循环使用在其他的网络服务中.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	规则的uuid			0.6

挂载端口转发规则（Attach Port Forwarding Rule）¶

用户可以使用AttachPortForwardingRule来挂载一个规则到虚拟机网卡上. 例如:

AttachPortForwardingRule ruleUuid=310a6cd618144ca683d78d74307f16a4 vmNicUuid=4b9c27321b794679a9ba8c18239bbb0d

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
ruleUuid	规则的uuid			0.6
vmNicUuid	虚拟机网卡的uuid			0.6

卸载端口转发规则（Detach Port Forwarding Rule）¶

用户可以使用DetachPortForwardingRule来从一个虚拟机网卡卸载一个规则. 例如:

DetachPortForwardingRule uuid=310a6cd618144ca683d78d74307f16a4

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	规则的uuid			0.6

查询端口转发规则（Query Port Forwarding Rule）¶

用户可以使用QueryPortForwardingRule来查询规则. 例如:

QueryPortForwardingRule vipPortStart=22 vipIp=17.200.20.6

QueryPortForwardingRule vmNic.l3Network.name=database-tier

原生域（Primitive Fields）¶

请参见 port forwarding rule inventory

嵌套和扩展域（Nested And Expanded Fields）¶

域（Field）	清单（Inventory）	描述	起始支持版本
vip	VIP inventory	该规则绑定的VIP	0.6
vmNic	VM nic inventory	该规则绑定的虚拟机网卡	0.6

全局配置（Global Configurations）¶

snatInboundTraffic ¶

名字	类别	默认值	可选的参数值
snatInboundTraffic	portForwarding	false	true false

该配置决定是否对端口转发规则的流入流量使用源NAT. 如果设置为true, 到达portForwardingRule.guestIp的流量会使用portForwardingRule.vipIp作为源IP（source IP）; 这在一个虚拟机上挂载了多个端口转发规则的时候比较有用; 它会强制虚拟机通过VIP回复流入的流量至数据包的来源, 而不是通过默认路由来回复.

标签（Tags）¶

用户可以使用resourceType=PortForwardingRuleVO在端口转发上创建用户标签. 例如:

CreateUserTag resourceType=PortForwardingRuleVO tag=ssh-rule resourceType=e960a93b7f974690bb779808f3c12a33

弹性IP地址（Elastic IP Address）¶

概览（Overview）¶

弹性IP地址(EIP) 提供了外部网络访问SNAT后面的L3网络的途径. EIP基于网络地址转换(NAT), 将一个网络（通常是公有网络）的IP地址转换成另一个网络（通常是一个私有网络）的IP地址; 就像它的名字一样, EIP可以动态的挂载到虚拟机或从一个虚拟机上卸载.

清单（Inventory）¶

属性（Properties）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	请参见资源属性			0.6
name	请参见资源属性			0.6
description	请参见资源属性	是		0.6
vmNicUuid	EIP绑定的虚拟机网卡的uuid	true		0.6
vipUuid	VIP的uuid			0.6
state	EIP的可用状态, 当前版本中未实现		Enabled Disabled	0.6
vipIp	VIP的IP地址			0.6
guestIp	虚拟机网卡的IP	是		0.6
createDate	请参见资源属性			0.6
lastOpDate	请参见资源属性			0.6

示例 ¶

{
    "createDate": "Nov 28, 2015 6:52:14 PM",
    "guestIp": "10.0.0.170",
    "lastOpDate": "Nov 28, 2015 6:52:14 PM",
    "name": "eip-vlan10",
    "state": "Enabled",
    "uuid": "76b9231c94cd4a3aac497200bb26a643",
    "vipIp": "192.168.0.189",
    "vipUuid": "429106d5a63a4995911c2c5f14299b85",
    "vmNicUuid": "70cac1fd0c2f4940ba32645e09d3e22f"
}

操作（Operations）¶

创建EIP（Create EIP）¶

用户可以使用CreateEip来创建一个EIP. 例如:

CreateEip name=eip1 vipUuid=429106d5a63a4995911c2c5f14299b85 vmNicUuid=70cac1fd0c2f4940ba32645e09d3e22f

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.6
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.6
description	资源的描述, 请参见资源属性	是	0.6
vipUuid	VIP的uuid		0.6
vmNicUuid	虚拟机网卡的uuid; 如果忽略该参数, EIP会被创建，但不会挂载到任何虚拟机网卡.	true	0.6

删除EIP（Delete EIP）¶

用户可以使用DeleteEip来删除一个EIP. 例如:

DeleteEip uuid=76b9231c94cd4a3aac497200bb26a643

被删除后, 绑定到该EIP的VIP会被回收使用在其他网络服务中.

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.6
uuid	EIP的uuid			0.6

挂载EIP（Attach EIP）¶

用户可以使用AttachEip来挂载一个EIP到一个虚拟机的网卡上. 例如:

AttachEip eipUuid=76b9231c94cd4a3aac497200bb26a643 vmNicUuid=70cac1fd0c2f4940ba32645e09d3e22f

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
eipUuid	EIP的uuid			0.6
vmNicUuid	虚拟机网卡的uuid			0.6

卸载EIP（Detach EIP）¶

用户可以使用DetachEip来从虚拟机的网卡卸载一个EIP. 例如:

DetachEip uuid=76b9231c94cd4a3aac497200bb26a643

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
uuid	EIP的uuid			0.6

查询EIP（Query EIP）¶

用户可以使用QueryEip来查询EIP. 例如:

QueryEip vipIp=191.13.10.2

QueryEip vmNic.vmInstance.state=Running

原生域（Primitive Fields）¶

请参见 EIP inventory

嵌套和扩展域（Nested And Expanded Fields）¶

域（Field）	清单（Inventory）	描述	起始支持版本
vip	VIP inventory	改EIP绑定的VIP	0.6
vmNic	VM nic inventory	该EIP绑定的虚拟机网卡	0.6

全局配置（Global Configurations）¶

snatInboundTraffic ¶

名字	类别	默认值	可选的参数值
snatInboundTraffic	eip	false	true false

该设置决定是否对EIP的流入流量使用源NAT. 如果设置为true, 到达eip.guestIp的流量会使用eip.vipIp作为源IP（source IP）; 这在一个虚拟机上挂载了多个EIP的时候比较有用; 它会强制虚拟机通过EIP回复流入的流量至数据包的来源, 而不是通过默认路由来回复.

标签（Tags）¶

用户可以使用resourceType=EipVO来在EIP上创建一个用户标签. 例如:

CreateUserTag resourceType=EipVO tag=web-public-ip resourceUuid=29fa6c2830c441aaa388d8165b80c24c

身份认证（Identity）¶

身份认证（Identity）

概览（Overview）¶

ZStack的身份认证服务（identity service）负责提供ZStack资源的访问控制（ access control）. 系统中定义了账户（account）, 用户（user）, 组（group）, 策略（policy）, 和配额（quota）等概念. 身份认证系统的整体结构如图所示:

账户（Account）¶

人们需要创建作为拥有所有他们资源的根身份认证（root identity）的账户, 才能对资源实施操作. 有两种账户类型: 管理员（admin）和普通用户（normal）. 管理员账户拥有不受限的权限, 通常由系统管理管理员拥有. 普通用户账户, 只能对虚拟机, 计算规格（instance offerings）, 云盘规格（disk offerings）, L3网络, 镜像（images）等资源的权限, 普通用户账户是由管理员账户创建的，从而使他们可以操作他们的资源.

API被分为了管理员权限（admin-only）API和非管理员权限（non-admin）API两类. 在:ref:`admin-only APIs <admin-only APIs>`章节中可以查看到管理员权限API的列表, 在:ref:`non-admin APIs <non-admin APIs>`中可以找到非管理员权限API的列表.

账户的清单（Account Inventory）¶

名字	描述	可选的	起始支持版本
uuid	请参见资源属性		0.8
name	账户的名字. 请参见资源属性		0.8
description	请参见资源属性	是	0.8
createDate	请参见资源属性		0.8
lastOpDate	请参见资源属性		0.8

示例 ¶

{
  "inventory": {
      "createDate": "Jul 22, 2015 10:18:34 AM",
      "lastOpDate": "Jul 22, 2015 10:18:34 AM",
      "name": "frank",
      "uuid": "3153a08ab21f46ca9e8b40ecfeec4255"
  }
}

用户（Users）¶

由于非管理员权限账户拥有对其所拥有资源的不受限权限, 创建的用户可以用来实现更细粒度（finely-grained）的权限控制. 用户只可以使用:ref:`policies <policy>`中指派（assigned）的API.

用户的清单（User Inventory）¶

名字	描述	可选的	起始支持版本
uuid	请参见资源属性		0.8
name	用户的名字, 请参见资源属性		0.8
description	请参见资源属性	是	0.8
accountUuid	拥有该用户的账户的uuid		0.8
createDate	请参见资源属性		0.8
lastOpDate	请参见资源属性		0.8

示例 ¶

{
  "inventory": {
      "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
      "createDate": "Jul 22, 2015 10:21:50 AM",
      "lastOpDate": "Jul 22, 2015 10:21:50 AM",
      "name": "user1",
      "uuid": "68ebcf6260c94adab9dcce9e059e0025"
  }
}

组（Groups）¶

账户可以创建组来管理用户. 通过给组指定策略, 账户可以为一个组的用户设置相同的权限.

组的清单（Group Inventory）¶

名字	描述	可选的	起始支持版本
uuid	请参见资源属性		0.8
name	组的名字, 请参见资源属性		0.8
description	请参见资源属性	是	0.8
accountUuid	拥有该组的账户的uuid		0.8
createDate	请参见资源属性		0.8
lastOpDate	请参见资源属性		0.8

示例 ¶

{
  "inventory": {
      "accountUuid": "36c27e8ff05c4780bf6d2fa65700f22e",
      "createDate": "Jul 22, 2015 10:23:02 AM",
      "name": "group1",
      "uuid": "0939fc6f772d44d6a8f9d45c89c2a716"
  }
}

策略（Policies）¶

策略是定义了用户可以使用哪些API的权限信息. 一个策略包含了由申明（statements）组成的数组，每个申明又定义了访问API的权限信息.

策略的清单（Policy Inventory）¶

名字	描述	可选的	起始支持版本
uuid	请参见资源属性		0.8
name	策略的名字, 请参见资源属性		0.8
description	请参见资源属性	是	0.8
accountUuid	拥有该组的账户的uuid, 请参见 account		0.8
statements	定义API权限的:ref:`statements <statements>`列表		0.8
createDate	请参见资源属性		0.8
lastOpDate	请参见资源属性		0.8

示例 ¶

{
  "inventories": [
      {
          "accountUuid": "3153a08ab21f46ca9e8b40ecfeec4255",
          "name": "DEFAULT-READ-3153a08ab21f46ca9e8b40ecfeec4255",
          "statements": [
              {
                  "actions": [
                      ".*:read"
                  ],
                  "effect": "Allow",
                  "name": "read-permission-for-account-3153a08ab21f46ca9e8b40ecfeec4255"
              }
          ],
          "uuid": "b5169828533b47988a0d09f262b5769c"
      }
  ]
}

申明（Statements）¶

申明是一个JSON文本, 其中包含了用于匹配API标识（API identities）的字符串以及对应的权限信息: Allow or Deny. 例如:

{
  "actions": [
      ".*:read",
      "instance:APICreateVmInstanceMsg"
  ],
  "effect": "Allow",
  "name": "read-permission-for-account-3153a08ab21f46ca9e8b40ecfeec4255"
}

actions**是一个用于匹配一个或多个标识的动作字符串（action strings）组成的列表. API标识是唯一标识一个API的字符串，其格式为***api_category:api_name*. 动作字符串可以是唯一识别单个API的完整的标识如*instance:APICreateVmInstanceMsg*, 也可以是一个匹配很多个API的正则表达式（regular expression）, 例如, *instance:.** 会和所有***instance***类别下的API匹配. 大多数的API只有一个***api_category:api_name***格式的标识; 但有些API拥有多个标识，因此可以使用正则表达式来匹配这些API.

effect 指示API调用匹配一个操作字符串时对应的决定是什么, 允许（allow）还是拒绝（deny）.

在:ref:`API identities <API identities>`中可以找到API标识的列表.

申明的清单（Statement Inventory）¶

名字	描述	可选的参数值	起始支持版本
name	申明的名字		0.8
effect	决定访问权限（permission decision）	Allow Deny	0.8
actions	匹配API标识的字符串列表		0.8

配额（Quota）¶

管理员账户可以使用配额来限制非管理员账户可以创建多少资源. ZStack会在创建非管理员账户时自动给它设定默认的配额, 管理员可以使用API :ref:`UpdateQuota <update quota>`来改变这个默认值. 可以在:ref:`default quotas <default quotas>`中找到默认配额的信息.

权限控制（Permission Control）¶

身份认证系统最让人激动的功能是可以控制API的访问权限, 可以控制什么人可以访问什么. 当用户登录进入ZStack时, 根据他们登录方式的不同, 会获得不同的API访问权限.

管理员（Administrators）: 以管理员账户登录后, 可以调用所有的API.

非管理员账户（Non-admin Account）: 以非管理员账户登录时, 只能执行管理员权限的API.

用户（User）: 以账户所属的用户登陆后, 只能执行挂载到该用户上或通过组作用到该用户上的策略赋予的权限的API.

使用用户和组（Using users and groups）¶

在ZStack中最好的控制访问权限的方法是是允许登录为用户. 假设你是一个团队的经理，并且你需要从你公司的IT部门申请一些由ZStack管理的虚拟机. 首先你需要让ZStack管理员为你创建非管理员账户; 有了这个账户后, 你可以创建一些用户和组并挂载合适的策略; 这时你可以将这些用户提供给你的团队成员，他们可以使用这些用户依照你创建的权限策略操作ZStack中的资源.

用一个实例来做说明, 假设你想在你的团队中创建下面这样的组织结构:

在这个组织结构中, 你有一个负责管理虚拟机的基础设施小组; 这个组有三个成员: David, Tony, Frank; 你还有另一个工作小组在这些虚拟机上实施他们的工作, 这个小组同样有三个成员: Lucy, Arhbi, Jeff. 基础设施小组拥有管理虚拟机生命周期的权限而另一个工作小组只能通过虚拟机的终端访问并使用这些虚拟机. 此外, 作为经理的你拥有所有的你的团队账户的API访问权限. 要创建这样一个组织结构:

创建账户ops-team:

>>>CreateAccount name=ops-team password=password

使用账户ops-team登录:

>>>LogInByAccount accountName=ops-team password=password

创建用户:

>>>CreateUser name=david password=password

对所有的用户重复以上操作 (tony, frank, lucy, arhbi, jeff, mgr)

创建组:

>>>CreateUserGroup name=infra

队另一个组重复上面这个操作(ops)

添加用户到组中:

>>>AddUserToGroup userUuid=d7646ae8af2140c0a3ccef2ad8da816d groupUuid=92c523a43651442489f8d2d598c7c3da

重复上面的操作，将所有用户添加到对应的组中. infra组(david, tony, frank), ops组(lucy, arhbi, jeff).

创建策略

创建第一个策略, 允许调用所有的虚拟机相关的API:

>>>CreatePolicy name=vm-management statements='[{"actions":["instance:.*"], "effect":"Allow"}]'

创建第二个策略, 允许访问虚拟机的终端:

>>>CreatePolicy name=vm-console statements='[{"actions":["instance:APIRequestConsoleAccessMsg"], "effect":"Allow"}]'

创建第三个策略, 允许访问使用的AP:

>>>CreatePolicy name=all statements='[{"actions":[".*"], "effect":"Allow"}]'

挂载策略到组上（Attach policies to groups）

将策略*vm-management*挂载到基础设施小组:

>>>AttachPolicyToUserGroup groupUuid=92c523a43651442489f8d2d598c7c3da policyUuid=afb3bfbb911a42e0a662286728e49891

将策略*vm-console*挂载到另一个工作小组:

>>>AttachPolicyToUserGroup groupUuid=0939fc6f772d44d6a8f9d45c89c2a716 policyUuid=3bddf41e2ba6469881a65287879e5d58

挂载策略到经理的用户(mgr)

挂载策略*all*到经理的用户(user: mgr):

>>>AttachPolicyToUser userUuid=d55c5fba4d1b4533961db9952dc15b00 policyUuid=36c27e8ff05c4780bf6d2fa65700f22e

到这里，你的组织结构就创建完成了, 你的组员可以使用他们的用户名口令登录.

权限判断（Permission Evaluation）¶

一个策略中包含了由申明组成的列表，而每个申明又定义了对于API的访问权限（允许或拒绝）; 用户可以挂载多个策略, 可以挂载到用户上或者他们所在的组上. 当用户访问API的时候, 总会优先从用户上挂载的策略开始做判断，之后是他们所属的组上挂载的策略，直到权限被确定(允许或者拒绝). 默认会拒绝没有匹配任何策略的API访问.

默认只读权限策略（Default Read Policy）¶

当用户被创建时, 一个默认的只读权限策略 (action: .*:read, effect: Allow) 会被挂载到新用户上, 因此用户可以查询资源(例如虚拟机, L3网络).

管理员账户（Admin Account）¶

在安装好ZStack之后, 默认会创建一个管理员账户(账户名: admin, 口令: password). 系统管理员可以使用这个账户来创建管理员用户, 这些用户拥有和管理员一样的不受限的访问权限, 这样可以允许不同的管理员用他们自己的账号口令登录. 管理员账户的口令可是使用API*UpdateAccount*来更改.

共享资源（Shared Resources）¶

一个账户可以共享资源给其他账户. 这对于公有云特别有用, 例如管理员账户可以预定义一些模板 (例如镜像, 计算规格, 云盘规格, l3网络), 这样非管理员账户(通常是客户注册的) 可以使用这些模板来创建虚拟机. 请参见API ShareResource.

资源可以共享至指定的账户或者所有账户. 当调用API:ref:`ShareResource <share resources>`并将参数*toPublic*设置为true时, 通过*resourceUuids指定的资源会对所有账户共享, 否则这些资源仅会被共享给*accountUuids*指定的账户. 当你通过API :ref:`RevokeSharing <revoke sharing>`召回资源时, 可以通过指定*accountUuids*来从指定的账户召回资源, 或者将*toPublic*设置为true进而从所有用户那里召回这个资源.

操作（Operations）¶

创建账户（Create Account）¶

管理员账户登陆后可以使用CreateAccount创建非管理员账户. 例如:

CreateAccount name=frank password=123456

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.8
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.8
description	资源的描述, 请参见资源属性	是	0.8
name	账户的名字		0.8
password	账户的口令		0.8

创建用户（Create Users）¶

一个账户可以使用CreateUser来创建一个用户. 例如:

>>>CreateUser name=david password=123456

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.8
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.8
description	资源的描述, 请参见资源属性	是	0.8
name	用户的名字		0.8
password	用户的口令		0.8

创建组（Create Groups）¶

一个账户可以使用CreateUserGroup来创建一个组. 例如:

>>>CreateUserGroup name=group

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.8
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.8
description	资源的描述, 请参见资源属性	是	0.8
name	组的名字		0.8

创建策略（Create Polices）¶

一个账户可以使用CreatePolicy来创建一个策略. 例如:

>>>CreatePolicy name=all statements='[{"actions":[".*"], "effect":"Allow"}]'

参数（Parameters）¶

名字	描述	可选的	起始支持版本
name	资源的名字, 请参见资源属性		0.8
resourceUuid	资源的uuid, 请参见创建（Create Resources）	是	0.8
name	策略的名字		0.8
statements	:ref:`statements <statements>`的JSON字符串		0.8

添加用户到组中（Add Users into Groups）¶

一个账户可以使用AddUserToGroup来添加一个用户到组中. 例如:

>>>AddUserToGroup userUuid=d7646ae8af2140c0a3ccef2ad8da816d groupUuid=92c523a43651442489f8d2d598c7c3da

参数（Parameters）¶

名字	描述	可选的	可选的额参数值	起始支持版本
userUuid	用户的uuid			0.8
groupUuid	组的uuid			0.8

挂载策略到组上（Attach Polices to Groups）¶

一个账户可以使用AttachPolicyToUserGroup来挂载一个策略到组上. 例如:

>>>AttachPolicyToUserGroup groupUuid=92c523a43651442489f8d2d598c7c3da policyUuid=afb3bfbb911a42e0a662286728e49891

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
groupUuid	组的uuid			0.8
policyUuid	策略的uuid			0.8

挂载策略到用户上（Attach Polices to Users）¶

账户可以使用AttachPolicyToUser来挂载一个策略到用户上. 例如:

>>>AttachPolicyToUser userUuid=d55c5fba4d1b4533961db9952dc15b00 policyUuid=36c27e8ff05c4780bf6d2fa65700f22e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
userUuid	用户的uuid			0.8
policyUuid	策略的uuid			0.8

从组卸载策略（Detach Polices from Groups）¶

一个账户可以使用DetachPolicyFromUserGroup来从组卸载一个策略. 例如:

>>>DetachPolicyFromUserGroup groupUuid=f1a092c6914840c9895c564abbc55375 policyUuid=afb3bfbb911a42e0a662286728e49891

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
groupUuid	组的uuid			0.8
policyUuid	策略的uuid			0.8

从用户卸载策略（Detach Polices from Users）¶

一个账户可以使用DetachPolicyFromUser来从用户卸载一个策略. 例如:

>>>DetachPolicyFromUser policyUuid=36c27e8ff05c4780bf6d2fa65700f22e userUuid=d7646ae8af2140c0a3ccef2ad8da816d

参数（Parameters）¶

重置账户口令（Reset Account Password）¶

一个账户可以使用UpdateAccount来重置它的口令. 例如:

>>>UpdateAccount password=password

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
password	新的口令			0.8
uuid	需要重置口令的账户的uuid. 主要用于管理员账户重置其他账户的口令, 由于ZStack可以从当前会话（current session）中获取账户的uuid信息, 因此该域可忽略.	是		0.8

重置用户口令（Reset User Password）¶

一个账户或一个用户可以使用UpdateUser来重置用户的口令. 例如:

>>>UpdateUser password=password

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
password	新的口令			0.8
uuid	用户的uuid. 主要用于账户更改用户的口令. 用户改变自己的口令时，由于ZStack可以从当前会话（current session）中获取用户的uuid信息, 因此这个域可以忽略For user changing own.	是		0.8

删除组（Delete Groups）¶

一个账户可以使用DeleteUserGroup来删除一个组. 例如:

>>>DeleteUserGroup uuid=bb0e50fe0cfa4ec1af1835f9c210ae8e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.8
uuid	组的uuid			0.8

删除用户（Delete Users）¶

一个账户可以使用DeleteUser来删除一个用户. 例如:

>>>DeleteUser uuid=fa4ec1af1835f9c210ae8e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.8
uuid	用户的uuid			0.8

删除策略（Delete Policies）¶

一个账户可以使用DeletePolicy来删除一个策略. 例如:

>>>DeletePolicy uuid=bb0e50fe0cfa4ec1af1835f9c210ae8e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.8
uuid	策略的uuid			0.8

删除账户（Delete Accounts）¶

管理员账户可以使用DeleteAccount来删除一个非管理员账户. 例如:

>>>DeleteAccount uuid=bb0e50fe0cfa4ec1af1835f9c210ae8e

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
deleteMode	请参见删除资源（Delete Resources）	是	Permissive Enforcing	0.8
uuid	账户的uuid			0.8

更新账户配额（Update Account Quota）¶

管理员账户可以使用UpdateQuota来更新一个账户的配额. 例如:

>>>UpdateQuota identityUuid=bb0e50fe0cfa4ec1af1835f9c210ae8e name=vm.num value=100

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
identityUuid	账户的uuid			0.8
name	配额的名字（quota name）		vip.num securityGroup.num l3.num portForwarding.num vm.num vm.cpuNum vm.memorySize volume.data.num volume.capacity eip.num	0.8

共享资源（Share Resources）¶

一个账户可以使用ShareResource来将资源共享其他账户. 例如:

ShareResource accountUuids=bb0e50fe0cfa4ec1af1835f9c210ae8e,bb0e50fe0cfa4ec1af1835f9c210ae8e resourceUuids=b0662d80cc4945f8abaf6d1096da9eb5,d55c5fba4d1b4533961db9952dc15b00

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
accountUuids	将资源共享至该列表中uuid指定的账户. 仅当toPublic被设置为true时, 该参数才能被忽略	是		0.8
resourceUuids	资源uuid的列表			0.8
toPublic	如果设置为true, 资源会被共享给所有账户	是	true false	0.8

召回共享资源（Revoke Shared Resources）¶

一个账户可以使用RevokeResourceSharing来从账户召回共享的资源. 例如:

RevokeResourceSharing accountUuids=bb0e50fe0cfa4ec1af1835f9c210ae8e resourceUuids=b0662d80cc4945f8abaf6d1096da9eb5,d55c5fba4d1b4533961db9952dc15b00

RevokeResourceSharing all=true accountUuids=bb0e50fe0cfa4ec1af1835f9c210ae8e

RevokeResourceSharing resourceUuids=b0662d80cc4945f8abaf6d1096da9eb5 toPublic=true

参数（Parameters）¶

名字	描述	可选的	可选的参数值	起始支持版本
accountUuids	该参数指定了从哪些账户召回共享的资源. 仅当域all设置时才能忽略这个域, 因为资源会从所有账户那里召回.	是		0.6
resourceUuids	指定哪些资源被召回			0.6
all	如果该参数被设置为true, 资源会从所有账户那里召回.	是	true false	0.6
toPublic	如果在调用ShareResource共享资源时时指定了’toPublic = true’, 在召回该资源时也必须将这个域设置为true.	是	true false	0.6

查询账户（Query Accounts）¶

一个账户可以使用QueryAccount来查询它自己的账户, 而管理员账户则可以查询所有账户. 例如:

>>>QueryAccount name=test

>>>QueryAccount group.name=group1

请参见 account inventory

域（Field）	清单（Inventory）	描述	起始支持版本
group	group inventory	所拥有的组	0.6
user	user inventory	所拥有的用户	0.6
policy	policy inventory	所拥有的策略	0.6
quota		所拥有的配额	0.6

查询用户（Query Users）¶

一个账户可以使用QueryUser来查询用户. 例如:

>>>QueryUser name=frank

>>>QueryUser name=frank policy.name=allow

请参见 user inventory

域（Field）	清单（Inventory）	描述	起始支持版本
account	请参见 account inventory	所属的账户	0.6
group	请参见 group inventory	用户所属的组	0.6
policy	请参见 policy inventory	该用户挂载的策略	0.6

查询策略（Query Policy）¶

一个账户可以使用QueryPolicy来查询策略. 例如:

>>>QueryPolicy name=vm-management

>>>QueryPolicy user.name=frank

请参见 policy inventory

域（Field）	清单（Inventory）	描述	起始支持版本
account	请参见 account inventory	所属账户	0.6
group	请参见 group inventory	该策略所挂载的组	0.6
user	请参见 user inventory	该策略所挂载的用户	0.6

查询组（Query Groups）¶

一个账户可以使用QueryUserGroup来查询组. 例如:

>>>QueryUserGroup name=group1

>>>QueryUserGroup user.name=frank

请参见 group inventory

域（Field）	清单（Inventory）	描述	起始支持版本
account	请参见 account inventory	所属账户	0.6
user	请参见 user inventory	该组中的用户	0.6
policy	请参见 policy inventory	该组上挂载的策略	0.6

参考信息（Reference）¶

管理员权限API（Admin-only APIs）¶

QueryGlobalConfig
GetGlobalConfig
UpdateGlobalConfig
GetHostAllocatorStrategies
GetCpuMemoryCapacity
ChangeInstanceOffering
IsReadyToGo
GetPrimaryStorageTypes
AttachPrimaryStorageToCluster
GetPrimaryStorageCapacity
UpdatePrimaryStorage
QueryPrimaryStorage
ChangePrimaryStorageState
SyncPrimaryStorageCapacity
DeletePrimaryStorage
ReconnectPrimaryStorage
DetachPrimaryStorageFromCluster
GetPrimaryStorageAllocatorStrategies
GetVolumeSnapshotTree
QueryBackupStorage
AttachBackupStorageToZone
GetBackupStorageTypes
ChangeBackupStorageState
GetBackupStorageCapacity
DetachBackupStorageFromZone
UpdateBackupStorage
DeleteBackupStorage
AddNetworkServiceProvider
AttachNetworkServiceProviderToL2Network
DetachNetworkServiceProviderFromL2Network
AttachL2NetworkToCluster
QueryL2VlanNetwork
CreateL2VlanNetwork
DetachL2NetworkFromCluster
DeleteL2Network
CreateL2NoVlanNetwork
UpdateL2Network
GetL2NetworkTypes
DeleteSearchIndex
SearchGenerateSqlTrigger
CreateSearchIndex
QueryManagementNode
CreateMessage
QueryCluster
DeleteCluster
UpdateCluster
CreateCluster
ChangeClusterState
CreateAccount
LogInByUser
SessionMessage
UpdateQuota
QueryAccount
LogInByAccount
ValidateSession
LogOut
UpdateZone
DeleteZone
CreateZone
QueryZone
ChangeZoneState
ChangeHostState
ReconnectHost
UpdateHost
DeleteHost
GetHypervisorTypes
QueryHost
QueryApplianceVm
AddIscsiFileSystemBackendPrimaryStorage
QueryIscsiFileSystemBackendPrimaryStorage
UpdateIscsiFileSystemBackendPrimaryStorage
AddLocalPrimaryStorage
UpdateKVMHost
AddKVMHost
AddNfsPrimaryStorage
QuerySftpBackupStorage
ReconnectSftpBackupStorage
UpdateSftpBackupStorage
AddSftpBackupStorage

非管理员权限API（Non-admin APIs）¶

UpdateVmInstance
GetVmAttachableL3Network
MigrateVm
StopVmInstance
GetVmAttachableDataVolume
QueryVmNic
AttachL3NetworkToVm
DestroyVmInstance
GetVmMigrationCandidateHosts
QueryVmInstance
DetachL3NetworkFromVm
RebootVmInstance
CreateVmInstance
StartVmInstance
ChangeImageState
UpdateImage
DeleteImage
CreateDataVolumeTemplateFromVolume
CreateRootVolumeTemplateFromRootVolume
QueryImage
CreateRootVolumeTemplateFromVolumeSnapshot
AddImage
RequestConsoleAccess
BackupDataVolume
AttachDataVolumeToVm
UpdateVolume
QueryVolume
CreateDataVolumeFromVolumeSnapshot
CreateDataVolumeFromVolumeTemplate
DetachDataVolumeFromVm
CreateDataVolume
GetDataVolumeAttachableVm
GetVolumeFormat
DeleteDataVolume
CreateVolumeSnapshot
ChangeVolumeState
DeleteDiskOffering
QueryInstanceOffering
UpdateInstanceOffering
CreateInstanceOffering
CreateDiskOffering
DeleteInstanceOffering
ChangeInstanceOfferingState
QueryDiskOffering
UpdateDiskOffering
ChangeDiskOfferingState
QueryVolumeSnapshotTree
DeleteVolumeSnapshot
UpdateVolumeSnapshot
DeleteVolumeSnapshotFromBackupStorage
QueryVolumeSnapshot
RevertVolumeFromSnapshot
BackupVolumeSnapshot
AddDnsToL3Network
CreateL3Network
GetFreeIp
UpdateL3Network
DeleteIpRange
ChangeL3NetworkState
AddIpRange
GetL3NetworkTypes
AddIpRangeByNetworkCidr
QueryIpRange
RemoveDnsFromL3Network
GetIpAddressCapacity
DeleteL3Network
UpdateIpRange
QueryL3Network
AttachNetworkServiceToL3Network
QueryNetworkServiceL3NetworkRef
QueryNetworkServiceProvider
GetNetworkServiceTypes
QueryL2Network
QueryUserTag
QuerySystemTag
DeleteTag
CreateUserTag
CreateSystemTag
QueryTag
AttachPolicyToUserGroup
RemoveUserFromGroup
AttachPolicyToUser
UpdateUser
AddUserToGroup
QueryQuota
ShareResource
DeleteAccount
CreateUserGroup
CreateUser
DetachPolicyFromUserGroup
QueryPolicy
QueryUser
DeletePolicy
RevokeResourceSharing
UpdateAccount
DeleteUser
DeleteUserGroup
CreatePolicy
DetachPolicyFromUser
QueryUserGroup
ReconnectVirtualRouter
QueryVirtualRouterOffering
CreateVirtualRouterOffering
QueryVirtualRouterVm
AttachPortForwardingRule
DetachPortForwardingRule
GetPortForwardingAttachableVmNics
ChangePortForwardingRuleState
UpdatePortForwardingRule
CreatePortForwardingRule
QueryPortForwardingRule
DeletePortForwardingRule
DetachEip
GetEipAttachableVmNics
UpdateEip
QueryEip
ChangeEipState
DeleteEip
CreateEip
AttachEip
ChangeSecurityGroupState
DetachSecurityGroupFromL3Network
DeleteSecurityGroupRule
CreateSecurityGroup
QueryVmNicInSecurityGroup
QuerySecurityGroup
AddSecurityGroupRule
QuerySecurityGroupRule
DeleteSecurityGroup
UpdateSecurityGroup
DeleteVmNicFromSecurityGroup
GetCandidateVmNicForSecurityGroup
AttachSecurityGroupToL3Network
AddVmNicToSecurityGroup
DeleteVip
UpdateVip
ChangeVipState
CreateVip
QueryVip

API标识（API Identities）¶

ReconnectVirtualRouter: virtualRouter:APIReconnectVirtualRouterMsg

GetNetworkServiceProvider: l2Network:read, l2Network:APIGetNetworkServiceProviderMsg

AddDnsToL3Network: l3Network:APIAddDnsToL3NetworkMsg

DeleteSecurityGroup: securityGroup:APIDeleteSecurityGroupMsg

AddImage: image:APIAddImageMsg

QueryUser: identity:read, identity:APIQueryUserMsg

GetL3NetworkTypes: l3Network:read, l3Network:APIGetL3NetworkTypesMsg

ShareResource: identity:APIShareResourceMsg

QueryVirtualRouterOffering: virtualRouter:read, virtualRouter:APIQueryVirtualRouterOfferingMsg

QueryIpRange: l3Network:read, l3Network:APIQueryIpRangeMsg

AttachDataVolumeToVm: volume:APIAttachDataVolumeToVmMsg

QueryUserGroup: identity:read, identity:APIQueryUserGroupMsg

QueryVmNicInSecurityGroup: securityGroup:read, securityGroup:APIQueryVmNicInSecurityGroupMsg

CreateSystemTag: tag:APICreateSystemTagMsg

CreateVip: vip:APICreateVipMsg

DeleteDiskOffering: configuration:APIDeleteDiskOfferingMsg

StartVmInstance: instance:APIStartVmInstanceMsg

GetVmAttachableL3Network: instance:read, instance:APIGetVmAttachableL3NetworkMsg

DeleteVip: vip:APIDeleteVipMsg

GetDataVolumeAttachableVm: volume:read, volume:APIGetDataVolumeAttachableVmMsg

QuerySystemTag: tag:read, tag:APIQuerySystemTagMsg

AttachL3NetworkToVm: instance:APIAttachL3NetworkToVmMsg

CreateUserTag: tag:APICreateUserTagMsg

CreateVmInstance: instance:APICreateVmInstanceMsg

CreateSecurityGroup: securityGroup:APICreateSecurityGroupMsg

UpdateVolumeSnapshot: volumeSnapshot:APIUpdateVolumeSnapshotMsg

QueryDiskOffering: configuration:read, configuration:APIQueryDiskOfferingMsg

StopVmInstance: instance:APIStopVmInstanceMsg

CreateEip: eip:APICreateEipMsg

ChangePortForwardingRuleState: portForwarding:APIChangePortForwardingRuleStateMsg

UpdateL3Network: l3Network:APIUpdateL3NetworkMsg

ChangeDiskOfferingState: configuration:APIChangeDiskOfferingStateMsg

MigrateVm: instance:APIMigrateVmMsg

ChangeVipState: vip:APIChangeVipStateMsg

AddIpRange: l3Network:APIAddIpRangeMsg

CreateDataVolume: volume:APICreateDataVolumeMsg

CreateDataVolumeFromVolumeSnapshot: volume:APICreateDataVolumeFromVolumeSnapshotMsg

UpdateImage: image:APIUpdateImageMsg

QueryVmNic: instance:read, instance:APIQueryVmNicMsg

QueryTag: tag:read, tag:APIQueryTagMsg

GetPortForwardingAttachableVmNics: portForwarding:APIGetPortForwardingAttachableVmNicsMsg

DeleteInstanceOffering: configuration:APIDeleteInstanceOfferingMsg

AttachPortForwardingRule: portForwarding:APIAttachPortForwardingRuleMsg

DeletePortForwardingRule: portForwarding:APIDeletePortForwardingRuleMsg

CreatePortForwardingRule: portForwarding:APICreatePortForwardingRuleMsg

UpdateIpRange: l3Network:APIUpdateIpRangeMsg

GetFreeIp: l3Network:read, l3Network:APIGetFreeIpMsg

ChangeL3NetworkState: l3Network:APIChangeL3NetworkStateMsg

QueryVip: vip:read, vip:APIQueryVipMsg

UpdateEip: eip:APIUpdateEipMsg

QueryVolumeSnapshotTree: volumeSnapshot:read, volumeSnapshot:APIQueryVolumeSnapshotTreeMsg

DetachDataVolumeFromVm: volume:APIDetachDataVolumeFromVmMsg

RebootVmInstance: instance:APIRebootVmInstanceMsg

UpdateInstanceOffering: configuration:APIUpdateInstanceOfferingMsg

DestroyVmInstance: instance:APIDestroyVmInstanceMsg

UpdateUser: identity:APIUpdateUserMsg

QueryNetworkServiceL3NetworkRef: l3Network:read, l3Network:APIQueryNetworkServiceL3NetworkRefMsg

CreateL3Network: l3Network:APICreateL3NetworkMsg

GetNetworkServiceTypes: l3Network:read, l3Network:APIGetNetworkServiceTypesMsg

GetVmAttachableDataVolume: instance:read, instance:APIGetVmAttachableDataVolumeMsg

QueryL3Network: l3Network:read, l3Network:APIQueryL3NetworkMsg

CreateDataVolumeTemplateFromVolume: image:APICreateDataVolumeTemplateFromVolumeMsg

DeleteSecurityGroupRule: securityGroup:APIDeleteSecurityGroupRuleMsg

QueryUserTag: tag:read, tag:APIQueryUserTagMsg

DeleteVolumeSnapshotFromBackupStorage: volumeSnapshot:APIDeleteVolumeSnapshotFromBackupStorageMsg

CreateDiskOffering: configuration:APICreateDiskOfferingMsg

QuerySecurityGroup: securityGroup:read, securityGroup:APIQuerySecurityGroupMsg

QueryVolumeSnapshot: volumeSnapshot:read, volumeSnapshot:APIQueryVolumeSnapshotMsg

QueryPortForwardingRule: portForwarding:read, portForwarding:APIQueryPortForwardingRuleMsg

UpdateDiskOffering: configuration:APIUpdateDiskOfferingMsg

GetCandidateVmNicForSecurityGroup: securityGroup:read, securityGroup:APIGetCandidateVmNicForSecurityGroupMsg

QueryPolicy: identity:read, identity:APIQueryPolicyMsg

GetEipAttachableVmNics: eip:APIGetEipAttachableVmNicsMsg

CreateInstanceOffering: configuration:APICreateInstanceOfferingMsg

AddIpRangeByNetworkCidr: l3Network:APIAddIpRangeByNetworkCidrMsg

UpdateVmInstance: instance:APIUpdateVmInstanceMsg

QueryVirtualRouterVm: virtualRouter:read, virtualRouter:APIQueryVirtualRouterVmMsg

RequestConsoleAccess: console:APIRequestConsoleAccessMsg

ChangeEipState: eip:APIChangeEipStateMsg

QuerySecurityGroupRule: securityGroup:read, securityGroup:APIQuerySecurityGroupRuleMsg

DetachSecurityGroupFromL3Network: securityGroup:APIDetachSecurityGroupFromL3NetworkMsg

CreateDataVolumeFromVolumeTemplate: volume:APICreateDataVolumeFromVolumeTemplateMsg

DeleteDataVolume: volume:APIDeleteDataVolumeMsg

AddVmNicToSecurityGroup: securityGroup:APIAddVmNicToSecurityGroupMsg

DeleteVolumeSnapshot: volumeSnapshot:APIDeleteVolumeSnapshotMsg

DetachEip: eip:APIDetachEipMsg

DetachPortForwardingRule: portForwarding:APIDetachPortForwardingRuleMsg

CreateVirtualRouterOffering: virtualRouter:APICreateVirtualRouterOfferingMsg

RevertVolumeFromSnapshot: volumeSnapshot:APIRevertVolumeFromSnapshotMsg

DeleteIpRange: l3Network:APIDeleteIpRangeMsg

UpdateVip: vip:APIUpdateVipMsg

AttachNetworkServiceToL3Network: l3Network:APIAttachNetworkServiceToL3NetworkMsg

DeleteTag: tag:APIDeleteTagMsg

RemoveDnsFromL3Network: l3Network:APIRemoveDnsFromL3NetworkMsg

DeleteL3Network: l3Network:APIDeleteL3NetworkMsg

UpdatePortForwardingRule: portForwarding:APIUpdatePortForwardingRuleMsg

ChangeVolumeState: volume:APIChangeVolumeStateMsg

QueryVmInstance: instance:read, instance:APIQueryVmInstanceMsg

GetVmMigrationCandidateHosts: instance:read, instance:APIGetVmMigrationCandidateHostsMsg

UpdateVolume: volume:APIUpdateVolumeMsg

QueryL2Network: l2Network:read, l2Network:APIQueryL2NetworkMsg

BackupVolumeSnapshot: volumeSnapshot:APIBackupVolumeSnapshotMsg

QueryQuota: identity:read, identity:APIQueryQuotaMsg

QueryImage: image:read, image:APIQueryImageMsg

RevokeResourceSharing: identity:APIRevokeResourceSharingMsg

UpdateSecurityGroup: securityGroup:APIUpdateSecurityGroupMsg

ChangeImageState: image:APIChangeImageStateMsg

AddSecurityGroupRule: securityGroup:APIAddSecurityGroupRuleMsg

QueryVolume: volume:read, volume:APIQueryVolumeMsg

AttachSecurityGroupToL3Network: securityGroup:APIAttachSecurityGroupToL3NetworkMsg

DeleteEip: eip:APIDeleteEipMsg

QueryEip: eip:read, eip:APIQueryEipMsg

DeleteImage: image:APIDeleteImageMsg

GetIpAddressCapacity: l3Network:read, l3Network:APIGetIpAddressCapacityMsg

ChangeInstanceOfferingState: configuration:APIChangeInstanceOfferingStateMsg

DeleteVmNicFromSecurityGroup: securityGroup:APIDeleteVmNicFromSecurityGroupMsg

CreateVolumeSnapshot: volumeSnapshot:APICreateVolumeSnapshotMsg

CreateRootVolumeTemplateFromRootVolume: image:APICreateRootVolumeTemplateFromRootVolumeMsg

GetVolumeFormat: volume:read, volume:APIGetVolumeFormatMsg

BackupDataVolume: volume:APIBackupDataVolumeMsg

CreateRootVolumeTemplateFromVolumeSnapshot: image:APICreateRootVolumeTemplateFromVolumeSnapshotMsg

QueryInstanceOffering: configuration:read, configuration:APIQueryInstanceOfferingMsg

ChangeSecurityGroupState: securityGroup:APIChangeSecurityGroupStateMsg

QueryNetworkServiceProvider: l3Network:read, l3Network:APIQueryNetworkServiceProviderMsg

AttachEip: eip:APIAttachEipMsg

DetachL3NetworkFromVm: instance:APIDetachL3NetworkFromVmMsg

默认配额（Default Quotas）¶

名字	描述	值	起始支持版本
vip.num	VIP的最大数量	20	0.8
securityGroup.num	安全组的最大数量	20	0.8
l3.num	L3网络的最大数量	20	0.8
portForwarding.num	端口转发规则的最大数量	20	0.8
vm.num	虚拟机的最多个数	20	0.8
vm.cpuNum	VCPU核的最大数量	80	0.8
vm.memorySize	总内存大小	85899345920 bytes (80G)	0.8
volume.data.num	数据云盘的最大容量	40	0.8
volume.capacity	数据云盘和根云盘的最大总容量	10995116277760 bytes (10T)	0.8
eip.num	EIP的最大数量	20	0.8

动态负载均衡（Elastic Load Balancing）¶

Table of contents

动态负载均衡（Elastic Load Balancing）

介绍 ¶

动态负载均衡（Elastic Load Balancing）能自动的把访问用户应用的流量分发到预先设置的多个后端（Backend）云主机（虚拟机VM），来提供高可靠高并发的访问服务。动态负载均衡可以自动探测用于分发的云主机的当前状态。它会将不可用的云主机（例如被用户停止、或是云主机宕机）从分发队列中移除，并可以在该云主机恢复正常功能后将其自动添加回来。

负载均衡 ¶

负载均衡使用一个 VIP 对外提供统一的IP地址。此外，它通过一个或者多个Listeners来定义负载均衡的属性：负载均衡端口（instance port），负载均衡协议（protocol），健康检查配置（health-check configurations），以及用于分发的后端云主机网卡。

数据结构 ¶

变量名	描述	是否为和选项	可选值	最早支持版本
uuid	参见资源属性			0.9
name	参见资源属性			0.9
description	参见资源属性	true		0.9
state	reserved in 0.9 version, always Enabled		Enabled Disabled	0.9
vipUuid	uuid of VIP			0.9
listeners	a list of listener			0.9
createDate	参见资源属性			0.9
lastOpDate	参见资源属性			0.9

示例 ¶

{
    "listeners": [
        {
            "createDate": "Aug 20, 2015 2:54:14 PM",
            "instancePort": 80,
            "lastOpDate": "Aug 20, 2015 2:54:14 PM",
            "loadBalancerPort": 80,
            "loadBalancerUuid": "0188cec6635845e0b2526a8e7e090e2a",
            "name": "80",
            "protocol": "http",
            "uuid": "ba5f192472ab4fc4b36e5af873f0fec5",
            "vmNicRefs": [
                {
                    "createDate": "Aug 20, 2015 2:55:49 PM",
                    "id": 18,
                    "lastOpDate": "Aug 20, 2015 2:55:49 PM",
                    "listenerUuid": "ba5f192472ab4fc4b36e5af873f0fec5",
                    "status": "Active",
                    "vmNicUuid": "35b8aadef2f847d9836bdf06121e1c29"
                },
                {
                    "createDate": "Aug 20, 2015 2:55:49 PM",
                    "id": 19,
                    "lastOpDate": "Aug 20, 2015 2:55:49 PM",
                    "listenerUuid": "ba5f192472ab4fc4b36e5af873f0fec5",
                    "status": "Active",
                    "vmNicUuid": "df7d40a47cb640a9b40001f2f318989a"
                }
            ]
        },
        {
            "createDate": "Aug 20, 2015 5:29:39 AM",
            "instancePort": 22,
            "lastOpDate": "Aug 20, 2015 5:29:39 AM",
            "loadBalancerPort": 22,
            "loadBalancerUuid": "0188cec6635845e0b2526a8e7e090e2a",
            "name": "ssh",
            "protocol": "tcp",
            "uuid": "2901fd13765c492b9a3d004e806a0beb",
            "vmNicRefs": [
                {
                    "createDate": "Aug 20, 2015 5:30:07 AM",
                    "id": 15,
                    "lastOpDate": "Aug 20, 2015 5:30:07 AM",
                    "listenerUuid": "2901fd13765c492b9a3d004e806a0beb",
                    "status": "Active",
                    "vmNicUuid": "35b8aadef2f847d9836bdf06121e1c29"
                },
                {
                    "createDate": "Aug 20, 2015 5:30:07 AM",
                    "id": 16,
                    "lastOpDate": "Aug 20, 2015 5:30:07 AM",
                    "listenerUuid": "2901fd13765c492b9a3d004e806a0beb",
                    "status": "Active",
                    "vmNicUuid": "df7d40a47cb640a9b40001f2f318989a"
                }
            ]
        }
    ],
    "name": "lb",
    "state": "Enabled",
    "uuid": "0188cec6635845e0b2526a8e7e090e2a",
    "vipUuid": "df6a73601f1741fd847cf5456b0d42ac"
}

Listener ¶

Listener定义了负载均衡应该如何处理发往VIP的网络包。它会设定将发往VIP某个端口（loadBalancerPort）的数据包分发到不同的后端云主机的端口（instancePort）。 Listener还定义了一些属性，例如连接超时，健康检查阀值等。

从用户的使用角度来说，Listener就是简单的定义了监听负载均衡IP的某个端口号，以及隐藏在私有网络上后端云主机用于接收的端口号。

负载均衡可以定义很多listeners，每个listener都可以设定不同的端口号。

此外，ZStack还通过系统标签（System Tags）定义了listener的额外属性：空闲连接超时，最大链接数，健康检查阀值，非健康监控阀值等。具体的细节可以看负载均衡系统标签.

数据结构 ¶

变量名	描述	是否为和选项	可选值	最早支持版本
uuid	参见资源属性			0.9
name	参见资源属性			0.9
description	参见资源属性	true		0.9
loadBalancerUuid	load balancer uuid			0.9
loadBalancerPort	前端端口号，数据到达VIP时的端口号。		1 ~ 65536	0.9
instancePort	后端端口号，数据分发到云主机的端口号。		1 ~ 65336	0.9
protocol	参见 protocol		http tcp	0.9
vmNicRefs	参见 nic reference			0.9
createDate	参见资源属性			0.9
lastOpDate	参见资源属性			0.9

协议 ¶

协议定义了负载均衡应该处理的数据包的类型。目前我们支持两种模式：tcp（网络第四层）和http（网络第七层）。其中tcp是默认的模式, 负载均衡会工作在纯粹的TCP模式，一个双向的链接会建立在客户端和服务器端之间。当设置协议为http时，从客户端到负载均衡，以及负载均衡到服务器端都会建立对应的链接。

示例 ¶

{
    "createDate": "Aug 20, 2015 2:54:14 PM",
    "instancePort": 80,
    "lastOpDate": "Aug 20, 2015 2:54:14 PM",
    "loadBalancerPort": 80,
    "loadBalancerUuid": "0188cec6635845e0b2526a8e7e090e2a",
    "name": "80",
    "protocol": "http",
    "uuid": "ba5f192472ab4fc4b36e5af873f0fec5",
    "vmNicRefs": [
        {
            "createDate": "Aug 20, 2015 2:55:49 PM",
            "id": 18,
            "lastOpDate": "Aug 20, 2015 2:55:49 PM",
            "listenerUuid": "ba5f192472ab4fc4b36e5af873f0fec5",
            "status": "Active",
            "vmNicUuid": "35b8aadef2f847d9836bdf06121e1c29"
        },
        {
            "createDate": "Aug 20, 2015 2:55:49 PM",
            "id": 19,
            "lastOpDate": "Aug 20, 2015 2:55:49 PM",
            "listenerUuid": "ba5f192472ab4fc4b36e5af873f0fec5",
            "status": "Active",
            "vmNicUuid": "df7d40a47cb640a9b40001f2f318989a"
        }
    ]
},

后端云主机网卡 ¶

用户可以把一个新的云主机添加到负载均衡的队列中来。一旦一个网卡的UUID被添加，它就会遵循负载均衡对应的算法在合适的时间被调度。一块网卡可以添加到不同的负载均衡的不同的listener上。当然不论添加多少listener，该网卡所在的云主机应该配置有处理相应网络请求的能力。

负载均衡listener通过调用 nic reference 来添加对应的云主机：

Nic Reference 数据结构 ¶

变量名	描述	可选值	最早支持版本
id	Nic Reference的uuid		0.9
listenerUuid	listener uuid		0.9
vmNicUuid	VM nic uuid		0.9
status	当网卡所在云主机为运行的时候，状态是active，否则是inactive	Active Inactive	0.9

当一个网卡加入了负载均衡listener之后，停止云主机会把Nic Reference的状态改成 Inactive; 启动云主机后会改变该状态为 Active; 删除云主机会把对应的NIC从listener中移除。

完整示例 ¶

假定用户需要创建一个负载均衡器，该负载均衡器会把访问公网IP 80端口和22端口的数据包重定向到后端的两台云主机上。

Public L3 Network UUID	参见资源属性
VM1 nic UUId	35b8aadef2f847d9836bdf06121e1c29
VM2 nic UUID	df7d40a47cb640a9b40001f2f318989a

创建a VIP

::: >>>CreateVip l3NetworkUuid=db6379182e524c06bc8d3ec900ab78d4

创建LB

::: >>>CreateLoadBalancer name=lb vipUuid=df6a73601f1741fd847cf5456b0d42ac

创建listeners

CreateLoadBalancerListener loadBalancerUuid=0188cec6635845e0b2526a8e7e090e2a loadBalancerPort=22 instancePort=22 name=ssh protocol=tcp

CreateLoadBalancerListener loadBalancerUuid=0188cec6635845e0b2526a8e7e090e2a loadBalancerPort=80 instancePort=80 name=80 protocol=http

添加nics到listeners

>>>AddVmNicToLoadBalancer listenerUuid=2901fd13765c492b9a3d004e806a0beb vmNicUuids=35b8aadef2f847d9836bdf06121e1c29,df7d40a47cb640a9b40001f2f318989a

>>>AddVmNicToLoadBalancer listenerUuid=4be2244667d948e286722a4a32e02e65 vmNicUuids=35b8aadef2f847d9836bdf06121e1c29,df7d40a47cb640a9b40001f2f318989a

操作 ¶

创建Load Balancer ¶

用户能够使用CreateLoadBalancer来创建一个负载均衡器。例如：

>>>CreateLoadBalancer name=lb vipUuid=df6a73601f1741fd847cf5456b0d42ac

参数 ¶

变量名	描述	是否为和选项	最早支持版本
name	资源名，参见资源属性		0.9
resourceUuid	资源uuid，参见创建（Create Resources）	true	0.9
description	资源描述，参见资源属性	true	0.9
vipUuid	VIP uuid		0.9
userTags	用户标签，参见创建标签（Create Tags）中的资源类型	true	0.9
systemTags	系统标签，参见创建标签（Create Tags）中的资源类型	true	0.9

Delete Load Balancer ¶

用户可以使用DeleteLoadBalancer 来删除一个负载均衡器。例如：

>>>DeleteLoadBalancer uuid=4be2244667d948e286722a4a32e02e65

参数 ¶

变量名	描述	是否为和选项	可选值	最早支持版本
deleteMode	参见删除资源（Delete Resources）	true	Permissive Enforcing	0.9
uuid	load balancer uuid			0.9

创建Listener ¶

用户可以使用CreateLoadBalancerListener 来创建一个负载均衡listener。例如：

CreateLoadBalancerListener loadBalancerUuid=0188cec6635845e0b2526a8e7e090e2a loadBalancerPort=22 instancePort=22 name=ssh protocol=tcp

参数 ¶

变量名	描述	是否为和选项	可选值	最早支持版本
name	资源名，参见资源属性			0.9
resourceUuid	资源uuid，参见创建（Create Resources）	true		0.9
description	资源描述，参见资源属性	true		0.9
loadBalancerUuid	load balancer uuid			0.9
loadBalancerPort	前端（frontend）负载均衡端口			0.9
instancePort	后端云主机端口。如果缺失，默认使用前端负载均衡端口。	true		0.9
protocol	参见 load balancer protocol		tcp http	0.9
userTags	用户标签，参见创建标签（Create Tags）中的资源类型	true		0.9
systemTags	系统标签，参见创建标签（Create Tags）中的资源类型	true		0.9

删除Listener ¶

用户可以使用DeleteLoadBalancerListener来删除一个listener。例如：

>>DeleteLoadBalancerListener uuid=0188cec6635845e0b2526a8e7e090e2a

参数 ¶

变量名	描述	是否为和选项	可选值	最早支持版本
deleteMode	参见删除资源（Delete Resources）	true	Permissive Enforcing	0.9
uuid	listener uuid			0.9

Add VM Nic to Load Balancer ¶

用户可以使用AddVmNicToLoadBalancer 来添加云主机到一个负载均衡中来。例如：

>>>AddVmNicToLoadBalancer listenerUuid=2901fd13765c492b9a3d004e806a0beb vmNicUuids=35b8aadef2f847d9836bdf06121e1c29,df7d40a47cb640a9b40001f2f318989a

参数 ¶

变量名	描述	是否为和选项	可选值	最早支持版本
listenerUuid	listener uuid			0.9
vmNicUuids	一组云主机网卡的uuid			0.9

从负载均衡中删除云主机网卡 ¶

用户可以使用RemoveVmNicFromLoadBalancer 来把一些云主机的网卡从负载均衡器中删除。例如：

>>>RemoveVmNicFromLoadBalancer listenerUuid=2901fd13765c492b9a3d004e806a0beb vmNicUuids=35b8aadef2f847d9836bdf06121e1c29,df7d40a47cb640a9b40001f2f318989a

参数 ¶

变量名	描述	是否为和选项	可选值	最早支持版本
listenerUuid	listener uuid			0.9
vmNicUuids	一组云主机网卡的uuid			0.9

查询负载均衡 ¶

用户可以使用QueryLoadBalancer来查询任意的负载均衡器。例如：

>>>QueryLoadBalancer name=lb

>>>QueryLoadBalancer listeners.vmNic.vmInstance.name=web

Primitive Fields of Query ¶

参见 load balancer inventory

Nested And Expanded Fields of Query ¶

Field	数据结构	描述	最早支持版本
listeners	参见 load balancer listener inventory	child listeners	0.9
vip	参见 vip inventory	bound VIP	0.9

Query Listener ¶

用户可以使用QueryLoadBalancerListener 来查询任意lisenter。例如：

>>>QueryLoadBalancerListener loadBalancerPort=80

>>>QueryLoadBalancerListener loadBalancer.vip.ip=192.168.0.10

Primitive Fields of Query ¶

参见 load balancer listener inventory

Nested And Expanded Fields of Query ¶

Field	数据结构	描述	最早支持版本
loadBalancer	参见 load balancer inventory	parent load balancer	0.9
vmNic	参见 vm nic inventory	joined VM nics	0.9

标签 ¶

用户可以给一个负载均衡器创建一个用户标签。例如:

CreateUserTag tag=web-lb resourceUuid=0a9f95a659444848846b5118e15bff32 resourceType=LoadBalancerVO

用户可以给一个负载均衡的listener创建一个用户标签。例如:

CreateUserTag tag=web-lb-80 resourceUuid=0a9f95a659444848846b5118e15bff32 resourceType=LoadBalancerListenerVO

系统标签 ¶

独立的虚拟路由器(Virtual Router)¶

在ZStack 0.9版本里，负载均衡服务是由虚拟路由器提供的。通常用户仅需要一个虚拟路由器来提供各自服务，例如SNAT，动态IP，端口转发和负载均衡等。如果用户对负载均衡有更高的要求，ZStack也可以单独创建只提供负载均衡服务的虚拟路由虚拟机。

标签	示例	起始版本
separateVirtualRouterVm	separateVirtualRouterVm	0.9

>>>CreateLoadBalancer name=lb vipUuid=df6a73601f1741fd847cf5456b0d42ac systemTags=separateVirtualRouterVm

Listener 配置 ¶

负载均衡listener拥有一组可以控制行为、可配置的系统标签，例如，最大连接数量、空闲连接超时、负载均衡算法等等。用户创建listener的时候，ZStack会设置一组默认值。用户也可以根据需求更改配置。

健康检查阀值（Healthy Threshold）¶

连续通过健康检查的最少次数，用于判断新添加云主机的健康度。

标签	示例	起始版本
healthyThreshold::{healthyThreshold}	healthyThreshold::2	0.9

健康检查的间隔时间 ¶

最大健康检查的间隔时间（秒）。

标签	示例	起始版本
healthCheckInterval::{healthCheckInterval}	healthCheckInterval::5	0.9

非健康检查阀值（Unhealthy Threshold）¶

连续不通过健康检查的最少次数，用于判断是否要把对应的云主机设定为非健康状态。

标签	示例	起始版本
unhealthyThreshold::{unhealthyThreshold}	unhealthyThreshold::2	0.9

空闲连接超时（Connection Idle Timeout）¶

最大关闭空闲连接的超时时间（秒），包括客户端和服务端任意方向的连接。

标签	示例	起始版本
connectionIdleTimeout::{connectionIdleTimeout}	60	0.9

最大允许连接数量（Max Connections）¶

最大允许的并发连接数量。

标签	示例	起始版本
maxConnection::{maxConnection}	maxConnection::5000	0.9

负载均衡算法（Balancing Algorithm）¶

负载均衡算法可以对网络包设定不同的路由规则。目前支持的算法有： roundrobin, leastconn, source

标签	示例	起始版本
balancerAlgorithm::{balancerAlgorithm}	balancerAlgorithm::leastconn	0.9

CreateLoadBalancerListener loadBalancerUuid=0188cec6635845e0b2526a8e7e090e2a loadBalancerPort=22 instancePort=22 name=ssh protocol=tcp
systemTags=maxConnection::10000,balancerAlgorithm::source,healthyThreshold::5

全局配置参数 ¶

空闲连接超时 ¶

系统标签的默认值 Connection Idle Timeout.

Name	Category	Default Value	Choices
connectionIdleTimeout	loadBalancer	60

健康检查阀值 ¶

系统标签的默认值 Healthy Threshold.

Name	Category	Default Value	Choices
healthyThreshold	loadBalancer	2

非健康监控阀值 ¶

系统标签的默认值 Unhealthy Threshold.

Name	Category	Default Value	Choices
unhealthyThreshold	loadBalancer	2

健康检查间隔时间 ¶

系统标签的默认值 Health Check Interval.

Name	Category	Default Value	Choices
healthCheckInterval	loadBalancer	5

最大连接数量 ¶

系统标签的默认值 Max Connection.

Name	Category	Default Value	Choices
maxConnection	loadBalancer	5000

负载均衡算法 ¶

系统标签的默认值 Balancing Algorithm.

Name	Category	Default Value	Choices
balancerAlgorithm	loadBalancer	roundrobin	roundrobin leastconn source