I did not have a clear understanding of when a security group would or
would not be applied to a port and reading the documentation did not
help. Massively expand the security groups document, adding a couple of
important notes along the way as well as references to the nova-specific
security group operations. The document is moved from the admin guide to
the user guide (with redirects) since these are not admin-only
operations by default.
Change-Id: I212bc99112aad2f1e3057befca381a26d702be2e
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
That's one giant hole in our docs. Whoops.
Change-Id: I8ac6f204dd3ebe424dfe4335a491b8c9df7d0cc4
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
As with the cells v2 docs before this, we have a number of architecture
focused documents in tree. The 'user/architecture' guide is relatively
up-to-date but is quite shallow, while the 'admin/arch' guide is
in-depth but almost a decade out-of-date, with references to things
like nova's in-built block storage service. Replace most of the latter
with more up-to-date information and the merge the former into it,
before renaming the file to 'admin/architecture'.
Change-Id: I518bb5d586b159b4796fb6139351ba423bc19639
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
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>
Take the opportunity to clean up the docs quite a bit, ultimately
combining two disparate guides on the scheduler into one.
Change-Id: Ia72d39b4774d93793b381359b554c717dc9a6994
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
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>
This change simply extracts and slightly reorders the existing rescue
documentation from the reboot reference page.
Closes-Bug: #1852609
Change-Id: I4ce8874aa3e879e89ab5c7c76162561acbdea5c4
This is a follow up to [1]. The user docs home page has a link
to the admin AZ guide but not a direct link to the user AZ guide
so that is added here.
[1] https://review.opendev.org/#/c/667133/10/doc/source/user/index.rst@75
Change-Id: I4acb120d2e347a43abc584107c7a19bb422af384
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
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>
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
Turns out we've a *lot* of disparate metadata systems. Attempt to both
link them somewhat through extensive cross-referencing and extract out
deployment-specific stuff from user-facing docs. Lots of changes here,
but in summary:
- Split out admin-focused content from the metadata API, config drive,
user data and vendordata docs.
- Merge the config drive, metadata service, vendordata and user-data
user docs, which are mostly talking about the same thing and are
fairly barren without the deployment components
- Make use of various oslo.config and Sphinx roles
Side note: I miss when we have tech writers to do this stuff for us :(
Change-Id: I4fb2b628bd93358a752e2397ae353221758e2984
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
Placement documents have been published since
I667387ec262680af899a628520c107fa0d4eec24.
So use links to placement documents
https://docs.openstack.org/placement/latest/
in nova documents.
Change-Id: I218a6d11fea934e8991e41b4b36203c6ba3e3dbf
The admin config resize doc was linking to a now non-existent
user guide doc which was deleted in pike. This change imports
the resize user guide from the openstack-manuals stable/ocata
branch, fixes the link, and updates the resize user doc to
(1) link to our internal shutdown_timeout config option reference
and (2) link to the image properties doc in glance for the
os_shutdown_timeout image property.
Change-Id: I9988abfd344d1d3b0b6eaf32b036369b51853965
Closes-Bug: #1784715
this document is out of date since a set of changes made such as
43f91a87cb39f6159bde8be8d02aa7
Put those 'to be fixed in queens' make people think it should
be already been fixed due to queen release, so remove them in order
to avoid confusion and we can continue to enhance this doc.
TrivialFix
Change-Id: I12dd385f4e1f159bdb9a78a629d4095889397c09
The metadata service docs were hard to find since they were nested
down in some nova-network admin guide docs, and they were a mix of
end user and admin deployment guide information.
This change splits out the end-user facing content into a user
guide and leaves the deployment-specific information in the admin
guide, and links are updated appropriately.
The admin guide portion also referenced some config options that no
longer exist, so those are also removed and vendordata_providers
is added with a link to the vendordata guide. The options themselves
are cleaned up for their current groups and linked to the config option
docs.
Change-Id: I66035366f3a7ca62ea12d6afa74d13db01ec9f8d
This imports the "launch instance" end user guide docs from
the openstack-manuals repo. As part of the docs migration
in Pike, these were forgotten. The copied contents come from
the stable/ocata branch of openstack-manuals, and therefore
likely need some updating, but that could be done in follow up
changes. This is an initial import to (1) publish the content
again somewhere and (2) fix broken links in the cinder docs
for booting from volume.
Change-Id: Ie039322660fd0e2e0403843448379b78114c425b
Partial-Bug: #1714017
Related-Bug: #1711267
Underscores make for really ugly URLs and every other document here is
now using hyphens for this very reason. Let's try to keep that going.
Change-Id: I5c99ff6b04ee97bac210a0d6762015225775c5ee
The idea is that each guide should be self contained, even though we can
link between them. Enforce this by duplicating a lot of the content from
the main index page to the user index page.
Change-Id: I160fed0f1b507eba7958666bf38f4138b0f62b3a
Stephen Finucane