openstack/nova
Code Issues Proposed changes
9a31212a44
nova/doc/source/reference/index.rst

121 lines
4.0 KiB
ReStructuredText
Raw Normal View History

Create reference subpage In an attempt to make the main navigation sidebar not be visual mud (and really confusing) create a reference sub page that explains all the references. Part of bp: doc-migration Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
2017-08-04 13:18:41 -04:00
================================
Technical Reference Deep Dives
================================
The nova project is large, and there are lots of complicated parts in it where
it helps to have an overview to understand how the internals of a particular
part work.
doc: cleanup references to conductor doc The conductor doc is not really end user material, so this moves it under reference/, removes it from the user page and adds it to the reference index for internals. Also makes the contributor page link to the reference internals since it's kind of weird to have one contributor section that only mentions one thing but the internals under reference have a lot more of that kind of detail. Finally, a todo is added so we don't forget to update the reference internals about versioned objects at some point since that's always a point of confusion for people. Change-Id: I8d3dbce5334afaa3e1ca309b2669eff9933a0104
2019-09-05 18:37:31 -04:00
.. _reference-internals:
Create reference subpage In an attempt to make the main navigation sidebar not be visual mud (and really confusing) create a reference sub page that explains all the references. Part of bp: doc-migration Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
2017-08-04 13:18:41 -04:00
Internals
=========
The following is a dive into some of the internals in nova.
* :doc:`/reference/rpc`: How nova uses AMQP as an RPC transport
docs: Document the scheduler workflow There have been some major changes to how scheduling works in Nova during the Pike and Queens cycles. This documents these design changes so that this new, more complex workflow is clearly spelled out. Co-Authored-By: Ed Leafe <ed@leafe.com> Change-Id: I15121d8fe9b715c0aec39dee4bfdf25ced42b481
2017-08-23 09:59:54 +01:00
* :doc:`/reference/scheduling`: The workflow through the scheduling process
Document differences and similaries between extra specs and hints Scheduler hints are not really documented very well at all except for being mentioned per scheduler filter in the admin configuration guide, nor are they documented within relation to flavor extra specs which are both used for impacting scheduling decisions and are choices that a deployer has to make based on how they configure their cloud. This change adds a document about scheduler hints and how they are similar to and different from flavor extra specs, including end user discoverability and interoperability, and thoughts on which should be used if writing a custom scheduler filter. The TODO in the API guide is also resolved by linking to this document. Change-Id: Ib1f35baacf59efafb9e4bccfcc4f0025d99ad5b2
2018-07-10 11:20:10 -04:00
* :doc:`/reference/scheduler-hints-vs-flavor-extra-specs`: The similarities
and differences between flavor extra specs and scheduler hints.
Live Migration sequence diagram Based on mriedem's hand-drawn version [1] (but not as pretty). [1] https://photos.google.com/share/AF1QipNpWVQKU8GK4_9wxVbiRJUqJnMzqPcBh6DvjVyBPIjjmi6ZU8r9TleQNo6pV1t9SA?key=NUl3OUFGYkRFTE8tMHhSX0lfc0Y1eEdoeHo4SUhn Co-Authored-By: Matt Riedemann <mriedem.os@gmail.com> Change-Id: I63046079cd3135b4b19c0c6745075f090d04e396
2017-09-21 15:57:09 -05:00
* :doc:`/reference/live-migration`: The live migration flow
Create reference subpage In an attempt to make the main navigation sidebar not be visual mud (and really confusing) create a reference sub page that explains all the references. Part of bp: doc-migration Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
2017-08-04 13:18:41 -04:00
* :doc:`/reference/services`: Module descriptions for some of the key modules
used in starting / running services
* :doc:`/reference/vm-states`: Cheat sheet for understanding the life cycle of
compute instances
* :doc:`/reference/threading`: The concurrency model used in nova, which is
based on eventlet, and may not be familiar to everyone.
doc: Split up notifications document This was actually three documents in one: - An admin doc detailing how to configure and use notifications - A contributor doc describing how to extend the versioned notifications - A reference doc listing available versioned notifications Split the doc up to reflect this Change-Id: I880f1c77387efcc3c1e147323b224e10156e0a52 Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
2021-11-09 14:55:54 +00:00
* :doc:`/reference/notifications`: The notifications available in nova.
update_provider_tree devref and docstring updates Design changes [1] from the Dublin PTG prompted some rewording of the docstring for ComputeDriver.update_provider_tree. And to avoid that docstring becoming too enormous, relevant chunks of the spec [2] are copied to a new devref document which is linked from that docstring. [1] https://review.openstack.org/#/c/552122/ [2] http://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/update-provider-tree.html Change-Id: I06504aa2a3fe6d39ecc1e681de43be8fee9e06f6 blueprint: update-provider-tree
2018-03-15 11:40:09 -05:00
* :doc:`/reference/update-provider-tree`: A detailed explanation of the
``ComputeDriver.update_provider_tree`` method.
Add contributor guide for upgrade status checks This adds some background, guidelines and structural notes on writing nova-status upgrade checks. This is intentionally written with some potentially redundant information or nova developers as it's also meant to be consumed outside nova as part of the community-wide "upgrade-checkers" goal for Stein [1]. Story: 2003570 [1] https://governance.openstack.org/tc/goals/stein/upgrade-checkers.html Change-Id: I340b25edeab3ac19c5d0bedfc69acd037d57bdd2
2018-08-27 17:19:30 -04:00
* :doc:`/reference/upgrade-checks`: A guide to writing automated upgrade
checks.
docs: Add documentation on database migrations Alembic does lots of new things. Provide docs for how to use this. We also improve upgrade docs slightly, removing references to ancient reviews that are no longer really helpful as well as calling out our N -> N+1 constraint. Change-Id: I3760b82ce3bd71aa0a760d7137d69dfa3f29dc1d Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
2021-07-08 16:10:49 +01:00
* :doc:`/reference/database-migrations`: A guide to writing database
migrations, be they online or offline.
doc: cleanup references to conductor doc The conductor doc is not really end user material, so this moves it under reference/, removes it from the user page and adds it to the reference index for internals. Also makes the contributor page link to the reference internals since it's kind of weird to have one contributor section that only mentions one thing but the internals under reference have a lot more of that kind of detail. Finally, a todo is added so we don't forget to update the reference internals about versioned objects at some point since that's always a point of confusion for people. Change-Id: I8d3dbce5334afaa3e1ca309b2669eff9933a0104
2019-09-05 18:37:31 -04:00
* :doc:`/reference/conductor`
.. todo:: Need something about versioned objects and how they fit in with
conductor as an object backporter during upgrades.
Create reference subpage In an attempt to make the main navigation sidebar not be visual mud (and really confusing) create a reference sub page that explains all the references. Part of bp: doc-migration Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
2017-08-04 13:18:41 -04:00
Docs for isolated aggregates request filter Added reference documentation and release note to explain how filtering of hosts by isolate aggregates works. Change-Id: I8d8086973039308f9041a36463a834b5275708e3 Implements: blueprint placement-req-filter-forbidden-aggregates
2019-07-15 18:31:46 +05:30
* :doc:`/reference/isolate-aggregates`: Describes how the placement filter
works in nova to isolate groups of hosts.
Add os-volume_attachments reference docs This change adds a simple sequence diagram showing the flow of a volume attachment between the various services, using the libvirt driver as an example virt driver. Change-Id: I631ac9de3d48aa0ad849f6615d0ad2052cb63e80
2020-11-02 17:28:26 +00:00
* :doc:`/reference/attach-volume`: Describes the attach volume flow, using the
libvirt virt driver as an example.
docs: Add reference docs for internal block device structures It's time to shine a light on this area of the codebase ahead of some much required cleanup. This documentation is based on an email sent almost 5 years ago but is still accurate today. Change-Id: I66cc2c5549833f269872748fb1532438f9ba8489
2021-01-20 14:52:27 +00:00
* :doc:`/reference/block-device-structs`: Block Device Data Structures
docs: Move the LibvirtDistroSupportMatrix wiki page into our docs This change moves the LibvirtDistroSupportMatrix [1] wiki page into the tree as a reference doc. The wiki page will be decommissioned once this change lands and is published. Some older distro information is removed to keep the table readable and a note is added to driver.py to ensure it updated with each version bump. [1] https://wiki.openstack.org/wiki/LibvirtDistroSupportMatrix Change-Id: Id49a4e400159130fbc676800aeca6b9746071a2e
2021-01-22 13:50:47 +00:00
* :doc:`/reference/libvirt-distro-support-matrix`: Libvirt virt driver OS
distribution support matrix
Docs for isolated aggregates request filter Added reference documentation and release note to explain how filtering of hosts by isolate aggregates works. Change-Id: I8d8086973039308f9041a36463a834b5275708e3 Implements: blueprint placement-req-filter-forbidden-aggregates
2019-07-15 18:31:46 +05:30
doc: Improve PDF document structure This is a follow-up patch for https://review.opendev.org/676730. In the TOC of the current PDF file [1], most contents related to user and admin guides are located under "For Contributors" section. This is weird. It happens because the latex builder constructs the document tree based on "toctree" directives even though they are marked as "hidden". This commit reorganizes "toctree" per section. The "toctree" directives must be placed at the end of individual sections. Otherwise, content of a last section and content just after "toctree" directive are concatenated into a same section in the rendered LaTeX document. This commit also improves the following as well: * Specify "openany" as "extraclassoptions" to skip blank pages along with "oneside" to use same page style for odd and even pages. * Set "tocdepth" and "secnumdepth" to 3 respectively. "tocdepth" controls the depth of TOC and "secnumdepth" controls the level of numbered sections in TOC. Note that this commit does not reorganize file structure under doc/source. I believe this should be done separately. [1] https://docs.openstack.org/nova/latest/doc-nova.pdf Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c Story: 2006100 Task: 35140
2019-09-18 06:01:51 +09:00
.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to
# keep the document structure in the PDF doc.
.. toctree::
:hidden:
rpc
scheduling
scheduler-hints-vs-flavor-extra-specs
live-migration
services
vm-states
threading
notifications
docs: Add documentation on database migrations Alembic does lots of new things. Provide docs for how to use this. We also improve upgrade docs slightly, removing references to ancient reviews that are no longer really helpful as well as calling out our N -> N+1 constraint. Change-Id: I3760b82ce3bd71aa0a760d7137d69dfa3f29dc1d Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
2021-07-08 16:10:49 +01:00
database-migrations
doc: Improve PDF document structure This is a follow-up patch for https://review.opendev.org/676730. In the TOC of the current PDF file [1], most contents related to user and admin guides are located under "For Contributors" section. This is weird. It happens because the latex builder constructs the document tree based on "toctree" directives even though they are marked as "hidden". This commit reorganizes "toctree" per section. The "toctree" directives must be placed at the end of individual sections. Otherwise, content of a last section and content just after "toctree" directive are concatenated into a same section in the rendered LaTeX document. This commit also improves the following as well: * Specify "openany" as "extraclassoptions" to skip blank pages along with "oneside" to use same page style for odd and even pages. * Set "tocdepth" and "secnumdepth" to 3 respectively. "tocdepth" controls the depth of TOC and "secnumdepth" controls the level of numbered sections in TOC. Note that this commit does not reorganize file structure under doc/source. I believe this should be done separately. [1] https://docs.openstack.org/nova/latest/doc-nova.pdf Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c Story: 2006100 Task: 35140
2019-09-18 06:01:51 +09:00
update-provider-tree
upgrade-checks
conductor
isolate-aggregates
api-microversion-history
Add os-volume_attachments reference docs This change adds a simple sequence diagram showing the flow of a volume attachment between the various services, using the libvirt driver as an example virt driver. Change-Id: I631ac9de3d48aa0ad849f6615d0ad2052cb63e80
2020-11-02 17:28:26 +00:00
attach-volume
docs: Add reference docs for internal block device structures It's time to shine a light on this area of the codebase ahead of some much required cleanup. This documentation is based on an email sent almost 5 years ago but is still accurate today. Change-Id: I66cc2c5549833f269872748fb1532438f9ba8489
2021-01-20 14:52:27 +00:00
block-device-structs
docs: Move the LibvirtDistroSupportMatrix wiki page into our docs This change moves the LibvirtDistroSupportMatrix [1] wiki page into the tree as a reference doc. The wiki page will be decommissioned once this change lands and is published. Some older distro information is removed to keep the table readable and a note is added to driver.py to ensure it updated with each version bump. [1] https://wiki.openstack.org/wiki/LibvirtDistroSupportMatrix Change-Id: Id49a4e400159130fbc676800aeca6b9746071a2e
2021-01-22 13:50:47 +00:00
libvirt-distro-support-matrix
doc: Improve PDF document structure This is a follow-up patch for https://review.opendev.org/676730. In the TOC of the current PDF file [1], most contents related to user and admin guides are located under "For Contributors" section. This is weird. It happens because the latex builder constructs the document tree based on "toctree" directives even though they are marked as "hidden". This commit reorganizes "toctree" per section. The "toctree" directives must be placed at the end of individual sections. Otherwise, content of a last section and content just after "toctree" directive are concatenated into a same section in the rendered LaTeX document. This commit also improves the following as well: * Specify "openany" as "extraclassoptions" to skip blank pages along with "oneside" to use same page style for odd and even pages. * Set "tocdepth" and "secnumdepth" to 3 respectively. "tocdepth" controls the depth of TOC and "secnumdepth" controls the level of numbered sections in TOC. Note that this commit does not reorganize file structure under doc/source. I believe this should be done separately. [1] https://docs.openstack.org/nova/latest/doc-nova.pdf Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c Story: 2006100 Task: 35140
2019-09-18 06:01:51 +09:00
Create reference subpage In an attempt to make the main navigation sidebar not be visual mud (and really confusing) create a reference sub page that explains all the references. Part of bp: doc-migration Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
2017-08-04 13:18:41 -04:00
Debugging
=========
* :doc:`/reference/gmr`: Inspired by Amiga, a way to trigger a very
comprehensive dump of a running service for deep debugging.
doc: Improve PDF document structure This is a follow-up patch for https://review.opendev.org/676730. In the TOC of the current PDF file [1], most contents related to user and admin guides are located under "For Contributors" section. This is weird. It happens because the latex builder constructs the document tree based on "toctree" directives even though they are marked as "hidden". This commit reorganizes "toctree" per section. The "toctree" directives must be placed at the end of individual sections. Otherwise, content of a last section and content just after "toctree" directive are concatenated into a same section in the rendered LaTeX document. This commit also improves the following as well: * Specify "openany" as "extraclassoptions" to skip blank pages along with "oneside" to use same page style for odd and even pages. * Set "tocdepth" and "secnumdepth" to 3 respectively. "tocdepth" controls the depth of TOC and "secnumdepth" controls the level of numbered sections in TOC. Note that this commit does not reorganize file structure under doc/source. I believe this should be done separately. [1] https://docs.openstack.org/nova/latest/doc-nova.pdf Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c Story: 2006100 Task: 35140
2019-09-18 06:01:51 +09:00
.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to
# keep the document structure in the PDF doc.
.. toctree::
:hidden:
gmr
Create reference subpage In an attempt to make the main navigation sidebar not be visual mud (and really confusing) create a reference sub page that explains all the references. Part of bp: doc-migration Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
2017-08-04 13:18:41 -04:00
Forward Looking Plans
=====================
The following section includes documents that describe the overall plan behind
groups of nova-specs. Most of these cover items relating to the evolution of
various parts of nova's architecture. Once the work is complete,
these documents will move into the "Internals" section.
If you want to get involved in shaping the future of nova's architecture,
these are a great place to start reading up on the current plans.
* :doc:`/reference/policy-enforcement`: How we want policy checks on API actions
to work in the future
docs: Add a new cells v2 document We currently have three cells v2 documents in-tree: - A 'user/cellsv2-layout' document that details the structure or architecture of a cells v2 deployment (which is to say, any modern nova deployment) - A 'user/cells' document, which is written from a pre-cells v2 viewpoint and details the changes that cells v2 *will* require and the benefits it *would* bring. It also includes steps for upgrading from pre-cells v2 (that is, pre-Pike) deployment or a deployment with cells v1 (which we removed in Train and probably broke long before) - An 'admin/cells' document, which doesn't contain much other than some advice for handling down cells Clearly there's a lot of cruft to be cleared out as well as some centralization of information that's possible. As such, we combine all of these documents into one document, 'admin/cells'. This is chosen over 'users/cells' since cells are not an end-user-facing feature. References to cells v1 and details on upgrading from pre-cells v2 deployments are mostly dropped, as are some duplicated installation/configuration steps. Formatting is fixed and Sphinx-isms used to cross reference config option where possible. Finally, redirects are added so that people can continue to find the relevant resources. The result is (hopefully) a one stop shop for all things cells v2-related that operators can use to configure and understand their deployments. Change-Id: If39db50fd8b109a5a13dec70f8030f3663555065 Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
2021-07-09 17:58:52 +01:00
* :doc:`/reference/stable-api`: What stable API means to nova
Create reference subpage In an attempt to make the main navigation sidebar not be visual mud (and really confusing) create a reference sub page that explains all the references. Part of bp: doc-migration Change-Id: I005fc24e49487631d7fe73cb498c61619bcaac9d
2017-08-04 13:18:41 -04:00
* :doc:`/reference/scheduler-evolution`: Motivation behind the scheduler /
placement evolution
docs: Rewrite host aggregate, availability zone docs These closely related features are the source of a disproportionate number of bugs and a large amount of confusion among users. The spread of information around multiple docs probably doesn't help matters. Do what we've already done for the metadata service and remote consoles and clean these docs up. There are a number of important changes: - All documentation related to host aggregates and availability zones is placed in one of three documents, '/user/availability-zones', '/admin/aggregates' and '/admin/availability-zones'. (note that there is no '/user/aggregates' document since this is not user-facing) - References to these features are updated to point to the new location - A glossary is added. Currently this only contains definitions for host aggregates and availability zones - nova CLI commands are replaced with their openstack CLI counterparts - Some gaps in related documentation are closed Change-Id: If847b0085dbfb4c813d4a8d14d99346f8252bc19 Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
2019-06-24 15:23:44 +01:00
doc: Improve PDF document structure This is a follow-up patch for https://review.opendev.org/676730. In the TOC of the current PDF file [1], most contents related to user and admin guides are located under "For Contributors" section. This is weird. It happens because the latex builder constructs the document tree based on "toctree" directives even though they are marked as "hidden". This commit reorganizes "toctree" per section. The "toctree" directives must be placed at the end of individual sections. Otherwise, content of a last section and content just after "toctree" directive are concatenated into a same section in the rendered LaTeX document. This commit also improves the following as well: * Specify "openany" as "extraclassoptions" to skip blank pages along with "oneside" to use same page style for odd and even pages. * Set "tocdepth" and "secnumdepth" to 3 respectively. "tocdepth" controls the depth of TOC and "secnumdepth" controls the level of numbered sections in TOC. Note that this commit does not reorganize file structure under doc/source. I believe this should be done separately. [1] https://docs.openstack.org/nova/latest/doc-nova.pdf Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c Story: 2006100 Task: 35140
2019-09-18 06:01:51 +09:00
.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to
# keep the document structure in the PDF doc.
.. toctree::
:hidden:
policy-enforcement
stable-api
scheduler-evolution
docs: Rewrite host aggregate, availability zone docs These closely related features are the source of a disproportionate number of bugs and a large amount of confusion among users. The spread of information around multiple docs probably doesn't help matters. Do what we've already done for the metadata service and remote consoles and clean these docs up. There are a number of important changes: - All documentation related to host aggregates and availability zones is placed in one of three documents, '/user/availability-zones', '/admin/aggregates' and '/admin/availability-zones'. (note that there is no '/user/aggregates' document since this is not user-facing) - References to these features are updated to point to the new location - A glossary is added. Currently this only contains definitions for host aggregates and availability zones - nova CLI commands are replaced with their openstack CLI counterparts - Some gaps in related documentation are closed Change-Id: If847b0085dbfb4c813d4a8d14d99346f8252bc19 Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
2019-06-24 15:23:44 +01:00
Additional Information
======================
* :doc:`/reference/glossary`: A quick reference guide to some of the terms you
might encounter working on or using nova.
doc: Improve PDF document structure This is a follow-up patch for https://review.opendev.org/676730. In the TOC of the current PDF file [1], most contents related to user and admin guides are located under "For Contributors" section. This is weird. It happens because the latex builder constructs the document tree based on "toctree" directives even though they are marked as "hidden". This commit reorganizes "toctree" per section. The "toctree" directives must be placed at the end of individual sections. Otherwise, content of a last section and content just after "toctree" directive are concatenated into a same section in the rendered LaTeX document. This commit also improves the following as well: * Specify "openany" as "extraclassoptions" to skip blank pages along with "oneside" to use same page style for odd and even pages. * Set "tocdepth" and "secnumdepth" to 3 respectively. "tocdepth" controls the depth of TOC and "secnumdepth" controls the level of numbered sections in TOC. Note that this commit does not reorganize file structure under doc/source. I believe this should be done separately. [1] https://docs.openstack.org/nova/latest/doc-nova.pdf Change-Id: Ie9685e6a4798357d4979aa6b4ff8a03663a9c71c Story: 2006100 Task: 35140
2019-09-18 06:01:51 +09:00
.. # NOTE(amotoki): toctree needs to be placed at the end of the secion to
# keep the document structure in the PDF doc.
.. toctree::
:hidden:
glossary
Copy Permalink