diff --git a/doc/source/admin/configuration/hypervisor-zvm.rst b/doc/source/admin/configuration/hypervisor-zvm.rst new file mode 100644 index 000000000000..cc7c0d58340a --- /dev/null +++ b/doc/source/admin/configuration/hypervisor-zvm.rst @@ -0,0 +1,146 @@ +zVM +=== + +z/VM System Requirements +~~~~~~~~~~~~~~~~~~~~~~~~ + +* The appropriate APARs installed, the current list of which can be found: z/VM + OpenStack Cloud Information (http://www.vm.ibm.com/sysman/osmntlvl.html). + +.. note:: + + IBM z Systems hardware requirements are based on both the applications and + the load on the system. + +Active Engine Guide +~~~~~~~~~~~~~~~~~~~ + +Active engine is used as an initial configuration and management tool during +deployed machine startup. Currently the z/VM driver uses ``zvmguestconfigure`` +and ``cloud-init`` as a two stage active engine. + +Installation and Configuration of zvmguestconfigure +--------------------------------------------------- + +Cloudlib4zvm supports initiating changes to a Linux on z Systems virtual +machine while Linux is shut down or the virtual machine is logged off. +The changes to Linux are implemented using an activation engine (AE) +that is run when Linux is booted the next time. The first active engine, +``zvmguestconfigure``, must be installed in the Linux on z Systems virtual +server so it can process change request files transmitted by the +cloudlib4zvm service to the reader of the virtual machine as a class X file. + +.. note:: + + An additional activation engine, cloud-init, should be installed to handle + OpenStack related tailoring of the system. + The cloud-init AE relies on tailoring performed by ``zvmguestconfigure``. + +Installation and Configuration of cloud-init +-------------------------------------------- + +OpenStack uses cloud-init as its activation engine. Some Linux distributions +include cloud-init either already installed or available to be installed. +If your distribution does not include cloud-init, you can download +the code from https://launchpad.net/cloud-init/+download. +After installation, if you issue the following +shell command and no errors occur, cloud-init is installed correctly:: + + cloud-init init --local + +Installation and configuration of cloud-init differs among different Linux +distributions, and cloud-init source code may change. This section provides +general information, but you may have to tailor cloud-init +to meet the needs of your Linux distribution. You can find a +community-maintained list of dependencies at http://ibm.biz/cloudinitLoZ. + +As of the Rocky release, the z/VM OpenStack support has been tested with +cloud-init 0.7.4 and 0.7.5 for RHEL6.x and SLES11.x, 0.7.6 for RHEL7.x and +SLES12.x, and 0.7.8 for Ubuntu 16.04. + +During cloud-init installation, some dependency packages may be required. +You can use zypper and python setuptools to easily resolve these dependencies. +See https://pypi.python.org/pypi/setuptools for more information. + +Image guide +~~~~~~~~~~~ + +This guideline will describe the requirements and steps to create and +configure images for use with z/VM. + +Image Requirements +------------------ + +* The following Linux distributions are supported for deploy: + + * RHEL 6.2, 6.3, 6.4, 6.5, 6.6, and 6.7 + * RHEL 7.0, 7.1 and 7.2 + * SLES 11.2, 11.3, and 11.4 + * SLES 12 and SLES 12.1 + * Ubuntu 16.04 + +* A supported root disk type for snapshot/spawn. The following are supported: + + * FBA + * ECKD + +* An image deployed on a compute node must match the disk type supported by + that compute node, as configured by the ``zvm_diskpool_type`` property in + the `zvmsdk.conf`_ configuration file in `zvm cloud connector`_ + A compute node supports deployment on either an ECKD or FBA image, + but not both at the same time. If you wish to switch image types, + you need to change the ``zvm_diskpool_type`` and + ``zvm_diskpool`` properties in the `zvmsdk.conf`_ file, accordingly. + Then restart the nova-compute service to make the changes take effect. + +* If you deploy an instance with an ephemeral disk, both the root disk and the + ephemeral disk will be created with the disk type that was specified by + ``zvm_diskpool_type`` property in the `zvmsdk.conf`_ file. That property can + specify either ECKD or FBA. + +* The network interfaces must be IPv4 interfaces. + +* Image names should be restricted to the UTF-8 subset, which corresponds to + the ASCII character set. In addition, special characters such as ``/``, ``\``, + ``$``, ``%``, ``@`` should not be used. For the FBA disk type "vm", + capture and deploy is supported only for an FBA disk with a single partition. + Capture and deploy is not supported for the FBA disk type "vm" on a CMS + formatted FBA disk. + +* The virtual server/Linux instance used as the source of the new image should + meet the following criteria: + + 1. The root filesystem must not be on a logical volume. + + 2. The minidisk on which the root filesystem resides should be a minidisk of + the same type as desired for a subsequent deploy (for example, an ECKD disk + image should be captured for a subsequent deploy to an ECKD disk). + + 3. The minidisks should not be a full-pack minidisk, since cylinder 0 on + full-pack minidisks is reserved, and should be defined with virtual + address 0100. + + 4. The root disk should have a single partition. + + 5. The image being captured should not have any network interface cards (NICs) + defined below virtual address 1100. + +In addition to the specified criteria, the following recommendations allow for +efficient use of the image: + +* The minidisk on which the root filesystem resides should be defined as a + multiple of full gigabytes in size (for example, 1GB or 2GB). + OpenStack specifies disk sizes in full gigabyte values, whereas z/VM + handles disk sizes in other ways (cylinders for ECKD disks, blocks for FBA + disks, and so on). See the appropriate online information if you need to + convert cylinders or blocks to gigabytes; for example: + http://www.mvsforums.com/helpboards/viewtopic.php?t=8316. + +* During subsequent deploys of the image, the OpenStack code will ensure that + a disk image is not copied to a disk smaller than the source disk, + as this would result in loss of data. The disk specified in + the flavor should therefore be equal to or slightly larger than the source + virtual machine's root disk. + +.. _zvmsdk.conf: https://cloudlib4zvm.readthedocs.io/en/latest/configuration.html#configuration-options +.. _zvm cloud connector: https://cloudlib4zvm.readthedocs.io/en/latest/ diff --git a/doc/source/admin/configuration/hypervisors.rst b/doc/source/admin/configuration/hypervisors.rst index 88ed368aa906..60db25f53917 100644 --- a/doc/source/admin/configuration/hypervisors.rst +++ b/doc/source/admin/configuration/hypervisors.rst @@ -15,6 +15,7 @@ Hypervisors hypervisor-hyper-v.rst hypervisor-virtuozzo.rst hypervisor-powervm.rst + hypervisor-zvm.rst OpenStack Compute supports many hypervisors, which might make it difficult for you to choose one. Most installations use only one hypervisor. However, you @@ -57,6 +58,9 @@ The following hypervisors are supported: * `PowerVM`_ Server virtualization with IBM PowerVM for AIX, IBM i, and Linux workloads on the Power Systems platform. +* `zVM`_ Server virtualization on z Systems and IBM LinuxONE, it can run Linux, + z/OS and more. + .. _KVM: http://www.linux-kvm.org/page/Main_Page .. _LXC: https://linuxcontainers.org/ .. _QEMU: http://wiki.qemu.org/Manual @@ -66,3 +70,4 @@ The following hypervisors are supported: .. _Hyper-V: https://azure.microsoft.com/en-us/ .. _Virtuozzo: https://www.virtuozzo.com/products/vip.html#product-virtuozzo/ .. _PowerVM: https://www.ibm.com/us-en/marketplace/ibm-powervm +.. _zVM: https://www.ibm.com/it-infrastructure/z/zvm