From cf932be1309c1f076584c413ad36fe9b3f66a8e6 Mon Sep 17 00:00:00 2001 From: Andreas Maier Date: Tue, 31 Jan 2017 19:28:36 +0100 Subject: [PATCH] Overhauled the documentation This change is supposed to improve the documentation that currently exists, without adding much new content. Details: * Reorganized the main page into a common overview section, a section for users of the driver, and a section for contributors, and a section with links for quick access. * Separated between the `README.rst` file and the introductory text on the main page, because the `README.rst` file stands on its own when shown on the Github code page, while the introductory text is part of the larger documentation. As a result, removed the `doc/source/readme.rst` file. * Added an empty chapter for the topology to the overview section of the main page, instead of referencing the readme file. * Cleaned up headings and file names somewhat. * Added link targets to any major headings. * Adapted the contributions page to the project, and added links for the Git repo and the Gerrit review page. Change-Id: Id7a9a632984ad8945ca1dd347a7766601030a373 Partial-Bug: 1660689 Signed-off-by: Andreas Maier --- CONTRIBUTING.rst | 19 ------ README.rst | 54 +++++++++-------- doc/source/configuration.rst | 17 ++++++ doc/source/contributing.rst | 28 ++++++++- doc/source/devref.rst | 4 +- doc/source/index.rst | 101 ++++++++++++++++--------------- doc/source/installation.rst | 33 ++++++++-- doc/source/readme.rst | 1 - doc/source/sample_config.rst | 12 ---- doc/source/specs/ocata/index.rst | 12 ++-- doc/source/support-matrix.rst | 2 + doc/source/topology.rst | 7 +++ doc/source/usage.rst | 7 --- 13 files changed, 172 insertions(+), 125 deletions(-) delete mode 100644 CONTRIBUTING.rst create mode 100644 doc/source/configuration.rst delete mode 100644 doc/source/readme.rst delete mode 100644 doc/source/sample_config.rst create mode 100644 doc/source/topology.rst delete mode 100644 doc/source/usage.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 9ad9ebd..0000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,19 +0,0 @@ -Contributing to Nova-DPM -============================ -If you would like to contribute to the development of OpenStack, -you must follow the steps in the "If you're a developer, start here" -section of this page: - - http://wiki.openstack.org/HowToContribute - -Once those steps have been completed, changes to OpenStack -should be submitted for review via the Gerrit tool, following -the workflow documented at: - - http://wiki.openstack.org/GerritWorkflow - -Pull requests submitted through GitHub will be ignored. - -Bugs should be filed on Launchpad, not GitHub: - - https://bugs.launchpad.net/nova-dpm diff --git a/README.rst b/README.rst index d7aba97..8dc8e20 100644 --- a/README.rst +++ b/README.rst @@ -1,33 +1,37 @@ -=============================== -nova-dpm -=============================== +========================== +openstack/nova-dpm Project +========================== -OpenStack Nova driver and agent for IBM z Systems PR/SM hypervisor in DPM mode +About this project +------------------ -On IBM z Systems, certain workloads run better in a logical partition than -in a virtual machine of a software hypervisor such as KVM or z/VM. +This project provides a Nova virtualization driver for the PR/SM hypervisor of +IBM z Systems and IBM LinuxOne machines that are in the DPM (Dynamic Partition +Manager) administrative mode. -The IBM z13 system (and IBM LinuxONE) introduced a new administrative mode -named "Dynamic Partition Manager" (DPM) that allows for managing the -firmware-based logical partition hypervisor (PR/SM) with the dynamic -capabilities known from software-based hypervisors. +The DPM mode enables dynamic capabilities of the firmware-based PR/SM +hypervisor that are usually known from software-based hypervisors, such as +creation, deletion and modification of partitions (i.e. virtual machines) and +virtual devices within these partitions, and dynamic assignment of these +virtual devices to physical I/O adapters. -These new dynamic capabilities provided by the DPM mode enables PR/SM to -act as a hypervisor managed by OpenStack using Nova. +The z/VM and KVM hypervisors on z Systems and LinuxONE machines are supported +by separate Nova virtualization drivers: -This project supports adding the PR/SM hypervisor in DPM mode as a -Nova hypervisor platform, by implementing a new Nova driver. +* KVM is supported by the standard libvirt/KVM driver in the + `openstack/nova `_ + project. -The other hypervisors on z Systems such as z/VM and KVM are already -supported by OpenStack via Nova drivers. These drivers will continue to be -supported. Adding support for PR/SM DPM allows addressing customers that -need or want to run their workloads in logical partitions, and provides the -advantage for them of using OpenStack as a uniform, standard, cloud -management platform on z Systems. +* z/VM is supported by the z/VM driver in the + `openstack/nova-zvm-virt-driver `_ + project. +Links +----- -* Free software: Apache license -* Documentation: http://nova-dpm.readthedocs.io/en/latest/ -* Source: http://git.openstack.org/cgit/openstack/nova-dpm -* Bugs: http://bugs.launchpad.net/nova-dpm - +* Documentation: ``_ +* Source: ``_ +* Github shadow: ``_ +* Bugs: ``_ +* Gerrit: ``_ +* License: Apache 2.0 license diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 0000000..e3b2795 --- /dev/null +++ b/doc/source/configuration.rst @@ -0,0 +1,17 @@ +.. _`configuration`: + +============= +Configuration +============= + +The following is a sample ``nova_dpm.conf`` configuration file for the nova-dpm +driver, for adaptation and use. + +It is auto-generated from the nova-dpm project when this documentation is +built, so if you are having issues with an option, please compare your version +of the ``nova-dpm`` Python package with the version of this documentation. + +The sample configuration can also be viewed in +`file form <_static/nova_dpm.conf.sample>`_. + +.. literalinclude:: _static/nova_dpm.conf.sample diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 1728a61..d1e2865 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,4 +1,30 @@ +.. `contributing`: + ============ Contributing ============ -.. include:: ../../CONTRIBUTING.rst + +If you would like to contribute to the development of the nova-dpm project, you +must follow the rules for OpenStack contributions described in the +"If you're a developer, start here" section of this page: + + http://wiki.openstack.org/HowToContribute + +Once those steps have been completed, changes to the nova-dpm project should be +submitted for review via the Gerrit tool, following the workflow documented at: + + http://wiki.openstack.org/GerritWorkflow + +Pull requests submitted through GitHub will be ignored. + +The Git repository for the nova-dpm project is here: + + http://git.openstack.org/cgit/openstack/nova-dpm + +Bugs against the nova-dpm project should be filed on Launchpad (not on GitHub): + + https://bugs.launchpad.net/nova-dpm + +Pending changes for the nova-dpm project can be seen on its Gerrit page: + + https://review.openstack.org/#/q/project:openstack/nova-dpm diff --git a/doc/source/devref.rst b/doc/source/devref.rst index 4ebf8aa..7a2c23d 100644 --- a/doc/source/devref.rst +++ b/doc/source/devref.rst @@ -1,3 +1,5 @@ +.. _`developer guide`: + =============== Developer Guide =============== @@ -41,4 +43,4 @@ To build the release notes:: in your local repository of this project. More information about *reno* can be found at: -http://docs.openstack.org/developer/reno/index.html \ No newline at end of file +http://docs.openstack.org/developer/reno/index.html diff --git a/doc/source/index.rst b/doc/source/index.rst index b51ff9c..0c0f0fa 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,67 +15,70 @@ under the License. Welcome to nova-dpm's documentation! -======================================== +==================================== -This project will be used for development of nova driver for supporting IBM System z PR/SM hypervisor in DPM mode as a valid nova hypervisor platform. +On IBM z Systems and IBM LinuxOne machines, certain workloads run better in a +partition of the firmware-based PR/SM (Processor Resource/System Manager) +hypervisor, than in a virtual machine of a software hypervisor such as KVM or +z/VM. -On IBM z Systems, certain workloads run better in a logical partition than -in a virtual machine of a software hypervisor such as KVM or z/VM. +This project provides a Nova virtualization driver for the PR/SM hypervisor of +IBM z Systems and IBM LinuxOne machines that are in the DPM (Dynamic Partition +Manager) administrative mode. -The IBM z13 system (and IBM LinuxONE) introduced a new administrative mode -named "Dynamic Partition Manager" (DPM) that allows for managing the -firmware-based logical partition hypervisor (PR/SM) with the dynamic -capabilities known from software-based hypervisors. +The DPM mode enables dynamic capabilities of the firmware-based PR/SM +hypervisor that are usually known from software-based hypervisors, such as +creation, deletion and modification of partitions (i.e. virtual machines) and +virtual devices within these partitions, and dynamic assignment of these +virtual devices to physical I/O adapters. -These new dynamic capabilities provided by the DPM mode enables PR/SM to -act as a hypervisor managed by OpenStack using Nova. +The z/VM and KVM hypervisors on z Systems and LinuxONE machines are supported +by separate Nova virtualization drivers: -This project supports adding the PR/SM hypervisor in DPM mode as a -Nova hypervisor platform, by implementing a new Nova driver. +* KVM is supported by the standard libvirt/KVM driver in the + `openstack/nova `_ + project. -The other hypervisors on z Systems such as z/VM and KVM are already -supported by OpenStack via Nova drivers. These drivers will continue to be -supported. Adding support for PR/SM DPM allows addressing customers that -need or want to run their workloads in logical partitions, and provides the -advantage for them of using OpenStack as a uniform, standard, cloud -management platform on z Systems. +* z/VM is supported by the z/VM driver in the + `openstack/nova-zvm-virt-driver `_ + project. -Nova-DPM Overview -===================== +Links +===== -Contents: +* Documentation: ``_ +* Source: ``_ +* Github shadow: ``_ +* Bugs: ``_ +* Gerrit: ``_ + +Overview +======== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + releasenotes/source/unreleased + topology + +Using the nova-dpm driver +========================= + +.. toctree:: + :maxdepth: 1 - readme - support-matrix installation - usage + configuration + support-matrix + +Contributing to the nova-dpm project +==================================== + +.. toctree:: + :glob: + :maxdepth: 1 + contributing - sample_config devref - - -Release Notes -============= - -.. toctree:: - :maxdepth: 1 - - releasenotes/source/unreleased - - -Specifications -============== - -Here you can find the specs, and spec template, for each release: - -.. toctree:: - :glob: - :maxdepth: 1 - - specs/ocata/index - - + specs/ocata/index diff --git a/doc/source/installation.rst b/doc/source/installation.rst index a7dc6a9..1d0a89e 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,12 +1,35 @@ +.. _`installation`: + ============ Installation ============ -At the command line:: +The nova-dpm virtualization driver must be installed on every OpenStack compute +node that is supposed to manage a z Systems or LinuxONE machine in DPM mode. - $ pip install nova-dpm +This section describes the manual installation of the nova-dpm driver from +the upstream OpenStack Git repository. -Or, if you have virtualenvwrapper installed:: +Normally, you should use the stable Git branch for the OpenStack release you +have on the compute node (e.g. for Ocata):: - $ mkvirtualenv nova-dpm - $ pip install nova-dpm + $ nova_dpm=https://github.com/openstack/nova-dpm/tree/stable/ocata + +If you want to use the latest development code level of the next OpenStack +release, use the ``master`` Git branch:: + + $ nova_dpm=https://github.com/openstack/nova-dpm/tree/master + +If the Python packages of your OpenStack installation are in the system Python +on the compute node, install the nova-dpm driver with:: + + $ sudo pip install $nova_dpm + +If the Python packages of your OpenStack installation are in a virtual Python +environment named ``venv`` that was established with ``virtualenvwrapper``, +install the nova-dpm driver with:: + + $ workon venv + $ pip install $nova_dpm + +After installing the driver, proceed with its :ref:`configuration`. diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/sample_config.rst b/doc/source/sample_config.rst deleted file mode 100644 index 8915288..0000000 --- a/doc/source/sample_config.rst +++ /dev/null @@ -1,12 +0,0 @@ -============================== -Nova-dpm Configuration Options -============================== - -The following is a sample Nova-dpm configuration for adaptation and use. -It is auto-generated from Nova-dpm when this documentation is built, so -if you are having issues with an option, please compare your version of -Nova-dpm with the version of this documentation. - -The sample configuration can also be viewed in `file form <_static/nova_dpm.conf.sample>`_. - -.. literalinclude:: _static/nova_dpm.conf.sample diff --git a/doc/source/specs/ocata/index.rst b/doc/source/specs/ocata/index.rst index 5f39204..e1be92e 100644 --- a/doc/source/specs/ocata/index.rst +++ b/doc/source/specs/ocata/index.rst @@ -1,6 +1,8 @@ -============================= -Nova-dpm Ocata Specifications -============================= +================================= +Nova-dpm specifications for Ocata +================================= + +**TODO:** Figure out what to do with this page and its child pages. Template: @@ -9,7 +11,7 @@ Template: Specification Template (Ocata release)