openstack/nova
Code Issues Proposed changes

Merge "doc: Start using openstackdoctheme's extlink extension"

Browse Source
This commit is contained in:
Zuul
2018-05-30 15:21:12 +00:00
committed by Gerrit Code Review
parent 465051809c dd1a416bc9
commit d741f624c8
56 changed files with 216 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
api-guide/source/conf.py
View File

@@ -277,3 +277,9 @@ pdf_documents = [
('index', u'ComputeAPIGuide', u'Compute API Guide', u'OpenStack '
'contributors')
]
# -- Options for openstackdocstheme -------------------------------------------
openstack_projects = [
'nova',
]

3
api-guide/source/general_info.rst
View File

@@ -247,8 +247,7 @@ on compute hosts rather than servers.
- **Aggregates**
See `Aggregates developer information
<https://docs.openstack.org/nova/latest/user/aggregates.html>`_.
See :nova-doc:`Aggregates Developer Information <user/aggregates.html>`.
- **Migrations**

30
api-guide/source/server_concepts.rst
View File

@@ -90,7 +90,7 @@ are exposed to administrators:
there is no ongoing compute API calls (running tasks), vm_state should reflect
what the customer expect the VM to be. When combined with task states,
a better picture can be formed regarding the server's health and progress.
Please see: `VM States <https://docs.openstack.org/nova/latest/reference/vm-states.html>`_.
Refer to :nova-doc:`VM States <reference/vm-states.html>`.
- task_state represents what is happening to the instance at the
current moment. These tasks can be generic, such as 'spawning', or specific,
@@ -613,17 +613,15 @@ TODO: Add description about how to custom scheduling policy for server booting.
Server Consoles
~~~~~~~~~~~~~~~
Server Consoles can also be supplied after server launched.
There are several server console services available.
First, users can get the console output from the specified server
and can limit the lines of console text by setting the length.
Second, users can access multiple types of remote consoles.
The user can use novnc, xvpvnc, rdp-html5, spice-html5, serial,
and webmks(start from microversion 2.8) through either the OpenStack
dashboard or the command line. Please see `Configure remote console access
<https://docs.openstack.org/nova/latest/admin/remote-console-access.html>`_.
Specifically for Xenserver, it provides the ability to create,
delete, detail, list specified server vnc consoles.
Server Consoles can also be supplied after server launched. There are several
server console services available. First, users can get the console output
from the specified server and can limit the lines of console text by setting
the length. Second, users can access multiple types of remote consoles. The
user can use novnc, xvpvnc, rdp-html5, spice-html5, serial, and webmks(start
from microversion 2.8) through either the OpenStack dashboard or the command
line. Refer to :nova-doc:`Configure remote console access
<admin/remote-console-access.html>`. Specifically for Xenserver, it provides
the ability to create, delete, detail, list specified server vnc consoles.
Server networks
~~~~~~~~~~~~~~~
@@ -884,8 +882,8 @@ Metadata API
------------
Nova provides a metadata api for servers to retrieve server specific metadata.
Neutron ensures this metadata api can be accessed through a predefined ip
address (169.254.169.254). For more details, see
`Metadata Service <https://docs.openstack.org/nova/latest/user/metadata-service.html>`_.
address (169.254.169.254). For more details, see :nova-doc:`Metadata Service
<user/metadata-service.html>`.
Config Drive
------------
@@ -893,8 +891,8 @@ Config Drive
Nova is able to write metadata to a special configuration drive that attaches
to the server when it boots. The server can mount this drive and read files
from it to get information that is normally available through the metadata
service. For more details, see
`Config Drive <https://docs.openstack.org/nova/latest/user/config-drive.html>`_.
service. For more details, see :nova-doc:`Config Drive
<user/config-drive.html>`.
User data
---------

2
doc/requirements.txt
View File

@@ -5,7 +5,7 @@ sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
sphinxcontrib-actdiag>=0.8.5 # BSD
sphinxcontrib-seqdiag>=0.8.4 # BSD
os-api-ref>=1.4.0 # Apache-2.0
openstackdocstheme>=1.18.1 # Apache-2.0
openstackdocstheme>=1.19.0 # Apache-2.0
# releasenotes
reno>=2.5.0 # Apache-2.0

7
doc/source/admin/arch.rst
View File

@@ -49,7 +49,7 @@ support across different hypervisors, see :doc:`/user/support-matrix`.
You can also orchestrate clouds using multiple hypervisors in different
availability zones. Compute supports the following hypervisors:
- `Baremetal <https://docs.openstack.org/ironic/latest/>`__
- :ironic-doc:`Baremetal <>`
- `Docker <https://www.docker.io>`__
@@ -173,9 +173,8 @@ virtualization system. It is still possible for the resulting instance to keep
ephemeral storage, depending on the flavor selected. In this case, the root
file system can be on the persistent volume, and its state is maintained, even
if the instance is shut down. For more information about this type of
configuration, see `Introduction to the Block Storage service
<https://docs.openstack.org/cinder/latest/configuration/block-storage/block-storage-overview.html>`_
in the OpenStack Configuration Reference.
configuration, see :cinder-doc:`Introduction to the Block Storage service
<configuration/block-storage/block-storage-overview.html>`.
.. note::

