Add sphinx documentation

In support of building the docs without the sphinx Makefile this also adds as
tox.ini that can be used to build the docs via:

tox -e docs

A few updates to setup.cfg are needed as well to acount for deleting old
scripts.

Change-Id: Ifa852f9684998ee695188d3e72df7cdc3c5e063e
This commit is contained in:
James Slagle 2015-02-25 12:49:26 -05:00
parent 25a6972fd5
commit ed5257972a
14 changed files with 586 additions and 2 deletions

View File

@ -0,0 +1,84 @@
Baremetal Environment Setup
===========================
instack-undercloud can be deployed in an all baremetal environment. One
baremetal node will be used as the undercloud, and other available baremetal
nodes will be used for the Overcloud deployment.
Minimum System Requirements
---------------------------
In order to produce a usable OpenStack install this setup requires five
baremetal machines: one machine for the undercloud, and one machine for each
Overcloud node.
.. image:: images/InstackSetup.png
The setup requires baremetal machines with the following minimum specifications:
* multi-core CPU
* 4GB memory
* 60GB free disk space
The undercloud machine needs to run RHEL 7.1 x86_64, which is discussed more below.
Preparing the Baremetal Environment
-----------------------------------
Networking
^^^^^^^^^^
The overcloud nodes will be deployed from the undercloud machine and therefore the machines need to have have their network settings modified to allow for the overcloud nodes to be PXE boot'ed using the undercloud machine. As such, the setup requires that:
* All overcloud machines in the setup must support IPMI
* A management provisioning network is setup for all of the overcloud machines.
One NIC from every machine needs to be in the same broadcast domain of the
provisioning network. In the tested environment, this required setting up a new
VLAN on the switch. Note that you should use the same NIC on each of the
overcloud machines ( for example: use the second NIC on each overcloud
machine). This is because during installation we will need to refer to that NIC
using a single name across all overcloud machines e.g. em2
* The provisioning network NIC should not be the same NIC that you are using
for remote connectivity to the undercloud machine. During the undercloud
installation, a openvswitch bridge will be created for Neutron and the
provisioning NIC will be bridged to the openvswitch bridge. As such,
connectivity would be lost if the provisioning NIC was also used for remote
connectivity to the undercloud machine.
* The overcloud machines can PXE boot off the NIC that is on the private VLAN.
In the tested environment, this required disabling network booting in the BIOS
for all NICs other than the one we wanted to boot and then ensuring that the
chosen NIC is at the top of the boot order (ahead of the local hard disk drive
and CD/DVD drives).
* For each overcloud machine you have: the MAC address of the NIC that will PXE
boot on the provisioning network the IPMI information for the machine (i.e. IP
address of the IPMI NIC, IPMI username and password)
Refer to the following diagram for more information
.. image:: images/TripleO_Network_Diagram_.jpg
Setting Up The Undercloud Machine
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#. Select a machine within the baremetal environment on which to install the
undercloud.
#. Install RHEL 7.1 x86_64 on this machine.
#. If needed, create a non-root user with sudo access to use for installing the
Undercloud::
sudo useradd stack
sudo passwd stack # specify a password
echo "stack ALL=(root) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/stack
sudo chmod 0440 /etc/sudoers.d/stack
#. Download and execute the instack-undercloud setup script::
curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host-rhel7 | bash -x
#. Copy the sample instack answers file to the home directory::
cp instack-undercloud/instack.answers.sample ~/instack.answers
#. Edit the ``instack.answers`` file appropriately.
#. Create a json file describing your baremetal nodes.

View File

@ -0,0 +1,31 @@
Building Images
===============
Images must be built prior to doing a deployment. A discovery ramdisk,
deployment ramdisk, and openstack-full image can all be built using
instack-undercloud.
It's recommended to build images on the installed undercloud directly since all
the dependencies are already present.
The following steps can be used to build images. They should be run as the same
non-root user that was used to install the undercloud.
#. Source rhel7rc to set appropriate environment variables::
source instack-undercloud/rhel7rc
#. Download the rhel7 cloud image or copy it from another host to the
undercloud::
curl -O http://download.devel.redhat.com/brewroot/packages/rhel-guest-image/7.0/20140930.0/images/rhel-guest-image-7.0-20140930.0.x86_64.qcow2
#. Build the 3 image types::
instack-undercloud/scripts/instack-build-images deploy-ramdisk
instack-undercloud/scripts/instack-build-images discovery-ramdisk
instack-undercloud/scripts/instack-build-images openstack-full
#. Load the images into Glance::
instack-undercloud/scripts/instack-prepare-for-overcloud

