Add documentation

Add documentation to decribe how to configure and run the
tests in the plugin.

Change-Id: I5e87f5833993dfae5ad405c9de668026fadd8008
This commit is contained in:
Ade Lee 2017-08-31 16:43:48 -04:00
parent a4e482798c
commit bed63f8d2a
8 changed files with 297 additions and 1 deletions

17
CONTRIBUTING.rst Normal file
View File

@ -0,0 +1,17 @@
If you would like to contribute to the development of OpenStack, you must
follow the steps in this page:
http://docs.openstack.org/infra/manual/developers.html
If you already have a good understanding of how the system works and your
OpenStack accounts are set up, you can skip to the development workflow
section of this documentation to learn how changes to OpenStack should be
submitted for review via the Gerrit tool:
http://docs.openstack.org/infra/manual/developers.html#development-workflow
Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/Tempest plugin novajoin-tempest-plugin

View File

@ -9,7 +9,7 @@ these tests into tempest.
Dependencies
------------
The novajoin_tempest_plugin tests the novajoin API, which requires the
existence of an IPA server.
existence of an IPA server.
Developers
----------

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

@ -0,0 +1,81 @@
# -*- coding: utf-8 -*-
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc',
'openstackdocstheme',
# 'sphinx.ext.intersphinx',
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'novajoin-tempest-plugin'
copyright = u'2017, OpenStack Developers'
# openstackdocstheme options
repository_name = 'openstack/novajoin-tempest-plugin'
bug_project = 'Tempest plugin novajoin-tempest-plugin'
bug_tag = ''
# 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
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static']
html_theme = 'openstackdocs'
# Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index',
'%s.tex' % project,
u'%s Documentation' % project,
u'OpenStack Developers', 'manual'),
]
# Example configuration for intersphinx: refer to the Python standard library.
# intersphinx_mapping = {'http://docs.python.org/': None}

View File

@ -0,0 +1,4 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst

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

@ -0,0 +1,23 @@
.. novajoin-tempest-plugin documentation master file, created by
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
=======================================================
Welcome to the documentation of novajoin-tempest-plugin
=======================================================
Contents:
.. toctree::
:maxdepth: 2
readme
contributing
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

162
doc/source/readme.rst Normal file
View File

