├── .gitignore ├── userManual ├── cli1.png ├── cli2.png ├── cli3.png ├── cli4.png ├── cli5.png ├── cli6.png ├── eip1.png ├── host.png ├── lb1.png ├── lb2.png ├── vip1.png ├── zone.png ├── cluster.png ├── query1.png ├── host-state.png ├── identity.png ├── identity2.png ├── identity3.png ├── l2Network.png ├── l3Network1.png ├── l3Network2.png ├── l3Network3.png ├── l3Network4.png ├── vm-state.png ├── word-view1.png ├── host-status.png ├── vm-networks1.png ├── world-view2.png ├── backupStorage1.png ├── backupStorage2.png ├── l2VlanNetwork1.png ├── portforwarding1.png ├── portforwarding2.png ├── primary-storage.png ├── security-group1.png ├── security-group2.png ├── security-group3.png ├── virtualrouter1.png ├── virtualrouter2.png ├── virtualrouter3.png ├── virtualrouter4.png ├── virtualrouter5.png ├── volume-status.png ├── volumeSnapshot1.png ├── volumeSnapshot2.png ├── volumeSnapshot3.png ├── volumeSnapshot4.png ├── volumeSnapshot5.png ├── l2NoVlanNetwork1.png ├── l2NoVlanNetwork2.png ├── resource-overall.png ├── l2Network-cluster1.png ├── l2Network-cluster2.png ├── backup-storage-status.png ├── primary-storage-status.png ├── single-node-deployment.png ├── multiple-nodes-deployment.png ├── primary-storage-cluster1.png ├── primary-storage-cluster2.png ├── primary-storage-cluster3.png ├── primary-storage-cluster4.png ├── l2Network-physical-interface.png ├── convertPNG.sh ├── globalConfigure.rst ├── cli.rst ├── introduction.rst ├── vip.rst ├── eip.rst ├── diskOffering.rst ├── zone.rst ├── portForwarding.rst ├── tag.rst ├── resource.rst ├── instanceOffering.rst ├── cluster.rst ├── l2Network.rst ├── primaryStorage.rst ├── query.rst └── backupStorage.rst ├── index.rst~ ├── index.rst ├── Makefile ├── conf.py └── LICENSE /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | .idea/* 3 | _build/* 4 | -------------------------------------------------------------------------------- /userManual/cli1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/cli1.png -------------------------------------------------------------------------------- /userManual/cli2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/cli2.png -------------------------------------------------------------------------------- /userManual/cli3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/cli3.png -------------------------------------------------------------------------------- /userManual/cli4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/cli4.png -------------------------------------------------------------------------------- /userManual/cli5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/cli5.png -------------------------------------------------------------------------------- /userManual/cli6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/cli6.png -------------------------------------------------------------------------------- /userManual/eip1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/eip1.png -------------------------------------------------------------------------------- /userManual/host.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/host.png -------------------------------------------------------------------------------- /userManual/lb1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/lb1.png -------------------------------------------------------------------------------- /userManual/lb2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/lb2.png -------------------------------------------------------------------------------- /userManual/vip1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/vip1.png -------------------------------------------------------------------------------- /userManual/zone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/zone.png -------------------------------------------------------------------------------- /userManual/cluster.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/cluster.png -------------------------------------------------------------------------------- /userManual/query1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/query1.png -------------------------------------------------------------------------------- /userManual/host-state.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/host-state.png -------------------------------------------------------------------------------- /userManual/identity.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/identity.png -------------------------------------------------------------------------------- /userManual/identity2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/identity2.png -------------------------------------------------------------------------------- /userManual/identity3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/identity3.png -------------------------------------------------------------------------------- /userManual/l2Network.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l2Network.png -------------------------------------------------------------------------------- /userManual/l3Network1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l3Network1.png -------------------------------------------------------------------------------- /userManual/l3Network2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l3Network2.png -------------------------------------------------------------------------------- /userManual/l3Network3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l3Network3.png -------------------------------------------------------------------------------- /userManual/l3Network4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l3Network4.png -------------------------------------------------------------------------------- /userManual/vm-state.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/vm-state.png -------------------------------------------------------------------------------- /userManual/word-view1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/word-view1.png -------------------------------------------------------------------------------- /userManual/host-status.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/host-status.png -------------------------------------------------------------------------------- /userManual/vm-networks1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/vm-networks1.png -------------------------------------------------------------------------------- /userManual/world-view2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/world-view2.png -------------------------------------------------------------------------------- /userManual/backupStorage1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/backupStorage1.png -------------------------------------------------------------------------------- /userManual/backupStorage2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/backupStorage2.png -------------------------------------------------------------------------------- /userManual/l2VlanNetwork1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l2VlanNetwork1.png -------------------------------------------------------------------------------- /userManual/portforwarding1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/portforwarding1.png -------------------------------------------------------------------------------- /userManual/portforwarding2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/portforwarding2.png -------------------------------------------------------------------------------- /userManual/primary-storage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/primary-storage.png -------------------------------------------------------------------------------- /userManual/security-group1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/security-group1.png -------------------------------------------------------------------------------- /userManual/security-group2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/security-group2.png -------------------------------------------------------------------------------- /userManual/security-group3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/security-group3.png -------------------------------------------------------------------------------- /userManual/virtualrouter1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/virtualrouter1.png -------------------------------------------------------------------------------- /userManual/virtualrouter2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/virtualrouter2.png -------------------------------------------------------------------------------- /userManual/virtualrouter3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/virtualrouter3.png -------------------------------------------------------------------------------- /userManual/virtualrouter4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/virtualrouter4.png -------------------------------------------------------------------------------- /userManual/virtualrouter5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/virtualrouter5.png -------------------------------------------------------------------------------- /userManual/volume-status.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/volume-status.png -------------------------------------------------------------------------------- /userManual/volumeSnapshot1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/volumeSnapshot1.png -------------------------------------------------------------------------------- /userManual/volumeSnapshot2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/volumeSnapshot2.png -------------------------------------------------------------------------------- /userManual/volumeSnapshot3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/volumeSnapshot3.png -------------------------------------------------------------------------------- /userManual/volumeSnapshot4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/volumeSnapshot4.png -------------------------------------------------------------------------------- /userManual/volumeSnapshot5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/volumeSnapshot5.png -------------------------------------------------------------------------------- /userManual/l2NoVlanNetwork1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l2NoVlanNetwork1.png -------------------------------------------------------------------------------- /userManual/l2NoVlanNetwork2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l2NoVlanNetwork2.png -------------------------------------------------------------------------------- /userManual/resource-overall.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/resource-overall.png -------------------------------------------------------------------------------- /userManual/l2Network-cluster1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l2Network-cluster1.png -------------------------------------------------------------------------------- /userManual/l2Network-cluster2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l2Network-cluster2.png -------------------------------------------------------------------------------- /userManual/backup-storage-status.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/backup-storage-status.png -------------------------------------------------------------------------------- /userManual/primary-storage-status.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/primary-storage-status.png -------------------------------------------------------------------------------- /userManual/single-node-deployment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/single-node-deployment.png -------------------------------------------------------------------------------- /userManual/multiple-nodes-deployment.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/multiple-nodes-deployment.png -------------------------------------------------------------------------------- /userManual/primary-storage-cluster1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/primary-storage-cluster1.png -------------------------------------------------------------------------------- /userManual/primary-storage-cluster2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/primary-storage-cluster2.png -------------------------------------------------------------------------------- /userManual/primary-storage-cluster3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/primary-storage-cluster3.png -------------------------------------------------------------------------------- /userManual/primary-storage-cluster4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/primary-storage-cluster4.png -------------------------------------------------------------------------------- /userManual/l2Network-physical-interface.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zstackio/doc/HEAD/userManual/l2Network-physical-interface.png -------------------------------------------------------------------------------- /userManual/convertPNG.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | files=`ls *.PNG` 4 | 5 | for f in $files 6 | do 7 | filename=`echo $f | cut -f1 -d'.'` 8 | echo $filename 9 | mv $f $filename.png 10 | done 11 | -------------------------------------------------------------------------------- /index.rst~: -------------------------------------------------------------------------------- 1 | ================== 2 | ZStack User Manual 3 | ================== 4 | 5 | ------------ 6 | Introduction 7 | ------------ 8 | 9 | ZStack is an open source software that manages compute nodes, networks, and storage to provide infrastructure as a service(IaaS) 10 | solution, written in Java and Python. 11 | 12 | This documentation is a full reference of all ZStack features. If you haven't installed ZStack and tried out several tutorials, 13 | please visit our `web site `_ for `installation `_ and `tutorials `_. 14 | 15 | Chapters in this documentation are arranged in sections of: 16 | 17 | - **Overview**: gives your a brief background of the topic. 18 | 19 | - **Inventory**: explains the data model of the resource (e.g. zone, virtual machine), which usually starts with a table listing 20 | properties of the resource, and is followed by detailed explanations of properties that are not straightforward. 21 | 22 | - **Operations**: explains every API manipulating the resource. APIs are explained in examples of ZStack command tool that you 23 | will see in chapter 3. 24 | 25 | - **Global Configurations**: explains every global configuration that can be applied to the resource, if there is any. 26 | 27 | - **System Tags**: explains every system tag that can be applied to the resource, if there is any. 28 | 29 | We recommend users to start with the chapter :ref:`Introduction` and read at least chapters :ref:`Resource Model `, :ref:`Command Line Tool `, 30 | and :ref:`Query ` all of which are important for your daily use of ZStack. For other chapters, you can use them as references 31 | when you need, for example, looking up chapter :ref:`Virtual Machine ` when you want to find out the command for creating a VM. 32 | 33 | -------- 34 | Chapters 35 | -------- 36 | 37 | .. toctree:: 38 | :maxdepth: 1 39 | 40 | userManual/introduction 41 | userManual/resource 42 | userManual/cli 43 | userManual/query 44 | userManual/globalConfigure 45 | userManual/tag 46 | userManual/zone 47 | userManual/cluster 48 | userManual/host 49 | userManual/primaryStorage 50 | userManual/l2Network 51 | userManual/l3Network 52 | userManual/image 53 | userManual/backupStorage 54 | userManual/volume 55 | userManual/diskOffering 56 | userManual/instanceOffering 57 | userManual/vm 58 | userManual/securityGroup 59 | userManual/virtualRouter 60 | userManual/vip 61 | userManual/portForwarding 62 | userManual/eip 63 | userManual/volumeSnapshot 64 | 65 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | ZStack User Manual 3 | ================== 4 | 5 | ------------ 6 | Introduction 7 | ------------ 8 | 9 | ZStack is an open source software that manages compute nodes, networks, and storage to provide infrastructure as a service(IaaS) 10 | solution, written in Java and Python. 11 | 12 | This documentation is a full reference of all ZStack features. If you haven't installed ZStack and tried out several tutorials, 13 | please visit our `web site `_ for `installation `_ and `tutorials `_. 14 | 15 | Chapters in this documentation are arranged in sections of: 16 | 17 | - **Overview**: gives your a brief background of the topic. 18 | 19 | - **Inventory**: explains the data model of the resource (e.g. zone, virtual machine), which usually starts with a table listing 20 | properties of the resource, and is followed by detailed explanations of properties that are not straightforward. 21 | 22 | - **Operations**: explains every API manipulating the resource. APIs are explained in examples of ZStack command tool that you 23 | will see in chapter 3. 24 | 25 | - **Global Configurations**: explains every global configuration that can be applied to the resource, if there is any. 26 | 27 | - **System Tags**: explains every system tag that can be applied to the resource, if there is any. 28 | 29 | We recommend users to start with the chapter :ref:`Introduction` and read at least chapters :ref:`Resource Model `, :ref:`Command Line Tool `, 30 | and :ref:`Query ` all of which are important for your daily use of ZStack. For other chapters, you can use them as references 31 | when you need, for example, looking up chapter :ref:`Virtual Machine ` when you want to find out the command for creating a VM. 32 | 33 | -------- 34 | Chapters 35 | -------- 36 | 37 | .. toctree:: 38 | :maxdepth: 1 39 | 40 | userManual/introduction 41 | userManual/resource 42 | userManual/cli 43 | userManual/query 44 | userManual/globalConfigure 45 | userManual/tag 46 | userManual/zone 47 | userManual/cluster 48 | userManual/host 49 | userManual/primaryStorage 50 | userManual/l2Network 51 | userManual/l3Network 52 | userManual/image 53 | userManual/backupStorage 54 | userManual/volume 55 | userManual/diskOffering 56 | userManual/instanceOffering 57 | userManual/vm 58 | userManual/securityGroup 59 | userManual/virtualRouter 60 | userManual/vip 61 | userManual/portForwarding 62 | userManual/eip 63 | userManual/volumeSnapshot 64 | userManual/identity 65 | userManual/lb 66 | 67 | -------------------------------------------------------------------------------- /userManual/globalConfigure.rst: -------------------------------------------------------------------------------- 1 | .. _global configure: 2 | 3 | ===================== 4 | Global Configurations 5 | ===================== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | Admins can use global configurations to configure a variety of features; all global configurations come with a default value; updating 15 | a global configuration doesn't require to restart the management node. 16 | 17 | We arrange resource related global configurations in each chapter, for those configurations that don't specifically categorise 18 | in any resource we list them in this chapter. 19 | 20 | --------- 21 | Inventory 22 | --------- 23 | 24 | .. list-table:: 25 | :widths: 20 40 10 20 10 26 | :header-rows: 1 27 | 28 | * - Name 29 | - Description 30 | - Optional 31 | - Choices 32 | - Since 33 | * - **category** 34 | - configuration category 35 | - 36 | - 37 | - 0.6 38 | * - **description** 39 | - configuration description 40 | - 41 | - 42 | - 0.6 43 | * - **name** 44 | - configuration name 45 | - 46 | - 47 | - 0.6 48 | * - **defaultValue** 49 | - default value 50 | - 51 | - 52 | - 0.6 53 | * - **value** 54 | - current value 55 | - 56 | - 57 | - 0.6 58 | 59 | Example 60 | ======= 61 | 62 | :: 63 | 64 | { 65 | "category": "identity", 66 | "defaultValue": "500", 67 | "description": "Max number of sessions management server accepts. When this limit met, new session will be rejected", 68 | "name": "session.maxConcurrent", 69 | "value": "500" 70 | } 71 | 72 | 73 | ---------- 74 | Operations 75 | ---------- 76 | 77 | Update Global Configurations 78 | ============================ 79 | 80 | Admins can use UpdateGlobalConfig to update a global configuration. For example:: 81 | 82 | UpdateGlobalConfig category=host name=connection.autoReconnectOnError value=true 83 | 84 | 85 | -------------------- 86 | Other Configurations 87 | -------------------- 88 | 89 | For configurations that don't categorise in individual chapter. 90 | 91 | 92 | .. _cloudBus.statistics.on: 93 | 94 | statistics.on 95 | ============= 96 | 97 | .. list-table:: 98 | :widths: 20 30 20 30 99 | :header-rows: 1 100 | 101 | * - Name 102 | - Category 103 | - Default Value 104 | - Choices 105 | * - **statistics.on** 106 | - cloudBus 107 | - false 108 | - - true 109 | - false 110 | 111 | Whether enables statistics that count time consuming of each message through JMX. 112 | 113 | 114 | .. _node.heartbeatInterval: 115 | 116 | node.heartbeatInterval 117 | ====================== 118 | 119 | .. list-table:: 120 | :widths: 20 30 20 30 121 | :header-rows: 1 122 | 123 | * - Name 124 | - Category 125 | - Default Value 126 | - Choices 127 | * - **node.heartbeatInterval** 128 | - managementServer 129 | - 5 130 | - > 0 131 | 132 | The interval that each management node writes heartbeat to database, in seconds. 133 | 134 | 135 | .. _node.joinDelay: 136 | 137 | node.joinDelay 138 | ============== 139 | 140 | .. list-table:: 141 | :widths: 20 30 20 30 142 | :header-rows: 1 143 | 144 | * - Name 145 | - Category 146 | - Default Value 147 | - Choices 148 | * - **node.joinDelay** 149 | - managementServer 150 | - 0 151 | - >= 0 152 | 153 | If non zero, each management node will delay random seconds from 0 to 'node.joinDelay' before publishing join event on the message bus. This 154 | avoid storm of join event when a large number of management nodes start at the same time. 155 | 156 | 157 | .. _configuration.key.public: 158 | 159 | key.public 160 | ========== 161 | 162 | .. list-table:: 163 | :widths: 20 30 20 30 164 | :header-rows: 1 165 | 166 | * - Name 167 | - Category 168 | - Default Value 169 | - Choices 170 | * - **key.public** 171 | - configuration 172 | - see your database 173 | - 174 | 175 | ZStack will inject this public SSH key to Linux servers that need to deploy agents; in this version, the Linux servers include KVM host, virtual router VMs, 176 | SFTP backup storage. After injecting, ZStack will use :ref:`key.private ` when needing SSH login. 177 | 178 | 179 | .. _configuration.key.private: 180 | 181 | key.private 182 | =========== 183 | 184 | .. list-table:: 185 | :widths: 20 30 20 30 186 | :header-rows: 1 187 | 188 | * - Name 189 | - Category 190 | - Default Value 191 | - Choices 192 | * - **key.private** 193 | - configuration 194 | - see your database 195 | - 196 | 197 | The private SSH key ZStack uses to SSH login remote Linux servers; see :ref:`key.public `. 198 | -------------------------------------------------------------------------------- /userManual/cli.rst: -------------------------------------------------------------------------------- 1 | .. _cli: 2 | 3 | ================= 4 | Command Line Tool 5 | ================= 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | zstack-cli is the command line tool for users to execute all ZStack APIs. All API examples in this user manual 15 | are demonstrated using zstack-cli. 16 | 17 | As ZStack is built on SOA(Service Oriented Architecture), all ZStack APIs are essentially messages; for example, you will see 18 | a CLI command called *StartVmInstance* in VM related chapter, which is actually mapping to the API message: APIStartVmInstanceMsg; 19 | nevertheless, people are more familiar with HTTP calls than messages, so ZStack ships a builtin HTTP server that wraps all API messages 20 | into HTTP post requests. zstack-cli is built on calling APIs through the builtin HTTP server. 21 | 22 | ----- 23 | Usage 24 | ----- 25 | 26 | Connect to ZStack management node 27 | ================================= 28 | 29 | zstack-cli is installed by default after you install a ZStack management node. You can launch it by simply typing 'zstack-cli' in a shell console: 30 | 31 | .. image:: cli1.png 32 | :align: center 33 | 34 | if no parameters are provided, zstack-cli will connect to 8080 port on localhost; to connect a remote ZStack management node, 35 | you can use options '-s' and '-p' to specify IP and port: 36 | 37 | .. image:: cli2.png 38 | :align: center 39 | 40 | .. note:: ZStack management nodes are running in Java servlet containers, for example, Tomcat, whose port numbers are rarely changed; most 41 | of the time you only need to specify the IP by '-s'. 42 | 43 | if you have a multi-node deployment, you can connect the zstack-cli to any management nodes. 44 | 45 | 46 | Modes 47 | ===== 48 | 49 | zstack-cli can work in a command mode that receives parameters from shell, runs once, and prints results to the shell console, for example: 50 | 51 | .. image:: cli3.png 52 | :align: center 53 | 54 | or an interactive shell mode that keeps a session for continuously executing, for example: 55 | 56 | .. image:: cli4.png 57 | :align: center 58 | 59 | people usually prefer interactive mode for manual execution but command mode for script integration. 60 | 61 | 62 | LogIn 63 | ===== 64 | 65 | In this ZStack version(0.6), the IAM(Identity and Access Management) system is not ready; only one account 'admin' with default password('password') 66 | is available. Before executing any commands, you need to run the login command 'LogInByAccount' to get a session token which is automatically saved 67 | by zstack-cli to ~/.zstack/cli/session and you don't need to keep it separately:: 68 | 69 | >>> LogInByAccount accountName=admin password=password 70 | 71 | 72 | LogOut 73 | ====== 74 | 75 | Once you finish your work, you can use 'LogOut' to invalidate current session:: 76 | 77 | >>> LogOut 78 | 79 | the LogOut command receives a parameter 'sessionUuid', but you don't need to provide it as zstack-cli will retrieve it from where it's kept. 80 | 81 | Execute API Commands 82 | ==================== 83 | 84 | Every API is a command with several parameters, you can execute them in either command mode or interactive mode:: 85 | 86 | >>> StartVmInstance uuid=11be8ac6adad44c68ae02493cba29846 87 | 88 | :: 89 | 90 | [root@localhost ~]# zstack-cli StartVmInstance uuid=11be8ac6adad44c68ae02493cba29846 91 | 92 | .. note:: In interactive mode, you can use Tab key to auto-complete a command or remind you about candidate parameters. 93 | 94 | 95 | View Command History 96 | ==================== 97 | 98 | You can use 'more' command to view your command history, for example:: 99 | 100 | >>> more 101 | 102 | or:: 103 | 104 | [root@localhost ~]# zstack-cli more 105 | 106 | the result format is the same to Linux *more* command, you can scroll up/down and search. 107 | 108 | .. image:: cli5.png 109 | :align: center 110 | 111 | 112 | to view the details of a command, use 'more' command following a command number:: 113 | 114 | >>> more 6 115 | 116 | or:: 117 | 118 | [root@localhost ~]# zstack-cli more 6 119 | 120 | the result is like: 121 | 122 | .. image:: cli6.png 123 | :align: center 124 | 125 | .. note:: Viewing command details is very useful when output of a command is larger than the screen size; for example, 126 | the result of QueryVmInstance. 127 | 128 | 129 | Export Command History 130 | ====================== 131 | 132 | You can export command history by 'save' command, saving one history each time or multiple histories at once:: 133 | 134 | >>> save 1 135 | Saved command: 1 result to file: /home/root/QueryZone-1.json 136 | 137 | :: 138 | 139 | [root@localhost ~]# zstack-cli -s 192.168.0.212 save 1 140 | Saved command: 1 result to file: /home/root/QueryZone-1.json 141 | 142 | or:: 143 | 144 | >>>save 1,2,3 145 | Saved command: 1 result to file: /home/root/QueryZone-1.json 146 | Saved command: 2 result to file: /home/root/CreateZone-2.json 147 | Saved command: 3 result to file: /home/root/LogInByAccount-3.json 148 | 149 | :: 150 | 151 | [root@localhost ~]# zstack-cli -s 192.168.0.212 save 1,2,3 152 | Saved command: 1 result to file: /home/root/QueryZone-1.json 153 | Saved command: 2 result to file: /home/root/CreateZone-2.json 154 | Saved command: 3 result to file: /home/root/LogInByAccount-3.json 155 | 156 | 157 | by default results are saved to current working folder, you can specify a destination folder by supplying an extra parameter of folder path:: 158 | 159 | >>> save 1 /tmp 160 | save history command 1 result to /tmp/COMMAND-1.json 161 | 162 | -------------------------------------------------------------------------------- /userManual/introduction.rst: -------------------------------------------------------------------------------- 1 | .. _introduction: 2 | 3 | ============ 4 | Introduction 5 | ============ 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | Depending on the scale of a cloud, a ZStack setup can be as simple as a single Linux machine running one ZStack management node, 15 | or a cluster of Linux servers running multiple ZStack management nodes. 16 | 17 | The Setup of A Single Management Node 18 | ===================================== 19 | 20 | .. image:: single-node-deployment.png 21 | :alt: a single management node deployment 22 | :align: center 23 | :height: 500px 24 | :width: 600px 25 | 26 | In the simplest setup, all ZStack software and third party dependencies are installed on a single Linux server. 27 | A typical setup includes five parts: 28 | 29 | - `RabbitMQ Message Server `_: The central message bus ZStack services use for communication. 30 | - `MySQL Database `_: The database ZStack stores metadata for resources in the cloud. 31 | - `Ansible `_: The configuration management tool ZStack uses to remotely deploy and upgrade agents. 32 | - ZStack Management Node: The main process encompassing all ZStack orchestration services. 33 | - ZStack UI Server: A web server providing user interface for end users. 34 | 35 | Besides, several python agents, which need deploying to local or remote machines at runtime, are packaged in the WAR file of 36 | ZStack management node and are deployed using Ansible. 37 | 38 | Because of ZStack's asynchronous architecture, a single management node is normally enough to manage a big cloud that may have tens of thousands 39 | of physical servers, hundreds of thousands of virtual machines(virtual machine is referred as VM in future chapters), and tens of thousands of concurrent API requests. 40 | However, in case of high availability and scaling out for a super large cloud, a setup of multiple management nodes is still valuable. 41 | 42 | A Deployment of Multiple Management Nodes 43 | ========================================= 44 | 45 | .. image:: multiple-nodes-deployment.png 46 | :alt: a multiple management nodes deployment 47 | :align: center 48 | :height: 1000px 49 | 50 | In this multiple nodes setup, the RabbitMQ server and MySQL database server are moved out to dedicated Linux machines; ZStack management nodes 51 | and Ansible are installed on every Linux server; multiple management nodes share the same RabbitMQ message server and MySQL database. ZStack UI servers, 52 | which also send API requests to management nodes through RabbitMQ, are deployed behind a load balancer which dispatches requests from users. 53 | 54 | In terms of clustering RabbitMQ and MySQL, admin can setup two RabbitMQ servers and an additional slave MySQL database server. 55 | 56 | ZStack's World View of A Cloud 57 | ============================== 58 | 59 | IaaS software usually use some terms such as 'zone', 'cluster' to describe how facilities in a data center make up a cloud, so does ZStack. 60 | To reduce the learning curve and to eliminate misunderstandings caused by self-created terms, ZStack tries to use terminologies that have been well known in existing IaaS software 61 | and datacenters as much as possible. 62 | 63 | Below is a diagram that how ZStack maps facilities of datacenters into its own language. 64 | 65 | .. image:: word-view1.png 66 | :alt: word view1 67 | :align: center 68 | :height: 1000px 69 | 70 | A datacenter, in ZStack's terms, is organized as follows: 71 | 72 | - **Zone**: 73 | 74 | A zone is a logic group of resources, such as clusters, L2 networks, primary storage. ZStacks uses zones to define visibility boundary between resources. 75 | For example, a primary storage in zone A is not visible to a cluster in zone B. In practice, zones can also be used as isolated domains for fault tolerance, just as 76 | Amazon EC2 availability zones. 77 | 78 | - **Cluster**: 79 | 80 | A cluster is a logic group of hosts. Hosts in the same cluster must have the same operating systems(hypervisor) and network configurations. Clusters are also known 81 | as host aggregations or host pools in other IaaS software. 82 | 83 | - **Host**: 84 | 85 | A host is a physical server installed with an operating system(hypervisor) to run VMs. 86 | 87 | - **L2 Network**: 88 | 89 | A L2 network is an abstraction of a layer 2 broadcast domain. Any technology, as long as providing a layer 2 broadcast domain, 90 | can be a type of L2 Network in ZStack. For example, VLAN, VxLan, or SDN technologies that create layer 2 overlay on layer 3 network. 91 | 92 | - **Primary Storage**: 93 | 94 | A primary storage provides disk spaces to store VMs' volumes which will be accessed by VMs' operating system during running. Primary Storage can be either filesystem 95 | based like NFS or block storage based like ISCSI. 96 | 97 | - **Backup Storage**: 98 | 99 | A backup Storage provides disk spaces to store images and volume snapshots both of which can be used to create volumes. Files on backup storage are not directly accessible 100 | to VMs; before being used, they need to be downloaded to primary storage. Backup Storage can either be filesystem based or object storage based. 101 | 102 | ZStack uses a so-called 'attaching strategy' to describe relationships between resources, for example, a cluster can be attached with multiple primary storage and L2 networks, vice versa. 103 | See related chapters(e.g. primary storage, L2 network) for details. 104 | 105 | A data center can have one or more zones. A diagram of multiple zones looks like: 106 | 107 | .. image:: world-view2.png 108 | :alt: world view2 109 | :align: center 110 | :height: 1000px 111 | 112 | 113 | .. note:: For simplicity, the diagram omits some facilities like aggregation switches, core switches, routers, load balancer, firewalls and so on. 114 | 115 | Besides above terms describing datacenter facilities, there are some other terms such as VM, instance offering, disk offering, which describe 116 | virtual resources; check details in relevant chapters. 117 | -------------------------------------------------------------------------------- /userManual/vip.rst: -------------------------------------------------------------------------------- 1 | .. _vip: 2 | 3 | ================== 4 | Virtual IP Address 5 | ================== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | When bridging communication between two networks, many network services such as Port Forwarding, EIP, VPN, Load Balancing need 15 | virtual Ip addresses (VIP); incoming packets are sent to VIPs and are routed to private network IPs. 16 | 17 | .. image:: vip1.png 18 | :align: center 19 | 20 | In real world cases, VIPs are usually public IPs that can be reached by the internet, routing traffics to behind private IPs 21 | which are often on a private network not visible to the internet. 22 | 23 | In this ZStack version, a VIP must be allocated before creating a port forwarding rule or an EIP. For this time being, 24 | as the virtual router provider is the only network service provider, a VIP should be 25 | created from a virtual router VM's public network(see :ref:`virtual router offering `) in order to route traffics 26 | to the guest network. 27 | 28 | .. _vip inventory: 29 | 30 | --------- 31 | Inventory 32 | --------- 33 | 34 | Properties 35 | ========== 36 | 37 | .. list-table:: 38 | :widths: 20 40 10 20 10 39 | :header-rows: 1 40 | 41 | * - Name 42 | - Description 43 | - Optional 44 | - Choices 45 | - Since 46 | * - **uuid** 47 | - see :ref:`resource properties` 48 | - 49 | - 50 | - 0.6 51 | * - **name** 52 | - see :ref:`resource properties` 53 | - 54 | - 55 | - 0.6 56 | * - **description** 57 | - see :ref:`resource properties` 58 | - true 59 | - 60 | - 0.6 61 | * - **ipRangeUuid** 62 | - uuid of IP range the VIP is allocated 63 | - 64 | - 65 | - 0.6 66 | * - **l3NetworkUuid** 67 | - uuid of L3 network the VIP is allocated 68 | - 69 | - 70 | - 0.6 71 | * - **ip** 72 | - IP address 73 | - 74 | - 75 | - 0.6 76 | * - **state** 77 | - VIP state, not implemented in this version 78 | - 79 | - - Enabled 80 | - Disabled 81 | - 0.6 82 | * - **gateway** 83 | - gateway 84 | - 85 | - 86 | - 0.6 87 | * - **netmask** 88 | - netmask 89 | - 90 | - 91 | - 0.6 92 | * - **serviceProvider** 93 | - name of service provider that uses this VIP 94 | - true 95 | - 96 | - 0.6 97 | * - **peerL3NetworkUuid** 98 | - uuid of L3 network to which this VIP routes traffic 99 | - 100 | - 101 | - 0.6 102 | * - **useFor** 103 | - the service name which uses the VIP 104 | - true 105 | - - EIP 106 | - PortForwarding 107 | - 0.6 108 | * - **createDate** 109 | - see :ref:`resource properties` 110 | - 111 | - 112 | - 0.6 113 | * - **lastOpDate** 114 | - see :ref:`resource properties` 115 | - 116 | - 117 | - 0.6 118 | 119 | Example 120 | ======= 121 | 122 | :: 123 | 124 | { 125 | "createDate": "Nov 28, 2015 6:52:01 PM", 126 | "gateway": "192.168.0.1", 127 | "ip": "192.168.0.189", 128 | "l3NetworkUuid": "95dede673ddf41119cbd04bcb5d73660", 129 | "lastOpDate": "Nov 28, 2015 6:52:01 PM", 130 | "name": "vip-905d8a5c191c6e30173037e9d4c0ec56", 131 | "netmask": "255.255.255.0", 132 | "peerL3NetworkUuid": "6572ce44c3f6422d8063b0fb262cbc62", 133 | "serviceProvider": "VirtualRouter", 134 | "state": "Enabled", 135 | "useFor": "Eip", 136 | "uuid": "429106d5a63a4995911c2c5f14299b85" 137 | } 138 | 139 | 140 | ---------- 141 | Operations 142 | ---------- 143 | 144 | Create VIP 145 | ========== 146 | 147 | Users can use CreateVip to create a VIP. For example:: 148 | 149 | CreateVip name=vip1 l3NetworkUuid=95dede673ddf41119cbd04bcb5d73660 150 | 151 | Parameters 152 | ++++++++++ 153 | 154 | .. list-table:: 155 | :widths: 20 40 10 20 10 156 | :header-rows: 1 157 | 158 | * - Name 159 | - Description 160 | - Optional 161 | - Choices 162 | - Since 163 | * - **name** 164 | - resource name, see :ref:`resource properties` 165 | - 166 | - 167 | - 0.6 168 | * - **resourceUuid** 169 | - resource uuid, see :ref:`create resource` 170 | - true 171 | - 172 | - 0.6 173 | * - **description** 174 | - resource description, see :ref:`resource properties` 175 | - true 176 | - 177 | - 0.6 178 | * - **l3NetworkUuid** 179 | - uuid of the L3 network that the VIP will be allocated 180 | - 181 | - 182 | - 0.6 183 | * - **requiredIp** 184 | - the IP address you want to acquire, see :ref:`requiredIp ` 185 | - 186 | - 187 | - 0.6 188 | * - **allocatorStrategy** 189 | - the algorithm of allocating a VIP 190 | - 191 | - - RandomIpAllocatorStrategy 192 | - 0.6 193 | 194 | .. _requiredIp: 195 | 196 | RequiredIp 197 | ---------- 198 | 199 | Users can instruct ZStack to allocate a specific VIP by specifying 'requiredIp', as long as the IP is still available on the target L3 200 | network. 201 | 202 | Delete VIP 203 | ========== 204 | 205 | Users can use DeleteVip to delete a VIP. For example:: 206 | 207 | DeleteVip uuid=429106d5a63a4995911c2c5f14299b85 208 | 209 | 210 | .. warning:: If there is a network service bound to the VIP, for example, an EIP; the network service entity(an EIP or a port forwarding rule) 211 | will be deleted automatically as well. 212 | 213 | Query VIP 214 | ========= 215 | 216 | Users can use QueryVip to query a VIP. For example:: 217 | 218 | QueryVip ip=17.16.89.2 serviceProvider!=null 219 | 220 | :: 221 | 222 | QueryVip eip.guestIp=10.256.99.2 223 | 224 | 225 | Primitive Fields 226 | ++++++++++++++++ 227 | 228 | see :ref:`VIP inventory ` 229 | 230 | Nested And Expanded Fields 231 | ++++++++++++++++++++++++++ 232 | 233 | .. list-table:: 234 | :widths: 20 30 40 10 235 | :header-rows: 1 236 | 237 | * - Field 238 | - Inventory 239 | - Description 240 | - Since 241 | * - **eip** 242 | - :ref:`EIP inventory ` 243 | - the EIP that the VIP is bound to 244 | - 0.6 245 | * - **portForwarding** 246 | - :ref:`port forwarding rule inventory ` 247 | - the port forwarding rule that the VIP is bound to 248 | - 0.6 249 | 250 | ---- 251 | Tags 252 | ---- 253 | 254 | Users can create user tags on a VIP with resourceType=VipVO. For example:: 255 | 256 | CreateUserTag tag=web-tier-vip resourceType=VipVO resourceUuid=c3206d0e29074e21984c584074c63920 257 | -------------------------------------------------------------------------------- /userManual/eip.rst: -------------------------------------------------------------------------------- 1 | .. _eip: 2 | 3 | ================== 4 | Elastic IP Address 5 | ================== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | An elastic IP(EIP) provides a way that allows outside network to reach a L3 network behind 15 | a source nat. EIP is based on network address translation(NAT) that maps an IP address of one network(usually a public network) 16 | to an IP address of another network(usually a private network); as being called elastic IP address, an EIP can be attached/detached 17 | to/from VMs dynamically. 18 | 19 | .. image:: eip1.png 20 | :align: center 21 | 22 | .. _eip inventory: 23 | 24 | --------- 25 | Inventory 26 | --------- 27 | 28 | Properties 29 | ========== 30 | 31 | .. list-table:: 32 | :widths: 20 40 10 20 10 33 | :header-rows: 1 34 | 35 | * - Name 36 | - Description 37 | - Optional 38 | - Choices 39 | - Since 40 | * - **uuid** 41 | - see :ref:`resource properties` 42 | - 43 | - 44 | - 0.6 45 | * - **name** 46 | - see :ref:`resource properties` 47 | - 48 | - 49 | - 0.6 50 | * - **description** 51 | - see :ref:`resource properties` 52 | - true 53 | - 54 | - 0.6 55 | * - **vmNicUuid** 56 | - uuid of VM nic the EIP is bound 57 | - true 58 | - 59 | - 0.6 60 | * - **vipUuid** 61 | - VIP uuid 62 | - 63 | - 64 | - 0.6 65 | * - **state** 66 | - EIP state, not implemented in this version 67 | - 68 | - - Enabled 69 | - Disabled 70 | - 0.6 71 | * - **vipIp** 72 | - VIP IP address 73 | - 74 | - 75 | - 0.6 76 | * - **guestIp** 77 | - IP of VM nic 78 | - true 79 | - 80 | - 0.6 81 | * - **createDate** 82 | - see :ref:`resource properties` 83 | - 84 | - 85 | - 0.6 86 | * - **lastOpDate** 87 | - see :ref:`resource properties` 88 | - 89 | - 90 | - 0.6 91 | 92 | Example 93 | ======= 94 | 95 | :: 96 | 97 | { 98 | "createDate": "Nov 28, 2015 6:52:14 PM", 99 | "guestIp": "10.0.0.170", 100 | "lastOpDate": "Nov 28, 2015 6:52:14 PM", 101 | "name": "eip-vlan10", 102 | "state": "Enabled", 103 | "uuid": "76b9231c94cd4a3aac497200bb26a643", 104 | "vipIp": "192.168.0.189", 105 | "vipUuid": "429106d5a63a4995911c2c5f14299b85", 106 | "vmNicUuid": "70cac1fd0c2f4940ba32645e09d3e22f" 107 | } 108 | 109 | ---------- 110 | Operations 111 | ---------- 112 | 113 | Create EIP 114 | ========== 115 | 116 | Users can use CreateEip to create an EIP. For example:: 117 | 118 | CreateEip name=eip1 vipUuid=429106d5a63a4995911c2c5f14299b85 vmNicUuid=70cac1fd0c2f4940ba32645e09d3e22f 119 | 120 | Parameters 121 | ++++++++++ 122 | 123 | .. list-table:: 124 | :widths: 20 40 10 20 10 125 | :header-rows: 1 126 | 127 | * - Name 128 | - Description 129 | - Optional 130 | - Choices 131 | - Since 132 | * - **name** 133 | - resource name, see :ref:`resource properties` 134 | - 135 | - 136 | - 0.6 137 | * - **resourceUuid** 138 | - resource uuid, see :ref:`create resource` 139 | - true 140 | - 141 | - 0.6 142 | * - **description** 143 | - resource description, see :ref:`resource properties` 144 | - true 145 | - 146 | - 0.6 147 | * - **vipUuid** 148 | - VIP uuid 149 | - 150 | - 151 | - 0.6 152 | * - **vmNicUuid** 153 | - VM nic uuid; if omitted, the EIP is created without attaching to any VM nic. 154 | - true 155 | - 156 | - 0.6 157 | 158 | Delete EIP 159 | ========== 160 | 161 | Users can use DeleteEip to delete an EIP. For example:: 162 | 163 | DeleteEip uuid=76b9231c94cd4a3aac497200bb26a643 164 | 165 | After deleting, the VIP to which this EIP bound is recycled so other network services can reuse it. 166 | 167 | Parameters 168 | ++++++++++ 169 | 170 | .. list-table:: 171 | :widths: 20 40 10 20 10 172 | :header-rows: 1 173 | 174 | * - Name 175 | - Description 176 | - Optional 177 | - Choices 178 | - Since 179 | * - **deleteMode** 180 | - see :ref:`delete resource` 181 | - true 182 | - - Permissive 183 | - Enforcing 184 | - 0.6 185 | * - **uuid** 186 | - EIP uuid 187 | - 188 | - 189 | - 0.6 190 | 191 | Attach EIP 192 | ========== 193 | 194 | Users can use AttachEip to attach an EIP to a VM nic. For example:: 195 | 196 | AttachEip eipUuid=76b9231c94cd4a3aac497200bb26a643 vmNicUuid=70cac1fd0c2f4940ba32645e09d3e22f 197 | 198 | 199 | Parameters 200 | ++++++++++ 201 | 202 | .. list-table:: 203 | :widths: 20 40 10 20 10 204 | :header-rows: 1 205 | 206 | * - Name 207 | - Description 208 | - Optional 209 | - Choices 210 | - Since 211 | * - **eipUuid** 212 | - EIP uuid 213 | - 214 | - 215 | - 0.6 216 | * - **vmNicUuid** 217 | - VM nic uuid 218 | - 219 | - 220 | - 0.6 221 | 222 | 223 | Detach EIP 224 | ========== 225 | 226 | Users can use DetachEip to detach an EIP from the VM nic. For example:: 227 | 228 | DetachEip uuid=76b9231c94cd4a3aac497200bb26a643 229 | 230 | 231 | Parameters 232 | ++++++++++ 233 | 234 | .. list-table:: 235 | :widths: 20 40 10 20 10 236 | :header-rows: 1 237 | 238 | * - Name 239 | - Description 240 | - Optional 241 | - Choices 242 | - Since 243 | * - **uuid** 244 | - EIP uuid 245 | - 246 | - 247 | - 0.6 248 | 249 | Query EIP 250 | ========= 251 | 252 | Users can use QueryEip to query EIPs. For example:: 253 | 254 | QueryEip vipIp=191.13.10.2 255 | 256 | :: 257 | 258 | QueryEip vmNic.vmInstance.state=Running 259 | 260 | 261 | Primitive Fields 262 | ++++++++++++++++ 263 | 264 | see :ref:`EIP inventory ` 265 | 266 | Nested And Expanded Fields 267 | ++++++++++++++++++++++++++ 268 | 269 | .. list-table:: 270 | :widths: 20 30 40 10 271 | :header-rows: 1 272 | 273 | * - Field 274 | - Inventory 275 | - Description 276 | - Since 277 | * - **vip** 278 | - :ref:`VIP inventory ` 279 | - VIP this EIP is bound 280 | - 0.6 281 | * - **vmNic** 282 | - :ref:`VM nic inventory ` 283 | - VM nic is EIP is attached 284 | - 0.6 285 | 286 | --------------------- 287 | Global Configurations 288 | --------------------- 289 | 290 | .. _eip.snatInboundTraffic: 291 | 292 | snatInboundTraffic 293 | ================== 294 | 295 | .. list-table:: 296 | :widths: 20 30 20 30 297 | :header-rows: 1 298 | 299 | * - Name 300 | - Category 301 | - Default Value 302 | - Choices 303 | * - **snatInboundTraffic** 304 | - eip 305 | - false 306 | - - true 307 | - false 308 | 309 | Whether to source NAT inbound traffics of an EIP. If true, the traffics reaching eip.guestIp will have a source IP equal to eip.vipIp; this is 310 | useful when a VM has multiple EIP attached; it forces a VM to reply incoming traffic through the EIP where the traffic comes from, rather than replying 311 | through the default route. 312 | 313 | ---- 314 | Tags 315 | ---- 316 | 317 | Users can create user tags on an EIP with resourceType=EipVO. For example:: 318 | 319 | CreateUserTag resourceType=EipVO tag=web-public-ip resourceUuid=29fa6c2830c441aaa388d8165b80c24c 320 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | PAPER = 8 | BUILDDIR = _build 9 | 10 | # User-friendly check for sphinx-build 11 | ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) 12 | $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) 13 | endif 14 | 15 | # Internal variables. 16 | PAPEROPT_a4 = -D latex_paper_size=a4 17 | PAPEROPT_letter = -D latex_paper_size=letter 18 | ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 19 | # the i18n builder cannot share the environment and doctrees with the others 20 | I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . 21 | 22 | .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext 23 | 24 | help: 25 | @echo "Please use \`make ' where is one of" 26 | @echo " html to make standalone HTML files" 27 | @echo " dirhtml to make HTML files named index.html in directories" 28 | @echo " singlehtml to make a single large HTML file" 29 | @echo " pickle to make pickle files" 30 | @echo " json to make JSON files" 31 | @echo " htmlhelp to make HTML files and a HTML help project" 32 | @echo " qthelp to make HTML files and a qthelp project" 33 | @echo " devhelp to make HTML files and a Devhelp project" 34 | @echo " epub to make an epub" 35 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" 36 | @echo " latexpdf to make LaTeX files and run them through pdflatex" 37 | @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" 38 | @echo " text to make text files" 39 | @echo " man to make manual pages" 40 | @echo " texinfo to make Texinfo files" 41 | @echo " info to make Texinfo files and run them through makeinfo" 42 | @echo " gettext to make PO message catalogs" 43 | @echo " changes to make an overview of all changed/added/deprecated items" 44 | @echo " xml to make Docutils-native XML files" 45 | @echo " pseudoxml to make pseudoxml-XML files for display purposes" 46 | @echo " linkcheck to check all external links for integrity" 47 | @echo " doctest to run all doctests embedded in the documentation (if enabled)" 48 | 49 | clean: 50 | rm -rf $(BUILDDIR)/* 51 | 52 | html: 53 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 54 | @echo 55 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." 56 | 57 | dirhtml: 58 | $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml 59 | @echo 60 | @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." 61 | 62 | singlehtml: 63 | $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml 64 | @echo 65 | @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." 66 | 67 | pickle: 68 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle 69 | @echo 70 | @echo "Build finished; now you can process the pickle files." 71 | 72 | json: 73 | $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json 74 | @echo 75 | @echo "Build finished; now you can process the JSON files." 76 | 77 | htmlhelp: 78 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp 79 | @echo 80 | @echo "Build finished; now you can run HTML Help Workshop with the" \ 81 | ".hhp project file in $(BUILDDIR)/htmlhelp." 82 | 83 | qthelp: 84 | $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp 85 | @echo 86 | @echo "Build finished; now you can run "qcollectiongenerator" with the" \ 87 | ".qhcp project file in $(BUILDDIR)/qthelp, like this:" 88 | @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/zstack.qhcp" 89 | @echo "To view the help file:" 90 | @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/zstack.qhc" 91 | 92 | devhelp: 93 | $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp 94 | @echo 95 | @echo "Build finished." 96 | @echo "To view the help file:" 97 | @echo "# mkdir -p $$HOME/.local/share/devhelp/zstack" 98 | @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/zstack" 99 | @echo "# devhelp" 100 | 101 | epub: 102 | $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub 103 | @echo 104 | @echo "Build finished. The epub file is in $(BUILDDIR)/epub." 105 | 106 | latex: 107 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 108 | @echo 109 | @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." 110 | @echo "Run \`make' in that directory to run these through (pdf)latex" \ 111 | "(use \`make latexpdf' here to do that automatically)." 112 | 113 | latexpdf: 114 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 115 | @echo "Running LaTeX files through pdflatex..." 116 | $(MAKE) -C $(BUILDDIR)/latex all-pdf 117 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 118 | 119 | latexpdfja: 120 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex 121 | @echo "Running LaTeX files through platex and dvipdfmx..." 122 | $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja 123 | @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." 124 | 125 | text: 126 | $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text 127 | @echo 128 | @echo "Build finished. The text files are in $(BUILDDIR)/text." 129 | 130 | man: 131 | $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man 132 | @echo 133 | @echo "Build finished. The manual pages are in $(BUILDDIR)/man." 134 | 135 | texinfo: 136 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 137 | @echo 138 | @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." 139 | @echo "Run \`make' in that directory to run these through makeinfo" \ 140 | "(use \`make info' here to do that automatically)." 141 | 142 | info: 143 | $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo 144 | @echo "Running Texinfo files through makeinfo..." 145 | make -C $(BUILDDIR)/texinfo info 146 | @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." 147 | 148 | gettext: 149 | $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale 150 | @echo 151 | @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." 152 | 153 | changes: 154 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes 155 | @echo 156 | @echo "The overview file is in $(BUILDDIR)/changes." 157 | 158 | linkcheck: 159 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck 160 | @echo 161 | @echo "Link check complete; look for any errors in the above output " \ 162 | "or in $(BUILDDIR)/linkcheck/output.txt." 163 | 164 | doctest: 165 | $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest 166 | @echo "Testing of doctests in the sources finished, look at the " \ 167 | "results in $(BUILDDIR)/doctest/output.txt." 168 | 169 | xml: 170 | $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml 171 | @echo 172 | @echo "Build finished. The XML files are in $(BUILDDIR)/xml." 173 | 174 | pseudoxml: 175 | $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml 176 | @echo 177 | @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." 178 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # -*- coding: utf-8 -*- 2 | # 3 | # zstack documentation build configuration file, created by 4 | # sphinx-quickstart on Thu Oct 16 20:17:50 2014. 5 | # 6 | # This file is execfile()d with the current directory set to its 7 | # containing dir. 8 | # 9 | # Note that not all possible configuration values are present in this 10 | # autogenerated file. 11 | # 12 | # All configuration values have a default; values that are commented out 13 | # serve to show the default. 14 | 15 | import sys 16 | import os 17 | 18 | # If extensions (or modules to document with autodoc) are in another directory, 19 | # add these directories to sys.path here. If the directory is relative to the 20 | # documentation root, use os.path.abspath to make it absolute, like shown here. 21 | #sys.path.insert(0, os.path.abspath('.')) 22 | 23 | # -- General configuration ------------------------------------------------ 24 | 25 | # If your documentation needs a minimal Sphinx version, state it here. 26 | #needs_sphinx = '1.0' 27 | 28 | # Add any Sphinx extension module names here, as strings. They can be 29 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 30 | # ones. 31 | extensions = [ 32 | 'sphinx.ext.ifconfig', 33 | ] 34 | 35 | # Add any paths that contain templates here, relative to this directory. 36 | templates_path = ['_templates'] 37 | 38 | # The suffix of source filenames. 39 | source_suffix = '.rst' 40 | 41 | # The encoding of source files. 42 | #source_encoding = 'utf-8-sig' 43 | 44 | # The master toctree document. 45 | master_doc = 'index' 46 | 47 | # General information about the project. 48 | project = u'zstack' 49 | copyright = u'2014, zstack.org' 50 | 51 | # The version info for the project you're documenting, acts as replacement for 52 | # |version| and |release|, also used in various other places throughout the 53 | # built documents. 54 | # 55 | # The short X.Y version. 56 | version = '0.6' 57 | # The full version, including alpha/beta/rc tags. 58 | release = '0.6' 59 | 60 | # The language for content autogenerated by Sphinx. Refer to documentation 61 | # for a list of supported languages. 62 | #language = None 63 | 64 | # There are two options for replacing |today|: either, you set today to some 65 | # non-false value, then it is used: 66 | #today = '' 67 | # Else, today_fmt is used as the format for a strftime call. 68 | #today_fmt = '%B %d, %Y' 69 | 70 | # List of patterns, relative to source directory, that match files and 71 | # directories to ignore when looking for source files. 72 | exclude_patterns = ['_build'] 73 | 74 | # The reST default role (used for this markup: `text`) to use for all 75 | # documents. 76 | #default_role = None 77 | 78 | # If true, '()' will be appended to :func: etc. cross-reference text. 79 | #add_function_parentheses = True 80 | 81 | # If true, the current module name will be prepended to all description 82 | # unit titles (such as .. function::). 83 | #add_module_names = True 84 | 85 | # If true, sectionauthor and moduleauthor directives will be shown in the 86 | # output. They are ignored by default. 87 | #show_authors = False 88 | 89 | # The name of the Pygments (syntax highlighting) style to use. 90 | pygments_style = 'sphinx' 91 | 92 | # A list of ignored prefixes for module index sorting. 93 | #modindex_common_prefix = [] 94 | 95 | # If true, keep warnings as "system message" paragraphs in the built documents. 96 | #keep_warnings = False 97 | 98 | 99 | # -- Options for HTML output ---------------------------------------------- 100 | 101 | # The theme to use for HTML and HTML Help pages. See the documentation for 102 | # a list of builtin themes. 103 | html_theme = 'default' 104 | 105 | # Theme options are theme-specific and customize the look and feel of a theme 106 | # further. For a list of options available for each theme, see the 107 | # documentation. 108 | #html_theme_options = {} 109 | 110 | # Add any paths that contain custom themes here, relative to this directory. 111 | #html_theme_path = [] 112 | 113 | # The name for this set of Sphinx documents. If None, it defaults to 114 | # " v documentation". 115 | #html_title = None 116 | 117 | # A shorter title for the navigation bar. Default is the same as html_title. 118 | #html_short_title = None 119 | 120 | # The name of an image file (relative to this directory) to place at the top 121 | # of the sidebar. 122 | #html_logo = None 123 | 124 | # The name of an image file (within the static path) to use as favicon of the 125 | # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 126 | # pixels large. 127 | #html_favicon = None 128 | 129 | # Add any paths that contain custom static files (such as style sheets) here, 130 | # relative to this directory. They are copied after the builtin static files, 131 | # so a file named "default.css" will overwrite the builtin "default.css". 132 | html_static_path = ['_static'] 133 | 134 | # Add any extra paths that contain custom files (such as robots.txt or 135 | # .htaccess) here, relative to this directory. These files are copied 136 | # directly to the root of the documentation. 137 | #html_extra_path = [] 138 | 139 | # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, 140 | # using the given strftime format. 141 | #html_last_updated_fmt = '%b %d, %Y' 142 | 143 | # If true, SmartyPants will be used to convert quotes and dashes to 144 | # typographically correct entities. 145 | #html_use_smartypants = True 146 | 147 | # Custom sidebar templates, maps document names to template names. 148 | #html_sidebars = {} 149 | 150 | # Additional templates that should be rendered to pages, maps page names to 151 | # template names. 152 | #html_additional_pages = {} 153 | 154 | # If false, no module index is generated. 155 | #html_domain_indices = True 156 | 157 | # If false, no index is generated. 158 | #html_use_index = True 159 | 160 | # If true, the index is split into individual pages for each letter. 161 | #html_split_index = False 162 | 163 | # If true, links to the reST sources are added to the pages. 164 | #html_show_sourcelink = True 165 | 166 | # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. 167 | #html_show_sphinx = True 168 | 169 | # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. 170 | #html_show_copyright = True 171 | 172 | # If true, an OpenSearch description file will be output, and all pages will 173 | # contain a tag referring to it. The value of this option must be the 174 | # base URL from which the finished HTML is served. 175 | #html_use_opensearch = '' 176 | 177 | # This is the file name suffix for HTML files (e.g. ".xhtml"). 178 | #html_file_suffix = None 179 | 180 | # Output file base name for HTML help builder. 181 | htmlhelp_basename = 'zstackdoc' 182 | 183 | 184 | # -- Options for LaTeX output --------------------------------------------- 185 | 186 | latex_elements = { 187 | # The paper size ('letterpaper' or 'a4paper'). 188 | #'papersize': 'letterpaper', 189 | 190 | # The font size ('10pt', '11pt' or '12pt'). 191 | #'pointsize': '10pt', 192 | 193 | # Additional stuff for the LaTeX preamble. 194 | #'preamble': '', 195 | } 196 | 197 | # Grouping the document tree into LaTeX files. List of tuples 198 | # (source start file, target name, title, 199 | # author, documentclass [howto, manual, or own class]). 200 | latex_documents = [ 201 | ('index', 'zstack.tex', u'zstack Documentation', 202 | u'zstack.org', 'manual'), 203 | ] 204 | 205 | # The name of an image file (relative to this directory) to place at the top of 206 | # the title page. 207 | #latex_logo = None 208 | 209 | # For "manual" documents, if this is true, then toplevel headings are parts, 210 | # not chapters. 211 | #latex_use_parts = False 212 | 213 | # If true, show page references after internal links. 214 | #latex_show_pagerefs = False 215 | 216 | # If true, show URL addresses after external links. 217 | #latex_show_urls = False 218 | 219 | # Documents to append as an appendix to all manuals. 220 | #latex_appendices = [] 221 | 222 | # If false, no module index is generated. 223 | #latex_domain_indices = True 224 | 225 | 226 | # -- Options for manual page output --------------------------------------- 227 | 228 | # One entry per manual page. List of tuples 229 | # (source start file, name, description, authors, manual section). 230 | man_pages = [ 231 | ('index', 'zstack', u'zstack Documentation', 232 | [u'zstack.org'], 1) 233 | ] 234 | 235 | # If true, show URL addresses after external links. 236 | #man_show_urls = False 237 | 238 | 239 | # -- Options for Texinfo output ------------------------------------------- 240 | 241 | # Grouping the document tree into Texinfo files. List of tuples 242 | # (source start file, target name, title, author, 243 | # dir menu entry, description, category) 244 | texinfo_documents = [ 245 | ('index', 'zstack', u'zstack Documentation', 246 | u'zstack.org', 'zstack', 'One line description of project.', 247 | 'Miscellaneous'), 248 | ] 249 | 250 | # Documents to append as an appendix to all manuals. 251 | #texinfo_appendices = [] 252 | 253 | # If false, no module index is generated. 254 | #texinfo_domain_indices = True 255 | 256 | # How to display URL addresses: 'footnote', 'no', or 'inline'. 257 | #texinfo_show_urls = 'footnote' 258 | 259 | # If true, do not generate a @detailmenu in the "Top" node's menu. 260 | #texinfo_no_detailmenu = False 261 | -------------------------------------------------------------------------------- /userManual/diskOffering.rst: -------------------------------------------------------------------------------- 1 | .. _disk offering: 2 | 3 | ============= 4 | Disk Offering 5 | ============= 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | A disk offering is a specification of a volume, which defines a volume's size and how it will be created. Disk offerings can 15 | be used to create both root volumes and data volumes. 16 | 17 | .. note:: There is no API to create a root volume; but if you provision a VM with an ISO image, you need to specify a disk 18 | offering that defines size and allocator strategy for the VM's root volume, which is the only way that creates a root volume 19 | from a disk offering. 20 | 21 | .. _disk offering inventory: 22 | 23 | --------- 24 | Inventory 25 | --------- 26 | 27 | Properties 28 | ========== 29 | 30 | .. list-table:: 31 | :widths: 20 40 10 20 10 32 | :header-rows: 1 33 | 34 | * - Name 35 | - Description 36 | - Optional 37 | - Choices 38 | - Since 39 | * - **uuid** 40 | - see :ref:`resource properties` 41 | - 42 | - 43 | - 0.6 44 | * - **name** 45 | - see :ref:`resource properties` 46 | - 47 | - 48 | - 0.6 49 | * - **description** 50 | - see :ref:`resource properties` 51 | - true 52 | - 53 | - 0.6 54 | * - **diskSize** 55 | - the size of volume in bytes, see :ref:`disk size ` 56 | - 57 | - 58 | - 0.6 59 | * - **state** 60 | - see :ref:`state ` 61 | - 62 | - - Enabled 63 | - Disabled 64 | - 0.6 65 | * - **type** 66 | - reserved field 67 | - 68 | - - zstack 69 | - 0.6 70 | * - **allocatorStrategy** 71 | - see :ref:`allocator strategy ` 72 | - 73 | - - DefaultPrimaryStorageAllocationStrategy 74 | - 0.6 75 | * - **createDate** 76 | - see :ref:`resource properties` 77 | - 78 | - 79 | - 0.6 80 | * - **lastOpDate** 81 | - see :ref:`resource properties` 82 | - 83 | - 84 | - 0.6 85 | 86 | .. _disk offering size: 87 | 88 | Disk Size 89 | +++++++++ 90 | 91 | DiskSize defines a volume's virtual size. As mentioned in :ref:`volume `, virtual size is the max size a volume can occupy in 92 | storage system after it is fully filled. Putting in a straight way, it's the size you want for the volume. 93 | 94 | .. _disk offering state: 95 | 96 | State 97 | +++++ 98 | 99 | Disk offerings have two states: 100 | 101 | - **Enabled**: 102 | 103 | The state that allows volumes to be created from this disk offering 104 | 105 | - **Disabled**: 106 | 107 | The state that DOESN'T allow volumes to be created from this disk offering 108 | 109 | .. _disk offering allocator strategy: 110 | 111 | Allocator Strategy 112 | ++++++++++++++++++ 113 | 114 | Allocator strategy defines how ZStack selects a primary storage when creating a new volume. Currently the only supported strategy is 115 | DefaultPrimaryStorageAllocationStrategy that finds a primary storage satisfying conditions:: 116 | 117 | 1. state is Enabled 118 | 2. status is Connected 119 | 3. availableCapacity is greater than disk offering's diskSize 120 | 4. has been attached to the cluster that runs the VM to which the volume will be attached 121 | 122 | .. note:: A volume created from a disk offering is only instantiated on primary storage when it's being attached to a VM. See :ref:`volume status NotInstantiated `. 123 | 124 | ---------- 125 | Operations 126 | ---------- 127 | 128 | Create Disk Offering 129 | ==================== 130 | 131 | Users can use CreateDiskOffering create a disk offering. For example:: 132 | 133 | CreateDiskOffering name=small diskSize=1073741824 134 | 135 | Parameters 136 | ++++++++++ 137 | 138 | .. list-table:: 139 | :widths: 20 40 10 20 10 140 | :header-rows: 1 141 | 142 | * - Name 143 | - Description 144 | - Optional 145 | - Choices 146 | - Since 147 | * - **name** 148 | - resource name, see :ref:`resource properties` 149 | - 150 | - 151 | - 0.6 152 | * - **resourceUuid** 153 | - resource uuid, see :ref:`create resource` 154 | - true 155 | - 156 | - 0.6 157 | * - **description** 158 | - resource description, see :ref:`resource properties` 159 | - true 160 | - 161 | - 0.6 162 | * - **diskSize** 163 | - disk size in bytes, see :ref:`size ` 164 | - 165 | - 166 | - 0.6 167 | * - **allocationStrategy** 168 | - see :ref:`allocator strategy ` 169 | - true 170 | - - DefaultPrimaryStorageAllocationStrategy 171 | - 0.6 172 | * - **type** 173 | - reserved filed, leave it alone 174 | - true 175 | - 176 | - 0.6 177 | 178 | Change State 179 | ============ 180 | 181 | Users can use ChangeDiskOfferingState to change the state of a disk offering. For example:: 182 | 183 | ChangeDiskOfferingState uuid=178c662bfcdd4145920682c58ebcbed4 stateEvent=enable 184 | 185 | Parameters 186 | ++++++++++ 187 | 188 | .. list-table:: 189 | :widths: 20 40 10 20 10 190 | :header-rows: 1 191 | 192 | * - Name 193 | - Description 194 | - Optional 195 | - Choices 196 | - Since 197 | * - **uuid** 198 | - disk offering uuid 199 | - 200 | - 201 | - 0.6 202 | * - **stateEvent** 203 | - state trigger event 204 | 205 | - enable: change state to Enabled 206 | - disable: change state to Disabled 207 | - 208 | - - enable 209 | - disable 210 | - 0.6 211 | 212 | Delete Disk Offering 213 | ==================== 214 | 215 | Users can use DeleteDiskOffering to delete a disk offering. For example:: 216 | 217 | DeleteDiskOffering uuid=178c662bfcdd4145920682c58ebcbed4 218 | 219 | Parameters 220 | ++++++++++ 221 | 222 | .. list-table:: 223 | :widths: 20 40 10 20 10 224 | :header-rows: 1 225 | 226 | * - Name 227 | - Description 228 | - Optional 229 | - Choices 230 | - Since 231 | * - **deleteMode** 232 | - see :ref:`delete resource` 233 | - true 234 | - - Permissive 235 | - Enforcing 236 | - 0.6 237 | * - **uuid** 238 | - disk offering uuid 239 | - 240 | - 241 | - 0.6 242 | 243 | Query Disk Offering 244 | =================== 245 | 246 | Users can use QueryDiskOffering to query disk offerings. For example:: 247 | 248 | QueryDiskOffering diskSize>=10000000 249 | 250 | :: 251 | 252 | QueryDiskOffering volume.name=data1 253 | 254 | 255 | Primitive Fields of Query 256 | +++++++++++++++++++++++++ 257 | 258 | see :ref:`disk offering inventory ` 259 | 260 | Nested And Expanded Fields of Query 261 | +++++++++++++++++++++++++++++++++++ 262 | 263 | .. list-table:: 264 | :widths: 20 30 40 10 265 | :header-rows: 1 266 | 267 | * - Field 268 | - Inventory 269 | - Description 270 | - Since 271 | * - **volume** 272 | - :ref:`volume inventory ` 273 | - volumes that are created from this disk offering 274 | - 0.6 275 | 276 | ---- 277 | Tags 278 | ---- 279 | 280 | Users can create user tags on a disk offering with resourceType=DiskOfferingVO. For example:: 281 | 282 | CreateUserTag tag=smallDisk resourceType=DiskOfferingVO resourceUuid=d6c49e73927d40abbfcf13852dc18367 283 | 284 | System Tags 285 | =========== 286 | 287 | Dedicated Primary Storage 288 | +++++++++++++++++++++++++ 289 | 290 | When creating volumes from disk offerings, users can use a system tag to specify primary storage 291 | on which the volumes will be created. 292 | 293 | .. list-table:: 294 | :widths: 20 30 40 10 295 | :header-rows: 1 296 | 297 | * - Tag 298 | - Description 299 | - Example 300 | - Since 301 | * - **primaryStorage::allocator::uuid::{uuid}** 302 | - | if present, volumes created from this disk offering will be 303 | | allocated on the primary storage of *uuid*; 304 | | an allocation failure will be raised if the specified primary storage 305 | | doesn't exist or doesn't have enough capacity. 306 | - primaryStorage::allocator::uuid::b8398e8b7ff24527a3b81dc4bc64d974 307 | - 0.6 308 | * - **primaryStorage::allocator::userTag::{tag}::required** 309 | - | if present, volumes created from this disk offering will be 310 | | allocated on the primary storage having user tag *tag*; 311 | | an allocation failure will be raised if no primary storage 312 | | has the *tag* or primary storage having the *tag* doesn't 313 | | have enough capacity. 314 | - primaryStorage::allocator::userTag::SSD::required 315 | - 0.6 316 | * - **primaryStorage::allocator::userTag::{tag}** 317 | - | if present, volumes created from this disk offering will 318 | | be primarily allocated on the primary storage having user tag *tag*, 319 | | if there is any; no failure will be raised if no primary storage 320 | | has the *tag* or primary storage having the *tag* doesn't 321 | | have enough capacity, instead, a random primary storage will be chosen 322 | | for the volume. 323 | - primaryStorage::allocator::userTag::SSD 324 | - 0.6 325 | 326 | if more than one above system tags present on a disk offering, the precedent order is:: 327 | 328 | primaryStorage::allocator::uuid::{uuid} > primaryStorage::allocator::userTag::{tag}::required > primaryStorage::allocator::userTag::{tag} 329 | -------------------------------------------------------------------------------- /userManual/zone.rst: -------------------------------------------------------------------------------- 1 | .. _zone: 2 | 3 | ==== 4 | Zone 5 | ==== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | A zone is a logic group of resources such as primary storage, clusters, L2 networks; it defines a visibility boundary that resources 15 | in the same zone can see each other and establish relationships, while resources in different zones cannot. For example, a primary storage in zone A 16 | can be attached to a cluster also in zone A, but cannot be attached to a cluster in zone B. 17 | 18 | Zones' child resources, including clusters, L2 Networks and primary Storage, are organized as follows: 19 | 20 | .. image:: zone.png 21 | :align: center 22 | 23 | 24 | Descendant resources of zones are not listed in above diagram. For instance, a host in a cluster is a descendant resource of the parent zone of the cluster. 25 | 26 | As a logic resource, zones maps facilities in datacenters to logic groups. Though there is no enforcement on how facilities must be mapped, 27 | some advices are given to make things simple and clear: 28 | 29 | - Hosts in the same physical layer 2 broadcast domain should be in the same zone, grouped as one or more clusters. 30 | - Physical layer2 broadcast domains should not span multiple zones, and should be mapped as L2 networks in a single zone. 31 | - Physical storage that provide disk spaces for VM volumes, known as primary storage, should not span multiple zones, and should be mapped as primary storage 32 | in a single zone. 33 | - A datacenter can have multiple zones. 34 | 35 | A zone can has one or more :ref:`backup storage` attached. Resources in a zone, for example primary storage, can only access backup storage attached 36 | to the zone. Also, a backup storage can be detached from a zone; after detaching, resources in the zone will not see the backup storage any more. Detaching backup storage 37 | is particularly useful when network typology changes in a datacenter, if the changes cause backup storage no longer accessible to resources of a zone. 38 | 39 | .. _zone inventory: 40 | 41 | --------- 42 | Inventory 43 | --------- 44 | 45 | Properties: 46 | =========== 47 | 48 | .. list-table:: 49 | :widths: 20 40 10 20 10 50 | :header-rows: 1 51 | 52 | * - Name 53 | - Description 54 | - Optional 55 | - Choices 56 | - Since 57 | * - **uuid** 58 | - see :ref:`resource properties` 59 | - 60 | - 61 | - 0.6 62 | * - **name** 63 | - see :ref:`resource properties` 64 | - 65 | - 66 | - 0.6 67 | * - **description** 68 | - see :ref:`resource properties` 69 | - true 70 | - 71 | - 0.6 72 | * - **state** 73 | - see `zone state`_ 74 | - 75 | - - Enabled 76 | - Disabled 77 | - 0.6 78 | * - **createDate** 79 | - see :ref:`resource properties` 80 | - 81 | - 82 | - 0.6 83 | * - **lastOpDate** 84 | - see :ref:`resource properties` 85 | - 86 | - 87 | - 0.6 88 | * - **type** 89 | - reserved field 90 | - 91 | - 92 | - 0.6 93 | 94 | Example 95 | ======= 96 | 97 | :: 98 | 99 | { 100 | "uuid": "b729da71b1c7412781d5de22229d5e17", 101 | "name": "TestZone", 102 | "description": "Test", 103 | "state": "Enabled", 104 | "type": "zstack", 105 | "createDate": "Jun 1, 2015 6:04:52 PM", 106 | "lastOpDate": "Jun 1, 2015 6:04:52 PM" 107 | } 108 | 109 | 110 | .. _`zone state`: 111 | 112 | State 113 | ===== 114 | 115 | Zones have two states: Enabled and Disabled. When changing a zone's state, the operation will be cascaded to all clusters and hosts all of which belong to the zone. 116 | For example, disabling a zone will change states of all clusters and hosts in this zone to Disabled. Because no VM can be created or started on a disabled host, 117 | putting a zone into Disabled state can prevent any VM from being created or started in this zone. 118 | 119 | .. note:: Admins can selectively enable hosts or clusters in a disabled zone or disable them in an enabled zone, in order to 120 | have fine-grained state control. 121 | 122 | 123 | ---------- 124 | Operations 125 | ---------- 126 | 127 | Create Zone 128 | =========== 129 | 130 | Admins can use CreateZone command to create a new zone. For example:: 131 | 132 | CreateZone name='San Jose Zone' description='this is a zone in San Jose datacenter' 133 | 134 | Parameters 135 | ++++++++++ 136 | 137 | .. list-table:: 138 | :widths: 20 40 10 20 10 139 | :header-rows: 1 140 | 141 | * - Name 142 | - Description 143 | - Optional 144 | - Choices 145 | - Since 146 | * - **name** 147 | - resource name, see :ref:`resource properties` 148 | - 149 | - 150 | - 0.6 151 | * - **resourceUuid** 152 | - resource uuid, see :ref:`create resource` 153 | - true 154 | - 155 | - 0.6 156 | * - **description** 157 | - resource description, see :ref:`resource properties` 158 | - true 159 | - 160 | - 0.6 161 | * - **type** 162 | - reserved field, don't evaluate it 163 | - true 164 | - 165 | - 0.6 166 | * - **userTags** 167 | - user tags, see :ref:`create tags`; resource type is ZoneVO 168 | - true 169 | - 170 | - 0.6 171 | * - **systemTags** 172 | - system tags, see :ref:`create tags`; resource type is ZoneVO 173 | - true 174 | - 175 | - 0.6 176 | 177 | Delete Zone 178 | =========== 179 | 180 | Admins can use DeleteZone command to delete a zone. For example:: 181 | 182 | DeleteZone uuid=28e94936284b45f99842ababfc3f976d 183 | 184 | .. danger:: There is no way to recover a deleted zone. 185 | 186 | Parameters 187 | ++++++++++ 188 | 189 | .. list-table:: 190 | :widths: 20 40 10 20 10 191 | :header-rows: 1 192 | 193 | * - Name 194 | - Description 195 | - Optional 196 | - Choices 197 | - Since 198 | * - **uuid** 199 | - zone uuid 200 | - 201 | - 202 | - 0.6 203 | * - **deleteMode** 204 | - see :ref:`delete resource` 205 | - true 206 | - - Permissive 207 | - Enforcing 208 | - 0.6 209 | 210 | Change State 211 | ============ 212 | 213 | Admins can use ChangeZoneState command to change the state of a zone. For example:: 214 | 215 | ChangeZoneState stateEvent=enable uuid=737896724f2645de9372f11b13a48223 216 | 217 | Parameters 218 | ++++++++++ 219 | 220 | .. list-table:: 221 | :widths: 20 40 10 20 10 222 | :header-rows: 1 223 | 224 | * - Name 225 | - Description 226 | - Optional 227 | - Choices 228 | - Since 229 | * - **uuid** 230 | - zone uuid 231 | - 232 | - 233 | - 0.6 234 | * - **stateEvent** 235 | - state trigger event. 236 | 237 | - enable: change state to Enabled 238 | - disable: change state to Disabled 239 | - 240 | - - enable 241 | - disable 242 | - 0.6 243 | 244 | Attach Backup Storage 245 | ===================== 246 | 247 | see :ref:`attach backup storage to zone `. 248 | 249 | Detach Backup Storage 250 | ===================== 251 | 252 | see :ref:`detach backup storage from zone `. 253 | 254 | Query Zone 255 | ========== 256 | 257 | Admins can use QueryZone to query zones. For example:: 258 | 259 | QueryZone name=zone1 260 | 261 | :: 262 | 263 | QueryZone vmInstance.uuid=13238c8e0591444e9160df4d3636be82 264 | 265 | Primitive Fields of Query 266 | +++++++++++++++++++++++++ 267 | 268 | see :ref:`zone inventory ` 269 | 270 | Nested And Expanded Fields of Query 271 | +++++++++++++++++++++++++++++++++++ 272 | 273 | .. list-table:: 274 | :widths: 20 30 40 10 275 | :header-rows: 1 276 | 277 | * - Field 278 | - Inventory 279 | - Description 280 | - Since 281 | * - **vmInstance** 282 | - :ref:`vm inventory ` 283 | - VMs belonging to this zone 284 | - 0.6 285 | * - **cluster** 286 | - :ref:`cluster inventory ` 287 | - clusters belonging to this zone 288 | - 0.6 289 | * - **host** 290 | - :ref:`host inventory ` 291 | - hosts belonging to this zone 292 | - 0.6 293 | * - **primaryStorage** 294 | - :ref:`primary storage inventory ` 295 | - primary storage belonging to this zone 296 | - 0.6 297 | * - **l2Network** 298 | - :ref:`L2 network inventory ` 299 | - L2 networks belonging to this zone 300 | - 0.6 301 | * - **l3Network** 302 | - :ref:`L3 network inventory ` 303 | - L3 networks belonging to this zone 304 | - 0.6 305 | * - **backupStorage** 306 | - :ref:`backup storage inventory ` 307 | - backup storage belonging to this zone 308 | - 0.6 309 | 310 | 311 | ---- 312 | Tags 313 | ---- 314 | 315 | Admins can create user tags on a zone with resourceType=ZoneVO. For example:: 316 | 317 | CreateUserTag resourceType=ZoneVO resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag=privateZone 318 | 319 | System Tags 320 | =========== 321 | 322 | .. _zone.host.reservedMemory: 323 | 324 | Reserved Capacity 325 | +++++++++++++++++ 326 | 327 | .. list-table:: 328 | :widths: 20 30 40 10 329 | :header-rows: 1 330 | 331 | * - Tag 332 | - Description 333 | - Example 334 | - Since 335 | * - **host::reservedMemory::{capacity}** 336 | - see :ref:`host capacity reservation` 337 | - host::reservedMemory::1G 338 | - 0.6 339 | -------------------------------------------------------------------------------- /userManual/portForwarding.rst: -------------------------------------------------------------------------------- 1 | .. _port forwarding: 2 | 3 | ======================= 4 | Elastic Port Forwarding 5 | ======================= 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | When user VMs are on a :ref:`private network or isolated network ` with SNAT service enabled, they can 15 | reach outside network but cannot be reached by outside network, which is the nature of SNAT. Users can create port forwarding 16 | rules to allow outside network to reach specific ports of user VMs behind SNAT. ZStack supports elastic port forwarding rules, 17 | which means rules can be attached/detached to/from VMs on demand. 18 | 19 | As the virtual router provider is the only network service provider in this ZStack version, a port forwarding rule is actually 20 | created between a virtual router VM's public network and guest network. 21 | 22 | .. image:: portforwarding1.png 23 | :align: center 24 | 25 | A VIP can be used for multiple port forwarding rules, as long as rules' port ranges don't overlap; for example: 26 | 27 | .. image:: portforwarding2.png 28 | :align: center 29 | 30 | .. _port forwarding rule inventory: 31 | 32 | ------------------------------ 33 | Port Forwarding Rule Inventory 34 | ------------------------------ 35 | 36 | Properties 37 | ========== 38 | 39 | .. list-table:: 40 | :widths: 20 40 10 20 10 41 | :header-rows: 1 42 | 43 | * - Name 44 | - Description 45 | - Optional 46 | - Choices 47 | - Since 48 | * - **uuid** 49 | - see :ref:`resource properties` 50 | - 51 | - 52 | - 0.6 53 | * - **name** 54 | - see :ref:`resource properties` 55 | - 56 | - 57 | - 0.6 58 | * - **description** 59 | - see :ref:`resource properties` 60 | - true 61 | - 62 | - 0.6 63 | * - **vipIp** 64 | - IP address of VIP 65 | - 66 | - 67 | - 0.6 68 | * - **guestIp** 69 | - IP address of VM nic 70 | - true 71 | - 72 | - 0.6 73 | * - **vipUuid** 74 | - uuid of VIP 75 | - 76 | - 77 | - 0.6 78 | * - **vipPortStart** 79 | - the start port of VIP 80 | - 81 | - 1 ~ 65535 82 | - 0.6 83 | * - **vipPortEnd** 84 | - the end port of VIP 85 | - 86 | - 1 ~ 65535 87 | - 0.6 88 | * - **privatePortStart** 89 | - the start port of guest IP 90 | - 91 | - 1 ~ 65535 92 | - 0.6 93 | * - **privatePortEnd** 94 | - the end port of guest IP 95 | - 96 | - 1 ~ 65535 97 | - 0.6 98 | * - **vmNicUuid** 99 | - uuid of guest VM nic 100 | - true 101 | - 102 | - 0.6 103 | * - **protocolType** 104 | - protocol type of network traffic 105 | - 106 | - - TCP 107 | - UDP 108 | - 0.6 109 | * - **state** 110 | - rule state, not implemented in this version 111 | - 112 | - - Enabled 113 | - Disabled 114 | - 0.6 115 | * - **allowedCidr** 116 | - source CIDR; the port forwarding rule only applies to traffics with this source CIDR 117 | - 118 | - 119 | - 0.6 120 | * - **createDate** 121 | - see :ref:`resource properties` 122 | - 123 | - 124 | - 0.6 125 | * - **lastOpDate** 126 | - see :ref:`resource properties` 127 | - 128 | - 129 | - 0.6 130 | 131 | Example 132 | ======= 133 | 134 | :: 135 | 136 | { 137 | "allowedCidr": "0.0.0.0/0", 138 | "createDate": "Dec 6, 2015 3:04:34 PM", 139 | "guestIp": "10.0.0.244", 140 | "lastOpDate": "Dec 6, 2015 3:04:34 PM", 141 | "name": "pf-9uf4", 142 | "privatePortEnd": 33, 143 | "privatePortStart": 33, 144 | "protocolType": "TCP", 145 | "state": "Enabled", 146 | "uuid": "310a6cd618144ca683d78d74307f16a4", 147 | "vipIp": "192.168.0.187", 148 | "vipPortEnd": 33, 149 | "vipPortStart": 33, 150 | "vipUuid": "433769b59a7c42199d762af01e08ec16", 151 | "vmNicUuid": "4b9c27321b794679a9ba8c18239bbb0d" 152 | } 153 | 154 | ---------- 155 | Operations 156 | ---------- 157 | 158 | Create Port Forwarding Rule 159 | =========================== 160 | 161 | Users can use CreatePortForwardingRule to create a port forwarding rule, with or without attaching to a VM nic. For example:: 162 | 163 | CreatePortForwardingRule name=pf1 vipPortStart=22 vipUuid=433769b59a7c42199d762af01e08ec16 protocolType=TCP vmNicUuid=4b9c27321b794679a9ba8c18239bbb0d 164 | 165 | A unattached rule can be attached to a VM nic later. 166 | 167 | Parameters 168 | ++++++++++ 169 | 170 | .. list-table:: 171 | :widths: 20 40 10 20 10 172 | :header-rows: 1 173 | 174 | * - Name 175 | - Description 176 | - Optional 177 | - Choices 178 | - Since 179 | * - **name** 180 | - resource name, see :ref:`resource properties` 181 | - 182 | - 183 | - 0.6 184 | * - **resourceUuid** 185 | - resource uuid, see :ref:`create resource` 186 | - true 187 | - 188 | - 0.6 189 | * - **description** 190 | - resource description, see :ref:`resource properties` 191 | - true 192 | - 193 | - 0.6 194 | * - **vipUuid** 195 | - VIP UUID 196 | - 197 | - 198 | - 0.6 199 | * - **vipPortStart** 200 | - the start port of VIP 201 | - 202 | - 1 - 65535 203 | - 0.6 204 | * - **vipPortEnd** 205 | - the end port of VIP; if omitted, it's set to vipPortStart. 206 | - true 207 | - 1 - 65535 208 | - 0.6 209 | * - **privatePortStart** 210 | - the start port of guest IP (VM nic's IP); if omitted, it's set to vipPortStart 211 | - true 212 | - 1 - 65535 213 | - 0.6 214 | * - **privatePortEnd** 215 | - the end port for guest IP (VM nic's IP); if omitted, it's set to vipPortEnd 216 | - true 217 | - 1 - 65535 218 | - 0.6 219 | * - **protocolType** 220 | - network traffic protocol type 221 | - 222 | - - TCP 223 | - UDP 224 | - 0.6 225 | * - **vmNicUuid** 226 | - uuid of VM nic this port forwarding rule will be attached to 227 | - true 228 | - 229 | - 0.6 230 | * - **allowedCidr** 231 | - source CIDR; the port forwarding rule only applies to traffics having this source CIDR; if omitted, it's set to 0.0.0.0/0 232 | - true 233 | - 234 | - 0.6 235 | 236 | Delete Port Forwarding Rule 237 | =========================== 238 | 239 | Users can use DeletePortForwardingRule to delete a port forwarding rule. For example:: 240 | 241 | DeletePortForwardingRule uuid=310a6cd618144ca683d78d74307f16a4 242 | 243 | The VIP is recycled for other network services to use, if no more port forwarding rules bound to it. 244 | 245 | Parameters 246 | ++++++++++ 247 | 248 | .. list-table:: 249 | :widths: 20 40 10 20 10 250 | :header-rows: 1 251 | 252 | * - Name 253 | - Description 254 | - Optional 255 | - Choices 256 | - Since 257 | * - **deleteMode** 258 | - see :ref:`delete resource` 259 | - true 260 | - - Permissive 261 | - Enforcing 262 | - 0.6 263 | * - **uuid** 264 | - rule uuid 265 | - 266 | - 267 | - 0.6 268 | 269 | Attach Port Forwarding Rule 270 | =========================== 271 | 272 | Users can use AttachPortForwardingRule to attach a rule to a VM nic. For example:: 273 | 274 | AttachPortForwardingRule ruleUuid=310a6cd618144ca683d78d74307f16a4 vmNicUuid=4b9c27321b794679a9ba8c18239bbb0d 275 | 276 | Parameters 277 | ++++++++++ 278 | 279 | .. list-table:: 280 | :widths: 20 40 10 20 10 281 | :header-rows: 1 282 | 283 | * - Name 284 | - Description 285 | - Optional 286 | - Choices 287 | - Since 288 | * - **ruleUuid** 289 | - rule uuid 290 | - 291 | - 292 | - 0.6 293 | * - **vmNicUuid** 294 | - VM nic uuid 295 | - 296 | - 297 | - 0.6 298 | 299 | Detach Port Forwarding Rule 300 | =========================== 301 | 302 | Users can use DetachPortForwardingRule to detach a rule from a VM nic. For example:: 303 | 304 | DetachPortForwardingRule uuid=310a6cd618144ca683d78d74307f16a4 305 | 306 | Parameters 307 | ++++++++++ 308 | 309 | .. list-table:: 310 | :widths: 20 40 10 20 10 311 | :header-rows: 1 312 | 313 | * - Name 314 | - Description 315 | - Optional 316 | - Choices 317 | - Since 318 | * - **uuid** 319 | - rule uuid 320 | - 321 | - 322 | - 0.6 323 | 324 | Query Port Forwarding Rule 325 | ========================== 326 | 327 | Users can use QueryPortForwardingRule to query rules. For example:: 328 | 329 | QueryPortForwardingRule vipPortStart=22 vipIp=17.200.20.6 330 | 331 | :: 332 | 333 | QueryPortForwardingRule vmNic.l3Network.name=database-tier 334 | 335 | 336 | Primitive Fields 337 | ++++++++++++++++ 338 | 339 | see :ref:`port forwarding rule inventory ` 340 | 341 | Nested And Expanded Fields 342 | ++++++++++++++++++++++++++ 343 | 344 | .. list-table:: 345 | :widths: 20 30 40 10 346 | :header-rows: 1 347 | 348 | * - Field 349 | - Inventory 350 | - Description 351 | - Since 352 | * - **vip** 353 | - :ref:`VIP inventory ` 354 | - VIP this rule is bound 355 | - 0.6 356 | * - **vmNic** 357 | - :ref:`VM nic inventory ` 358 | - VM nic this rule is attached 359 | - 0.6 360 | 361 | --------------------- 362 | Global Configurations 363 | --------------------- 364 | 365 | .. _portForwarding.snatInboundTraffic: 366 | 367 | snatInboundTraffic 368 | ================== 369 | 370 | .. list-table:: 371 | :widths: 20 30 20 30 372 | :header-rows: 1 373 | 374 | * - Name 375 | - Category 376 | - Default Value 377 | - Choices 378 | * - **snatInboundTraffic** 379 | - portForwarding 380 | - false 381 | - - true 382 | - false 383 | 384 | Whether to source NAT inbound traffic of a port forwarding rule. If true, the traffics reaching portForwardingRule.guestIp will have a source IP equal to portForwardingRule.vipIp; this is 385 | useful when a VM has multiple port forwarding rules attached; it forces a VM to reply incoming traffics through VIPs where traffics come from, rather than replying 386 | through the default route. 387 | 388 | ---- 389 | Tags 390 | ---- 391 | 392 | Users can create user tags on a port forwarding rule with resourceType=PortForwardingRuleVO. For example:: 393 | 394 | CreateUserTag resourceType=PortForwardingRuleVO tag=ssh-rule resourceType=e960a93b7f974690bb779808f3c12a33 395 | -------------------------------------------------------------------------------- /userManual/tag.rst: -------------------------------------------------------------------------------- 1 | .. _tag: 2 | 3 | ==== 4 | Tags 5 | ==== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | ZStack provides two types of tags to help users and plugins organize resources, introduce extra resource properties, and 15 | instruct ZStack to perform specific business logic. For the architecture design of tags see `The Tag System `_. 16 | 17 | --------- 18 | User Tags 19 | --------- 20 | 21 | Users can create user tags on resources they own, which is particular useful when aggregating a set of similar resources; 22 | for example, users can put a tag 'web' on VMs that work as web servers:: 23 | 24 | CreateUserTag resourceType=VmInstanceVO resourceUuid=613af3fe005914c1643a15c36fd578c6 tag=web 25 | 26 | :: 27 | 28 | CreateUserTag resourceType=VmInstanceVO resourceUuid=5eb55c39db015c1782c7d814900a9609 tag=web 29 | 30 | :: 31 | 32 | CreateUserTag resourceType=VmInstanceVO resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag=web 33 | 34 | and later on, use :ref:`Query API with tags ` to retrieve those VMs:: 35 | 36 | QueryVmInstance __userTag__=web 37 | 38 | 39 | Users can also use user tags cooperating with system tags to change ZStack's business logic; for example, users may want all VMs working as web 40 | servers to create their root volumes on a special primary storage which provides better IO performance by SSD; to do so, 41 | users can create a user tag 'forWebTierVM' on the primary storage:: 42 | 43 | CreateUserTag tag=forWebTierVM resourceType=PrimaryStorageVO resourceUuid=6572ce44c3f6422d8063b0fb262cbc62 44 | 45 | then create a system tag on an instance offering:: 46 | 47 | CreateSystemTag tag=primaryStorage::allocator::userTag::forWebTierVM resourceType=InstanceOfferingVO resourceUuid=8f69ef6c2c444cdf8c019fa0969d56a5 48 | 49 | then, when users create a VM with the instance offering[uuid:8f69ef6c2c444cdf8c019fa0969d56a5], ZStack will make sure the VM's root volume 50 | will be created on only the primary storage with user tag 'forWebTierVM', in this case, which is the primary storage with UUID 6572ce44c3f6422d8063b0fb262cbc62. 51 | 52 | ----------- 53 | System Tags 54 | ----------- 55 | 56 | System tags have wider usage than user tags; users can use them to instruct ZStack to do some specific business logic, like the example in the section above. Plugins, 57 | which extend ZStack's functionality, can use system tags to introduce additional resource properties, or to record metadata which tightly bind to resources. 58 | 59 | for example, to carry out live migration or live snapshot on KVM hosts, ZStack needs to know KVM hosts' libvirt version and QEMU version all of which are treated 60 | as meta data, so ZStack records them as system tags of hosts. For example, admins can view system tags of a KVM host by:: 61 | 62 | QuerySystemTag fields=tag resourceUuid=d07066c4de02404a948772e131139eb4 63 | 64 | *d07066c4de02404a948772e131139eb4* is the KVM host UUID, the output is like:: 65 | 66 | { 67 | "inventories": [ 68 | { 69 | "tag": "capability:liveSnapshot" 70 | }, 71 | { 72 | "tag": "qemu-img::version::2.0.0" 73 | }, 74 | { 75 | "tag": "os::version::14.04" 76 | }, 77 | { 78 | "tag": "libvirt::version::1.2.2" 79 | }, 80 | { 81 | "tag": "os::release::trusty" 82 | }, 83 | { 84 | "tag": "os::distribution::Ubuntu" 85 | } 86 | ], 87 | "success": true 88 | } 89 | 90 | this kind of system tags, which record meta data, are called inherent system tags; inherent system tags can only be created by ZStack's services or plugins, and cannot 91 | be deleted by DeleteTag API. 92 | 93 | To add new functionality, a plugin usually needs to add new properties to a resource; though a plugin cannot change a resource's database schema to add a new 94 | column, it can create new properties as system tags of a resource. For example, when creating a VM, users can specify the VM's hostname for the default L3 network:: 95 | 96 | CreateVmInstance name=testTag systemTags=hostname::web-server-1 l3NetworkUuids=6572ce44c3f6422d8063b0fb262cbc62 instanceOfferingUuid=04b5419ca3134885be90a48e372d3895 imageUuid=f1205825ec405cd3f2d259730d47d1d8 97 | 98 | this hostname is implemented by a system tag; if you look at :ref:`VM inventory in chapter 'Virtual Machine' `, there is no property called 'hostname'; however, you can find it 99 | from the VM's system tags:: 100 | 101 | QuerySystemTag fields=tag,uuid resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7 102 | 103 | :: 104 | 105 | { 106 | "inventories": [ 107 | { 108 | "tag": "hostname::web-server-1", 109 | "uuid": "596070a6276746edbf0f54ef721f654e" 110 | } 111 | ], 112 | "success": true 113 | } 114 | 115 | this kind of system tags are non-inherent, users can delete them by DeleteTag; for example, if users want to change the hostname of the former VM to 116 | 'web-server-nginx', they can do:: 117 | 118 | 119 | DeleteTag uuid=596070a6276746edbf0f54ef721f654e 120 | 121 | :: 122 | 123 | CreateSystemTag resourceType=VmInstanceVO tag=hostname::web-server-nginx resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7 124 | 125 | after stopping and starting the VM, the guest operating system will receive the new hostname as 'web-server-nginx'. 126 | 127 | .. note:: System tags are pre-defined by ZStack's services and plugins; user cannot create a non-existing system tag on a resource. 128 | You can find resources' system tags in *Tags* section of every resource chapter. 129 | 130 | --------------- 131 | Name Convention 132 | --------------- 133 | 134 | Both user tags and system tags can have at most 2048 characters. 135 | 136 | For user tags, there is no enforced name convention, but it's recommended to use human readable and meaningful strings. 137 | 138 | For system tags, as defined by ZStack's services and plugins, they follow the format that uses *::* as delimiters. 139 | 140 | .. _tag resource type: 141 | 142 | ------------- 143 | Resource Type 144 | ------------- 145 | 146 | When creating a tag, user must specify the resource type that the tag is associated with. In this version, a list of resource types 147 | is showed as follows: 148 | 149 | .. list-table:: 150 | :widths: 100 151 | 152 | * - ZoneVO 153 | * - ClusterVO 154 | * - HostVO 155 | * - PrimaryStorageVO 156 | * - BackupStorageVO 157 | * - ImageVO 158 | * - InstanceOfferingVO 159 | * - DiskOfferingVO 160 | * - VolumeVO 161 | * - L2NetworkVO 162 | * - L3NetworkVO 163 | * - IpRangeVO 164 | * - VipVO 165 | * - EipVO 166 | * - VmInstanceVO 167 | * - VmNicVO 168 | * - SecurityGroupRuleVO 169 | * - SecurityGroupVO 170 | * - PortForwardingRuleVO 171 | * - VolumeSnapshotTreeVO 172 | * - VolumeSnapshotVO 173 | 174 | Derived resources use their parent types; for example, SftpBackupStorage's resourceType is 'BackupStorageVO'. 175 | In *Tags* section of every resource chapter, we will explain what resource types to use when creating tags. 176 | 177 | ---------- 178 | Operations 179 | ---------- 180 | 181 | .. _create tags: 182 | 183 | Create Tags 184 | =========== 185 | 186 | There are two ways to create tags; for resources that have been created, users can use command CreateUserTag or CreateSystemTag 187 | to create a user tag or a system tag. For example:: 188 | 189 | CreateUserTag resourceType=DiskOfferingVO resourceUuid=50fcc61947f7494db69436ebbbefda34 tag=for-large-DB 190 | 191 | :: 192 | 193 | CreateSystemTag resourceType=HostVO resourceUuid=50fcc61947f7494db69436ebbbefda34 tag=reservedMemory::1G 194 | 195 | For a resource that is going to be created, as it's not been created yet, there is no resource UUID that can be referred in the CreateUserTag 196 | and CreateSystemTag commands; in this case, users can use *userTags* and *systemTags* fields, both of which are of a list type that receives a list of tags, 197 | of every *creational API command*; for example:: 198 | 199 | CreateVmInstance name=testTag systemTags=hostname::web-server-1 200 | userTags=in-super-data-center,has-public-IP,hot-fix-applied-2015-5-1 201 | l3NetworkUuids=6572ce44c3f6422d8063b0fb262cbc62 202 | instanceOfferingUuid=04b5419ca3134885be90a48e372d3895 imageUuid=f1205825ec405cd3f2d259730d47d1d8 203 | 204 | Parameters 205 | ++++++++++ 206 | 207 | CreateUserTag and CreateSystemTag have the same API parameters: 208 | 209 | .. list-table:: 210 | :widths: 20 40 20 20 211 | :header-rows: 1 212 | 213 | * - Name 214 | - Description 215 | - Optional 216 | - Since 217 | * - **resourceUuid** 218 | - resource UUID; for example, VM's UUID uuid, instance offering's UUID 219 | - 220 | - 0.6 221 | * - **resourceType** 222 | - resource type; see :ref:`resource type ` 223 | - 224 | - 0.6 225 | * - **tag** 226 | - tag string 227 | - 228 | - 0.6 229 | 230 | Delete Tag 231 | ========== 232 | 233 | Users can use DeleteTag to delete a user tag or a non-inherent system tag. For example:: 234 | 235 | DeleteTag uuid=7813d03bb85840c489789f8df3a5915b 236 | 237 | Parameters 238 | ++++++++++ 239 | 240 | .. list-table:: 241 | :widths: 20 40 10 20 10 242 | :header-rows: 1 243 | 244 | * - Name 245 | - Description 246 | - Optional 247 | - Choices 248 | - Since 249 | * - **deleteMode** 250 | - see :ref:`delete resource` 251 | - true 252 | - - Permissive 253 | - Enforcing 254 | - 0.6 255 | * - **uuid** 256 | - tag UUID 257 | - 258 | - 259 | - 0.6 260 | 261 | Query Tags 262 | ========== 263 | 264 | Users can use QueryUserTag to query user tags, for example:: 265 | 266 | QueryUserTag resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag~=web-server-% 267 | 268 | or QuerySystemTag to query system tags, for example:: 269 | 270 | QuerySystemTag resourceUuid=50fcc61947f7494db69436ebbbefda34 271 | 272 | .. note:: When querying tags, as the resourceUuid has uniquely identified a resource, you don't need to specify the resource type; for example:: 273 | 274 | QueryUserTag resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 resourceType=VmInstanceVO 275 | 276 | is redundant because ZStack knows resourceUuid *0cd1ef8c9b9e0ba82e0cc9cc17226a26* maps to type *VmInstanceVO*. 277 | 278 | And don't forget you can use *__userTag__* and *__systemTag__* to query resources with tags, see :ref:`Query API with tags `. 279 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | 203 | -------------------------------------------------------------------------------- /userManual/resource.rst: -------------------------------------------------------------------------------- 1 | .. _resource: 2 | 3 | ============== 4 | Resource Model 5 | ============== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | ZStack is essentially a configuration management system for resources in the cloud. Resources can be physical resources(e.g. hosts, networks, storage) 11 | or virtual resources(e.g. VMs). In this version, a full diagram of ZStack resources is like: 12 | 13 | .. image:: resource-overall.png 14 | :align: center 15 | :alt: resource overall 16 | 17 | 18 | .. note:: This diagram aims to give an overall idea that what ZStack resources look like. 19 | It neither exhibits exact relationship among resources nor shows amount of resources. 20 | 21 | --------------------- 22 | Resource Relationship 23 | --------------------- 24 | 25 | Resources have four relationships: 26 | 27 | - **Parent - Child**: 28 | 29 | A resource can be the parent or a child of another resource. For example, a cluster is a child resource of a zone, while a zone is the parent resource of a cluster. 30 | 31 | - **Ancestor - Descendant**: 32 | 33 | A resource can be the lineal ancestor or a lineal descendant of another resource. For example, a zone is the ancestor resource of VMs; a VM is a descendant resource of a zone. 34 | 35 | - **Sibling**: 36 | 37 | Resources sharing the same parent resource are siblings. For example, clusters, hosts, primary storage, L2 networks are sibling resources because all of them are child resources of zones. 38 | 39 | - **Friend**: 40 | 41 | Resources which don't have above three relationships but still need to cooperate with each other in some scenarios are friends. For example, primary storage and 42 | backup storage are friends, because primary storage need to download images from backup storage in order to create VMs. 43 | 44 | 45 | Resources that don't have any relationship are irrelevant resources; for example, security groups and clusters are irrelevant resources. 46 | 47 | .. note:: In this version, ZStack doesn't have a concept of region, so zones and backup storage doesn't have a parent resource; however, they are still considered as 48 | siblings. 49 | 50 | .. _resource properties: 51 | 52 | ------------------- 53 | Resource Properties 54 | ------------------- 55 | 56 | There are four properties common to almost all resources: 57 | 58 | - **UUID**: 59 | 60 | ZStack uses `UUIDv4 (Universally Unique Identifier) `_ to uniquely identify a resource. Unlike regular UUIDs which 61 | has four hyphens in string, the UUIDs ZStack use have hyphens stripped. For example, 80b5ca2c76154da298a1a248b975372a. 62 | 63 | - **Name**: 64 | 65 | Names are human readable strings with maximum 255 characters. Names can be duplicated, as ZStack doesn't use them as resource identifiers. 66 | Names can have any visible ASCII characters(e.g. %, #, ^, space); however, putting symbols 67 | in a name may make query APIs hard to use. The best practice for naming a resource is only using letters, digits, '-'(hyphen), and '_'(underscore). 68 | 69 | .. note:: Please avoid using ','(comma) in names, though it's legal. In query APIs, ZStack uses comma to split a value into a list when the condition operator is '?='(which means 'in'). 70 | For example, querying VMs by a condition 'name' and an operator '?=' is like:: 71 | 72 | QueryVmInstance name?=vm1,vm2,vm3 73 | 74 | what it does is: finding out VMs whose names are vm1 or vm2 or vm3. For people familiar with SQL, it is equal to:: 75 | 76 | select * from VmInstance where name in ('vm1', 'vm2', 'vm3') 77 | 78 | if you have a comma in VMs' names, for example, 'v,m1', then the query becomes:: 79 | 80 | QueryVmInstance name?=v,m1,vm2,vm3 81 | 82 | which turns out to find VMs whose names are in ['v', 'm1', 'vm2', 'vm3] 83 | 84 | - **Description**: 85 | 86 | Descriptions are human readable strings with maximum 2048 characters. Still, ZStack doesn't enforces any limited character set on descriptions. 87 | 88 | - **Created Date**: 89 | 90 | A immutable date indicating the time that resources were created. 91 | 92 | - **Last Operation Date**: 93 | 94 | A date indicating the last time resources were updated. The date changes every time after a update has been performed on a resource; 95 | updates can be either from user operations or ZStack's internal operations. 96 | 97 | .. note:: Some resources may not have names and descriptions, for example, DNS, security group rules. These resources are not considered as independent resources and must be with their parent 98 | resources. 99 | 100 | Each resource may have its specific properties, for example, VMs have a property 'hostUuid'. As ZStack uses JSON in APIs, properties of resources are encompassed in a JSON map in most 101 | API responses. The JSON map is called *'inventory'* in ZStack's language. In following chapters, when talking about an inventory of a resource, we are referring to the map containing the resource's properties. 102 | Here is an example of VM inventory:: 103 | 104 | { 105 | "inventory": { 106 | "uuid": "94d991c631674b16be65bfdf28b9e84a", 107 | "name": "TestVm", 108 | "description": "Test", 109 | "zoneUuid": "acadddc85a604db4b1b7358605cd6015", 110 | "clusterUuid": "f6cd5db05a0d49d8b12721e0bf721b4c", 111 | "imageUuid": "061141410a0449b6919b50e90d68b7cd", 112 | "hostUuid": "908131845d284d7f821a74362fff3d19", 113 | "lastHostUuid": "908131845d284d7f821a74362fff3d19", 114 | "instanceOfferingUuid": "91cb47f1416748afa7e0d34f4d0731ef", 115 | "rootVolumeUuid": "19aa7ec504a247d89b511b322ffa483c", 116 | "type": "UserVm", 117 | "hypervisorType": "KVM", 118 | "createDate": "Jun 1, 2015 6:11:47 PM", 119 | "lastOpDate": "Jun 1, 2015 6:11:47 PM", 120 | "state": "Running", 121 | "vmNics": [ 122 | { 123 | "uuid": "6b58e6b2ba174ef4bce8a549de9560e8", 124 | "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a", 125 | "usedIpUuid": "4ecc80a2d1d93d48b32680827542ddbb", 126 | "l3NetworkUuid": "55f85b8fa9a647f1be251787c66550ee", 127 | "ip": "10.12.140.148", 128 | "mac": "fa:f0:08:8c:20:00", 129 | "netmask": "255.0.0.0", 130 | "gateway": "10.10.2.1", 131 | "deviceId": 0, 132 | "createDate": "Jun 1, 2015 6:11:47 PM", 133 | "lastOpDate": "Jun 1, 2015 6:11:47 PM" 134 | }, 135 | { 136 | "uuid": "889cfcab8c08409296c649611a4df50c", 137 | "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a", 138 | "usedIpUuid": "8877537e11783ee0bfe8af0fcf7a6388", 139 | "l3NetworkUuid": "c6134efd3af94db7b2928ddc5deba540", 140 | "ip": "10.4.224.72", 141 | "mac": "fa:e3:87:b1:71:01", 142 | "netmask": "255.0.0.0", 143 | "gateway": "10.0.0.1", 144 | "deviceId": 1, 145 | "createDate": "Jun 1, 2015 6:11:47 PM", 146 | "lastOpDate": "Jun 1, 2015 6:11:47 PM" 147 | }, 148 | { 149 | "uuid": "cba0da7a12d44b2e878dd5803d078337", 150 | "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a", 151 | "usedIpUuid": "f90d01a098303956823ced02438ae3ab", 152 | "l3NetworkUuid": "c7e9e14f2af742c29c3e25d58f16a45f", 153 | "ip": "10.29.42.155", 154 | "mac": "fa:2d:31:08:da:02", 155 | "netmask": "255.0.0.0", 156 | "gateway": "10.20.3.1", 157 | "deviceId": 2, 158 | "createDate": "Jun 1, 2015 6:11:47 PM", 159 | "lastOpDate": "Jun 1, 2015 6:11:47 PM" 160 | } 161 | ], 162 | "allVolumes": [ 163 | { 164 | "uuid": "19aa7ec504a247d89b511b322ffa483c", 165 | "name": "ROOT-for-TestVm", 166 | "description": "Root volume for VM[uuid:94d991c631674b16be65bfdf28b9e84a]", 167 | "primaryStorageUuid": "24931b95b45e41fb8e41a640302d4c00", 168 | "vmInstanceUuid": "94d991c631674b16be65bfdf28b9e84a", 169 | "rootImageUuid": "061141410a0449b6919b50e90d68b7cd", 170 | "installUrl": "/opt/zstack/nfsprimarystorage/prim-24931b95b45e41fb8e41a640302d4c00/rootVolumes/acct-36c27e8ff05c4780bf6d2fa65700f22e/vol-19aa7ec504a247d89b511b322ffa483c/19aa7ec504a247d89b511b322ffa483c.qcow2", 171 | "type": "Root", 172 | "format": "qcow2", 173 | "size": 3.221225472E10, 174 | "deviceId": 0, 175 | "state": "Enabled", 176 | "status": "Ready", 177 | "createDate": "Jun 1, 2015 6:11:47 PM", 178 | "lastOpDate": "Jun 1, 2015 6:11:47 PM" 179 | } 180 | ] 181 | } 182 | } 183 | 184 | ------------------- 185 | Resource Operations 186 | ------------------- 187 | 188 | Resources support full or partial CRUD(Create, Read, Update, Delete) operations. 189 | 190 | 191 | .. _create resource: 192 | 193 | Create Resources 194 | ================ 195 | 196 | Every resource has own creational APIs. There is one parameter 'resourceUuid' common to all creational APIs. 197 | When 'resourceUuid' is not null, ZStack will use its value as the UUID for the resource being created; otherwise ZStack will automatically generate a UUID. 198 | 199 | .. warning:: When using 'resourceUuid', please make sure the UUID you provide is a UUIDv4 with hyphens striped. Otherwise, ZStack will return an invalid 200 | argument error if it's not a valid UUIDv4 with hyphens stripped, or an internal error if there has been a resource of the same type with the same UUID in 201 | the database. 202 | 203 | Here is an example of creating a cluster:: 204 | 205 | CreateCluster name=cluster1 description='awesome cluster' hypervisorType=KVM zoneUuid=061141410a0449b6919b50e90d68b7cd 206 | 207 | or:: 208 | 209 | CreateCluster resourceUuid=f31e38309e2047beac588e111fa2051f name=cluster1 description='awesome cluster' hypervisorType=KVM zoneUuid=061141410a0449b6919b50e90d68b7cd 210 | 211 | 212 | Read Resources 213 | ============== 214 | 215 | Every resource has own query API that returns a list of inventories for read. 216 | For details, see :ref:`Query `. Here is an example of querying VMs:: 217 | 218 | QueryVmInstance allVolumes.type=Data allVolumes.size>1099511627776 219 | 220 | The example does: finding out all VMs which have one or more data volumes with size greater than 1099511627776 bytes(1T) 221 | 222 | 223 | Update Resources 224 | ================ 225 | 226 | A resource can be updated by various APIs. Updating a resource is actually performing an action to the resource. For example, 227 | starting a VM, stopping a VM. Please refer to corresponding chapters for actions for resources. Here is an example 228 | of starting a VM:: 229 | 230 | StartVmInstance uuid=94d991c631674b16be65bfdf28b9e84a 231 | 232 | Most update APIs will return a resource inventory. 233 | 234 | 235 | .. _delete resource: 236 | 237 | Delete Resources 238 | ================ 239 | 240 | A resource can be deleted. ZStack's philosophy for deleting is: every resource should be deletable; and deleting a resource should always be success 241 | unless user allows an expected failure; for example, a plugin may allow user to set a 'none-deletable' tag on a VM, and throw an error when the VM is being 242 | deleted. 243 | 244 | Deleting a resource is not always easy in IaaS, especially for a resource that has many descendants; some software hard code to delete all descendant resources; 245 | some software simply throws an error when a resource being deleted still has descendant resources alive. 246 | 247 | ZStack handles deleting in an elegant way. When a resource is being deleted, a so-called `Cascade Framework `_ will calculate relationships among this resource and 248 | rest resources in the cloud, and propagate proper actions to related resources if necessary. For example, when deleting a zone, a deleting 249 | action will be spread to all descendants of the zone, which means all descendant resources like VMs, hosts, clusters, L2 Networks in this zone will be deleted before the zone 250 | deleted; and backup storage attached to the zone will be detached. With the cascade framework, deleting resources in ZStack is easy and reliable. 251 | 252 | Every resource has own deleting API. A parameter *deleteMode* which has options **Permissive** and **Enforcing** is common to all deleting APIs. 253 | When *deleteMode* is set to Permissive, ZStack will stop the deleting if an error happens, or the deleting is not permitted; in this 254 | case, an error code with detailed reason will be returned. When *deleteMode* is set to Enforcing, ZStack will ignore any errors and permissions but delete resources directly; in this case, 255 | a deleting will always be success. 256 | 257 | Here is an example of deleting a VM:: 258 | 259 | DestroyVmInstance uuid=94d991c631674b16be65bfdf28b9e84a 260 | 261 | 262 | -------------------------------------------------------------------------------- /userManual/instanceOffering.rst: -------------------------------------------------------------------------------- 1 | .. _instance offering: 2 | 3 | ================= 4 | Instance Offering 5 | ================= 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | An instance offering is a specification of VM's memory, CPU, and host allocation algorithm; it defines the volume of computing 15 | resource a VM can have. 16 | 17 | .. _instance offering inventory: 18 | 19 | --------- 20 | Inventory 21 | --------- 22 | 23 | Properties 24 | ========== 25 | 26 | .. list-table:: 27 | :widths: 20 40 10 20 10 28 | :header-rows: 1 29 | 30 | * - Name 31 | - Description 32 | - Optional 33 | - Choices 34 | - Since 35 | * - **uuid** 36 | - see :ref:`resource properties` 37 | - 38 | - 39 | - 0.6 40 | * - **name** 41 | - see :ref:`resource properties` 42 | - 43 | - 44 | - 0.6 45 | * - **description** 46 | - see :ref:`resource properties` 47 | - true 48 | - 49 | - 0.6 50 | * - **cpuNum** 51 | - VCPU number, see :ref:`CPU capacity ` 52 | - 53 | - 54 | - 0.6 55 | * - **cpuSpeed** 56 | - VCPU speed, see :ref:`CPU capacity ` 57 | - 58 | - 59 | - 0.6 60 | * - **memorySize** 61 | - memory size, in bytes 62 | - 63 | - 64 | - 0.6 65 | * - **type** 66 | - instance offering type, default is UserVm, see :ref:`type ` 67 | - true 68 | - - UserVm 69 | - VirtualRouter 70 | - 0.6 71 | * - **allocatorStrategy** 72 | - host allocator strategy, see :ref:`allocator strategy ` 73 | - 74 | - - DefaultHostAllocatorStrategy 75 | - DesignatedHostAllocatorStrategy 76 | - 0.6 77 | * - **state** 78 | - see :ref:`state ` 79 | - 80 | - - Enabled 81 | - Disabled 82 | - 0.6 83 | * - **createDate** 84 | - see :ref:`resource properties` 85 | - 86 | - 87 | - 0.6 88 | * - **lastOpDate** 89 | - see :ref:`resource properties` 90 | - 91 | - 92 | - 0.6 93 | 94 | .. _instance offering cpu capacity: 95 | 96 | CPU Capacity 97 | ++++++++++++ 98 | 99 | Instance offerings use cpuNum and cpuSpeed to define a VM's CPU capacity. cpuNum, very straightforward, means the number 100 | of VCPU that a VM has; cpuSpeed is a little special; as a VM's VCPU always has the frequency same to the host's 101 | physical CPU, cpuSpeed here actually means VCPU weight in hypervisors. Depending on hypervisor types, the use and implementation of 102 | cpuSpeed vary. 103 | 104 | KVM CPU Speed 105 | ------------- 106 | 107 | In KVM, ZStack will set the result of 'cpuSpeed * cpuNum' to VM's XML configuration to libvirt:: 108 | 109 | 110 | 128 111 | 112 | 113 | shares = cpuNum * cpuSpeed 114 | 115 | .. _instance offering type: 116 | 117 | Type 118 | ++++ 119 | 120 | The type of instance offering; currently there are two types: 121 | 122 | - **UserVm**: instance offering for creating user VMs. 123 | 124 | - **VirtualRouter**: instance offering for creating virtual router VMs; see :ref:`virtual router `. 125 | 126 | .. _instance offering allocator strategy: 127 | 128 | Allocator Strategy 129 | ++++++++++++++++++ 130 | 131 | Allocator strategy defines the algorithm of selecting destination hosts for creating VMs. 132 | 133 | DefaultHostAllocatorStrategy 134 | ---------------------------- 135 | 136 | DefaultHostAllocatorStrategy uses below algorithm: 137 | 138 | Input Parameters 139 | **************** 140 | .. list-table:: 141 | :widths: 30 70 142 | :header-rows: 1 143 | 144 | * - Name 145 | - Description 146 | * - **image** 147 | - image used to create the VM 148 | * - **L3 network** 149 | - L3 networks the VM will have nics on 150 | * - **instance offering** 151 | - instance offering 152 | * - **tags** 153 | - tags for host allocation 154 | 155 | Algorithm 156 | ********* 157 | 158 | :: 159 | 160 | l2_networks = get_parent_l2_networks(l3_networks) 161 | host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks() 162 | check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1) 163 | host_set2 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set1) 164 | host_set3 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set2) 165 | primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached_to_clusters_of_hosts(image, host_set3) 166 | host_set4 = remove_hosts_that_cannot_access_primary_storage(host_set3) 167 | host_set5 = remove_avoided_hosts(host_set4) 168 | host_set6 = call_tag_plugin(tags, host_set5) 169 | 170 | return randomly_pick_one_host(host_set6) 171 | 172 | 173 | .. _DesignatedHostAllocatorStrategy: 174 | 175 | DesignatedHostAllocatorStrategy 176 | ------------------------------- 177 | 178 | DesignatedHostAllocatorStrategy uses algorithm: 179 | 180 | Input Parameters 181 | **************** 182 | .. list-table:: 183 | :widths: 30 60 10 184 | :header-rows: 1 185 | 186 | * - Name 187 | - Description 188 | - Optional 189 | * - **image** 190 | - image used to create the VM 191 | - 192 | * - **L3 network** 193 | - L3 networks the VM will have nics on 194 | - 195 | * - **instance offering** 196 | - instance offering 197 | - 198 | * - **tags** 199 | - tags for host allocation 200 | - 201 | * - **zone** 202 | - the zone the VM wants to run 203 | - true 204 | * - **cluster** 205 | - the cluster the VM wants to run 206 | - true 207 | * - **host** 208 | - the host the VM wants to run 209 | - true 210 | 211 | Algorithm 212 | ********* 213 | 214 | :: 215 | 216 | l2_networks = get_parent_l2_networks(l3_networks) 217 | host_set1 = find_hosts_in_cluster_that_have_attached_to_l2_networks() 218 | check_if_backup_storage_having_image_have_attached_to_zone_of_hosts(host_set1) 219 | 220 | if host is not null: 221 | host_set2 = list(find_host_in_host_set1(host)) 222 | else if cluster is not null: 223 | host_set2 = find_host_in_cluster_and_host_set1(cluster) 224 | else if zone is not null: 225 | host_set2 = find_host_in_zone_and_host_set1(zone) 226 | 227 | host_set3 = remove_hosts_not_having_state_Enabled_and_status_Connected(host_set2) 228 | host_set4 = remove_hosts_not_having_capacity_required_by_instance_offering(host_set3) 229 | primary_storage = find_Enabled_Connected_primary_storage_having_enough_capacity_for_root_volume_and_attached_to_clusters_of_hosts(image, host_set4) 230 | host_set5 = remove_hosts_that_cannot_access_primary_storage(host_set4) 231 | host_set6 = remove_avoided_hosts(host_set5) 232 | host_set7 = call_tag_plugin(tags, host_set6) 233 | 234 | return randomly_pick_one_host(host_set7) 235 | 236 | 237 | .. note:: DesignatedHostAllocatorStrategy is a little special of not being specified in instance offerings; when a zoneUuid or a clusterUuid or 238 | a hostUuid is specified in :ref:`CreateVmInstance `, DesignatedHostAllocatorStrategy automatically overrides 239 | the strategy in instance offering. 240 | 241 | .. _instance offering state: 242 | 243 | State 244 | +++++ 245 | 246 | Instance offerings have two states: 247 | 248 | - **Enabled**: 249 | 250 | The state that allows VMs to be created from this instance offering 251 | 252 | - **Disabled**: 253 | 254 | The state that DOESN'T allows VMs to be created from this instance offering 255 | 256 | ---------- 257 | Operations 258 | ---------- 259 | 260 | .. _CreateInstanceOffering: 261 | 262 | Create Instance Offering 263 | ======================== 264 | 265 | Users can use CreateInstanceOffering to create an instance offering. For example:: 266 | 267 | CreateInstanceOffering name=small cpuNum=1 cpuSpeed=1000 memorySize=1073741824 268 | 269 | Parameters 270 | ++++++++++ 271 | 272 | .. list-table:: 273 | :widths: 20 40 10 20 10 274 | :header-rows: 1 275 | 276 | * - Name 277 | - Description 278 | - Optional 279 | - Choices 280 | - Since 281 | * - **name** 282 | - resource name, see :ref:`resource properties` 283 | - 284 | - 285 | - 0.6 286 | * - **resourceUuid** 287 | - resource uuid, see :ref:`create resource` 288 | - true 289 | - 290 | - 0.6 291 | * - **description** 292 | - resource description, see :ref:`resource properties` 293 | - true 294 | - 295 | - 0.6 296 | * - **cpuNum** 297 | - VCPU num, see :ref:`CPU capacity ` 298 | - 299 | - 300 | - 0.6 301 | * - **cpuSpeed** 302 | - VCPU speed, see :ref:`CPU capacity ` 303 | - 304 | - 305 | - 0.6 306 | * - **memorySize** 307 | - memory size, in bytes 308 | - 309 | - 310 | - 0.6 311 | * - **type** 312 | - type, default is UserVm, see :ref:`type ` 313 | - true 314 | - - UserVm 315 | - VirtualRouter 316 | - 0.6 317 | 318 | .. _DeleteInstanceOffering: 319 | 320 | Delete Instance Offering 321 | ======================== 322 | 323 | Users can use DeleteInstanceOffering to delete an instance offering. For example:: 324 | 325 | DeleteInstanceOffering uuid=1164a094fea34f1e8265c802a8048bae 326 | 327 | 328 | Parameters 329 | ++++++++++ 330 | 331 | .. list-table:: 332 | :widths: 20 40 10 20 10 333 | :header-rows: 1 334 | 335 | * - Name 336 | - Description 337 | - Optional 338 | - Choices 339 | - Since 340 | * - **deleteMode** 341 | - see :ref:`delete resource` 342 | - true 343 | - - Permissive 344 | - Enforcing 345 | - 0.6 346 | * - **uuid** 347 | - instance offering uuid 348 | - 349 | - 350 | - 0.6 351 | 352 | Change State 353 | ============ 354 | 355 | Users can use ChangeInstanceOfferingState to change a state of instance offering. For example:: 356 | 357 | ChangeInstanceOfferingState uuid=1164a094fea34f1e8265c802a8048bae stateEvent=enable 358 | 359 | Parameters 360 | ++++++++++ 361 | 362 | .. list-table:: 363 | :widths: 20 40 10 20 10 364 | :header-rows: 1 365 | 366 | * - Name 367 | - Description 368 | - Optional 369 | - Choices 370 | - Since 371 | * - **stateEvent** 372 | - state trigger event 373 | 374 | - enable: change state to Enabled 375 | - disable: change state to Disabled 376 | - 377 | - - enable 378 | - disable 379 | - 0.6 380 | * - **uuid** 381 | - instance offering uuid 382 | - 383 | - 384 | - 0.6 385 | 386 | Query Instance Offering 387 | ======================= 388 | 389 | Users can use QueryInstanceOffering to query instance offerings. For example:: 390 | 391 | QueryInstanceOffering cpuSpeed=512 cpuNum>2 392 | 393 | :: 394 | 395 | QueryInstanceOffering vmInstance.state=Stopped 396 | 397 | 398 | Primitive Fields of Query 399 | +++++++++++++++++++++++++ 400 | 401 | see :ref:`instance offering inventory ` 402 | 403 | Nested and Expanded Fields of Query 404 | +++++++++++++++++++++++++++++++++++ 405 | 406 | .. list-table:: 407 | :widths: 20 30 40 10 408 | :header-rows: 1 409 | 410 | * - Field 411 | - Inventory 412 | - Description 413 | - Since 414 | * - **vmInstance** 415 | - :ref:`VM inventory ` 416 | - VMs that are created from this instance offering 417 | - 0.6 418 | 419 | ---- 420 | Tags 421 | ---- 422 | 423 | Users can create user tags on an instance offering with resourceType=InstanceOfferingVO. For example:: 424 | 425 | CreateUserTag resourceType=InstanceOfferingVO tag=web-server-offering resourceUuid=45f909969ce24865b1bbca4adb66710a 426 | 427 | System Tags 428 | =========== 429 | 430 | Dedicated Primary Storage 431 | +++++++++++++++++++++++++ 432 | 433 | When creating VMs, users can use a system to specify primary storage on which root volumes will be created. 434 | 435 | .. list-table:: 436 | :widths: 20 30 40 10 437 | :header-rows: 1 438 | 439 | * - Tag 440 | - Description 441 | - Example 442 | - Since 443 | * - **primaryStorage::allocator::uuid::{uuid}** 444 | - | if present, the VM's root volume will be allocated on 445 | | the primary storage whose uuid is *uuid*; 446 | | an allocation failure will be raised if the specified primary storage 447 | | doesn't exist or doesn't have enough capacity. 448 | - primaryStorage::allocator::uuid::b8398e8b7ff24527a3b81dc4bc64d974 449 | - 0.6 450 | * - **primaryStorage::allocator::userTag::{tag}::required** 451 | - | if present, the VM's root volume will be allocated on the 452 | | primary storage which has user tag *tag*; 453 | | an allocation failure will be raised if no primary storage has 454 | | the *tag* or primary storage having the *tag* doesn't 455 | | have enough capacity 456 | - primaryStorage::allocator::userTag::SSD::required 457 | - 0.6 458 | * - **primaryStorage::allocator::userTag::{tag}** 459 | - | if present, the VM's root volume will be allocated on the primary storage 460 | | which has user tag *tag*, if there is any; 461 | | NO failure will be raised if no primary storage has the *tag* or 462 | | primary storage having the *tag* doesn't 463 | | have enough capacity, instead, a random primary storage will be chosen. 464 | - primaryStorage::allocator::userTag::SSD 465 | - 0.6 466 | 467 | if more than one above system tags present on a disk offering, the precedent order is:: 468 | 469 | primaryStorage::allocator::uuid::{uuid} > primaryStorage::allocator::userTag::{tag}::required > primaryStorage::allocator::userTag::{tag} 470 | -------------------------------------------------------------------------------- /userManual/cluster.rst: -------------------------------------------------------------------------------- 1 | .. _cluster: 2 | 3 | ======= 4 | Cluster 5 | ======= 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | A cluster is a logic group of analogy hosts. Hosts in the same cluster must be installed with the same operating systems(hypervisor), have 15 | the same layer2 network connectivity, and can access the same primary storage. In real datacenters, a cluster usually maps to a rack. 16 | 17 | A typical cluster and its relationship to primary storage, L2 networks is shown in below diagram. 18 | 19 | .. image:: cluster.png 20 | :align: center 21 | 22 | A cluster can have one or more primary storage attached, as long as hosts in the cluster can all access these primary storage. Also, a 23 | primary storage can be detached from a cluster; this is particularly useful when network typology changes in datacenters, which causes 24 | the primary storage no longer accessible to hosts in the cluster. 25 | 26 | A cluster can have one or more L2 networks attached, as long as hosts in the cluster are all in the physical layer2 broadcast domains those 27 | L2 networks represent. Also, a L2 network can be detached from a cluster, if network typology changes in the datacenter cause 28 | hosts in the cluster no longer in the layer2 broadcast domain of the L2 network. 29 | 30 | The size of a cluster, which is the maximum hosts the cluster can contain, is not enforced. 31 | 32 | 33 | .. _cluster inventory: 34 | 35 | --------- 36 | Inventory 37 | --------- 38 | 39 | Properties 40 | ========== 41 | 42 | .. list-table:: 43 | :widths: 20 40 10 20 10 44 | :header-rows: 1 45 | 46 | * - Name 47 | - Description 48 | - Optional 49 | - Choices 50 | - Since 51 | * - **uuid** 52 | - see :ref:`resource properties` 53 | - 54 | - 55 | - 0.6 56 | * - **name** 57 | - see :ref:`resource properties` 58 | - 59 | - 60 | - 0.6 61 | * - **description** 62 | - see :ref:`resource properties` 63 | - true 64 | - 65 | - 0.6 66 | * - **hypervisorType** 67 | - see `cluster hypervisor type`_ 68 | - 69 | - - KVM 70 | - 0.6 71 | * - **state** 72 | - see `cluster state`_ 73 | - 74 | - - Enabled 75 | - Disabled 76 | - 0.6 77 | * - **zoneUuid** 78 | - uuid of zone containing the cluster. See :ref:`zone `. 79 | - 80 | - 81 | - 0.6 82 | * - **createDate** 83 | - see :ref:`resource properties` 84 | - 85 | - 86 | - 0.6 87 | * - **lastOpDate** 88 | - see :ref:`resource properties` 89 | - 90 | - 91 | - 0.6 92 | * - **type** 93 | - reserved field 94 | - 95 | - 96 | - 0.6 97 | * - **userTags** 98 | - user tags, see :ref:`create tags` 99 | - true 100 | - 101 | - 0.6 102 | * - **systemTags** 103 | - system tags, see :ref:`create tags` 104 | - true 105 | - 106 | - 0.6 107 | 108 | Example 109 | ======= 110 | 111 | :: 112 | 113 | { 114 | "inventory": { 115 | "uuid": "c1bd173d5cd84f0e9e7c47195ae27ec6", 116 | "name": "cluster1", 117 | "description": "test", 118 | "state": "Enabled", 119 | "zoneUuid": "1b830f5bd1cb469b821b4b77babfdd6f" 120 | "hypervisorType": "KVM", 121 | "lastOpDate": "Jun 1, 2015 5:54:09 PM", 122 | "createDate": "Jun 1, 2015 5:54:09 PM", 123 | "type": "zstack", 124 | } 125 | } 126 | 127 | .. _cluster hypervisor type: 128 | 129 | Hypervisor Type 130 | =============== 131 | 132 | Hypervisor type indicates what hypervisor(operating system) installed on hosts in the cluster. In this ZStack version, the only supported hypervisor is KVM. 133 | 134 | .. _cluster state: 135 | 136 | State 137 | ===== 138 | 139 | Cluster has two states: Enabled and Disabled, just like :ref:`zone `. When changing the state of a cluster, the operation will be spread to all hosts of the cluster; 140 | For example, disabling a cluster will disable all hosts in the cluster as well. 141 | 142 | .. note:: Admins can selectively enable hosts in a disabled cluster or disable them in an enabled cluster, in order to have fine-grained state control. 143 | 144 | ---------- 145 | Operations 146 | ---------- 147 | 148 | Create Cluster 149 | ============== 150 | 151 | Admins can use CreateCluster command to create a cluster. For example:: 152 | 153 | CreateCluster name=cluster1 hypervisorType=KVM zoneUuid=1b830f5bd1cb469b821b4b77babfdd6f 154 | 155 | Parameters 156 | ++++++++++ 157 | 158 | .. list-table:: 159 | :widths: 20 40 10 20 10 160 | :header-rows: 1 161 | 162 | * - Name 163 | - Description 164 | - Optional 165 | - Choices 166 | - Since 167 | * - **zoneUuid** 168 | - uuid of parent zone 169 | - 170 | - 171 | - 0.6 172 | * - **name** 173 | - resource name, see :ref:`resource properties` 174 | - 175 | - 176 | - 0.6 177 | * - **resourceUuid** 178 | - resource uuid, see :ref:`create resource` 179 | - true 180 | - 181 | - 0.6 182 | * - **description** 183 | - resource description, see :ref:`resource properties` 184 | - true 185 | - 186 | - 0.6 187 | * - **hypervisorType** 188 | - see `cluster hypervisor type`_ 189 | - 190 | - 191 | - 0.6 192 | * - **type** 193 | - reserved field, don't evaluate it 194 | - true 195 | - 196 | - 0.6 197 | 198 | Delete Cluster 199 | ============== 200 | 201 | Admins can use DeleteCluster to delete a cluster. For example:: 202 | 203 | DeleteCluster uuid=c1bd173d5cd84f0e9e7c47195ae27ec6 204 | 205 | .. danger:: Deleting a cluster will delete hosts in the cluster; VMs will be migrated to other clusters or be stopped if no available clusters to migrate; 206 | primary storage and L2 networks attached to the cluster will be detached. There is no way to recover a deleted cluster. 207 | 208 | Parameters 209 | ++++++++++ 210 | 211 | .. list-table:: 212 | :widths: 20 40 10 20 10 213 | :header-rows: 1 214 | 215 | * - Name 216 | - Description 217 | - Optional 218 | - Choices 219 | - Since 220 | * - **uuid** 221 | - cluster uuid 222 | - 223 | - 224 | - 0.6 225 | * - **deleteMode** 226 | - see :ref:`delete resource` 227 | - true 228 | - - Permissive 229 | - Enforcing 230 | - 0.6 231 | 232 | Change State 233 | ============ 234 | 235 | Admins can use ChangeClusterState to change the state of a cluster. For example:: 236 | 237 | ChangeClusterState uuid=c1bd173d5cd84f0e9e7c47195ae27ec6 stateEvent=disable 238 | 239 | Parameters 240 | ++++++++++ 241 | 242 | .. list-table:: 243 | :widths: 20 40 10 20 10 244 | :header-rows: 1 245 | 246 | * - Name 247 | - Description 248 | - Optional 249 | - Choices 250 | - Since 251 | * - **uuid** 252 | - cluster uuid 253 | - 254 | - 255 | - 0.6 256 | * - **stateEvent** 257 | - state trigger event 258 | 259 | - enable: change state to Enabled 260 | - disable: change state to Disabled 261 | - 262 | - - enable 263 | - disable 264 | - 0.6 265 | 266 | .. _attach primary storage to cluster: 267 | 268 | Attach Primary Storage 269 | ====================== 270 | 271 | Admins can use AttachPrimaryStorageToCluster command to attach a primary storage to a cluster. For example:: 272 | 273 | AttachPrimaryStorageToCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 primaryStorageUuid=1b830f5bd1cb469b821b4b77babfdd6f 274 | 275 | .. note:: Only sibling primary storage can be attached to a cluster. In other words, primary storage and clusters must be in the 276 | same zone. 277 | 278 | Parameters 279 | ++++++++++ 280 | 281 | .. list-table:: 282 | :widths: 20 40 10 20 10 283 | :header-rows: 1 284 | 285 | * - Name 286 | - Description 287 | - Optional 288 | - Choices 289 | - Since 290 | * - **clusterUuid** 291 | - cluster uuid 292 | - 293 | - 294 | - 0.6 295 | * - **primaryStorageUuid** 296 | - primary storage uuid 297 | - 298 | - 299 | - 0.6 300 | 301 | .. _detach primary storage from cluster: 302 | 303 | Detach Primary Storage 304 | ====================== 305 | 306 | Admin cans use DetachPrimaryStorageFromCluster to detach a primary storage from a cluster. For example:: 307 | 308 | DetachPrimaryStorageFromCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 primaryStorageUuid=1b830f5bd1cb469b821b4b77babfdd6f 309 | 310 | .. note:: During detaching, VMs that have root volumes on the primary storage and that run in the cluster will be stopped. Users can 311 | start those VMs again if the primary storage is still attached to some other clusters, or start them after the primary storage 312 | is attached to a new cluster. 313 | 314 | Detaching primary storage is useful when admin wants to make a primary storage on longer accessible to a cluster. For example, in order to move VMs 315 | from a cluster equipped with aged hosts to a cluster with new, powerful hosts, admins can detach the primary storage on which root volumes of VMs locate 316 | from the old cluster and attach it to the new cluster, then start those stopped VMs; because the old cluster cannot access the primary storage anymore, 317 | ZStack will choose the new cluster to start VMs. 318 | 319 | Parameters 320 | ++++++++++ 321 | 322 | .. list-table:: 323 | :widths: 20 40 10 20 10 324 | :header-rows: 1 325 | 326 | * - Name 327 | - Description 328 | - Optional 329 | - Choices 330 | - Since 331 | * - **clusterUuid** 332 | - cluster uuid 333 | - 334 | - 335 | - 0.6 336 | * - **primaryStorageUuid** 337 | - primary storage uuid 338 | - 339 | - 340 | - 0.6 341 | 342 | .. _cluster attach L2 Network: 343 | 344 | Attach L2 Network 345 | ================= 346 | 347 | Admin can use AttachL2NetworkToCluster command to attach a L2 network to a cluster. For example:: 348 | 349 | AttachL2NetworkToCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 l2NetworkUuid=1b830f5bd1cb469b821b4b77babfdd6f 350 | 351 | .. note:: Only sibling L2 networks can be attached to a cluster. In other words, L2 networks and clusters must be in the 352 | same zone. 353 | 354 | Parameters 355 | ++++++++++ 356 | 357 | .. list-table:: 358 | :widths: 20 40 10 20 10 359 | :header-rows: 1 360 | 361 | * - Name 362 | - Description 363 | - Optional 364 | - Choices 365 | - Since 366 | * - **clusterUuid** 367 | - cluster uuid 368 | - 369 | - 370 | - 0.6 371 | * - **l2NetworkUuid** 372 | - L2 network uuid 373 | - 374 | - 375 | - 0.6 376 | 377 | .. _cluster detach L2 network: 378 | 379 | Detach L2 Network 380 | ================= 381 | 382 | Admins can use DetachL2NetworkFromCluster command to detach a L2 network from a cluster. For example:: 383 | 384 | DetachL2NetworkFromCluster clusterUuid=c1bd173d5cd84f0e9e7c47195ae27ec6 l2NetworkUuid=1b830f5bd1cb469b821b4b77babfdd6f 385 | 386 | .. note:: During detaching, VMs which run in the clusters and have nics on the L2 networks(through L3 networks) will be stopped. Users can 387 | start those VMs again if the L2 networks are still attached to other clusters, or start them after the L2 networks 388 | are attached to new clusters. 389 | 390 | Detaching L2 networks can be useful when admins want to make network typology changes in datacenters. After hosts in a cluster no longer connect to a physical layer2 network, 391 | admin can detach the L2 network representing the physical layer2 network from the cluster. 392 | 393 | Parameters 394 | ++++++++++ 395 | 396 | .. list-table:: 397 | :widths: 20 40 10 20 10 398 | :header-rows: 1 399 | 400 | * - Name 401 | - Description 402 | - Optional 403 | - Choices 404 | - Since 405 | * - **clusterUuid** 406 | - cluster uuid 407 | - 408 | - 409 | - 0.6 410 | * - **l2NetworkUuid** 411 | - L2 network uuid 412 | - 413 | - 414 | - 0.6 415 | 416 | Query Cluster 417 | ============= 418 | 419 | Admins can use QueryCluster to query clusters. For example:: 420 | 421 | QueryCluster hypervisorType=KVM 422 | 423 | :: 424 | 425 | QueryCluster primaryStorage.availableCapacity>100000000 426 | 427 | Primitive Fields of Query 428 | +++++++++++++++++++++++++ 429 | 430 | see :ref:`cluster inventory ` 431 | 432 | Nested And Expanded Fields of Query 433 | +++++++++++++++++++++++++++++++++++ 434 | 435 | .. list-table:: 436 | :widths: 20 30 40 10 437 | :header-rows: 1 438 | 439 | * - Field 440 | - Inventory 441 | - Description 442 | - Since 443 | * - **zone** 444 | - see :ref:`zone inventory ` 445 | - parent zone 446 | - 0.6 447 | * - **host** 448 | - see :ref:`host inventory ` 449 | - hosts belonging to this cluster 450 | - 0.6 451 | * - **vmInstance** 452 | - see :ref:`vm inventory ` 453 | - VMs belonging to this cluster 454 | - 0.6 455 | * - **l2Network** 456 | - see :ref:`L2 network inventory ` 457 | - L2 networks attached to this cluster 458 | - 0.6 459 | * - **primaryStorage** 460 | - see :ref:`primary storage inventory ` 461 | - primary storage attached to this cluster 462 | - 0.6 463 | 464 | ---- 465 | Tags 466 | ---- 467 | 468 | Admins can create user tags on a cluster with resourceType=ClusterVO. For example:: 469 | 470 | CreateUserTag resourceType=ClusterVO resourceUuid=80a979b9e0234564a22a4cca8c1dff43 tag=secureCluster 471 | 472 | System Tags 473 | =========== 474 | 475 | .. _cluster.host.reservedMemory: 476 | 477 | Reserved Capacity 478 | +++++++++++++++++ 479 | 480 | .. list-table:: 481 | :widths: 20 30 40 10 482 | :header-rows: 1 483 | 484 | * - Tag 485 | - Description 486 | - Example 487 | - Since 488 | * - **host::reservedMemory::{capacity}** 489 | - see :ref:`host capacity reservation` 490 | - host::reservedMemory::1G 491 | - 0.6 492 | 493 | .. _hypervisor: http://en.wikipedia.org/wiki/Hypervisor 494 | 495 | -------------------------------------------------------------------------------- /userManual/l2Network.rst: -------------------------------------------------------------------------------- 1 | .. _l2Network: 2 | 3 | ========== 4 | L2 Network 5 | ========== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | A L2 network reflects a `layer2 broadcast domain `_ in a datacenter. That means, 15 | in addition to the traditional OSI data link layer, all technologies that provide layer 2 isolation can be L2 networks 16 | in ZStack. For example, VLAN, VxLAN, or SDNs that create layer 2 overlay networks. In ZStack, a L2 network is responsible 17 | for providing the layer 2 isolation method to child L3 networks. 18 | 19 | .. image:: l2Network.png 20 | :align: center 21 | 22 | A L2 network can be attached to sibling clusters. 23 | 24 | .. _l2Network inventory: 25 | 26 | --------- 27 | Inventory 28 | --------- 29 | 30 | .. _l2Network properties: 31 | 32 | Properties 33 | ========== 34 | 35 | .. list-table:: 36 | :widths: 20 40 10 20 10 37 | :header-rows: 1 38 | 39 | * - Name 40 | - Description 41 | - Optional 42 | - Choices 43 | - Since 44 | * - **uuid** 45 | - see :ref:`resource properties` 46 | - 47 | - 48 | - 0.6 49 | * - **name** 50 | - see :ref:`resource properties` 51 | - 52 | - 53 | - 0.6 54 | * - **description** 55 | - see :ref:`resource properties` 56 | - true 57 | - 58 | - 0.6 59 | * - **zoneUuid** 60 | - uuid of parent zone, see :ref:`zone ` 61 | - 62 | - 63 | - 0.6 64 | * - **physicalInterface** 65 | - see :ref:`physical interface ` 66 | - 67 | - 68 | - 0.6 69 | * - **type** 70 | - L2 network type 71 | - 72 | - - L2NoVlanNetwork 73 | - L2VlanNetwork 74 | - 0.6 75 | * - **attachedClusterUuids** 76 | - a list of cluster uuid to which the L2 network has attached, see :ref:`attach cluster ` 77 | - 78 | - 79 | - 0.6 80 | * - **createDate** 81 | - see :ref:`resource properties` 82 | - 83 | - 84 | - 0.6 85 | * - **lastOpDate** 86 | - see :ref:`resource properties` 87 | - 88 | - 89 | - 0.6 90 | 91 | .. _l2Network physical interface: 92 | 93 | Physical Interface 94 | ================== 95 | 96 | The physical interface is a string that contains information needed by a L2 network plugin for manipulating network system in a datacenter. 97 | The information encoded in physical interface is specific to L2 network types and hypervisor types of clusters that L2 networks may 98 | attach. This sounds a little complex. The complexity is originated from hypervisors using their own notations to describe L2 networks, and 99 | a L2 network can be attached to multiple clusters of different hypervisor types. A real world example may help to understand this. 100 | 101 | Let's say your datacenter has a L2 network (l2Network A) which spans to two clusters, one is a KVM cluster, another is a VMWare cluster. In KVM, 102 | the L2 network is realized by ethernet device in Linux operating system; in this example, let's assume each eth0 of KVM hosts 103 | connects to the L2 network. In the VMWare cluster, the L2 network is realized by vswitch; in this example, let's assume vswitch0 in the VMWare cluster 104 | connects to the L2 network; then the typology is like: 105 | 106 | .. image:: l2Network-physical-interface.png 107 | :align: center 108 | 109 | As mentioned in section :ref:`host `, lots of operations seemingly applied to clusters are actually delegated to hosts; 110 | Here, when attaching the L2 network A to the KVM cluster and the VMWare cluster, ZStack must understand what are notations describing the L2 111 | network in those hypervisors of clusters; in this case, ZStack must know that on KVM hosts, eth0 is the representation of the L2 network, but on VMWare 112 | hosts, vswitch0 is the representation. Physical interface is the field that encodes those hypervisor specific information. 113 | 114 | .. note:: As this ZStack version supports only KVM, we won't discuss VMWare details for L2 networks. Above example largely aims to help understand 115 | the design of the physical interface. 116 | 117 | .. _l2Network attach cluster: 118 | 119 | Attaching Cluster 120 | ================= 121 | 122 | Attaching cluster is to associate L2 networks to sibling clusters, which provides a flexible way that manifests relations between hosts and 123 | layer 2 networks in a real datacenter. Let's see a concrete example. 124 | 125 | .. image:: l2Network-cluster1.png 126 | :align: center 127 | 128 | Let's assume the network typology in your datacenter is as above diagram. Eth0 of hosts in all clusters are on the same layer 2 network called L2 129 | Network1; eth1 of cluster1 and cluster3 are on another layer 2 network called L2 network2. To describe this typology in ZStack, you can attach L2 network1 130 | to all three clusters but attach L2 network2 to only cluster1 and cluster3. 131 | 132 | A couple months later, the network typology needs changing because of business requirements, you unplug cables of eth1 of hosts in cluster3 from the rack switch, 133 | so cluster3 is not with L2 network2 anymore; you can detach the L2 network2 from cluster3 to notify ZStack about the network typology change. 134 | 135 | 136 | .. image:: l2Network-cluster2.png 137 | :align: center 138 | 139 | L2NoVlanNetwork 140 | =============== 141 | 142 | L2NoVlanNetwork, whose properties are listed in :ref:`properties ` is the base type of L2 Networks. 143 | The 'NoVlan' in the name DOESN'T mean the network cannot use VLAN technology, it only denotes that ZStack itself will not use VLAN 144 | to create a layer 2 broadcast domain in an active manner. To make it clear, take a look at below two diagrams: 145 | 146 | .. image:: l2NoVlanNetwork1.png 147 | :align: center 148 | :width: 500px 149 | :height: 400px 150 | 151 | In this setup, two switch ports 5 and 12 are untagged with VLAN 10(access port with VLAN 10 in Cisco term), and connect to eth0 on host1 and host2 respectively. This 152 | is a very valid setup matching to a L2NoVlanNetwork. Admin cans create a L2NoVlanNetwork with 'physicalInterface' = 'eth0' and attach it to the cluster. 153 | 154 | .. image:: l2NoVlanNetwork2.png 155 | :align: center 156 | :width: 500px 157 | :height: 400px 158 | 159 | In this setup, two switch ports 5 and 12 are tagged with VLAN 10(trunk port with VLAN 10 in Cisco term), and respectively connect to eth0.10 that is a pre-created VLAN device on host1 160 | and host2. This is also a very valid setup matching to a L2NoVlanNetwork. Admins can create a L2NoVlanNetwork with 'physicalInterface' = 161 | 'eth0.10' and attach it to the cluster. 162 | 163 | Now it should be understood that a L2NoVlanNetwork maps to a pre-created layer 2 broadcast domain; ZStack won't create any new broadcast domain for L2NoVlanNetwork. 164 | 165 | L2NoVlanNetwork KVM Specific 166 | ++++++++++++++++++++++++++++ 167 | 168 | When attaching a L2NoVlanNetwork to a KVM cluster, the :ref:`physicalInterface ` should be the ethernet device name in the Linux operating system; for example, 169 | eth0, eth0.10, em1. ZStack will use 'physicalInterface' as device name when creating a bridge using brctl. The pseudo operations are like:: 170 | 171 | Assuming physicalInterface = eth0 172 | 173 | brctl create br_eth0 174 | brctl addif br_eth0 eth0 175 | 176 | .. note:: If you have multiple clusters of hosts whose ethernet devices connect to the same L2 network, and you want to attach that L2 network to those clusters, 177 | please make sure names of all ethernet devices are the same among all Linux operating systems on hosts. For example, all ethernet devices are named as eth0. 178 | The best practice is installing the same Linux system on hosts of those clusters, or using udev to make all device names same. 179 | 180 | L2NoVlanNetwork Inventory Example 181 | +++++++++++++++++++++++++++++++++ 182 | 183 | :: 184 | 185 | { 186 | "inventory": { 187 | "uuid": "f685ff94513542bbb8e814027f8deb13", 188 | "name": "l2-basic", 189 | "description": "Basic L2 Test", 190 | "zoneUuid": "45a2864b6ddf4d2fb9b4c3736a923dcb", 191 | "physicalInterface": "eth0", 192 | "type": "L2NoVlanNetwork", 193 | "createDate": "Jun 1, 2015 12:58:35 PM", 194 | "lastOpDate": "Jun 1, 2015 12:58:35 PM", 195 | "attachedClusterUuids": [] 196 | } 197 | } 198 | 199 | L2VlanNetwork 200 | ============= 201 | 202 | A L2VlanNetwork is a L2 network that ZStack will actively use a VLAN to create a layer 2 broadcast domain. The ways that ZStack create layer 2 broadcast domains depend 203 | on hypervisor types of clusters, to which L2 networks are going to attach. In addition to :ref:`properties `, a L2VlanNetwork has one more property: 204 | 205 | .. list-table:: 206 | :widths: 20 40 10 20 10 207 | :header-rows: 1 208 | 209 | * - Name 210 | - Description 211 | - Optional 212 | - Choices 213 | - Since 214 | * - **vlan** 215 | - VLAN id used to create layer 2 broadcast domain 216 | - 217 | - [0, 4095] 218 | - 0.6 219 | 220 | When attaching a L2VlanNetwork to a cluster, ZStack uses 'vlan' collaborating with 'physicalInterface' to create vlan devices on hosts in the cluster; in order to make this work, 221 | the switch ports to which ethernet devices identified by 'physicalInterface' connect must be tagged with 'vlan'. For example: 222 | 223 | .. image:: l2VlanNetwork1.png 224 | :align: center 225 | :width: 500px 226 | :height: 400px 227 | 228 | In this setup, switch ports 5 and 12 have been tagged with VLAN 10, then admins can create a L2VlanNetwork with 'physicalInterface' = 'eth0' and 'vlan' = 10 and 229 | attach it to the cluster. 230 | 231 | L2VlanNetwork KVM Specific 232 | ++++++++++++++++++++++++++ 233 | 234 | When attaching a L2VlanNetwork to a KVM cluster, ZStack will create VLAN devices on all hosts in the cluster then create bridges. The pseudo operations are like:: 235 | 236 | Assuming physicalInterface = eth0, vlan = 10 237 | 238 | vconfig add eth0 10 239 | brctl create br_eth0_10 240 | brctl addif br_eth0_10 eth0.10 241 | 242 | .. note:: Like L2NoVlanNetwork, please make sure ethernet device names of all hosts in clusters to which a L2VlanNetwork is about to attach are the same. 243 | 244 | L2VlanNetwork Inventory Example 245 | +++++++++++++++++++++++++++++++ 246 | 247 | :: 248 | 249 | { 250 | "inventory": { 251 | "vlan": 10, 252 | "uuid": "14a01b0978684b2ea6e5a355c7c7fd73", 253 | "name": "TestL2VlanNetwork", 254 | "description": "Test", 255 | "zoneUuid": "c74f8ff8a4c5456b852713b82c034074", 256 | "physicalInterface": "eth0", 257 | "type": "L2VlanNetwork", 258 | "createDate": "Jun 1, 2015 4:31:47 PM", 259 | "lastOpDate": "Jun 1, 2015 4:31:47 PM", 260 | "attachedClusterUuids": [] 261 | } 262 | } 263 | 264 | ---------- 265 | Operations 266 | ---------- 267 | 268 | Create L2 Network 269 | ================= 270 | 271 | The commands creating L2 networks vary for different L2 network types. 272 | 273 | 274 | Create L2NoVlanNetwork 275 | ====================== 276 | 277 | Admins can use CreateL2NoVlanNetwork to create a L2NoVlanNetwork. For example:: 278 | 279 | CreateL2NoVlanNetwork name=management-network physicalInterface=eth0 zoneUuid=9a94e647a9f64bb392afcdc5396cc1e4 280 | 281 | Parameters 282 | ++++++++++ 283 | 284 | .. list-table:: 285 | :widths: 20 40 10 20 10 286 | :header-rows: 1 287 | 288 | * - Name 289 | - Description 290 | - Optional 291 | - Choices 292 | - Since 293 | * - **name** 294 | - resource name, see :ref:`resource properties` 295 | - 296 | - 297 | - 0.6 298 | * - **resourceUuid** 299 | - resource uuid, see :ref:`create resource` 300 | - true 301 | - 302 | - 0.6 303 | * - **description** 304 | - resource description, see :ref:`resource properties` 305 | - true 306 | - 307 | - 0.6 308 | * - **zoneUuid** 309 | - uuid of parent zone, see :ref:`zone ` 310 | - 311 | - 312 | - 0.6 313 | * - **physicalInterface** 314 | - see :ref:`physical interface ` 315 | - 316 | - 317 | - 0.6 318 | 319 | Delete L2 Network 320 | ================= 321 | 322 | Admins can use DeleteL2Network to delete a L2 network. For example:: 323 | 324 | DeleteL2Network uuid=a5535531eb7346ce89cfd7e643ad1ef8 325 | 326 | .. danger:: Deleting a L2 network will cause its child L3 network to be deleted. For consequences of deleting L3 networks, 327 | see :ref:`delete l3Network`. There is no way to recover a deleted L2 network. 328 | 329 | Parameters 330 | ++++++++++ 331 | 332 | .. list-table:: 333 | :widths: 20 40 10 20 10 334 | :header-rows: 1 335 | 336 | * - Name 337 | - Description 338 | - Optional 339 | - Choices 340 | - Since 341 | * - **deleteMode** 342 | - see :ref:`delete resource` 343 | - true 344 | - - Permissive 345 | - Enforcing 346 | - 0.6 347 | * - **uuid** 348 | - L2 network uuid 349 | - 350 | - 351 | - 0.6 352 | 353 | Attach Cluster 354 | ============== 355 | 356 | See :ref:`cluster attach L2 network`. 357 | 358 | Detach Cluster 359 | ============== 360 | 361 | See :ref:`cluster detach L2 network`. 362 | 363 | Query L2 Network 364 | ================ 365 | 366 | Admins can use QueryL2Network to query L2 networks. For example:: 367 | 368 | QueryL2Network physicalInterface=eth0 369 | 370 | :: 371 | 372 | QueryL2Network l3Network.ipRanges.startIp=192.168.0.2 373 | 374 | 375 | Primitive Fields of Query 376 | +++++++++++++++++++++++++ 377 | 378 | see :ref:`L2 network inventory `. 379 | 380 | Nested and Expanded Fields of Query 381 | +++++++++++++++++++++++++++++++++++ 382 | 383 | .. list-table:: 384 | :widths: 20 30 40 10 385 | :header-rows: 1 386 | 387 | * - Field 388 | - Inventory 389 | - Description 390 | - Since 391 | * - **l3Network** 392 | - :ref:`L3 network inventory ` 393 | - L3 networks belonging to this L2 network 394 | - 0.6 395 | * - **cluster** 396 | - :ref:`cluster inventory ` 397 | - clusters this L2 network is attached to 398 | - 0.6 399 | * - **zone** 400 | - :ref:`zone inventory ` 401 | - parent zone 402 | - 0.6 403 | 404 | ---- 405 | Tags 406 | ---- 407 | 408 | Admins can create user tags on a L2 network with resourceType=L2NetworkVO. For example:: 409 | 410 | CreateUserTag resourceType=L2NetworkVO tag=publicL2 resourceUuid=cff4be8694174b0fb831a9fe53b1d62b 411 | 412 | -------------------------------------------------------------------------------- /userManual/primaryStorage.rst: -------------------------------------------------------------------------------- 1 | .. _primary storage: 2 | 3 | =============== 4 | Primary Storage 5 | =============== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | A primary storage is the storage system in datacenter that stores disk volumes for VMs. Primary storage can be local disks(e.g. hard 15 | drives of hosts) or network shared (e.g. NAS, SAN ) storage. 16 | 17 | .. image:: primary-storage.png 18 | :align: center 19 | 20 | A primary storage stores volumes for VMs running in clusters that have been attached to this primary storage. 21 | 22 | A primary storage can be attached to only sibling clusters. 23 | 24 | .. note:: In this ZStack version, NFS is the only supported primary storage 25 | 26 | .. _primary storage inventory: 27 | 28 | --------- 29 | Inventory 30 | --------- 31 | 32 | Properties 33 | ========== 34 | 35 | .. list-table:: 36 | :widths: 20 40 10 20 10 37 | :header-rows: 1 38 | 39 | * - Name 40 | - Description 41 | - Optional 42 | - Choices 43 | - Since 44 | * - **uuid** 45 | - see :ref:`resource properties` 46 | - 47 | - 48 | - 0.6 49 | * - **name** 50 | - see :ref:`resource properties` 51 | - 52 | - 53 | - 0.6 54 | * - **description** 55 | - see :ref:`resource properties` 56 | - true 57 | - 58 | - 0.6 59 | * - **zoneUuid** 60 | - uuid of parent zone, see :ref:`zone ` 61 | - 62 | - 63 | - 0.6 64 | * - **totalCapacity** 65 | - total disk capacity, in bytes, see :ref:`capacity ` 66 | - 67 | - 68 | - 0.6 69 | * - **availableCapacity** 70 | - available disk capacity, in bytes, see :ref:`capacity ` 71 | - 72 | - 73 | - 0.6 74 | * - **url** 75 | - see :ref:`url ` 76 | - 77 | - 78 | - 0.6 79 | * - **type** 80 | - primary storage type 81 | - 82 | - - NFS 83 | - 0.6 84 | * - **state** 85 | - see :ref:`state ` 86 | - 87 | - - Enabled 88 | - Disabled 89 | - 0.6 90 | * - **status** 91 | - see :ref:`status ` 92 | - 93 | - - Connecting 94 | - Connected 95 | - Disconnected 96 | - 0.6 97 | * - **attachedClusterUuids** 98 | - a list of cluster uuid to which the primary storage has been attached, see :ref:`attach cluster ` 99 | - 100 | - 101 | - 0.6 102 | * - **createDate** 103 | - see :ref:`resource properties` 104 | - 105 | - 106 | - 0.6 107 | * - **lastOpDate** 108 | - see :ref:`resource properties` 109 | - 110 | - 111 | - 0.6 112 | 113 | 114 | Example 115 | ======= 116 | 117 | :: 118 | 119 | { 120 | "inventory": { 121 | "uuid": "f4ac0a3119c94c6fae844c2298615d27", 122 | "zoneUuid": "f04caf351c014aa890126fc78193d063", 123 | "name": "nfs", 124 | "url": "192.168.0.220:/storage/nfs", 125 | "description": "Test Primary Storage", 126 | "totalCapacity": 10995116277768819, 127 | "availableCapacity": 10995162768, 128 | "type": "NFS", 129 | "state": "Enabled", 130 | "mountPath": "/opt/zstack/f4ac0a3119c94c6fae844c2298615d27", 131 | "createDate": "Jun 1, 2015 2:42:51 PM", 132 | "lastOpDate": "Jun 1, 2015 2:42:51 PM", 133 | "attachedClusterUuids": [ 134 | "f23e402bc53b4b5abae87273b6004016", 135 | "4a1789235a86409a9a6db83f97bc582f", 136 | "fe755538d4e845d5b82073e4f80cb90b", 137 | "1f45d6d6c02b43bfb6196dcacb5b8a25" 138 | ] 139 | } 140 | } 141 | 142 | .. _primary storage capacity: 143 | 144 | Capacity 145 | ++++++++ 146 | 147 | ZStack keeps tracking disk capacities of primary storage in order to select suitable one to create volumes. The capacities reported by 148 | different primary storage plugins may be different; for example, for those supporting over-provisioning, the capacity reported may be larger 149 | than real; for those not supporting over-provisioning, the capacity reported may be equal to or smaller than real. 150 | 151 | NFS Capacity 152 | ------------ 153 | 154 | NFS doesn't support over-provisioning, so the capacity is counted by volumes' virtual sizes using below formulas:: 155 | 156 | totalCapacity = NFS's total capacity 157 | availableCapacity = totalCapacity - sum(volumes' virtual sizes) 158 | 159 | Volumes' virtual sizes will be discussed in chapter :ref:`volume `; for those impatient, a volume's virtual size is the size when a volume is 160 | fully filled; for example, when you created a volume with 1G capacity, before it's fully filled, its real size may be 10M because of 161 | thin-provisioning technology. 162 | 163 | .. _primary storage url: 164 | 165 | URL 166 | +++ 167 | 168 | A URL is a string that contains information needed by primary storage plugins for manipulating storage systems. Although it's named as URL, 169 | the certain format of the string is up to primary storage types and is not necessary to strictly follow the URL convention, to give 170 | flexibilities to plugins to encode information that may not be able to fit in the URL format. 171 | 172 | NFS URL 173 | ------- 174 | 175 | For NFS primary storage, the URL is encoded as:: 176 | 177 | ip-or-dns-name-of-nfs-server:/absolute-path-to-directory 178 | 179 | For example:: 180 | 181 | 192.168.0.220:/storage/nfs/ 182 | 183 | 184 | .. _primary storage state: 185 | 186 | State 187 | ===== 188 | 189 | Primary storage has two states: 190 | 191 | - **Enabled**: 192 | 193 | the state that allows volumes to be created 194 | 195 | - **Disabled**: 196 | 197 | the state that DOESN'T allow volumes to be created 198 | 199 | .. _primary storage status: 200 | 201 | Status 202 | ====== 203 | 204 | Like :ref:`host status `, primary storage status reflect the status of command channels amid ZStack management nodes 205 | and primary storage. Command channels are the ways ZStack management nodes communicate with storage systems that primary storage represent; 206 | depending on primary storage types, for example, it can be HTTP connections among ZStack management nodes and primary storage agents or communication 207 | methods provided by storage SDKs. 208 | 209 | There are three status: 210 | 211 | - **Connecting**: 212 | 213 | A ZStack management node is trying to establish the command channel between itself and the primary storage. No operations can be performed to the primary storage. 214 | 215 | - **Connected** 216 | 217 | The command channel has been successfully established between a ZStack management node and the primary storage. Operations can be performed to the primary storage. 218 | 219 | - **Disconnected** 220 | 221 | The command channel has lost between a ZStack management node and the primary storage. No operations can be performed to the primary storage. 222 | 223 | ZStack management nodes will try to establish command channels when booting and will periodically send 224 | ping commands to primary storage to check health of command channels during running; once a primary storage fails to respond, 225 | or a ping command times out, the command channel is considered as lost and the primary storage will be placed in Disconnected. 226 | 227 | .. note:: ZStack will keep sending ping commands when a primary storage is in status of Disconnected. Once the primary storage recovers and responds to ping commands, ZStack 228 | will reestablish the command channel and place the primary storage in status of Connected. So when a primary storage is physically removed from the cloud, please delete 229 | it from ZStack, otherwise ZStack will keep pinging it. 230 | 231 | Here is the transition diagram: 232 | 233 | .. image:: primary-storage-status.png 234 | :align: center 235 | 236 | State and Status 237 | ================ 238 | 239 | There is no direct relations between states and status. States represent admin's decisions to primary storage, 240 | while status represent communication conditions of primary storage. 241 | 242 | .. _primary storage attached cluster: 243 | 244 | Attaching Cluster 245 | ================= 246 | 247 | Attaching clusters is to associate primary storage to sibling clusters, which provides a flexible way that manifests relations between hosts and storage systems in a real datacenter. 248 | Let's see a concreted example; assuming you have a cluster (cluster A) attached to a NFS primary storage (NFS1), like below diagram: 249 | 250 | .. image:: primary-storage-cluster1.png 251 | :align: center 252 | 253 | Some time later, the cluster A is running out of memory but the primary storage still have plenty of disk spaces, 254 | so you decide to add another cluster (cluster B) which will also use NFS1; then you can create cluster B and attach NFS1 to it. 255 | 256 | .. image:: primary-storage-cluster2.png 257 | :align: center 258 | 259 | After running a while, the hardware of cluster A is getting outdated and you decide to retire them; you add a new powerful cluster (cluster C) attached to NFS1 260 | and place all hosts in cluster A into maintenance mode, so all VMs running in cluster A are migrated to cluster B or cluster C; lastly, you detach NFS1 from 261 | cluster A and delete it. Now the datacenter looks like: 262 | 263 | .. image:: primary-storage-cluster3.png 264 | :align: center 265 | 266 | Finally, NFS1 starts running out of capacity, you add one more primary storage (NFS2), and attach it to both cluster B and cluster C. 267 | 268 | .. image:: primary-storage-cluster4.png 269 | :align: center 270 | 271 | ---------- 272 | Operations 273 | ---------- 274 | 275 | Add Primary Storage 276 | =================== 277 | 278 | The commands adding a primary storage varies for different types of primary storage. 279 | 280 | Add NFS Primary Storage 281 | +++++++++++++++++++++++ 282 | 283 | Admins can use AddNfsPrimaryStorage to add a NFS primary storage. For example:: 284 | 285 | AddNfsPrimaryStorage name=nfs1 zoneUuid=1b830f5bd1cb469b821b4b77babfdd6f url=192.168.0.220:/storage/nfs 286 | 287 | Properties 288 | ---------- 289 | 290 | .. list-table:: 291 | :widths: 20 40 10 20 10 292 | :header-rows: 1 293 | 294 | * - Name 295 | - Description 296 | - Optional 297 | - Choices 298 | - Since 299 | * - **name** 300 | - resource name, see :ref:`resource properties` 301 | - 302 | - 303 | - 0.6 304 | * - **resourceUuid** 305 | - resource uuid, see :ref:`create resource` 306 | - true 307 | - 308 | - 0.6 309 | * - **description** 310 | - resource description, see :ref:`resource properties` 311 | - true 312 | - 313 | - 0.6 314 | * - **zoneUuid** 315 | - uuid of parent zone, see :ref:`zone ` 316 | - 317 | - 318 | - 0.6 319 | * - **url** 320 | - see :ref:`url ` 321 | - 322 | - 323 | - 0.6 324 | 325 | Delete Primary Storage 326 | ====================== 327 | 328 | Admins can use DeletePrimaryStorage to delete a primary storage. For example:: 329 | 330 | DeletePrimaryStorage uuid=2c830f5bd1cb469b821b4b77babfdd6f 331 | 332 | .. danger:: Deleting a primary storage will delete all volumes and volume snapshots it contains. VMs will be deleted as results of 333 | deleting root volumes. There is no way to recover a deleted primary storage. Clusters attached will be detached. 334 | 335 | Properties 336 | ++++++++++ 337 | 338 | .. list-table:: 339 | :widths: 20 40 10 20 10 340 | :header-rows: 1 341 | 342 | * - Name 343 | - Description 344 | - Optional 345 | - Choices 346 | - Since 347 | * - **deleteMode** 348 | - see :ref:`delete resource` 349 | - true 350 | - - Permissive 351 | - Enforcing 352 | - 0.6 353 | * - **uuid** 354 | - primary storage uuid 355 | - 356 | - 357 | - 0.6 358 | 359 | Change Primary Storage State 360 | ============================ 361 | 362 | Admins can use ChangePrimaryStorageState to change the state of a primary storage. For example:: 363 | 364 | ChangePrimaryStorageState stateEvent=enable uuid=2c830f5bd1cb469b821b4b77babfdd6f 365 | 366 | Properties 367 | ++++++++++ 368 | 369 | .. list-table:: 370 | :widths: 20 40 10 20 10 371 | :header-rows: 1 372 | 373 | * - Name 374 | - Description 375 | - Optional 376 | - Choices 377 | - Since 378 | * - **uuid** 379 | - primary storage uuid 380 | - 381 | - 382 | - 0.6 383 | * - **stateEvent** 384 | - state trigger event 385 | 386 | - enable: change state to Enabled 387 | - disable: change state to Disabled 388 | - 389 | - - enable 390 | - disable 391 | - 0.6 392 | 393 | Attach Cluster 394 | ============== 395 | 396 | See :ref:`attach primary storage to cluster`. 397 | 398 | 399 | Detach Cluster 400 | ============== 401 | 402 | See :ref:`detach primary storage from cluster`. 403 | 404 | Query Primary Storage 405 | ===================== 406 | 407 | Admins can use QueryPrimaryStorage to query primary storage. For example:: 408 | 409 | QueryPrimaryStorage totalCapacity<100000000000 410 | 411 | :: 412 | 413 | QueryPrimaryStorage volumeSnapshot.uuid?=13238c8e0591444e9160df4d3636be82,33107835aee84c449ac04c9622892dec 414 | 415 | Primitive Fields of Query 416 | +++++++++++++++++++++++++ 417 | 418 | see :ref:`primary storage inventory ` 419 | 420 | Nested And Expanded Fields of Query 421 | +++++++++++++++++++++++++++++++++++ 422 | 423 | .. list-table:: 424 | :widths: 20 30 40 10 425 | :header-rows: 1 426 | 427 | * - Field 428 | - Inventory 429 | - Description 430 | - Since 431 | * - **zone** 432 | - :ref:`zone inventory ` 433 | - parent zone 434 | - 0.6 435 | * - **volume** 436 | - :ref:`volume inventory ` 437 | - volumes on this primary storage 438 | - 0.6 439 | * - **volumeSnapshot** 440 | - :ref:`volume snapshot inventory ` 441 | - volume snapshots on this primary storage 442 | - 0.6 443 | * - **cluster** 444 | - :ref:`cluster inventory ` 445 | - clusters the primary storage is attached to 446 | - 0.6 447 | 448 | --------------------- 449 | Global Configurations 450 | --------------------- 451 | 452 | .. _mount.base: 453 | 454 | mount.base 455 | ========== 456 | 457 | .. list-table:: 458 | :widths: 20 30 20 30 459 | :header-rows: 1 460 | 461 | * - Name 462 | - Category 463 | - Default Value 464 | - Choices 465 | * - **mount.base** 466 | - nfsPrimaryStorage 467 | - /opt/zstack/nfsprimarystorage 468 | - absolute path that starts with '/' 469 | 470 | The mount point that NFS primary storage is mounted on the KVM hosts. 471 | 472 | .. note:: Changing this value only affect new NFS primary storage 473 | 474 | ---- 475 | Tags 476 | ---- 477 | 478 | Users can create user tags on a primary storage with resourceType=PrimaryStorageVO. For example:: 479 | 480 | CreateUserTag resourceType=PrimaryStorage tag=SSD resourceUuid=e084dc809fec4092ab0eff797d9529d5 481 | 482 | System Tags 483 | =========== 484 | 485 | Storage Volume Snapshot 486 | +++++++++++++++++++++++ 487 | 488 | .. list-table:: 489 | :widths: 20 30 40 10 490 | :header-rows: 1 491 | 492 | * - Tag 493 | - Description 494 | - Example 495 | - Since 496 | * - **capability:snapshot** 497 | - if present, the primary storage supports storage volume snapshot 498 | - capability:snapshot 499 | - 0.6 500 | 501 | 502 | -------------------------------------------------------------------------------- /userManual/query.rst: -------------------------------------------------------------------------------- 1 | .. _query: 2 | 3 | ===== 4 | Query 5 | ===== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | A main challenge for users operating large clouds is to find wanted resources accurately and quickly. For example, to find a 15 | VM which has an EIP (17.12.53.8) out of 100,000 VMs. ZStack provides comprehensive APIs that can query every field of every 16 | resource. See `The Query API `_ for the architecture design. 17 | 18 | ------------ 19 | Architecture 20 | ------------ 21 | 22 | Every ZStack resource groups its properties as an inventory in JSON format; for example, a zone inventory:: 23 | 24 | { 25 | "uuid": "b729da71b1c7412781d5de22229d5e17", 26 | "name": "TestZone", 27 | "description": "Test", 28 | "state": "Enabled", 29 | "type": "zstack", 30 | "createDate": "Jun 1, 2015 6:04:52 PM", 31 | "lastOpDate": "Jun 1, 2015 6:04:52 PM" 32 | } 33 | 34 | a resource inventory can include inventories of other resources; for example, a L3 network inventory contains IP range inventories:: 35 | 36 | { 37 | "createDate": "Nov 10, 2015 7:52:57 PM", 38 | "dns": [ 39 | "8.8.8.8" 40 | ], 41 | "ipRanges": [ 42 | { 43 | "createDate": "Nov 10, 2015 7:52:58 PM", 44 | "endIp": "192.168.0.190", 45 | "gateway": "192.168.0.1", 46 | "l3NetworkUuid": "95dede673ddf41119cbd04bcb5d73660", 47 | "lastOpDate": "Nov 10, 2015 7:52:58 PM", 48 | "name": "ipr-mmbj", 49 | "netmask": "255.255.255.0", 50 | "startIp": "192.168.0.180", 51 | "uuid": "13238c8e0591444e9160df4d3636be82" 52 | } 53 | ], 54 | "l2NetworkUuid": "33107835aee84c449ac04c9622892dec", 55 | "lastOpDate": "Nov 10, 2015 7:52:57 PM", 56 | "name": "L3-SYSTEM-PUBLIC", 57 | "networkServices": [], 58 | "state": "Enabled", 59 | "system": true, 60 | "type": "L3BasicNetwork", 61 | "uuid": "95dede673ddf41119cbd04bcb5d73660", 62 | "zoneUuid": "3a3ed8916c5c4d93ae46f8363f080284" 63 | } 64 | 65 | there are two types of inventory fields: primitive field and nested field; a field is of primitive types of number, string, boolean and date; 66 | in above example, uuid, name, system are primitive fields; a nested field is of composite types which usually represent inventories of other resources; 67 | in above example, ipRanges is a nested fields. 68 | 69 | .. note:: A nested field can only be queried by its sub-fields; for example, for the field *ipRanges*, you cannot do:: 70 | 71 | QueryL3Network ipRanges='[{"name":"ipr-mmbj""}]' 72 | 73 | instead, you need to query its sub-field:: 74 | 75 | QueryL3Network ipRanges.name=ipr-mmbj 76 | 77 | 78 | Every field of every inventory is queryable unless it's explicitly stated as unqueryable; 79 | for an inventory, there is a corresponding query API, for example, QueryZone, QueryHost, QueryVmInstance; the responses of 80 | query APIs always carry a list of inventories, or an empty list if no matching result is found. A query response is like:: 81 | 82 | { 83 | "inventories": [ 84 | { 85 | "availableCpuCapacity": 13504, 86 | "availableMemoryCapacity": 16824565760, 87 | "clusterUuid": "b429625fe2704a3e94d698ccc0fae4fb", 88 | "createDate": "Nov 10, 2015 6:32:43 PM", 89 | "hypervisorType": "KVM", 90 | "lastOpDate": "Nov 10, 2015 6:32:43 PM", 91 | "managementIp": "192.168.0.212", 92 | "name": "U1404-192.168.0.212", 93 | "state": "Enabled", 94 | "status": "Connected", 95 | "totalCpuCapacity": 14400, 96 | "totalMemoryCapacity": 16828235776, 97 | "uuid": "d07066c4de02404a948772e131139eb4", 98 | "zoneUuid": "3a3ed8916c5c4d93ae46f8363f080284" 99 | } 100 | ], 101 | "success": true 102 | } 103 | 104 | A query API consists of a list of query conditions and several helper parameters: 105 | 106 | Query API Parameters 107 | ==================== 108 | 109 | .. list-table:: 110 | :widths: 20 40 10 20 10 111 | :header-rows: 1 112 | 113 | * - Name 114 | - Description 115 | - Optional 116 | - Choices 117 | - Since 118 | * - **conditions** 119 | - a list of :ref:`QueryCondition ` 120 | - 121 | - 122 | - 0.6 123 | * - **limit** 124 | - the maximum number of inventories returned by the query API; default to 1000 125 | - true 126 | - 127 | - 0.6 128 | * - **start** 129 | - the first inventory to return; default to 0 130 | - true 131 | - 132 | - 0.6 133 | * - **count** 134 | - if true, the query response will return only count of inventories; default to false 135 | - 136 | - - true 137 | - false 138 | - 0.6 139 | * - **replyWithCount** 140 | - if true, the query response will return both inventories and count; default to false 141 | - 142 | - - true 143 | - false 144 | - 0.6 145 | * - **sortBy** 146 | - the field by which the result inventories will be sorted. The field must be a primitive field 147 | - true 148 | - 149 | - 0.6 150 | * - **sortDirection** 151 | - if 'sortBy' is not null, this field specifies the sorting direction; default to 'asc' 152 | - 153 | - - asc 154 | - desc 155 | - 0.6 156 | * - **fields** 157 | - a list of primitive fields; when specified, the result inventory will contain only those fields. 158 | - true 159 | - 160 | - 0.6 161 | 162 | .. _QueryCondition: 163 | 164 | Query Condition 165 | =============== 166 | 167 | Query APIs receive a list of query conditions which have properties as following: 168 | 169 | .. list-table:: 170 | :widths: 20 40 10 20 10 171 | :header-rows: 1 172 | 173 | * - Name 174 | - Description 175 | - Optional 176 | - Choices 177 | - Since 178 | * - **name** 179 | - field name 180 | - 181 | - 182 | - 0.6 183 | * - **op** 184 | - comparison operator 185 | - 186 | - - = 187 | - != 188 | - > 189 | - >= 190 | - < 191 | - <= 192 | - in 193 | - not in 194 | - is null 195 | - is not null 196 | - like 197 | - not like 198 | - 0.6 199 | * - **value** 200 | - query value 201 | - 202 | - 203 | - 0.6 204 | 205 | a field name can be of a primitive field, or of a sub-field of a nested field, or of a sub-field of an expanded field(see :ref:`Join `); 206 | 'op' are comparison operators which are from SQL language. 207 | 208 | .. note:: for CLI tool, some operators have different forms from SQL, listed in column 'CLI Form' 209 | 210 | .. list-table:: 211 | :widths: 10 10 80 212 | :header-rows: 1 213 | 214 | * - Op 215 | - CLI Form 216 | - Description 217 | * - = 218 | - = 219 | - equal operator; case insensitive for string comparison 220 | * - != 221 | - != 222 | - not equal operator; case insensitive for string comparison 223 | * - > 224 | - > 225 | - greater than operator; check MySQL specification for string comparison 226 | * - >= 227 | - >= 228 | - greater than or equal operator; check MySQL specification for string comparison 229 | * - < 230 | - < 231 | - less than; check MySQL specification for string comparison 232 | * - <= 233 | - <= 234 | - less than or equal operator; check MySQL specification for string comparison 235 | * - in 236 | - ?= 237 | - check whether a value is within a set of values 238 | * - not in 239 | - !?= 240 | - check whether a value is NOT within a set of values 241 | * - is null 242 | - =null 243 | - NULL value test 244 | * - is not null 245 | - !=null 246 | - NOT NULL value test 247 | * - like 248 | - ~= 249 | - simple pattern matching. Use % to match any number of characters, even zero characters; use _ to matches exactly one character 250 | * - not like 251 | - !~= 252 | - negation of simple pattern matching. Use % to match any number of characters, even zero characters; use _ to matches exactly one character 253 | 254 | The relation among conditions is logical AND, it's the only relation supported in this ZStack version. For example:: 255 | 256 | QueryL3Network ipRanges.name=range1 name=L3Network1 257 | 258 | is to find L3 networks whose names are 'L3Network1' AND which have one or more IP ranges with names 'range1'. 259 | 260 | CLI Query Conditions 261 | ==================== 262 | 263 | There are two ways to write conditions in CLI, one is the original form of query API:: 264 | 265 | QueryHost conditions='[{"name":"name", "op":"=", "value":"KVM1"}]' 266 | 267 | another is CLI form:: 268 | 269 | QueryHost name=KVM1 270 | 271 | I am sure you will prefer the CLI form as it's more intuitive and human readable. The CLI form always expresses query conditions in formula of:: 272 | 273 | condition_name(no_space)CLI_comparison_operator(no_space)condition_value 274 | 275 | .. warning:: please note there is no space between condition_name and CLI_comparison_operator and condition_value:: 276 | 277 | name=KVM1 278 | 279 | is valid but:: 280 | 281 | name = KVM1 282 | 283 | is INVALID. See :ref:`CLI ` for more details. 284 | 285 | When typing in CLI, you can use *Tab* key for auto-completion and reminding you about queryable fields including primitive fields, 286 | nested fields, and expanded fields: 287 | 288 | .. image:: query1.png 289 | :align: center 290 | 291 | .. _query join: 292 | 293 | Join(Expanded Query) 294 | ==================== 295 | 296 | Join is called expanded query in ZStack; it allows users to query a resource by fields that are neither primitive nor nested but 297 | other resources' fields that have relation to this resource; those fields are called expanded fields in ZStack's terms. 298 | 299 | For example, to find the parent L3 network of a VM nic having an EIP with VIP 17.16.0.53:: 300 | 301 | QueryL3Network vmNic.eip.vipIp=17.16.0.53 302 | 303 | here L3 network inventory has no field called 'vmNic.eip.vipIp'; however, it has a relation to VM nic inventory that has a relation to EIP inventory; so we can 304 | construct an expanded query that spans to three inventories: L3 network inventory, VM nic inventory, and EIP inventory. Thanks for this nuclear weapon, ZStack 305 | has around four millions query conditions and countless combinations of conditions. Let's see a more complex and artificial example:: 306 | 307 | QueryVolumeSnapshot volume.vmInstance.vmNics.l3Network.l2Network.attachedClusterUuids?=13238c8e0591444e9160df4d3636be82 308 | 309 | This complex query is to find volume snapshots created from volumes of VMs that have nics on L3 networks whose parent L2 networks are 310 | attached to a cluster of uuid equal to 13238c8e0591444e9160df4d3636be82. Though users will barely do such a query, it shows the power of the query APIs. 311 | 312 | .. note:: Check query operations in each chapter for expanded queries a resource can make, or use CLI auto-completion as a reminder. 313 | 314 | Query List 315 | ========== 316 | 317 | When a field is a list, it can contain primitive types such as int, long, string or nested inventories. Querying list has nothing special; we have this section 318 | to remind you that don't incorrectly think you can only use 'in'(?=) and 'not in'(!?=) when querying a list field; in fact, you can use all comparison operators; 319 | for example:: 320 | 321 | QueryL3Network dns~=72.72.72.% 322 | 323 | is to find all L3 networks that have DNS like 72.72.72.*:: 324 | 325 | QueryL3Network ipRanges.startIp=192.168.0.10 326 | 327 | is to find all L3 networks whose IP ranges starting with IP 192.168.0.10. 328 | 329 | .. _query with tags: 330 | 331 | Query Tags 332 | ========== 333 | 334 | In section :ref:`tags ` you will see every resource can have user tags and system tags both of which can be a part of query conditions. 335 | ZStack uses two special fields: *__userTag__* and *__systemTag__* for query; for example:: 336 | 337 | QueryVmInstance __userTag__?=web-tier-VMs 338 | 339 | :: 340 | 341 | QueryHost __systemTag__?=os::distribution::Ubuntu managementIp=192.168.0.212 342 | 343 | operators >, >=, <, <= only return resources that have tags matching specified conditions; 'is not null' returns resources that have tags; 344 | 'is null' returns resources that have no tags; !=, 'not in', 'not like' return resources that have tags not matching conditions as well as resources that have no tags. 345 | 346 | .. note:: If you want to make negative comparison operators(!=, 'not in', 'not like') not to return resources that have no tags, you can use them with 'not null'. 347 | For example:: 348 | 349 | QueryVmInstance __userTag__!=database __userTag__!=null 350 | 351 | is to find VMs that have user tags not equal to 'database'. 352 | 353 | Avoid Loop Query 354 | ================ 355 | 356 | Most ZStack resources have bi-direction expanded queries, for example, hosts have an expanded query to clusters and clusters also have an expanded 357 | query to hosts. This makes it's possible to query a resource from any directions, which may also lead to loop queries. For example:: 358 | 359 | QueryHost vmInstance.vmNics.eip.vmNic.vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2 360 | 361 | is a loop query, it does the thing equal to:: 362 | 363 | QueryHost vmInstance.uuid=d40e459b97db5a63dedaffcd05cfe3c2 364 | 365 | Behaviors of loop queries is undefined; you may or may not get the correct results. Please avoid loop query in your practice. 366 | 367 | Use Query Efficiently 368 | ===================== 369 | 370 | Query APIs are powerful that you can do the same thing by different routes. For example, to find VMs that are running on the 371 | host of UUID e497e90ab1e64db099eea93f998d525b, you can either do:: 372 | 373 | QueryVmInstance hostUuid=e497e90ab1e64db099eea93f998d525b 374 | 375 | or:: 376 | 377 | QueryVmInstance host.uuid=e497e90ab1e64db099eea93f998d525b 378 | 379 | The first one is more efficient, because it queries a primitive field which only involves the VM table; the later one is an expanded 380 | query which joins both VM table and host table. When your query condition is a UUID, it's always suggested querying the primitive field instead of the sub-field 381 | of an expanded field. 382 | 383 | 384 | -------- 385 | Examples 386 | -------- 387 | 388 | Normal Query 389 | ============ 390 | 391 | :: 392 | 393 | QueryL3Network name=L3-SYSTEM-PUBLIC 394 | 395 | Query Count 396 | =========== 397 | 398 | :: 399 | 400 | QueryL3Network name=L3-SYSTEM-PUBLIC count=true 401 | 402 | 403 | Normal Query With Count 404 | ======================= 405 | 406 | :: 407 | 408 | QueryL3Network name=L3-SYSTEM-PUBLIC replyWithCount=true 409 | 410 | 411 | Set Limit 412 | ========= 413 | 414 | :: 415 | 416 | QueryL3Network l2NetworkUuid=33107835aee84c449ac04c9622892dec limit=10 417 | 418 | Set Start 419 | ========= 420 | 421 | :: 422 | 423 | QueryL3Network l2NetworkUuid=33107835aee84c449ac04c9622892dec start=10 limit=100 424 | 425 | 426 | .. note:: Using start and limit, UI can implement pagination. 427 | 428 | 429 | Select Fields 430 | ============= 431 | 432 | :: 433 | 434 | QueryL3Network fields=name,uuid l2NetworkUuid=33107835aee84c449ac04c9622892dec 435 | 436 | 437 | .. note:: Only primitive fields can be selected. 438 | 439 | Sort 440 | ==== 441 | 442 | :: 443 | 444 | QueryL3Network l2NetworkUuid=33107835aee84c449ac04c9622892dec sortBy=createDate sortDirection=desc 445 | 446 | .. note:: Only primitive field can be used as sorted field. 447 | 448 | 449 | 450 | 451 | -------------------------------------------------------------------------------- /userManual/backupStorage.rst: -------------------------------------------------------------------------------- 1 | .. _backup storage: 2 | 3 | ============== 4 | Backup Storage 5 | ============== 6 | 7 | .. contents:: `Table of contents` 8 | :depth: 6 9 | 10 | -------- 11 | Overview 12 | -------- 13 | 14 | A backup Storage is a storage system that stores :ref:`images ` for creating volumes. Backup storage can be 15 | filesystem based storage(e.g. NFS) or object store based storage(e.g. OpenStack swift), as long as the storage is network 16 | shared storage. Besides providing templates for creating volumes, backup storage also allow users to backup entities including 17 | volumes and volume snapshots. 18 | 19 | A backup storage must be attached to a :ref:`zone ` before the zone's descendant resources can access it. 20 | Admins can take this advantage to share images across multiple zones, for example: 21 | 22 | .. image:: backupStorage1.png 23 | :align: center 24 | 25 | In the early stage of a cloud, there may be only one zone(Zone1) with a single backup storage. In pace with business development, 26 | admins may decide to create another zone(Zone2) but still use existing images for VMs; then admins can attach the backup 27 | storage to Zone2, so both Zone1 and Zone2 share the same images. 28 | 29 | .. image:: backupStorage2.png 30 | :align: center 31 | 32 | .. note:: In this ZStack version, the only supported backup storage is :ref:`SFTP backup storage ` 33 | 34 | .. _backup storage inventory: 35 | 36 | --------- 37 | Inventory 38 | --------- 39 | 40 | Properties 41 | ========== 42 | 43 | .. list-table:: 44 | :widths: 20 40 10 20 10 45 | :header-rows: 1 46 | 47 | * - Name 48 | - Description 49 | - Optional 50 | - Choices 51 | - Since 52 | * - **uuid** 53 | - see :ref:`resource properties` 54 | - 55 | - 56 | - 0.6 57 | * - **name** 58 | - see :ref:`resource properties` 59 | - 60 | - 61 | - 0.6 62 | * - **description** 63 | - see :ref:`resource properties` 64 | - true 65 | - 66 | - 0.6 67 | * - **url** 68 | - see :ref:`url ` 69 | - 70 | - 71 | - 0.6 72 | * - **totalCapacity** 73 | - total disk capacity in bytes, see :ref:`capacity ` 74 | - 75 | - 76 | - 0.6 77 | * - **availableCapacity** 78 | - available disk capacity in bytes, see :ref:`capacity ` 79 | - 80 | - 81 | - 0.6 82 | * - **type** 83 | - backup storage type 84 | - 85 | - - SftpBackupStorage 86 | - 0.6 87 | * - **state** 88 | - see :ref:`state ` 89 | - 90 | - - Enabled 91 | - Disabled 92 | - 0.6 93 | * - **status** 94 | - see :ref:`status ` 95 | - 96 | - - Connecting 97 | - Connected 98 | - Disconnected 99 | - 0.6 100 | * - **attachedZoneUuids** 101 | - a list of zone UUID the backup storage has been attached 102 | - 103 | - 104 | - 0.6 105 | * - **createDate** 106 | - see :ref:`resource properties` 107 | - 108 | - 109 | - 0.6 110 | * - **lastOpDate** 111 | - see :ref:`resource properties` 112 | - 113 | - 114 | - 0.6 115 | 116 | Example 117 | +++++++ 118 | 119 | :: 120 | 121 | { 122 | "attachedZoneUuids": [ 123 | "36de66d82f424639af67215a465418f6" 124 | ], 125 | "availableCapacity": 1258407346176, 126 | "name": "sftp", 127 | "state": "Enabled", 128 | "status": "Connected", 129 | "totalCapacity": 1585341214720, 130 | "type": "SftpBackupStorage", 131 | "url": "/export/backupStorage/sftp", 132 | "uuid": "33a35f75885f45ab96ea2626ce9c05a6", 133 | "lastOpDate": "Jun 1, 2015 3:42:26 PM", 134 | "createDate": "Jun 1, 2015 3:42:26 PM" 135 | } 136 | 137 | .. _backup storage url: 138 | 139 | URL 140 | +++ 141 | 142 | URL is a string that contains information needed by backup storage plugins for manipulating storage systems. Although it's named as 143 | URL, the certain format of the string is up to backup storage types and is not necessary to strictly follow the URL convention, to give 144 | flexibilities to plugins to encode information that may not be able to fit in the URL format. 145 | 146 | .. _sftp backup storage url: 147 | 148 | SFTP Backup Storage URL 149 | ----------------------- 150 | 151 | For SFTP backup storage, the URL is the absolute path of a directory in the filesystem. For example, /storage/sftp. 152 | 153 | .. _backup storage capacity: 154 | 155 | Capacity 156 | ++++++++ 157 | 158 | ZStack keeps tracking disk capacities of backup storage in order to select suitable one when allocating space for storing images. 159 | The capacity is calculated by below formulas:: 160 | 161 | totalCapacity = backup storage's total capacity 162 | availableCapacity = totalCapacity - sum(images' real sizes) 163 | 164 | .. _backup storage state: 165 | 166 | State 167 | +++++ 168 | 169 | Backup storage have two states: 170 | 171 | - **Enabled**: 172 | 173 | The state that allows images to be registered, backup, and downloaded 174 | 175 | - **Disabled**: 176 | 177 | The state that DOESN'T allow images to be registered, backup, and downloaded. Especially, if an image is only stored on 178 | a disabled backup storage, and if that image is not downloaded to image caches of primary storage yet, no VMs can be 179 | created from that image. 180 | 181 | .. _backup storage status: 182 | 183 | Status 184 | ++++++ 185 | 186 | Status reflects the status of command channels amid ZStack management nodes and backup storage. 187 | 188 | - **Connecting**: 189 | 190 | A ZStack management node is trying to establish the command channel between itself and a backup storage. No operations can be performed to the backup storage. 191 | 192 | - **Connected** 193 | 194 | The command channel has been successfully established between a ZStack management node and a backup storage. Operations can be performed to the backup storage. 195 | 196 | - **Disconnected** 197 | 198 | The command channel has lost between a ZStack management node and a backup storage. No operations can be performed to the backup storage. 199 | 200 | ZStack management nodes will try to setup command channels every time when they boot, and will periodically send 201 | ping commands to backup storage to check the health of command channels. Once a backup storage fails to respond, 202 | or a ping command times out, the command channel is considered as lost and the backup storage will be placed in 203 | the status of Disconnected. 204 | 205 | .. warning:::: ZStack will keep sending ping commands when a backup storage is in the status of Disconnected. Once the backup storage recovers and responds to ping commands, ZStack 206 | will reestablish the command channel and place the backup storage in the status of Connected. So when a backup storage is physically removed from a cloud, please delete 207 | it from ZStack, otherwise ZStack will keep pinging it. 208 | 209 | Here is the transition diagram: 210 | 211 | .. image:: backup-storage-status.png 212 | :align: center 213 | 214 | .. _sftp backup storage: 215 | 216 | ------------------- 217 | SFTP Backup Storage 218 | ------------------- 219 | 220 | SFTP backup storage is a Linux server that stores images in native filesystem and uses OpenSSH server/client to transfer images. 221 | ZStack uses a python agent (SftpBackupStorageAgent) to manage the Linux server; images are uploaded/downloaded to/from the server 222 | by `SCP `_. Besides properties in :ref:`backup storage inventory `, 223 | SFTP backup storage has an extra property: 224 | 225 | .. list-table:: 226 | :widths: 20 40 10 20 10 227 | :header-rows: 1 228 | 229 | * - Name 230 | - Description 231 | - Optional 232 | - Choices 233 | - Since 234 | * - **hostname** 235 | - the IP address or DNS name of the SFTP backup storage 236 | - 237 | - 238 | - 0.6 239 | 240 | Example 241 | ======= 242 | 243 | :: 244 | 245 | { 246 | "attachedZoneUuids": [ 247 | "36de66d82f424639af67215a465418f6" 248 | ], 249 | "availableCapacity": 1258407346176, 250 | "hostname": "172.16.0.220", 251 | "name": "sftp", 252 | "state": "Enabled", 253 | "status": "Connected", 254 | "totalCapacity": 1585341214720, 255 | "type": "SftpBackupStorage", 256 | "url": "/export/backupStorage/sftp", 257 | "uuid": "33a35f75885f45ab96ea2626ce9c05a6", 258 | "lastOpDate": "Jun 1, 2015 3:42:26 PM", 259 | "createDate": "Jun 1, 2015 3:42:26 PM" 260 | } 261 | 262 | ---------- 263 | Operations 264 | ---------- 265 | 266 | Add Backup Storage 267 | ================== 268 | 269 | The commands to add a backup storage vary for different backup storage types. 270 | 271 | Add SFTP Backup Storage 272 | +++++++++++++++++++++++ 273 | 274 | Admins can use AddSftpBackupStorage to add a new backup storage. For example:: 275 | 276 | AddSftpBackupStorage name=sftp1 url=/storage/sftp1 hostname=192.168.0.220 username=root password=password 277 | 278 | Parameters 279 | ---------- 280 | 281 | .. list-table:: 282 | :widths: 20 40 10 20 10 283 | :header-rows: 1 284 | 285 | * - Name 286 | - Description 287 | - Optional 288 | - Choices 289 | - Since 290 | * - **name** 291 | - resource name, see :ref:`resource properties` 292 | - 293 | - 294 | - 0.6 295 | * - **resourceUuid** 296 | - resource uuid, see :ref:`create resource` 297 | - true 298 | - 299 | - 0.6 300 | * - **description** 301 | - resource description, see :ref:`resource properties` 302 | - true 303 | - 304 | - 0.6 305 | * - **url** 306 | - see :ref:`url ` 307 | - 308 | - 309 | - 0.6 310 | * - **hostname** 311 | - the IP address or DNS name of the SFTP backup storage 312 | - 313 | - 314 | - 0.6 315 | * - **username** 316 | - the user **root** 317 | - 318 | - root 319 | - 0.6 320 | * - **password** 321 | - the SSH password for user **root** 322 | - 323 | - 324 | - 0.6 325 | 326 | Delete Backup Storage 327 | ===================== 328 | 329 | Admins can use DeleteBackupStorage to delete a backup storage. For example:: 330 | 331 | DeleteBackupStorage uuid=1613b627cb2e4ffcb30e7e59935064be 332 | 333 | .. warning:: When deleting, a backup storage will be detached from attached zones. Copies of images and of volume snapshots 334 | on the backup storage will be deleted; if a copy is the only copy of an image or a volume snapshot, the image 335 | or the volume snapshot will be deleted as well. There is no way to recover a deleted backup storage. 336 | 337 | Parameters 338 | ++++++++++ 339 | 340 | .. list-table:: 341 | :widths: 20 40 10 20 10 342 | :header-rows: 1 343 | 344 | * - Name 345 | - Description 346 | - Optional 347 | - Choices 348 | - Since 349 | * - **uuid** 350 | - backup storage uuid 351 | - 352 | - 353 | - 0.6 354 | * - **deleteMode** 355 | - see :ref:`delete resource` 356 | - true 357 | - - Permissive 358 | - Enforcing 359 | - 0.6 360 | 361 | 362 | Change State 363 | ============ 364 | 365 | Admins can use ChangeBackupStorageState to change the state of a backup storage. For example:: 366 | 367 | ChangeBackupStorageState uuid=33a35f75885f45ab96ea2626ce9c05a6 stateEvent=enable 368 | 369 | Parameters 370 | ++++++++++ 371 | 372 | .. list-table:: 373 | :widths: 20 40 10 20 10 374 | :header-rows: 1 375 | 376 | * - Name 377 | - Description 378 | - Optional 379 | - Choices 380 | - Since 381 | * - **uuid** 382 | - backup storage uuid 383 | - 384 | - 385 | - 0.6 386 | * - **stateEvent** 387 | - state trigger event 388 | 389 | - enable: change the state to Enabled 390 | - disable: change the state to Disabled 391 | - 392 | - - enable 393 | - disable 394 | - 0.6 395 | 396 | .. _attach backup storage to zone: 397 | 398 | Attach Zone 399 | =========== 400 | 401 | Admins can use AttachBackupStorageToZone to attach a backup storage to a zone. For example:: 402 | 403 | AttachBackupStorageToZone backupStorageUuid=d086c30f33914c98a6078269bab7bc8f zoneUuid=d086c30f33914c98a6078269bab7bc8f 404 | 405 | Parameters 406 | ++++++++++ 407 | 408 | .. list-table:: 409 | :widths: 20 40 10 20 10 410 | :header-rows: 1 411 | 412 | * - Name 413 | - Description 414 | - Optional 415 | - Choices 416 | - Since 417 | * - **backupStorageUuid** 418 | - the backup storage uuid 419 | - 420 | - 421 | - 0.6 422 | * - **zoneUuid** 423 | - the zone uuid 424 | - 425 | - 426 | - 0.6 427 | 428 | .. _detach backup storage from zone: 429 | 430 | Detach Zone 431 | =========== 432 | 433 | Admins can use DetachBackupStorageFromZone to detach a backup storage from a zone. For example:: 434 | 435 | DetachBackupStorageFromZone backupStorageUuid=d086c30f33914c98a6078269bab7bc8f zoneUuid=d086c30f33914c98a6078269bab7bc8f 436 | 437 | Parameters 438 | ++++++++++ 439 | 440 | .. list-table:: 441 | :widths: 20 40 10 20 10 442 | :header-rows: 1 443 | 444 | * - Name 445 | - Description 446 | - Optional 447 | - Choices 448 | - Since 449 | * - **backupStorageUuid** 450 | - the backup storage uuid 451 | - 452 | - 453 | - 0.6 454 | * - **zoneUuid** 455 | - the zone uuid 456 | - 457 | - 458 | - 0.6 459 | 460 | Query Backup Storage 461 | ==================== 462 | 463 | Admins can use QueryBackupStorage to query backup storage. For example:: 464 | 465 | QueryBackupStorage state=Enabled 466 | 467 | :: 468 | 469 | QueryBackupStorage image.platform=Linux 470 | 471 | 472 | Primitive Fields of Query 473 | +++++++++++++++++++++++++ 474 | 475 | see :ref:`backup storage inventory ` 476 | 477 | 478 | .. _backup storage nested fields: 479 | 480 | Nested And Expanded Fields of Query 481 | +++++++++++++++++++++++++++++++++++ 482 | 483 | .. list-table:: 484 | :widths: 20 30 40 10 485 | :header-rows: 1 486 | 487 | * - Field 488 | - Inventory 489 | - Description 490 | - Since 491 | * - **zone** 492 | - :ref:`zone inventory ` 493 | - zones this backup storage is attached to 494 | - 0.6 495 | * - **image** 496 | - :ref:`image inventory ` 497 | - images this backup storage contains 498 | - 0.6 499 | * - **volumeSnapshot** 500 | - :ref:`volume snapshot inventory ` 501 | - volume snapshots this backup storage contains 502 | - 0.6 503 | 504 | Query SFTP Backup Storage 505 | ========================= 506 | 507 | Admins can use QuerySftpBackupStorage to query SFTP backup storage:: 508 | 509 | QuerySftpBackupStorage name=sftp 510 | 511 | Primitive Fields of Query 512 | +++++++++++++++++++++++++ 513 | 514 | see :ref:`SFTP backup storage inventory ` 515 | 516 | Nested and Expanded Fields of Query 517 | +++++++++++++++++++++++++++++++++++ 518 | 519 | see :ref:`backup storage nested and expanded fields ` 520 | 521 | --------------------- 522 | Global Configurations 523 | --------------------- 524 | 525 | .. _ping.interval: 526 | 527 | ping.interval 528 | ============= 529 | 530 | .. list-table:: 531 | :widths: 20 30 20 30 532 | :header-rows: 1 533 | 534 | * - Name 535 | - Category 536 | - Default Value 537 | - Choices 538 | * - **ping.interval** 539 | - backupStorage 540 | - 60 541 | - > 0 542 | 543 | The interval that management nodes send ping commands to backup storage, in seconds. 544 | 545 | .. _ping.parallelismDegree: 546 | 547 | ping.parallelismDegree 548 | ====================== 549 | 550 | .. list-table:: 551 | :widths: 20 30 20 30 552 | :header-rows: 1 553 | 554 | * - Name 555 | - Category 556 | - Default Value 557 | - Choices 558 | * - **ping.parallelismDegree** 559 | - backupStorage 560 | - 50 561 | - > 0 562 | 563 | The max number of backup storage that management nodes will ping in parallel. 564 | 565 | ---- 566 | Tags 567 | ---- 568 | 569 | Admins can create user tags on a backup storage with resourceType=BackupStorageVO. For example:: 570 | 571 | CreateUserTag tag=lab1 resourceType=BackupStorageVO resourceUuid=2906471068802c501773d3ee55b7766e 572 | 573 | --------------------------------------------------------------------------------