x/nova-dpm
Code Issues Proposed changes

Overhauled the documentation

Browse Source 
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 <maiera@de.ibm.com>
This commit is contained in:
Andreas Maier 2017-01-31 19:28:36 +01:00
parent eb2bc80389
commit cf932be130
13 changed files with 172 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
CONTRIBUTING.rst
View File

@ -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

54
README.rst
View File

@ -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 <http://git.openstack.org/cgit/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 <http://git.openstack.org/cgit/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: `<http://nova-dpm.readthedocs.io/en/latest/>`_
* Source: `<http://git.openstack.org/cgit/openstack/nova-dpm>`_
* Github shadow: `<https://github.com/openstack/nova-dpm>`_
* Bugs: `<http://bugs.launchpad.net/nova-dpm>`_
* Gerrit: `<https://review.openstack.org/#/q/project:openstack/nova-dpm>`_
* License: Apache 2.0 license

17
doc/source/configuration.rst Normal file
View File

@ -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

28
doc/source/contributing.rst
View File

@ -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

4
doc/source/devref.rst
View File

@ -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
http://docs.openstack.org/developer/reno/index.html

101
doc/source/index.rst
View File

@ -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 <http://git.openstack.org/cgit/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 <http://git.openstack.org/cgit/openstack/nova-zvm-virt-driver>`_
project.
Nova-DPM Overview
=====================
Links
=====
Contents:
* Documentation: `<http://nova-dpm.readthedocs.io/en/latest/>`_
* Source: `<http://git.openstack.org/cgit/openstack/nova-dpm>`_
* Github shadow: `<https://github.com/openstack/nova-dpm>`_
* Bugs: `<http://bugs.launchpad.net/nova-dpm>`_
* Gerrit: `<https://review.openstack.org/#/q/project:openstack/nova-dpm>`_
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

33
doc/source/installation.rst
View File

@ -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`.

1
doc/source/readme.rst
View File

@ -1 +0,0 @@
.. include:: ../../README.rst

12
doc/source/sample_config.rst
View File

@ -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

12
doc/source/specs/ocata/index.rst
View File

@ -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) <template>
Ocata implemented specs:
Specs implemented in Ocata:
.. toctree::
:glob:
@ -17,7 +19,7 @@ Ocata implemented specs:
implemented/*
Ocata approved (but not implemented) specs:
Specs approved (but not implemented) in Ocata:
.. toctree::
:glob:

2
doc/source/support-matrix.rst
View File

@ -1,4 +1,6 @@
.. `feature support matrix`:
======================
Feature Support Matrix
======================

7
doc/source/topology.rst Normal file
View File

@ -0,0 +1,7 @@
.. `topology`:
========
Topology
========
**TODO:** Describe the topology

7
doc/source/usage.rst
View File

@ -1,7 +0,0 @@
========
Usage
========
To use nova-dpm in a project::
import nova_dpm