openstack/tripleo-incubator
Code Issues Proposed changes

Switch to only one top-level heading per doc

Browse Source 
Some of our docs have many top-level headings, leading to confusing
toctrees.

To fix this I've found all the top-level headings (except the first,
which is the document title) and made them second-level headings, as
well as demoting all subheadings inside them.

The heading hierarchy is now:

=====
-----
^^^^^
~~~~~

Change-Id: Ie2dbba83d98608e0ad9699c003ac179e67d6da97
This commit is contained in:
James Polley 2014-07-03 05:29:50 +02:00
parent 8eb7bd6487
commit 90acd67c8a
2 changed files with 40 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
README.rst
View File

@ -245,10 +245,11 @@ allocation, and other essential operational tasks.
Development plan
================
----------------
Stage 1 - Implemented but not polished
--------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OpenStack on OpenStack with three distinct clouds:
@ -275,7 +276,7 @@ deploying behind firewalls and other restricted networking environments.
Enrollment of machines is manual, as is hardware setup including RAID.
Stage 2 - being worked on
-------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^
OpenStack on OpenStack with two distinct clouds. The seed cloud from stage 1
is replaced by a full HA configuration in the undercloud, permitting it to
@ -285,7 +286,7 @@ undercloud will be done using a seed cloud, but that will hand-off to the
undercloud and stop existing once the undercloud is live.
Stage N
-------
^^^^^^^
OpenStack on itself: OpenStack on OpenStack with one cloud:
@ -307,10 +308,10 @@ Infrastructure such as Glance, Swift and Keystone will be solely owned by the
one cloud: there is no duplication needed.
Developer introduction and guidelines
=====================================
-------------------------------------
Principles
----------
^^^^^^^^^^
1. Developer tools (like disk-image-builder) should have a non-intrusive
footprint on the machine of users. Requiring changing of global settings
@ -335,13 +336,13 @@ Principles
effort of other people.
Getting started
---------------
^^^^^^^^^^^^^^^
See the TripleO userguide for basic setup instructions - as a developer you
need to be set up as a user too.
Efficient development
---------------------
^^^^^^^^^^^^^^^^^^^^^
When working on overcloud features using virtual machines, just register all
your nodes directly with the seed - the seed and the undercloud are
@ -374,7 +375,7 @@ large and interfere with efficient development. Dive under and run the
core tools directly - that's what they are for.
Iterating on in-instance code
-----------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are broadly three sets of code for TripleO - the heat templates which
define the cluster, the code that runs within instances to map heat metadata
@ -386,7 +387,7 @@ them but then if it fails ssh into the instance, tweak the state and re-run the
code (e.g. by running ``os-collect-config --force --one``).
Iterating on heat templates
---------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can use heat stack-update to update a deployed stack which will take effect
immediately as long as the image id's have not changed - this permits testing
@ -394,7 +395,7 @@ different metadata mappings without waiting for full initial deployments to take
effect.
Iterating on post-deploy code
-----------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Generally speaking, just run API calls to put state back to whatever it would
be before your code runs. E.g. if you are testing nova flavor management code
@ -402,14 +403,14 @@ you might delete all the flavors and recreate the initial defaults, then just
run your specific code again.
Caveats
=======
-------
It is important to consider some unresolved issues in this plan.
.. _tested_platforms:
Tested platforms
----------------
^^^^^^^^^^^^^^^^
At this moment, the distributions that are tested by the CI systems are Ubuntu
and Fedora. Currently, we specifically test Ubuntu Trusty VMs and Fedora 20 VMs,
@ -430,7 +431,7 @@ If you use any other distribution not listed above, the script will identify
your machine as unsupported.
Security
--------
^^^^^^^^
Nova baremetal does nothing to secure transfers via PXE on the
network. This means that a node spoofing DHCP and TFTP on the provisioning
@ -445,7 +446,7 @@ SDN is in place. This carries the same attack vector as the PXE problems noted
above, and so should be given similar consideration.
Machine State
-------------
^^^^^^^^^^^^^
Currently there is no way to guarantee preservation (or deletion) of any of the
drive contents on a machine if it is deleted in nova baremetal. The planned

48
doc/source/deploying.rst
View File