9
doc/source/admin/configuration/hypervisor-xen-api.rst
View File

@@ -376,11 +376,10 @@ Networking configuration
------------------------
The Networking service in the Compute node is running
``neutron-openvswitch-agent``, this manages dom0's OVS. You can refer
Networking `openvswitch_agent.ini sample`__ for details,
however there are several specific items to look out for.
__ https://docs.openstack.org/neutron/latest/configuration/samples/openvswitch-agent.html
``neutron-openvswitch-agent``. This manages ``dom0``\'s OVS. You should refer
to the :neutron-doc:`openvswitch_agent.ini sample
<configuration/samples/openvswitch-agent.html>` for details, however there are
several specific items to look out for.
.. code-block:: ini

6
doc/source/admin/configuration/resize.rst
View File

@@ -14,9 +14,9 @@ compute nodes over ssh. For KVM you need hostnames to resolve properly and
passwordless ssh access between your compute hosts. Direct access from one
compute host to another is needed to copy the VM file across.
Cloud end users can find out how to resize a server by reading the `OpenStack
End User Guide <https://docs.openstack.org/user-guide/
cli_change_the_size_of_your_server.html>`_.
Cloud end users can find out how to resize a server by reading the
:python-openstackclient-doc:`OpenStack CLI Guide
<cli/command-objects/server.html#server-resize>`
XenServer
~~~~~~~~~

5
doc/source/admin/huge-pages.rst
View File

@@ -200,8 +200,8 @@ run:
$ openstack flavor set m1.large --property hw:mem_page_size=any
For more information about the syntax for ``hw:mem_page_size``, refer to the
`Flavors`_ guide.
For more information about the syntax for ``hw:mem_page_size``, refer to
:doc:`flavors`.
Applications are frequently packaged as images. For applications that require
the IO performance improvements that huge pages provides, configure image
@@ -235,5 +235,4 @@ guide.
.. Links
.. _`Linux THP guide`: https://www.kernel.org/doc/Documentation/vm/transhuge.txt
.. _`Linux hugetlbfs guide`: https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt
.. _`Flavors`: https://docs.openstack.org/admin-guide/compute-flavors.html
.. _`Image metadata`: https://docs.openstack.org/image-guide/image-metadata.html

4
doc/source/admin/manage-logs.rst
View File

@@ -35,8 +35,8 @@ For more about the logging configuration syntax, including the ``handlers`` and
on logging configuration files.
For an example of the ``logging.conf`` file with various defined handlers, see
the `Example Configuration File for nova
<https://docs.openstack.org/oslo.log/latest/admin/example_nova.html>`__.
the :oslo.log-doc:`Example Configuration File for nova
<admin/example_nova.html>`.
Syslog
~~~~~~

11
doc/source/admin/manage-the-cloud.rst
View File

@@ -21,9 +21,8 @@ might be restricted by the Identity service.
variables for convenience), for the ability to administer the cloud from the
command line.
To install python-openstackclient, follow the instructions in the `OpenStack
User Guide
<https://docs.openstack.org/user-guide/common/cli-install-openstack-command-line-clients.html>`_.
For more information on ``python-openstackclient``, refer to the
:python-openstackclient-doc:`documentation <>`.
#. Confirm the installation was successful:
@@ -44,9 +43,9 @@ might be restricted by the Identity service.
$ openstack help SUBCOMMAND
For a complete list of ``openstack`` commands and parameters, see the
`OpenStack Command-Line Reference
<https://docs.openstack.org/cli-reference/openstack.html>`__.
For a complete list of ``openstack`` commands and parameters, refer to the
:python-openstackclient-doc:`OpenStack Command-Line Reference
<cli/index.html>`.
#. Set the required parameters as environment variables to make running
commands easier. For example, you can add ``--os-username`` as an

19
doc/source/admin/manage-volumes.rst
View File

@@ -6,11 +6,11 @@ Depending on the setup of your cloud provider, they may give you an endpoint to
use to manage volumes. You can use the ``openstack`` CLI to manage volumes.
For the purposes of the compute service, attaching, detaching and
:doc:`creating a server from a volume <../user/launch-instance-from-volume>`
are of primary interest.
:doc:`creating a server from a volume </user/launch-instance-from-volume>` are
of primary interest.
Refer to the `block storage service CLI guide on managing volumes
<https://docs.openstack.org/cinder/latest/cli/cli-manage-volumes.html>`_.
Refer to the :python-openstackclient-doc:`CLI documentation
<cli/command-objects/volume.html>` for more information.
Volume multi-attach
@@ -19,7 +19,8 @@ Volume multi-attach
Nova `added support for multiattach volumes`_ in the 17.0.0 Queens release.
This document covers the nova-specific aspects of this feature. Refer
to the `block storage admin guide`_ for more details about creating
to the :cinder-doc:`block storage admin guide
<admin/blockstorage-volume-multiattach.html>` for more details about creating
multiattach-capable volumes.
Boot from volume and attaching a volume to a server that is not
@@ -33,11 +34,12 @@ Requirements
~~~~~~~~~~~~
* The minimum required compute API microversion for attaching a
multiattach-capable volume to more than one server is `2.60`_.
multiattach-capable volume to more than one server is :ref:`2.60
<api-microversion-queens>`.
* Cinder 12.0.0 (Queens) or newer is required.
* The ``nova-compute`` service must be running at least Queens release level
code (17.0.0) and the hypervisor driver must support attaching block storage
devices to more than one guest. Refer to the `feature support matrix`_ for
devices to more than one guest. Refer to :doc:`/user/support-matrix` for
details on which compute drivers support volume multiattach.
* When using the libvirt compute driver, the following native package versions
determine multiattach support:
@@ -72,9 +74,6 @@ volume back end. It purposefully does not use the Pike Ubuntu Cloud Archive
package mirror so that it gets qemu<2.10.
.. _added support for multiattach volumes: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/multi-attach-volume.html
.. _block storage admin guide: https://docs.openstack.org/cinder/latest/admin/blockstorage-volume-multiattach.html
.. _recorded overview and demo: https://www.youtube.com/watch?v=hZg6wqxdEHk
.. _2.60: https://docs.openstack.org/nova/latest/reference/api-microversion-history.html#maximum-in-queens
.. _feature support matrix: https://docs.openstack.org/nova/latest/user/support-matrix.html#operation_multiattach_volume
.. _nova repository: http://git.openstack.org/cgit/openstack/nova/tree/playbooks/legacy/nova-multiattach/run.yaml
.. _tempest repository: http://codesearch.openstack.org/?q=CONF.compute_feature_enabled.volume_multiattach&i=nope&files=&repos=tempest

