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

113 lines
3.6 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:`/reference/notifications`: How the notifications subsystem works in
nova, and considerations when adding notifications.
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.
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.
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
update-provider-tree
upgrade-checks
conductor
isolate-aggregates
api-microversion-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
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.
Remove cells v1 (for the most part) from the docs As discussed in the mailing list [1] since cells v1 has been deprecated since Pike and the biggest user of it (CERN as far as we know) moved to cells v2 in Queens, we can start rolling back the cells v1 specific documentation to avoid confusing people new to nova about what cells is and making them understand there was an optional v1. There are still a few mentions of cells v1 left in here for things like adding a new cell which need to be re-written and for that I've left a todo. Users can still get at cells v1 specific docs from published stable branches and/or rebuilding the docs from before this change. [1] http://lists.openstack.org/pipermail/openstack-discuss/2019-February/002569.html Change-Id: Idaa04a88b6883254cad9a8c6665e1c63a67e88d3
2019-02-13 13:59:09 -05:00
* :doc:`/user/cells`: How cells v2 is evolving
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/policy-enforcement`: How we want policy checks on API actions
to work in the future
* :doc:`/reference/stable-api`: What stable api means to nova
* :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:
/user/cells
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