@ -2,10 +2,10 @@ Deploying TripleO
=================
Components
==========
----------
Essential Components
--------------------
^^^^^^^^^^^^^^^^^^^^
Essential components make up the self-deploying infrastructure that is
the heart of TripleO.
@ -28,7 +28,7 @@ the heart of TripleO.
- Authentication and service catalog (Keystone)
Additional Components
---------------------
^^^^^^^^^^^^^^^^^^^^^
These components add value to the TripleO story, making it safer to
upgrade and evolve an environment, but are secondary to the core thing
@ -39,7 +39,7 @@ itself.
- Monitoring and alerting (Ceilometer/nagios/etc)
Dependencies
============
------------
Each component can only be deployed once its dependencies are available.
@ -50,7 +50,7 @@ number of vendors, which will permit you to run diskimage-builder to get
going.
Diskimage-builder
-----------------
^^^^^^^^^^^^^^^^^
An internet connection is also required to download the various packages
used in preparing each image.
@ -61,14 +61,14 @@ of TripleO is in use. Avoiding Heat is useful when doing a incremental
adoption of TripleO (see later in this document).
Baremetal machine deployment
----------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Baremetal deployments are delivered via Nova. Additionally, the network
must be configured so that the baremetal host machine can receive TFTP
from any physical machine that is being booted.
Nova
----
^^^^
Nova depends on Keystone, Glance and Neutron. In future Cinder will be
one of the dependencies.
@ -88,39 +88,39 @@ There are three ways the service can be deployed:
TripleO.
Cinder
------
^^^^^^
Cinder is needed for persistent storage on bare metal machines. That
aspect of TripleO is not yet available : when an instance is deleted,
the storage is deleted with it.
Neutron
-------
^^^^^^^
Neutron depends on Keystone. The same three deployment options exist as
for Nova. The Neutron network node(s) must be the only DHCP servers on
the network.
Glance
------
^^^^^^
Glance depends on Keystone. The same three deployment options exist as
for Nova.
Keystone
--------
^^^^^^^^
Keystone has no external dependencies. The same three deployment options
exist as for Nova.
Heat
----
^^^^
Heat depends on Nova, Cinder and Keystone. The same three deployment
options exist as for Nova.
In-instance configuration
-------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^
The os-config-applier and os-refresh-config tools depend on Heat to
provide cluster configuration metadata. They can be used before Heat is
@ -136,7 +136,7 @@ avoid conflicting when organisations with an investment in
Chef/Puppet/Salt start using TripleO.
Deploying TripleO incrementally
===============================
-------------------------------
The general sequence is:
@ -157,7 +157,7 @@ The general sequence is:
services onto it, and then continuing up the stack.
Current caveats / workarounds
=============================
-----------------------------
These are all documented in README.rst and in the
`TripleO bugtracker`_.
@ -165,7 +165,7 @@ These are all documented in README.rst and in the
.. _`TripleO bugtracker`: https://launchpad.net/tripleo
No API driven persistent storage
--------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Every 'nova boot' will reset the data on the machine it deploys to. To
do incremental image based updates they have to be done within the
@ -174,14 +174,14 @@ written rules to split out persistent data into another partition - so
some assembly required.
VLANs for physical nodes require customised images (rather than just metadata).
-------------------------------------------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you require VLANs you should create a diskimage-builder element to
add the vlan package and vlan configuration to /etc/network/interfaces
as a first-boot rule.
New seed image creation returns tmpfs space errors (systems with < 9GB of RAM)
------------------------------------------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Creating a new seed image takes up to 4.5GB of space inside a /tmp/imageXXXXX
directory. tmpfs can take up to 50% of RAM and systems with less than 9GB of
@ -196,10 +196,10 @@ prevent the space errors by:
If you are using ``boot-seed-vm``, set the environment variable ``DIB_NO_TMPFS=1``.
Example deployments (possible today)
====================================
------------------------------------
Baremetal only
--------------
^^^^^^^^^^^^^^
In this scenario you make use of the baremetal driver to deploy
unspecialised machine images, and perform specialisation using
@ -287,7 +287,7 @@ HOWTO
connect to your Chef/Puppet/Salt environments.
Baremetal with Heat
-------------------
^^^^^^^^^^^^^^^^^^^
In this scenario you use the baremetal driver to deploy specialised
machine images which are orchestrated by Heat.
@ -327,7 +327,7 @@ HOWTO
the image id of your cfn-tools customised image.
GRE Neutron OpenStack managed by Heat
-----------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In this scenario we build on Baremetal with Heat to deploy a full
OpenStack orchestrated by Heat, with specialised disk images for
@ -489,12 +489,12 @@ Deploy Overcloud
Follow devtest again, but modify the images you build per the undercloud notes, and for machines you put public services on, follow the undercloud notes to fix them up.
Example deployments (future)
============================
----------------------------
WARNING: Here be draft notes.
VM seed + bare metal under cloud
--------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- need to be aware nova metadata wont be available after booting as the
default rule assumes this host never initiates requests