15
doc/source/admin/networking-nova.rst
View File

@@ -13,8 +13,8 @@ configuration for your Compute instances.
You can choose to either install and configure ``nova-network`` or use the
OpenStack Networking service (neutron). This section contains a brief overview
of ``nova-network``. For more information about OpenStack Networking, see
`Networking <https://docs.openstack.org/admin-guide/networking.html>`_.
of ``nova-network``. For more information about OpenStack Networking, refer to
:neutron-doc:`the documentation <>`.
Networking concepts
~~~~~~~~~~~~~~~~~~~
@@ -417,9 +417,8 @@ Configure public (floating) IP addresses
This section describes how to configure floating IP addresses with
``nova-network``. For information about doing this with OpenStack Networking,
see `L3-routing-and-NAT
<https://docs.openstack.org/neutron/latest/admin/archives/adv-features.html
#l3-routing-and-nat>`_.
refer to :neutron-doc:`L3-routing-and-NAT
<admin/archives/adv-features.html#l3-routing-and-nat>`.
Private and public IP addresses
-------------------------------
@@ -561,9 +560,9 @@ perform floating IP operations:
# openstack floating ip delete CIDR
For more information about how administrators can associate floating IPs with
instances, see `ip floating
<https://docs.openstack.org/python-openstackclient/latest/cli/command-objects/
ip-floating.html>`__ in the python-openstackclient User Documentation.
instances, see :python-openstackclient-doc:`ip floating
<cli/command-objects/ip-floating.html>` in the *python-openstackclient* User
Documentation.
Automatically add floating IPs
------------------------------

19
doc/source/admin/pci-passthrough.rst
View File

@@ -18,7 +18,7 @@ assigned to only one guest and cannot be shared.
.. note::
For information on attaching virtual SR-IOV devices to guests, refer to the
`Networking Guide`_.
:neutron-doc:`Networking Guide <admin/config-sriov>`.
To enable PCI passthrough, follow the steps below:
@@ -40,7 +40,9 @@ To enable PCI passthrough, follow the steps below:
Configure nova-scheduler (Controller)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Configure ``nova-scheduler`` as specified in `Configure nova-scheduler`_.
#. Configure ``nova-scheduler`` as specified in :neutron-doc:`Configure
nova-scheduler
<admin/config-sriov.html#configure-nova-scheduler-controller`.
#. Restart the ``nova-scheduler`` service.
@@ -82,7 +84,8 @@ Enable PCI passthrough (Compute)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enable VT-d and IOMMU. For more information, refer to steps one and two in
`Create Virtual Functions`_.
:neutron-doc:`Create Virtual Functions
<admin/config-sriov.html#create-virtual-functions-compute`.
For Hyper-V compute nodes, the requirements are as follows:
@@ -100,8 +103,10 @@ devices, run the following Powershell commands:
If the compute node passes all the requirements, the desired assignable PCI
devices to be disabled and unmounted from the host, in order to be assignable
by Hyper-V. The following can be read for more details: `Hyper-V PCI passthrough`_.
by Hyper-V. The following can be read for more details: `Hyper-V PCI
passthrough`__.
.. __: https://blogs.technet.microsoft.com/heyscriptingguy/2016/07/14/passing-through-devices-to-hyper-v-vms-by-using-discrete-device-assignment/
Configure PCI devices (Compute)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -157,9 +162,3 @@ available with the specified ``vendor_id`` and ``product_id`` that matches the
.. code-block:: console
# openstack server create --flavor m1.large --image cirros-0.3.5-x86_64-uec --wait test-pci
.. Links
.. _`Create Virtual Functions`: https://docs.openstack.org/neutron/latest/admin/config-sriov.html#create-virtual-functions-compute
.. _`Configure nova-scheduler`: https://docs.openstack.org/neutron/latest/admin/config-sriov.html#configure-nova-scheduler-controller
.. _`Networking Guide`: https://docs.openstack.org/neutron/latest/admin/config-sriov.html
.. _`Hyper-V PCI passthrough`: https://blogs.technet.microsoft.com/heyscriptingguy/2016/07/14/passing-through-devices-to-hyper-v-vms-by-using-discrete-device-assignment/