@ -0,0 +1,162 @@
..
Except where otherwise noted, this document is licensed under Creative
Commons Attribution 3.0 License. You can view the license at:
https://creativecommons.org/licenses/by/3.0/
.. _tempest_tests:
Tempest Tests
=============
Novajoin is a Nova metadata service that is used to register newly created
Nova instances with IPA. This tempest plugin provides tests that validate
that functionality.
The tests are therefore expected to be executed on a node which has been
registered as an IPA client and on which nova is configured to integrate
with novajoin as a metadata server.
In particular, on an OSP13 TripleO deployment that has been configured to use
TLS for both internal and external services, novajoin runs on the undercloud
node. This means that the undercloud node is registered as an IPA client, and
that the undercloud nova server is configured to retrieve metadata from
novajoin.
It also means that the overcloud controllers and compute nodes are registered
as IPA clients, with the required services and certificates issued.
Setup
-----
This section describes how to set up these tests on an RDO system.
To set up tempest on the RDO system, use dnf to install tempest:
$ sudo dnf install -y openstack-tempest python-devel
Also install the novajoin-tempest-plugin.
$ sudo dnf install python-devel gcc
$ git clone https://github.com/vakwetu/novajoin_tempest_plugin.git
$ cd novajoin_tempest_plugin
$ sudo python setup.py install
Prepare a working directory to run the tempest tests.
$ cd ~
$ tempest init tempest_run
$ cd tempest_run
The discovery command detailed below only appears to work for v2 of the
keystone API. Copy the stackrc file and convert the OS_AUTH_URL to a v2
version.
$ cp /home/stack/stackrc .
$ vi stackrc (convert to v2 by changing as follows:
OS_AUTH_URL=https://192.168.24.2:13000/v2.0
OS_IDENTITY_API_VERSION='2'
$ source ./stackrc
There is currently a bug in the code used to discover and generate
tempest config files if the volume service (cinder) is not installed.
To work around this, comment out the line:
#check_volume_backup_service(clients.volume_service, conf, services)
at around line 203 in the file
/usr/lib/python2.7/site-packages/config_tempest/config_tempest.py.
Run the discovery command to generate the required tempest config file
under ./etc/tempest.
$ discover-tempest-config --verbose \
--image http://download.cirros-cloud.net/0.3.4/cirros-0.3.4-x86_64-disk.img \
--out etc/tempest.conf --debug --create identity.uri $OS_AUTH_URL \
compute.allow_tenant_isolation true object-storage.operator_role \
swiftoperator identity.admin_password $OS_PASSWORD
The tests need credentials to connect to the IPA server. In our tests, we
have used the keytab for the novajoin user. Copy this keytab and set the
appropriate ownership and permissions for the user executing the plugin.
$ sudo cp /etc/novajoin/krb5.keytab /home/stack/krb5.keytab
$ sudo chown stack: /home/stack/krb5.keytab
Add the following directives to the [validation] stanza in the generated
tempest configuration file in ./etc/tempest.conf to configure the ssh
client.
$ vi tempest/tempest.conf
[validation]
connect_method = fixed
network_for_ssh = ctlplane
Tempest Configuration
---------------------
The tempest plugin has additional configuration parameters as defined in
./novajoin_tempest_plugin/config.py.
Some of these are described below. All of these config directives would be
specified under a [novajoin] stanza in ./etc/tempest.conf.
NovajoinGroup = [
cfg.StrOpt('keytab',
default='/home/stack/novajoin.keytab',
help='Keytab to connect to IPA as the novajoin user'),
cfg.StrOpt('tripleo',
default='True',
help='Run triple-O config tests'),
cfg.ListOpt('tripleo_controllers',
default=['overcloud-controller-0'],
help='List of overcloud controller short host names'),
cfg.ListOpt('tripleo_computes',
default=['overcloud-novacompute-0'],
help='List of overcloud compute short host names'),
cfg.StrOpt('tripleo_undercloud',
default='undercloud',
help='Undercloud short host name'
)
Running the tests
-----------------
The tests in test_novajoin_enrollment validate that newly created Nova
instances (with the appropriate metadata) are registered with IPA and all
the requested services and hosts are created. The test also confirms that
the instances and services are appropriately deleted when the instance
is deleted. To run these tests,
$ tempest run --regex test_novajoin_enrollment
The tests in test_tripleo_deployment should be run on the undercloud in a
TLS enabled tripleo deployment. These tests verify that the undercloud
and overcloud nodes are registered with IPA and that the required hosts
and services have been created in the IPA server. In addition, it
confirms that the certificates requested by Heat are tracked by certmonger
on the overcloud nodes.
$ tempest run --regex test_tripleo_deployment
The tests in test_tripleo_tls should be run on the undercloud in a TLS enabled
tripleo deployment. These tests verify that all services have TLS connections
on all external and internal connections using the openssl client to attempt
TLS connections.
$ tempest run --regex test_tripleo_tls

View File

@ -4,6 +4,7 @@
hacking>=0.12.0,<0.13 # Apache-2.0
doc8 # Apache-2.0
python-subunit>=0.0.18 # Apache-2.0/BSD
sphinx>=1.2.1,!=1.3b1,<1.4 # BSD
oslosphinx>=4.7.0 # Apache-2.0
@ -11,5 +12,6 @@ oslotest>=1.10.0 # Apache-2.0
testrepository>=0.0.18 # Apache-2.0/BSD
testscenarios>=0.4 # Apache-2.0/BSD
testtools>=1.4.0 # MIT
openstackdocstheme>=1.11.0 # Apache-2.0
oslo.log>=3.22.0 # Apache-2.0

View File

@ -14,6 +14,7 @@ commands = python setup.py testr --slowest --testr-args='{posargs}'
[testenv:pep8]
commands =
doc8 doc/source/ HACKING.rst CONTRIBUTING.rst README.rst
flake8 {posargs}
[testenv:venv]
@ -22,6 +23,12 @@ commands = {posargs}
[testenv:debug]
commands = oslo_debug_helper {posargs}
[testenv:docs]
commands = python setup.py build_sphinx
[doc8]
extension=.rst
[flake8]
# E123, E125 skipped as they are invalid PEP-8.