From 3293046d3091e7017beafe92bfe361e6d204bfb1 Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Tue, 18 Nov 2014 06:51:16 -0500 Subject: [PATCH] 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 --- doc/source/changes.rst | 2 +- doc/source/contributing.rst | 12 ++++----- doc/source/faq.rst | 6 ++--- doc/source/guides/multinode-lab.rst | 40 ++++++++++++++-------------- doc/source/guides/single-machine.rst | 16 +++++------ doc/source/guides/single-vm.rst | 14 +++++----- doc/source/overview.rst | 18 ++++++------- doc/source/plugins.rst | 4 +-- 8 files changed, 56 insertions(+), 56 deletions(-) diff --git a/doc/source/changes.rst b/doc/source/changes.rst index f4a326d60e..7b753753e5 100644 --- a/doc/source/changes.rst +++ b/doc/source/changes.rst @@ -3,7 +3,7 @@ Changes ======= 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 7ca3d64afd..8c9e6584ec 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -10,9 +10,9 @@ License Agreement (CLA). If you have already done that for another OpenStack project you are good to go. Things To Know -~~~~~~~~~~~~~~ +============== -| +| | **Where Things Are** The official DevStack repository is located at @@ -30,7 +30,7 @@ queue `__ 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 @@ that describes the layout, style and conventions of the project. Because ``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 @@ the script pages for devstack.org and possibly even simple code 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 b7943ba130..f39471cb4e 100644 --- a/doc/source/faq.rst +++ b/doc/source/faq.rst @@ -7,7 +7,7 @@ FAQ - `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 @@ Q: How about RHEL 6? 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 @@ Q: Why are my configuration changes ignored? ``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 4c60b6a745..44601d8713 100644 --- a/doc/source/guides/multinode-lab.rst +++ b/doc/source/guides/multinode-lab.rst @@ -6,10 +6,10 @@ Here is OpenStack in a realistic test configuration with multiple 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 @@ Install a couple of packages to bootstrap configuration: 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 @@ For Fedora and CentOS/RHEL edit 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 @@ From here on use the ``stack`` user. **Logout** and **login** as the ``stack`` user. Set Up Ssh -~~~~~~~~~~ +---------- Set up the stack user on each node with an ssh key for access: @@ -98,7 +98,7 @@ Set up the stack user on each node with an ssh key for access: 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 @@ From here on there are some differences between the cluster controller (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 @@ to poke at your shiny new OpenStack. The most recent log file is 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 @@ to poke at your shiny new OpenStack. The most recent log file is 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 @@ this when it runs but there are times it needs to still be done by hand: 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 @@ for scripting: # Get admin creds . openrc admin admin - + # List existing tenants keystone tenant-list @@ -260,7 +260,7 @@ for scripting: # 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 @@ Swift config files are located in ``SWIFT_CONFIG_DIR`` (default 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 @@ involved but looks something like this: 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 @@ output there. In the example above, add this to the compute node 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 @@ To pull Glance from an experimental fork: 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 @@ How to reset the bridge configuration: 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 a7a1099bc7..17e9b9e153 100644 --- a/doc/source/guides/single-machine.rst +++ b/doc/source/guides/single-machine.rst @@ -7,10 +7,10 @@ nice for kicking the tires, but doesn't compare to the feeling you get 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 @@ work but you may need to tell Network Manager to keep its fingers off 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 @@ To make things easier later change your host to use a static IP instead 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 @@ From here on you should use the user you created. **Logout** and **login** as that user. Download DevStack -~~~~~~~~~~~~~~~~~ +----------------- We'll grab the latest version of DevStack via https: @@ -72,7 +72,7 @@ We'll grab the latest version of DevStack via https: 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 @@ see a summary of ``stack.sh``'s work, including the relevant URLs, 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 ef59953eb6..a41c4e14f1 100644 --- a/doc/source/guides/single-vm.rst +++ b/doc/source/guides/single-vm.rst @@ -9,16 +9,16 @@ launched in the cloud will be slow as they are running in QEMU 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 @@ can manually kick off the script below as a non-root user in a 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 @@ As DevStack will refuse to run as root, this configures ``cloud-init`` 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 40782403fa..23ccf27d0a 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -13,10 +13,10 @@ Below is a list of what is specifically is supported (read that as "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 @@ release (for Python 2.6 testing).* side-effects on other OS platforms. Databases -~~~~~~~~~ +--------- *As packaged by the host OS* @@ -41,7 +41,7 @@ Databases - PostgreSQL Queues -~~~~~~ +------ *As packaged by the host OS* @@ -49,14 +49,14 @@ Queues - Qpid Web Server -~~~~~~~~~~ +---------- *As packaged by the host OS* - Apache OpenStack Network -~~~~~~~~~~~~~~~~~ +----------------- *Default to Nova Network, optionally use Neutron* @@ -65,7 +65,7 @@ OpenStack Network 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 @@ Additional services not included directly in DevStack can be tied in to 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 b4136c4653..485cd0f04e 100644 --- a/doc/source/plugins.rst +++ b/doc/source/plugins.rst @@ -6,7 +6,7 @@ DevStack has a couple of plugin mechanisms to allow easily adding 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 @@ The arguments are: but after ``unstack.sh`` has been called. Hypervisor -~~~~~~~~~~ +========== Hypervisor plugins are fairly new and condense most hypervisor configuration into one place.