3
doc/source/admin/service-groups.rst
View File

@@ -47,8 +47,7 @@ To use the memcache driver, you must install memcached. You might already have
it installed, as the same driver is also used for the OpenStack Object Storage
and OpenStack dashboard. To install memcached, see the *Environment ->
Memcached* section in the `Installation Tutorials and Guides
<https://docs.openstack.org/project-install-guide/ocata>`_ depending on your
distribution.
<https://docs.openstack.org/install-guide>`_ depending on your distribution.
These values in the ``/etc/nova/nova.conf`` file are required on every node for
the memcache driver:

4
doc/source/admin/virtual-gpu.rst
View File

@@ -66,9 +66,7 @@ Configure a flavor to request one virtual GPU:
The enabled vGPU types on the compute hosts are not exposed to API users.
Flavors configured for vGPU support can be tied to host aggregates as a means
to properly schedule those flavors onto the compute hosts that support them.
See the `host aggregates`_ guide for more information.
.. _host aggregates: https://docs.openstack.org/nova/latest/user/aggregates.html
See the :doc:`/user/aggregates` for more information.
Create instances with virtual GPU devices
-----------------------------------------

4
doc/source/cli/nova-api-metadata.rst
View File

@@ -41,8 +41,8 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* `Using WSGI with Nova <https://docs.openstack.org/nova/latest/wsgi.html>`__
* :nova-doc:`OpenStack Nova <>`
* :nova-doc:`Using WSGI with Nova <wsgi.html>`
Bugs
====

4
doc/source/cli/nova-api-os-compute.rst
View File

@@ -41,8 +41,8 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* `Using WSGI with Nova <https://docs.openstack.org/nova/latest/user/wsgi.html>`__
* :nova-doc:`OpenStack Nova <>`
* :nova-doc:`Using WSGI with Nova <user/wsgi.html>`
Bugs
====

4
doc/source/cli/nova-api.rst
View File

@@ -41,8 +41,8 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* `Using WSGI with Nova <https://docs.openstack.org/nova/latest/user/wsgi.html>`__
* :nova-doc:`OpenStack Nova <>`
* :nova-doc:`Using WSGI with Nova <user/wsgi.html>`
Bugs
====

2
doc/source/cli/nova-cells.rst
View File

@@ -46,7 +46,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-compute.rst
View File

@@ -42,7 +42,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-conductor.rst
View File

@@ -37,7 +37,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-console.rst
View File

@@ -41,7 +41,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-consoleauth.rst
View File

@@ -45,7 +45,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-dhcpbridge.rst
View File

@@ -48,7 +48,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-manage.rst
View File

@@ -279,7 +279,7 @@ Nova Cells v2
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-network.rst
View File

@@ -45,7 +45,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-novncproxy.rst
View File

@@ -41,7 +41,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-rootwrap.rst
View File

@@ -57,7 +57,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-scheduler.rst
View File

@@ -41,7 +41,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-serialproxy.rst
View File

@@ -41,7 +41,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-spicehtml5proxy.rst
View File

@@ -41,7 +41,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

4
doc/source/cli/nova-status.rst
View File

@@ -93,7 +93,7 @@ Upgrade
make a successful request to the endpoint. The command also checks to
see that there are compute node resource providers checking in with the
Placement service. More information on the Placement service can be found
at: `<https://docs.openstack.org/nova/latest/user/placement.html>`_
at :nova-doc:`user/placement.html>`.
**16.0.0 (Pike)**
@@ -117,7 +117,7 @@ Upgrade
See Also
========
* OpenStack Nova Docs: `<https://docs.openstack.org/nova/latest/>`_
* :nova-doc:`OpenStack Nova <>`
Bugs
====

2
doc/source/cli/nova-xvpvncproxy.rst
View File

@@ -41,7 +41,7 @@ Files
See Also
========
* `OpenStack Nova <https://docs.openstack.org/nova/latest/>`__
* :nova-doc:`OpenStack Nova <>`
Bugs
====

21
doc/source/conf.py
View File

@@ -171,6 +171,27 @@ latex_documents = [
u'OpenStack Foundation', 'manual'),
]
# -- Options for openstackdocstheme -------------------------------------------
# keep this ordered to keep mriedem happy
openstack_projects = [
'ceilometer',
'cinder',
'glance',
'horizon',
'ironic',
'keystone',
'neutron',
'nova',
'oslo.log',
'oslo.messaging',
'oslo.i18n',
'oslo.versionedobjects',
'python-novaclient',
'python-openstackclient',
'reno',
'watcher',
]
# -- Custom extensions --------------------------------------------------------

2
doc/source/contributor/how-to-get-involved.rst
View File

@@ -328,7 +328,7 @@ How to do great nova-spec reviews?
https://specs.openstack.org/openstack/nova-specs/specs/rocky/template.html
https://docs.openstack.org/nova/latest/contributor/blueprints.html#specs
:doc:`/contributor/blueprints`.
Spec reviews are always a step ahead of the normal code reviews. Follow
the above links for some great information on specs/reviews.

