use a more common rst header hiearchy
While rst doesn't actually care about the order of headers, reviewers
sometimes do. And the build in emacs mode has a certain order
specified that it can easily rotate between.
Standardize on == h1, = h2, - h3, ~ h4 in the code.
Change-Id: I80ff6df6ef0703a3c3005809069428018bb355d4
diff --git a/doc/source/changes.rst b/doc/source/changes.rst
index f4a326d..7b75375 100644
--- a/doc/source/changes.rst
+++ b/doc/source/changes.rst
@@ -3,7 +3,7 @@
=======
Recent Changes What's been happening?
--------------------------------------
+=====================================
These are the commits to DevStack for the last six months. For the
complete list see `the DevStack project in
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 7ca3d64..8c9e658 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -10,9 +10,9 @@
OpenStack project you are good to go.
Things To Know
-~~~~~~~~~~~~~~
+==============
-|
+|
| **Where Things Are**
The official DevStack repository is located at
@@ -30,7 +30,7 @@
is, however, used for all commits except for the text of this website.
That should also change in the near future.
-|
+|
| **HACKING.rst**
Like most OpenStack projects, DevStack includes a ``HACKING.rst`` file
@@ -38,7 +38,7 @@
``HACKING.rst`` is in the main DevStack repo it is considered
authoritative. Much of the content on this page is taken from there.
-|
+|
| **bashate Formatting**
Around the time of the OpenStack Havana release we added a tool to do
@@ -51,9 +51,9 @@
formatting. Run it on the entire project with ``./run_tests.sh``.
Code
-~~~~
+====
-|
+|
| **Repo Layout**
The DevStack repo generally keeps all of the primary scripts at the root
diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index b7943ba..f39471c 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -7,7 +7,7 @@
- `Miscellaneous <#misc>`__
General Questions
-~~~~~~~~~~~~~~~~~
+=================
Q: Can I use DevStack for production?
A: No. We mean it. Really. DevStack makes some implementation
@@ -77,7 +77,7 @@
is valuable so we do it...
Operation and Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================
Q: Can DevStack handle a multi-node installation?
A: Indirectly, yes. You run DevStack on each node with the
@@ -157,7 +157,7 @@
``FORCE_PREREQ=1`` and the package checks will never be skipped.
Miscellaneous
-~~~~~~~~~~~~~
+=============
Q: ``tools/fixup_stuff.sh`` is broken and shouldn't 'fix' just one version of packages.
A: [Another not-a-question] No it isn't. Stuff in there is to
diff --git a/doc/source/guides/multinode-lab.rst b/doc/source/guides/multinode-lab.rst
index 4c60b6a..44601d8 100644
--- a/doc/source/guides/multinode-lab.rst
+++ b/doc/source/guides/multinode-lab.rst
@@ -6,10 +6,10 @@
physical servers.
Prerequisites Linux & Network
------------------------------
+=============================
Minimal Install
-~~~~~~~~~~~~~~~
+---------------
You need to have a system with a fresh install of Linux. You can
download the `Minimal
@@ -27,7 +27,7 @@
apt-get install -y git sudo || yum install -y git sudo
Network Configuration
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
The first iteration of the lab uses OpenStack's FlatDHCP network
controller so only a single network will be required. It should be on
@@ -60,10 +60,10 @@
GATEWAY=192.168.42.1
Installation shake and bake
----------------------------
+===========================
Add the DevStack User
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
OpenStack runs as a non-root user that has sudo access to root. There is
nothing special about the name, we'll use ``stack`` here. Every node
@@ -88,7 +88,7 @@
``stack`` user.
Set Up Ssh
-~~~~~~~~~~
+----------
Set up the stack user on each node with an ssh key for access:
@@ -98,7 +98,7 @@
echo "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCyYjfgyPazTvGpd8OaAvtU2utL8W6gWC4JdRS1J95GhNNfQd657yO6s1AH5KYQWktcE6FO/xNUC2reEXSGC7ezy+sGO1kj9Limv5vrvNHvF1+wts0Cmyx61D2nQw35/Qz8BvpdJANL7VwP/cFI/p3yhvx2lsnjFE3hN8xRB2LtLUopUSVdBwACOVUmH2G+2BWMJDjVINd2DPqRIA4Zhy09KJ3O1Joabr0XpQL0yt/I9x8BVHdAx6l9U0tMg9dj5+tAjZvMAFfye3PJcYwwsfJoFxC8w/SLtqlFX7Ehw++8RtvomvuipLdmWCy+T9hIkl+gHYE4cS3OIqXH7f49jdJf jesse@spacey.local" > ~/.ssh/authorized_keys
Download DevStack
-~~~~~~~~~~~~~~~~~
+-----------------
Grab the latest version of DevStack:
@@ -112,7 +112,7 @@
(aka 'head node') and the compute nodes.
Configure Cluster Controller
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
The cluster controller runs all OpenStack services. Configure the
cluster controller's DevStack in ``local.conf``:
@@ -153,7 +153,7 @@
available in ``stack.sh.log``.
Configure Compute Nodes
-~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------
The compute nodes only run the OpenStack worker services. For additional
machines, create a ``local.conf`` with:
@@ -196,7 +196,7 @@
available in ``stack.sh.log``.
Cleaning Up After DevStack
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
Shutting down OpenStack is now as simple as running the included
``unstack.sh`` script:
@@ -223,10 +223,10 @@
sudo virsh list | grep inst | awk '{print $1}' | xargs -n1 virsh destroy
Options pimp your stack
------------------------
+=======================
Additional Users
-~~~~~~~~~~~~~~~~
+----------------
DevStack creates two OpenStack users (``admin`` and ``demo``) and two
tenants (also ``admin`` and ``demo``). ``admin`` is exactly what it
@@ -242,7 +242,7 @@
# Get admin creds
. openrc admin admin
-
+
# List existing tenants
keystone tenant-list
@@ -260,7 +260,7 @@
# keystone role-list
Swift
-~~~~~
+-----
Swift requires a significant amount of resources and is disabled by
default in DevStack. The support in DevStack is geared toward a minimal
@@ -280,7 +280,7 @@
it...) ``local.conf``.
Volumes
-~~~~~~~
+-------
DevStack will automatically use an existing LVM volume group named
``stack-volumes`` to store cloud-created volumes. If ``stack-volumes``
@@ -305,7 +305,7 @@
vgcreate stack-volumes /dev/sdc
Syslog
-~~~~~~
+------
DevStack is capable of using ``rsyslog`` to aggregate logging across the
cluster. It is off by default; to turn it on set ``SYSLOG=True`` in
@@ -319,7 +319,7 @@
SYSLOG_HOST=192.168.42.11
Using Alternate Repositories/Branches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
The git repositories for all of the OpenStack services are defined in
``stackrc``. Since this file is a part of the DevStack package changes
@@ -349,10 +349,10 @@
GLANCE_REPO=https://github.com/mcuser/glance.git
Notes stuff you might need to know
-----------------------------------
+==================================
Reset the Bridge
-~~~~~~~~~~~~~~~~
+----------------
How to reset the bridge configuration:
@@ -363,7 +363,7 @@
sudo brctl delbr br100
Set MySQL Password
-~~~~~~~~~~~~~~~~~~
+------------------
If you forgot to set the root password you can do this:
diff --git a/doc/source/guides/single-machine.rst b/doc/source/guides/single-machine.rst
index a7a1099..17e9b9e 100644
--- a/doc/source/guides/single-machine.rst
+++ b/doc/source/guides/single-machine.rst
@@ -7,10 +7,10 @@
with hardware.
Prerequisites Linux & Network
------------------------------
+=============================
Minimal Install
-~~~~~~~~~~~~~~~
+---------------
You need to have a system with a fresh install of Linux. You can
download the `Minimal
@@ -25,7 +25,7 @@
the interface(s) that OpenStack uses for bridging.
Network Configuration
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
Determine the network configuration on the interface used to integrate
your OpenStack cloud with your existing network. For example, if the IPs
@@ -36,10 +36,10 @@
of DHCP (i.e. 192.168.1.201).
Installation shake and bake
----------------------------
+===========================
Add your user
-~~~~~~~~~~~~~
+-------------
We need to add a user to install DevStack. (if you created a user during
install you can skip this step and just give the user sudo privileges
@@ -61,7 +61,7 @@
**login** as that user.
Download DevStack
-~~~~~~~~~~~~~~~~~
+-----------------
We'll grab the latest version of DevStack via https:
@@ -72,7 +72,7 @@
cd devstack
Run DevStack
-~~~~~~~~~~~~
+------------
Now to configure ``stack.sh``. DevStack includes a sample in
``devstack/samples/local.conf``. Create ``local.conf`` as shown below to
@@ -120,7 +120,7 @@
accounts and passwords to poke at your shiny new OpenStack.
Using OpenStack
-~~~~~~~~~~~~~~~
+---------------
At this point you should be able to access the dashboard from other
computers on the local network. In this example that would be
diff --git a/doc/source/guides/single-vm.rst b/doc/source/guides/single-vm.rst
index ef59953..a41c4e1 100644
--- a/doc/source/guides/single-vm.rst
+++ b/doc/source/guides/single-vm.rst
@@ -9,16 +9,16 @@
operation. Speed not required.
Prerequisites Cloud & Image
----------------------------
+===========================
Virtual Machine
-~~~~~~~~~~~~~~~
+---------------
DevStack should run in any virtual machine running a supported Linux
release. It will perform best with 2Gb or more of RAM.
OpenStack Deployment & cloud-init
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
If the cloud service has an image with ``cloud-init`` pre-installed, use
it. You can get one from `Ubuntu's Daily
@@ -33,10 +33,10 @@
bare-bones server installation.
Installation shake and bake
----------------------------
+===========================
Launching With Cloud-Init
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
This cloud config grabs the latest version of DevStack via git, creates
a minimal ``local.conf`` file and kicks off ``stack.sh``. It should be
@@ -79,13 +79,13 @@
to create a non-root user and run the ``start.sh`` script as that user.
Launching By Hand
-~~~~~~~~~~~~~~~~~
+-----------------
Using a hypervisor directly, launch the VM and either manually perform
the steps in the embedded shell script above or copy it into the VM.
Using OpenStack
-~~~~~~~~~~~~~~~
+---------------
At this point you should be able to access the dashboard. Launch VMs and
if you give them floating IPs access those VMs from other machines on
diff --git a/doc/source/overview.rst b/doc/source/overview.rst
index 4078240..23ccf27 100644
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@@ -13,10 +13,10 @@
"tested") going forward.
Supported Components
---------------------
+====================
Base OS
-~~~~~~~
+-------
*The OpenStack Technical Committee (TC) has defined the current CI
strategy to include the latest Ubuntu release and the latest RHEL
@@ -33,7 +33,7 @@
side-effects on other OS platforms.
Databases
-~~~~~~~~~
+---------
*As packaged by the host OS*
@@ -41,7 +41,7 @@
- PostgreSQL
Queues
-~~~~~~
+------
*As packaged by the host OS*
@@ -49,14 +49,14 @@
- Qpid
Web Server
-~~~~~~~~~~
+----------
*As packaged by the host OS*
- Apache
OpenStack Network
-~~~~~~~~~~~~~~~~~
+-----------------
*Default to Nova Network, optionally use Neutron*
@@ -65,7 +65,7 @@
mode using linuxbridge or OpenVSwitch.
Services
-~~~~~~~~
+--------
The default services configured by DevStack are Identity (Keystone),
Object Storage (Swift), Image Storage (Glance), Block Storage (Cinder),
@@ -77,14 +77,14 @@
scripts that perform the configuration and startup of the service.
Node Configurations
-~~~~~~~~~~~~~~~~~~~
+-------------------
- single node
- multi-node is not tested regularly by the core team, and even then
only minimal configurations are reviewed
Exercises
-~~~~~~~~~
+---------
The DevStack exercise scripts are no longer used as integration and gate
testing as that job has transitioned to Tempest. They are still
diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
index b4136c4..485cd0f 100644
--- a/doc/source/plugins.rst
+++ b/doc/source/plugins.rst
@@ -6,7 +6,7 @@
support for additional projects and features.
Extras.d Hooks
-~~~~~~~~~~~~~~
+==============
These hooks are an extension of the service calls in
``stack.sh`` at specific points in its run, plus ``unstack.sh`` and
@@ -93,7 +93,7 @@
but after ``unstack.sh`` has been called.
Hypervisor
-~~~~~~~~~~
+==========
Hypervisor plugins are fairly new and condense most hypervisor
configuration into one place.