242
doc/source/conf.py Normal file
View File

@ -0,0 +1,242 @@
# -*- coding: utf-8 -*-
#
# instack-undercloud documentation build configuration file, created by
# sphinx-quickstart on Wed Feb 25 10:56:57 2015.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'instack-undercloud'
copyright = u'2015, RDO'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '2.0.0'
# The full version, including alpha/beta/rc tags.
release = '2.0.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'instack-underclouddoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'instack-undercloud.tex', u'instack-undercloud Documentation',
u'RDO', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'instack-undercloud', u'instack-undercloud Documentation',
[u'RDO'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'instack-undercloud', u'instack-undercloud Documentation',
u'RDO', 'instack-undercloud', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'

View File

@ -0,0 +1,36 @@
Deploying the Overcloud
=======================
All the commands on this page require that the appropriate stackrc file has
been sourced into the environment::
source stackrc
Registering Nodes
-----------------
Register nodes for your deployment with Ironic::
instack-undercloud/scripts/instack-ironic-deployment --nodes-json instackenv.json --register-nodes
Disovering Nodes
----------------
Discover hardware attributes of nodes and match them to a deployment profile::
instack-undercloud/scripts/instack-ironic-deployment --discover-nodes
Check what profiles were matched for the discovered nodes::
instack-undercloud/scripts/instack-ironic-deployment --show-profile
Deploying Nodes
---------------
Create the necessary flavors::
instack-undercloud/scripts/instack-ironic-deployment --setup-flavors
Deploy the the *openstack-full* image to 3 nodes::
COMPUTE_COUNT=3 CONTROL_COUNT=0 instack-undercloud/scripts/instack-ironic-deployment --deploy-nodes

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 92 KiB

25
doc/source/index.rst Normal file
View File

@ -0,0 +1,25 @@
.. instack-undercloud documentation master file, created by
sphinx-quickstart on Wed Feb 25 10:56:57 2015.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to instack-undercloud's documentation!
==============================================
Contents:
.. toctree::
Introduction <intro>
Setup <setup>
Installing the Undercloud <install-undercloud>
Building Images <build-images>
Deploying the Overcloud <deploy-overcloud>
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -0,0 +1,31 @@
Installing the Undercloud
=========================
Make sure you are logged in as a non-root user (such as the stack user) on the
node on which you want to install the undercloud.
If you used the virt setup this node will be a VM called *instack* and you can
use the stack user.
For a baremetal setup this will be the host you selected for the Undercloud
while preparing the environment.
#. Download and execute the instack-undercloud setup script::
curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host-rhel7 | bash -x
#. Source rhel7rc to set appropriate environment variables::
source instack-undercloud/rhel7rc
#. Run script to install the undercloud::
instack-undercloud/scripts/instack-install-undercloud
Once the install script has run to completion, you should take note of the
files ``/root/stackrc`` and ``/root/tripleo-undercloud-passwords``. Both these
files will be needed to interact with the installed undercloud. Copy them to
the home directory for easier use later.::
sudo cp /root/tripleo-undercloud-passwords .
sudo cp /root/stackrc .

7
doc/source/intro.rst Normal file
View File

@ -0,0 +1,7 @@
Introduction
============
instack-undercloud is a scripted installer and other tooling for OpenStack
based on `TripleO`_.
.. _Tripleo: https://wiki.openstack.org/wiki/TripleO

7
doc/source/setup.rst Normal file
View File

@ -0,0 +1,7 @@
Setup
=====
.. toctree::
Virtual Environment Setup <virt-setup>
Baremetal Environment Setup <baremetal-setup>

97
doc/source/virt-setup.rst Normal file
View File

@ -0,0 +1,97 @@
Virtual Environment Setup
=========================
instack-undercloud can be deployed in a virtual environment using virtual
machines instead of actual baremetal. One baremetal machine is still needed to
act as the host for the virtual machines.
instack-undercloud contains the necessary tooling to create and configure the
environment.
Minimum System Requirements
---------------------------
This setup creates 5 virtual machines consisting of 4GB of memory and 40GB of
disk space on each. The virtual machine disk files are thinly provisioned and
will not take up the full 40GB initially.
The minimum system requirements for the virtual host machine are:
* A baremetal machine with virtualization hardware extenstions enabled.
Nested KVM is **not** supported.
* At least (1) quad core CPU
* 12GB free memory
* 120GB disk space [#]_
If you want to increase the scaling of one or more overcloud nodes, you will
need to ensure you have enough memory and disk space.
Preparing the Host Machine
--------------------------
#. Make sure sshd service is installed and running.
#. The user performing all of the installation steps on the virt host needs to
have sudo enabled. You can use an existing user or use the following commands
to create a new user called stack with password-less sudo enabled. Do not run
the rest of the steps in this guide as root.
* Example commands to create a user::
sudo useradd stack
sudo passwd stack # specify a password
echo "stack ALL=(root) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/stack
sudo chmod 0440 /etc/sudoers.d/stack
#. Make sure you are logged in as the non-root user you intend to use.
#. Add export of LIBVIRT_DEFAULT_URI to your bashrc file::
echo 'export LIBVIRT_DEFAULT_URI="qemu:///system"' >> ~/.bashrc
#. Download and execute the instack-undercloud setup script::
curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host-rhel7 | bash -x
#. Run scripts to install required dependencies::
source /usr/libexec/openstack-tripleo/devtest_variables.sh
tripleo install-dependencies
tripleo set-usergroup-membership
# The previous command has added the user to the libvirtd group, so we need to login to the new group
newgrp libvirtd
newgrp
#. Download the RHEL 7.1 cloud image or copy it over from a different
location::
curl -O http://download.devel.redhat.com/brewroot/packages/rhel-guest-image/7.1/20150203.1/images/rhel-guest-image-7.1-20150203.1.x86_64.qcow2
#. Source rhel7rc to set appropriate environment variables::
source instack-undercloud/rhel7rc
export DIB_YUM_REPO_CONF=/etc/yum.repos.d/rhos-release-6-rhel-7.1.repo
export NODE_DIST=rhel7
#. Run the script to setup your virtual environment::
instack-undercloud/scripts/instack-virt-setup
When the script has completed successfully it will output the IP address of the
instack vm that has now been installed with a base OS.
Running virsh list --all will show you now have one virtual machine called
*instack* and 4 called *baremetal[0-3]*.
You can ssh to the instack vm as the root user::
ssh root@<instack-vm-ip>
The vm contains a ``stack`` user to be used for installing the undercloud. You
can ``su - stack`` to switch to the stack user account.
.. rubric:: Footnotes
.. [#] Note that some default partitioning scheme will most likely not provide
enough space to the partition containing the default path for libvirt image
storage (/var/lib/libvirt/images). The easiest fix is to customize the
partition layout at the time of install to provide at least 200 GB of space for
that path.

View File

@ -26,10 +26,8 @@ scripts =
scripts/instack-delete-overcloud scripts/instack-delete-overcloud
scripts/instack-deploy-overcloud scripts/instack-deploy-overcloud
scripts/instack-install-undercloud scripts/instack-install-undercloud
scripts/instack-install-undercloud-source
scripts/instack-ironic-deployment scripts/instack-ironic-deployment
scripts/instack-prepare-for-overcloud scripts/instack-prepare-for-overcloud
scripts/instack-setup-delorean
scripts/instack-setup-host-rhel7 scripts/instack-setup-host-rhel7
scripts/instack-test-overcloud scripts/instack-test-overcloud
scripts/instack-update-overcloud scripts/instack-update-overcloud

2
test-requirements.txt Normal file
View File

@ -0,0 +1,2 @@
oslosphinx
sphinx>=1.1.2,<1.2

24
tox.ini Normal file
View File

@ -0,0 +1,24 @@
[tox]
minversion = 1.6
skipsdist = True
[testenv]
usedevelop = True
install_command = pip install {opts} {packages}
setenv = VIRTUAL_ENV={envdir}
deps = -r{toxinidir}/test-requirements.txt
[testenv:venv]
commands = {posargs}
[testenv:docs]
commands = python setup.py build_sphinx
[testenv:pep8]
deps = bashate
whitelist_externals = bash
commands = bash -c "find scripts -type f | xargs bashate -v"
[flake8]
ignore = H803
exclude = .tox