5
doc/source/contributor/microversions.rst
View File

@@ -356,8 +356,8 @@ necessary to add changes to other places which describe your change:
* Add a verbose description to
``nova/api/openstack/compute/rest_api_version_history.rst``.
* Add a `release note`_ with a ``features`` section announcing the new or
changed feature and the microversion.
* Add a :doc:`release note </contributor/releasenotes>` with a ``features``
section announcing the new or changed feature and the microversion.
* Update the expected versions in affected tests, for example in
``nova/tests/unit/api/openstack/compute/test_versions.py``.
@@ -375,7 +375,6 @@ necessary to add changes to other places which describe your change:
* Update the `API Reference`_ documentation as appropriate. The source is
located under `api-ref/source/`.
.. _release note: https://docs.openstack.org/nova/latest/contributor/releasenotes.html
.. _API Reference: https://developer.openstack.org/api-ref/compute/
Allocating a microversion

15
doc/source/contributor/placement.rst
View File

@@ -40,10 +40,11 @@ increasing the number of WSGI application instances and scaling the RDBMS using
traditional database scaling techniques.
For sake of consistency and because there was initially intent to make the
entities in the placement service available over RPC, `versioned objects`_ are
used to provide the interface between the HTTP application layer and the
SQLAlchemy-driven persistence layer. Even without RPC, these objects provide
useful structuring and separation of the code.
entities in the placement service available over RPC,
:oslo.versionedobjects-doc:`versioned objects <>` are used to provide the
interface between the HTTP application layer and the SQLAlchemy-driven
persistence layer. Even without RPC, these objects provide useful structuring
and separation of the code.
Though the placement service doesn't aspire to be a `microservice` it does
aspire to continue to be small and minimally complex. This means a relatively
@@ -145,8 +146,8 @@ there are a few bits of required housekeeping that must be done in the code:
microversion and give a very brief summary of the added feature.
* Update ``nova/api/openstack/placement/rest_api_version_history.rst``
to add a more detailed section describing the new microversion.
* Add a `release note`_ with a ``features`` section announcing the new or
changed feature and the microversion.
* Add a :reno-doc:`release note <>` with a ``features`` section announcing the
new or changed feature and the microversion.
* If the ``version_handler`` decorator (see below) has been used,
increment ``TOTAL_VERSIONED_METHODS`` in
``nova/tests/unit/api/openstack/placement/test_microversion.py``.
@@ -413,13 +414,11 @@ When creating new code for the placement service, please be aware of the plan
for an eventual extraction and avoid creating unnecessary interdependencies.
.. _WSGI: https://www.python.org/dev/peps/pep-3333/
.. _versioned objects: http://docs.openstack.org/developer/oslo.versionedobjects/
.. _wsgify: http://docs.webob.org/en/latest/api/dec.html
.. _WebOb: http://docs.webob.org/en/latest/
.. _Request: http://docs.webob.org/en/latest/reference.html#request
.. _Response: http://docs.webob.org/en/latest/#response
.. _microversions: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html
.. _release note: https://docs.openstack.org/reno/latest/user/usage.html
.. _gabbi: https://gabbi.readthedocs.io/
.. _telemetry: http://specs.openstack.org/openstack/telemetry-specs/specs/kilo/declarative-http-tests.html
.. _wsgi-intercept: http://wsgi-intercept.readthedocs.io/

5
doc/source/contributor/policies.rst
View File

@@ -108,7 +108,8 @@ Metrics Gathering
Nova currently has a monitor plugin to gather CPU metrics on compute nodes.
This feeds into the MetricsFilter and MetricsWeigher in the scheduler. The
CPU metrics monitor is only implemented for the libvirt compute driver.
External projects like `Ceilometer`_ and `Watcher`_ consume these metrics.
External projects like :ceilometer-doc:`Ceilometer <>` and
:watcher-doc:`Watcher <>` consume these metrics.
Over time people have tried to add new monitor plugins for things like memory
bandwidth. There have also been attempts to expose these monitors over CLI,
@@ -127,6 +128,4 @@ replacement, the deprecation is open-ended, but serves as a signal that new
deployments should not rely on the metrics that Nova gathers and should instead
focus their efforts on alternative solutions for placement.
.. _Ceilometer: https://docs.openstack.org/ceilometer/latest/
.. _Watcher: https://docs.openstack.org/watcher/latest/
.. _Newton midcycle: http://lists.openstack.org/pipermail/openstack-dev/2016-August/100600.html

12
doc/source/contributor/process.rst
View File

@@ -223,9 +223,7 @@ when you create the bug report).
When do I need a blueprint vs a spec?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For more details see:
- https://docs.openstack.org/nova/latest/contributor/blueprints.html
For more details refer to :doc:`/contributor/blueprints`.
To understand this question, we need to understand why blueprints and
specs are useful.
@@ -426,8 +424,7 @@ Interoperable API, supporting a vibrant ecosystem
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An interoperable API that gives users on-demand access to compute
resources is at the heart of Nova's mission:
https://docs.openstack.org/nova/latest/contributor/project-scope.html#mission
resources is at the heart of :ref:`nova's mission <nova-mission>`.
Nova has a vibrant ecosystem of tools built on top of the current Nova
API. All features should be designed to work with all technology
@@ -910,9 +907,8 @@ this technique during M.
Feature Classification
~~~~~~~~~~~~~~~~~~~~~~
This is a look at moving forward this effort:
- https://docs.openstack.org/nova/latest/user/support-matrix.html
This is a look at moving forward the :doc:`support matrix effort
</user/support-matrix>`.
The things we need to cover:

4
doc/source/contributor/project-scope.rst
View File

@@ -22,8 +22,10 @@ should and should not be doing, and why.
Please treat this as a discussion of interesting, and hopefully useful,
examples. It is not intended to be an exhaustive policy statement.
.. _nova-mission:
Mission
--------
-------
Our mission statement starts with:

20
doc/source/contributor/releasenotes.rst
View File

@@ -6,13 +6,12 @@ Release Notes
What is reno ?
--------------
Nova uses `reno <http://docs.openstack.org/developer/reno/usage.html>`_ for
providing release notes in-tree. That means that a patch can include a *reno
file* or a series can have a follow-on change containing that file explaining
what the impact is.
Nova uses :reno-doc:`reno <>` for providing release notes in-tree. That means
that a patch can include a *reno file* or a series can have a follow-on change
containing that file explaining what the impact is.
A *reno file* is a YAML file written in the releasenotes/notes tree which is
generated using the reno tool this way:
A *reno file* is a YAML file written in the ``releasenotes/notes`` tree which
is generated using the *reno* tool this way:
.. code-block:: bash
@@ -21,8 +20,7 @@ generated using the reno tool this way:
where usually ``<name-your-file>`` can be ``bp-<blueprint_name>`` for a
blueprint or ``bug-XXXXXX`` for a bugfix.
Refer to the `reno documentation <http://docs.openstack.org/developer/reno/usage.html#editing-a-release-note>`_
for the full list of sections.
Refer to the :reno-doc:`reno documentation <user/index.html>` for more information.
When a release note is needed
@@ -48,8 +46,10 @@ need to provide a release note :-)
* If the patch has an `APIImpact <http://docs.openstack.org/infra/manual/developers.html#peer-review>`_ tag
* For nova-manage and python-novaclient changes, if it adds or changes a
new command, including adding new options to existing commands
* not all blueprints in general, just the ones impacting a `contractual API <http://docs.openstack.org/developer/nova/policies.html#public-contractual-apis>`_
* a new virt driver is provided or an existing driver impacts the `HypervisorSupportMatrix <http://docs.openstack.org/developer/nova/support-matrix.html>`_
* not all blueprints in general, just the ones impacting a
:doc:`/contributor/policies`
* a new virt driver is provided or an existing driver impacts the
:doc:`HypervisorSupportMatrix </user/support-matrix>`
* ``critical``
* Bugfixes categorized as Critical in Launchpad *impacting users*

43
doc/source/index.rst
View File

@@ -30,13 +30,12 @@ servers to provide that service.
It requires the following additional OpenStack services for basic function:
* `Keystone <https://docs.openstack.org/keystone/latest/>`__: This provides
identity and authentication for all OpenStack services.
* `Glance <https://docs.openstack.org/glance/latest/>`__: This provides the
compute image repository. All compute instances launch from glance images.
* `Neutron <https://docs.openstack.org/neutron/latest/>`__: This is
responsible for provisioning the virtual or physical networks that compute
instances connect to on boot.
* :keystone-doc:`Keystone <>`: This provides identity and authentication for
all OpenStack services.
* :glance-doc:`Glance <>`: This provides the compute image repository. All
compute instances launch from glance images.
* :neutron-doc:`Neutron <>`: This is responsible for provisioning the virtual
or physical networks that compute instances connect to on boot.
It can also integrate with other services to include: persistent block
storage, encrypted disks, and baremetal compute instances.
@@ -50,19 +49,15 @@ either tools or the API directly.
Tools for using Nova
--------------------
* `Horizon
<https://docs.openstack.org/horizon/latest/user/launch-instances.html>`_: The
official web ui for the OpenStack Project.
* `OpenStack Client
<https://docs.openstack.org/python-openstackclient/latest/>`_: The official
CLI for OpenStack Projects. You should use this as your CLI for most things,
it includes not just nova commands but also commands for most of the projects
in OpenStack.
* `Nova Client
<https://docs.openstack.org/python-novaclient/latest/user/shell.html>`_: For
some very advanced features (or administrative commands) of nova you may need
to use nova client. It is still supported, but the ``openstack`` cli is
recommended.
* :horizon-doc:`Horizon <user/launch-instances.html>`: The official web UI for
the OpenStack Project.
* :python-openstackclient-doc:`OpenStack Client <>`: The official CLI for
OpenStack Projects. You should use this as your CLI for most things, it
includes not just nova commands but also commands for most of the projects in
OpenStack.
* :python-novaclient-doc:`Nova Client <user/shell.html>`: For some very
advanced features (or administrative commands) of nova you may need to use
nova client. It is still supported, but the ``openstack`` cli is recommended.
Writing to the API
------------------
@@ -117,11 +112,9 @@ Installation
.. TODO(sdague): links to all the rest of the install guide pieces.
The detailed install guide for nova. A functioning nova will also require
having installed `keystone
<https://docs.openstack.org/keystone/latest/install/>`__, `glance
<https://docs.openstack.org/glance/latest/install/>`__, and `neutron
<https://docs.openstack.org/neutron/latest/install/>`__. Please ensure that you
follow their install guides first.
having installed :keystone-doc:`keystone <install/>`, :glance-doc:`glance
<install/>`, and :neutron-doc:`neutron <install/>`. Ensure that you follow
their install guides first.
.. toctree::
:maxdepth: 2

7
doc/source/install/compute-install-obs.rst
View File

@@ -122,10 +122,9 @@ Install and configure components
firewall service by using the
``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
`Networking service install guide`__ for more details.
.. __: https://docs.openstack.org/neutron/latest/install/compute-install-obs.html#configure-the-compute-service-to-use-the-networking-service
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
the :neutron-doc:`Networking service install guide
<install/compute-install-obs.html>` for more details.
* In the ``[vnc]`` section, enable and configure remote console access:

8
doc/source/install/compute-install-rdo.rst
View File

@@ -114,10 +114,10 @@ Install and configure components
service by using the ``nova.virt.firewall.NoopFirewallDriver`` firewall
driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
`Networking service install guide`__ for more details.
.. __: https://docs.openstack.org/neutron/latest/install/compute-install-rdo.html#configure-the-compute-service-to-use-the-networking-service
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
the :neutron-doc:`Networking service install guide
<install/compute-install-rdo.html#configure-the-compute-service-to-use-the-networking-service>`
for more details.
* In the ``[vnc]`` section, enable and configure remote console access:

8
doc/source/install/compute-install-ubuntu.rst
View File

@@ -104,10 +104,10 @@ Install and configure components
service by using the ``nova.virt.firewall.NoopFirewallDriver`` firewall
driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
`Networking service install guide`__ for more details.
.. __: https://docs.openstack.org/neutron/latest/install/compute-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
the :neutron-doc:`Networking service install guide
<install/compute-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service>`
for more details.
* In the ``[vnc]`` section, enable and configure remote console access:

8
doc/source/install/controller-install-obs.rst
View File

@@ -378,10 +378,10 @@ Install and configure components
Compute firewall driver by using the
``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
`Networking service install guide`__ for more details.
.. __: https://docs.openstack.org/neutron/latest/install/controller-install-obs.html#configure-the-compute-service-to-use-the-networking-service
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
the :neutron-doc:`Networking service install guide
<install/controller-install-obs.html#configure-the-compute-service-to-use-the-networking-service>`
for more details.
* In the ``[vnc]`` section, configure the VNC proxy to use the management
interface IP address of the controller node:

7
doc/source/install/controller-install-rdo.rst
View File

@@ -369,10 +369,9 @@ Install and configure components
Compute firewall driver by using the
``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
`Networking service install guide`__ for more details.
.. __: https://docs.openstack.org/neutron/latest/install/controller-install-rdo.html#configure-the-compute-service-to-use-the-networking-service
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
the :neutron-doc:`Networking service install guide
<install/compute-install-rdo.html>` for more details.
* In the ``[vnc]`` section, configure the VNC proxy to use the management
interface IP address of the controller node:

8
doc/source/install/controller-install-ubuntu.rst
View File

@@ -359,10 +359,10 @@ Install and configure components
Compute firewall driver by using the
``nova.virt.firewall.NoopFirewallDriver`` firewall driver.
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. See the
`Networking service install guide`__ for more details.
.. __: https://docs.openstack.org/neutron/latest/install/controller-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service
* Configure the ``[neutron]`` section of **/etc/nova/nova.conf**. Refer to
the :neutron-doc:`Networking service install guide
<install/controller-install-ubuntu.html#configure-the-compute-service-to-use-the-networking-service>`
for more information.
* In the ``[vnc]`` section, configure the VNC proxy to use the management
interface IP address of the controller node:

3
doc/source/reference/i18n.rst
View File

@@ -1,8 +1,7 @@
Internationalization
====================
Nova uses the `oslo.i18n library
<http://docs.openstack.org/developer/oslo.i18n/index.html>`_ to support
Nova uses the :oslo.i18n-doc:`oslo.i18n library <>` to support
internationalization. The oslo.i18n library is built on top of `gettext
<http://docs.python.org/library/gettext.html>`_ and provides functions that are
used to enable user-facing strings such as log messages to appear in the

25
doc/source/reference/notifications.rst
View File

@@ -13,12 +13,13 @@
Notifications in Nova
=====================
Similarly to other OpenStack services Nova emits notifications to the message
bus with the Notifier class provided by oslo.messaging [1]_. From the
notification consumer point of view a notification consists of two parts: an
envelope with a fixed structure defined by oslo.messaging and a payload defined
by the service emitting the notification. The envelope format is the
following::
bus with the Notifier class provided by :oslo.messaging-doc:`oslo.messaging
<reference/notifier.html>`. From the notification consumer point of view a
notification consists of two parts: an envelope with a fixed structure defined
by oslo.messaging and a payload defined by the service emitting the
notification. The envelope format is the following::
{
"priority": <string, selected from a predefined list by the sender>,
@@ -62,7 +63,7 @@ The versioned notification concept is created to fix the shortcomings of the
unversioned notifications. The envelope structure of the emitted notification
is the same as in the unversioned notification case as it is provided by
oslo.messaging. However the payload is not a free form dictionary but a
serialized oslo versionedobject [2]_.
serialized :oslo.versionedobjects-doc:`oslo versionedobjects object <>`.
.. _service.update:
@@ -300,9 +301,9 @@ notification should be created with care to avoid future needs of adding extra
level of inheritance that changes the name of the leaf class as that name is
present in the payload class. If this cannot be avoided and the only change is
the renaming then the version of the new payload shall be the same as the old
payload was before the rename. See [3]_ as an example. If the renaming
payload was before the rename. See [1]_ as an example. If the renaming
involves any other changes on the payload (e.g. adding new fields) then the
version of the new payload shall be higher than the old payload was. See [4]_
version of the new payload shall be higher than the old payload was. See [2]_
as an example.
What should be in the notification payload
@@ -344,9 +345,5 @@ Existing versioned notifications
.. versioned_notifications::
.. [1] http://docs.openstack.org/developer/oslo.messaging/notifier.html
.. [2] http://docs.openstack.org/developer/oslo.versionedobjects
.. [3] https://review.openstack.org/#/c/463001/
.. [4] https://review.openstack.org/#/c/453077/
.. [1] https://review.openstack.org/#/c/463001/
.. [2] https://review.openstack.org/#/c/453077/

9
doc/source/user/cellsv2-layout.rst
View File

@@ -285,10 +285,11 @@ Notifications
With a multi-cell environment with multiple message queues, it is
likely that operators will want to configure a separate connection to
a unified queue for notifications. This can be done in the
configuration file of all nodes. See the `oslo.messaging configuration
<https://docs.openstack.org/oslo.messaging/latest/configuration/opts.html#oslo_messaging_notifications.transport_url>`_
documentation for more details.
a unified queue for notifications. This can be done in the configuration file
of all nodes. Refer to the :oslo.messaging-doc:`oslo.messaging configuration
documentation
<configuration/opts.html#oslo_messaging_notifications.transport_url>` for more
details.
Neutron Metadata API proxy
~~~~~~~~~~~~~~~~~~~~~~~~~~

10
doc/source/user/flavors.rst
View File

@@ -63,12 +63,10 @@ RXTX Factor
.. note::
This property only applies if using the `xen` compute driver with the
`nova-network` network driver. It will likely be deprecated in a future
release. `neutron` users should refer to the `neutron QoS
documentation`__.
__ https://docs.openstack.org/neutron/latest/admin/config-qos.html
This property only applies if using the ``xen`` compute driver with the
``nova-network`` network driver. It will likely be deprecated in a future
release. ``neutron`` users should refer to the :neutron-doc:`neutron QoS
documentation <admin/config-qos.html>`
Is Public
Boolean value that defines whether the flavor is available to all users or

10
doc/source/user/launch-instance-from-volume.rst
View File

@@ -35,10 +35,10 @@ To complete these tasks, use these parameters on the
.. note::
To attach a volume to a running instance, see
`Attach a volume to an instance`_.
To attach a volume to a running instance, refer to the
:cinder-doc:`Cinder documentation
<cli/cli-manage-volumes.html#attach-a-volume-to-an-instance>`.
.. _Attach a volume to an instance: https://docs.openstack.org/cinder/latest/cli/cli-manage-volumes.html#attach-a-volume-to-an-instance
.. _Boot_instance_from_image_and_attach_non-bootable_volume:
Boot instance from image and attach non-bootable volume
@@ -293,8 +293,8 @@ the volume to boot an instance.
This requires an encrypted volume type, which must be created ahead of
time by an admin. See
`Create an encrypted volume type <https://docs.openstack.org/horizon/latest/admin/manage-volumes.html#create-an-encrypted-volume-type>`_
time by an admin. Refer to
:horizon-doc:`admin/manage-volumes.html#create-an-encrypted-volume-type`.
in the OpenStack Horizon Administration Guide.
#. Create a VM from previously created bootable volume. The volume is not

2
nova/api/openstack/compute/rest_api_version_history.rst
View File

@@ -758,6 +758,8 @@ Added pagination support for migrations, there are four changes:
* The query parameter schema of the ``GET /os-migrations`` API no longer
allows additional properties.
.. _api-microversion-queens:
2.60 (Maximum in Queens)
------------------------

6
placement-api-ref/source/conf.py
View File

@@ -88,3 +88,9 @@ latex_documents = [
('index', 'Placement.tex', u'OpenStack Placement API Documentation',
u'OpenStack Foundation', 'manual'),
]
# -- Options for openstackdocstheme -------------------------------------------
openstack_projects = [
'nova',
]

4
placement-api-ref/source/index.rst
View File

@@ -5,8 +5,8 @@
===============
This is a reference for the OpenStack Placement API. To learn more about
OpenStack Placement API concepts, please refer to the
`Placement Introduction <https://docs.openstack.org/nova/latest/user/placement.html>`_.
OpenStack Placement API concepts, please refer to the :nova-doc:`Placement
Introduction <user/placement.html>`.
The Placement API uses JSON for data exchange. As such, the ``Content-Type``
header for APIs sending data payloads in the request body (i.e. ``PUT`` and