diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/admin/image-building.rst | 453 | ||||
| -rw-r--r-- | doc/source/admin/index.rst | 18 | ||||
| -rw-r--r-- | doc/source/admin/template-override/opendaylight-source.rst | 27 | ||||
| -rw-r--r-- | doc/source/admin/template-override/ovs-dpdk.rst | 31 | ||||
| -rw-r--r-- | doc/source/conf.py | 90 | ||||
| -rw-r--r-- | doc/source/contributor/CONTRIBUTING.rst | 88 | ||||
| -rw-r--r-- | doc/source/contributor/bug-triage.rst | 8 | ||||
| -rw-r--r-- | doc/source/contributor/index.rst | 17 | ||||
| -rw-r--r-- | doc/source/contributor/running-tests.rst | 116 | ||||
| -rw-r--r-- | doc/source/index.rst | 54 |
10 files changed, 902 insertions, 0 deletions
diff --git a/doc/source/admin/image-building.rst b/doc/source/admin/image-building.rst new file mode 100644 index 000000000..4eb9d8d7e --- /dev/null +++ b/doc/source/admin/image-building.rst @@ -0,0 +1,453 @@ +.. _image-building: + +========================= +Building Container Images +========================= + +The ``kolla-build`` command is responsible for building Docker images. + +.. note:: + + When developing Kolla it can be useful to build images using files located in + a local copy of Kolla. Use the ``tools/build.py`` script instead of + ``kolla-build`` command in all below instructions. + +Generating kolla-build.conf +=========================== + +Install tox and generate the build configuration. The build configuration is +designed to hold advanced customizations when building containers. + +Create kolla-build.conf using the following steps. + +:: + + pip install tox + tox -e genconfig + +The location of the generated configuration file is +``etc/kolla/kolla-build.conf``, it can also be copied to ``/etc/kolla``. The +default location is one of ``/etc/kolla/kolla-build.conf`` or +``etc/kolla/kolla-build.conf``. + +Guide +===== + +In general, images are built like this:: + + kolla-build + +By default, the above command would build all images based on CentOS image. + +The operator can change the base distro with the ``-b`` option:: + + kolla-build -b ubuntu + +There are following distros available for building images: + +- centos +- oraclelinux +- rhel +- ubuntu + +.. warning:: + + Fedora images are deprecated since Newton and will be removed + in the future. + +It is possible to build only a subset of images by specifying them on the +command line:: + + kolla-build keystone + +In this case, the build script builds all images whose name contains the +``keystone`` string along with their dependencies. + +Multiple names may be specified on the command line:: + + kolla-build keystone nova + +The set of images built can be defined as a profile in the ``profiles`` section +of ``kolla-build.conf``. Later, profile can be specified by ``--profile`` CLI +argument or ``profile`` option in ``kolla-build.conf``. Kolla provides some +pre-defined profiles: + +- ``infra`` infrastructure-related images +- ``main`` core OpenStack images +- ``aux`` auxiliary images such as trove, magnum, ironic +- ``default`` minimal set of images for a working deploy + +For example, due to Magnum requires Heat, following profile can be add to +``profiles`` section in ``kolla-build.conf`` :: + + magnum = magnum,heat + +These images can be built using command line :: + + kolla-build --profile magnum + +Or put following line to ``DEFAULT`` section in ``kolla-build.conf`` :: + + profile = magnum + + +``kolla-build`` uses ``kolla`` as default Docker namespace. This is +controlled with the ``-n`` command line option. To push images to a Dockerhub +repository named ``mykollarepo``:: + + kolla-build -n mykollarepo --push + +To push images to a `local registry +<https://docs.openstack.org/kolla-ansible/latest/multinode.html#deploy-a-registry>`_, +use ``--registry`` flag:: + + kolla-build --registry 172.22.2.81:5000 --push + +The build configuration can be customized using a config file, the default +location being one of ``/etc/kolla/kolla-build.conf`` or +``etc/kolla/kolla-build.conf``. This file can be generated using the following +command:: + + tox -e genconfig + +Build OpenStack from source +=========================== + +When building images, there are two methods of the OpenStack install. One is +``binary``. Another is ``source``. The ``binary`` means that OpenStack will be +installed from apt/yum. And the ``source`` means that OpenStack will be +installed from source code. The default method of the OpenStack install is +``binary``. It can be changed to ``source`` using the ``-t`` option:: + + kolla-build -t source + +The locations of OpenStack source code are written in +``etc/kolla/kolla-build.conf``. +Now the source type supports ``url``, ``git``, and ``local``. The location of +the ``local`` source type can point to either a directory containing the source +code or to a tarball of the source. The ``local`` source type permits to make +the best use of the Docker cache. + +``etc/kolla/kolla-build.conf`` looks like:: + + [glance-base] + type = url + location = http://tarballs.openstack.org/glance/glance-master.tar.gz + + [keystone-base] + type = git + location = https://git.openstack.org/openstack/keystone + reference = stable/mitaka + + [heat-base] + type = local + location = /home/kolla/src/heat + + [ironic-base] + type = local + location = /tmp/ironic.tar.gz + +To build RHEL containers, it is necessary to include registration with RHN +of the container runtime operating system. To obtain a RHN +username/password/pool id, contact Red Hat. Use a template's header block +overrides file, add the following:: + + RUN subscription-manager register --user=<user-name> \ + --password=<password> && subscription-manager attach --pool <pool-id> + +Dockerfile Customisation +======================== + +As of the Newton release, the ``kolla-build`` tool provides a Jinja2 based +mechanism which allows operators to customise the Dockerfiles used to generate +Kolla images. + +This offers a lot of flexibility on how images are built, e.g. installing extra +packages as part of the build, tweaking settings, installing plugins, and +numerous other capabilities. Some of these examples are described in more +detail below. + +Generic Customisation +--------------------- + +Anywhere the line ``{% block ... %}`` appears may be modified. The Kolla +community have added blocks throughout the Dockerfiles where we think they will +be useful, however, operators are free to submit more if the ones provided are +inadequate. + +The following is an example of how an operator would modify the setup steps +within the Horizon Dockerfile. + +First, create a file to contain the customisations, e.g. +``template-overrides.j2``. In this place the following:: + + {% extends parent_template %} + + # Horizon + {% block horizon_redhat_binary_setup %} + RUN useradd --user-group myuser + {% endblock %} + +Then rebuild the horizon image, passing the ``--template-override`` argument:: + + kolla-build --template-override template-overrides.j2 horizon + +.. note:: + + The above example will replace all contents from the original block. Hence + in many cases one may want to copy the original contents of the block before + making changes. + + More specific functionality such as removing/appending entries is available + for packages, described in the next section. + +Package Customisation +--------------------- + +Packages installed as part of a container build can be overridden, appended to, +and deleted. Taking the Horizon example, the following packages are installed +as part of a binary install type build: + +* ``openstack-dashboard`` +* ``httpd`` +* ``mod_wsgi`` +* ``mod_ssl`` +* ``gettext`` + +To add a package to this list, say, ``iproute``, first create a file, e.g. +``template-overrides.j2``. In this place the following:: + + {% extends parent_template %} + + # Horizon + {% set horizon_packages_append = ['iproute'] %} + +Then rebuild the horizon image, passing the ``--template-override`` argument:: + + kolla-build --template-override template-overrides.j2 horizon + +Alternatively ``template_override`` can be set in ``kolla-build.conf``. + +The ``append`` suffix in the above example carries special significance. It +indicates the operation taken on the package list. The following is a complete +list of operations available: + +override + Replace the default packages with a custom list. + +append + Add a package to the default list. + +remove + Remove a package from the default list. + +Using a different base image +---------------------------- + +Base-image can be specified by argument ``--base-image``. For example:: + + kolla-build --base-image registry.access.redhat.com/rhel7/rhel --base rhel + + +Plugin Functionality +-------------------- + +The Dockerfile customisation mechanism is also useful for adding/installing +plugins to services. An example of this is Neutron's third party L2 drivers_. + +The bottom of each Dockerfile contains two blocks, ``image_name_footer``, and +``footer``. The ``image_name_footer`` is intended for image specific +modifications, while the ``footer`` can be used to apply a common set of +modifications to every Dockerfile. + +For example, to add the ``networking-cisco`` plugin to the ``neutron_server`` +image, one may want to add the following to the ``template-override`` file:: + + {% extends parent_template %} + + {% block neutron_server_footer %} + RUN git clone https://git.openstack.org/openstack/networking-cisco \ + && pip --no-cache-dir install networking-cisco + {% endblock %} + +Astute readers may notice there is one problem with this however. Assuming +nothing else in the Dockerfile changes for a period of time, the above ``RUN`` +statement will be cached by Docker, meaning new commits added to the Git +repository may be missed on subsequent builds. To solve this the Kolla build +tool also supports cloning additional repositories at build time, which will be +automatically made available to the build, within an archive named +``plugins-archive``. + +.. note:: + + The following is available for source build types only. + +To use this, add a section to ``/etc/kolla/kolla-build.conf`` in the following +format:: + + [<image>-plugin-<plugin-name>] + +Where ``<image>`` is the image that the plugin should be installed into, and +``<plugin-name>`` is the chosen plugin identifier. + +Continuing with the above example, add the following to +``/etc/kolla/kolla-build.conf``:: + + [neutron-server-plugin-networking-cisco] + type = git + location = https://git.openstack.org/openstack/networking-cisco + reference = master + +The build will clone the repository, resulting in the following archive +structure:: + + plugins-archive.tar + |__ plugins + |__networking-cisco + +The template now becomes:: + + {% block neutron_server_footer %} + ADD plugins-archive / + pip --no-cache-dir install /plugins/* + {% endblock %} + +Many of the Dockerfiles already copy the ``plugins-archive`` to the image and +install available plugins at build time. + +Additions Functionality +----------------------- + +The Dockerfile customisation mechanism is also useful for adding/installing +additions into images. An example of this is adding your jenkins job build +metadata (say formatted into a jenkins.json file) into the image. + +Similarly to the plugins mechanism, the Kolla build tool also supports cloning +additional repositories at build time, which will be automatically made +available to the build, within an archive named ``additions-archive``. The main +difference between ``plugins-archive`` and ``additions-archive`` is that +``plugins-archive`` is copied to the relevant images and processed to install +available plugins while ``additions-archive`` processing is left to the Kolla +user. + +.. note:: + + The following is available for source build types only. + +To use this, add a section to ``/etc/kolla/kolla-build.conf`` in the following +format:: + + [<image>-additions-<additions-name>] + +Where ``<image>`` is the image that the plugin should be installed into, and +``<additions-name>`` is the chosen additions identifier. + +Continuing with the above example, add the following to +``/etc/kolla/kolla-build.conf``:: + + [neutron-server-additions-jenkins] + type = local + location = /path/to/your/jenkins/data + +The build will copy the directory, resulting in the following archive +structure:: + + additions-archive.tar + |__ additions + |__jenkins + +Alternatively, it is also possible to create an ``additions-archive.tar`` file +yourself without passing by ``/etc/kolla/kolla-build.conf`` in order to use the +feature for binary build type. + +The template now becomes:: + + {% block neutron_server_footer %} + ADD additions-archive / + RUN cp /additions/jenkins/jenkins.json /jenkins.json + {% endblock %} + +Custom Repos +------------ + +Red Hat +------- +The build method allows the operator to build containers from custom repos. +The repos are accepted as a list of comma separated values and can be in the +form of ``.repo``, ``.rpm``, or a url. See examples below. + +Update ``rpm_setup_config`` in ``/etc/kolla/kolla-build.conf``:: + + rpm_setup_config = https://trunk.rdoproject.org/centos7/currrent/delorean.repo,https://trunk.rdoproject.org/centos7/delorean-deps.repo + +If specifying a ``.repo`` file, each ``.repo`` file will need to exist in the +same directory as the base Dockerfile (``kolla/docker/base``):: + + rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo + +Ubuntu +------ +For Debian based images, additional apt sources may be added to the build as +follows:: + + apt_sources_list = custom.list + +Known issues +============ + +#. Can't build base image because Docker fails to install systemd or httpd. + + There are some issues between Docker and AUFS. The simple workaround to + avoid the issue is that add ``-s devicemapper`` or ``-s btrfs`` to + ``DOCKER_OPTS``. Get more information about `the issue from the Docker bug + tracker <https://github.com/docker/docker/issues/6980>`_ and `how to + configure Docker with BTRFS back end <https://docs.docker.com/engine/userguide/storagedriver/btrfs-driver/#prerequisites>`_. + +#. Mirrors are unreliable. + + Some of the mirrors Kolla uses can be unreliable. As a result occasionally + some containers fail to build. To rectify build problems, the build tool + will automatically attempt three retries of a build operation if the first + one fails. The retry count is modified with the ``--retries`` option. + +Kolla-ansible with Local Registry +--------------------------------- + +To make kolla-ansible pull images from a local registry, set +``"docker_registry"`` to ``"172.22.2.81:5000"`` in +``"/etc/kolla/globals.yml"``. Make sure Docker is allowed to pull images from +insecure registry. See +`Docker Insecure Registry +<https://docs.openstack.org/kolla-ansible/latest/multinode.html#deploy-a-registry>`_. + +Building behind a proxy +----------------------- + +We can insert http_proxy settings into the images to +fetch packages during build, and then unset them at the end to avoid having +them carry through to the environment of the final images. Note however, it's +not possible to drop the info completely using this method; it will still be +visible in the layers of the image. + +To set the proxy settings, we can add this to the template's header block:: + + ENV http_proxy=https://evil.corp.proxy:80 + ENV https_proxy=https://evil.corp.proxy:80 + +To unset the proxy settings, we can add this to the template's footer block:: + + ENV http_proxy="" + ENV https_proxy="" + +Besides this configuration options, the script will automatically read these +environment variables. If the host system proxy parameters match the ones +going to be used, no other input parameters will be needed. These are the +variables that will be picked up from the user env:: + + HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, FTP_PROXY, + ftp_proxy, NO_PROXY, no_proxy + +Also these variables could be overwritten using ``--build-args``, which have +precedence. + +.. _drivers: https://wiki.openstack.org/wiki/Neutron#Plugins diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst new file mode 100644 index 000000000..4724b3bb2 --- /dev/null +++ b/doc/source/admin/index.rst @@ -0,0 +1,18 @@ +=================== +Administrator Guide +=================== + +Building Container Images +------------------------- + +If you are a system administrator running Kolla, this section contains +information that should help you understand how to build container image +or build some images using ``--template-override``. + + +.. toctree:: + :maxdepth: 2 + :glob: + + image-building + template-override/* diff --git a/doc/source/admin/template-override/opendaylight-source.rst b/doc/source/admin/template-override/opendaylight-source.rst new file mode 100644 index 000000000..61a3415ba --- /dev/null +++ b/doc/source/admin/template-override/opendaylight-source.rst @@ -0,0 +1,27 @@ +================== +OpenDaylight Build +================== + +The `opendaylight-template-overrides.j2` template override shows how to build +an OpenDaylight container image with a different version than the one packaged +with the distro. + +Building OpenDaylight Container Images +====================================== + +kolla-build.conf +---------------- + +Point to the desired version of OpenDaylight in `kolla-build.conf`: + +.. code-block:: console + + [opendaylight] + type = url + location = https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/integration/distribution-karaf/0.6.0-Carbon/distribution-karaf-0.6.0-Carbon.tar.gz + +Build the container by executing the following command: + +:: + + kolla-build --type source --template-override contrib/template-override/opendaylight-template-overrides.j2 opendaylight diff --git a/doc/source/admin/template-override/ovs-dpdk.rst b/doc/source/admin/template-override/ovs-dpdk.rst new file mode 100644 index 000000000..e47cfe0ff --- /dev/null +++ b/doc/source/admin/template-override/ovs-dpdk.rst @@ -0,0 +1,31 @@ +OVS-DPDK Source build +===================== + +CentOS and Oracle Linux currently do not provide packages +for ovs with dpdk. +The Ubuntu packages do not support UIO based drivers. +To use the uio_pci_generic driver on Ubuntu a source build is required. + +Building ovs with dpdk containers from source +--------------------------------------------- + +- Append the following to /etc/kolla/kolla-build.conf to select the version + of ovs and dpdk to use for your source build. + +kolla-build.conf +________________ + +[openvswitch-base-plugin-ovs] +type = git +location = https://github.com/openvswitch/ovs.git +reference = v2.7.0 + +[openvswitch-base-plugin-dpdk] +type = git +location = http://dpdk.org/git/dpdk +reference = v17.02 + +- To build the container execute the follow command:: + + tools/build.py --template-override \ + contrib/template-override/ovs-dpdk.j2 dpdk diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 000000000..d4a23cab2 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,90 @@ +# -*- 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 = [ + 'openstackdocstheme', + 'sphinx.ext.autodoc', +] + +# 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'kolla' +copyright = u'2013-present, OpenStack Foundation' + +# 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. +from kolla.version import version_info as kolla_version +# The full version, including alpha/beta/rc tags. +release = kolla_version.version_string_with_vcs() +# The short X.Y version. +version = kolla_version.canonical_version_string() + +# 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 = 'openstackdocs' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Must set this variable to include year, month, day, hours, and minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + +# 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 Foundation', 'manual'), +] + +# openstackdocstheme options +repository_name = 'openstack/kolla' +bug_project = 'kolla' +bug_tag = '' diff --git a/doc/source/contributor/CONTRIBUTING.rst b/doc/source/contributor/CONTRIBUTING.rst new file mode 100644 index 000000000..7b6ce18f4 --- /dev/null +++ b/doc/source/contributor/CONTRIBUTING.rst @@ -0,0 +1,88 @@ +.. _CONTRIBUTING: + +================= +How To Contribute +================= + +Basics +====== + +#. Our source code is hosted on `OpenStack Kolla Git`_. Bugs should be filed on + launchpad_. + +#. Please follow OpenStack `Gerrit Workflow`_ to contribute to Kolla. + +#. Note the branch you're proposing changes to. ``master`` is the current focus + of development. Kolla project has a strict policy of only allowing backports + in ``stable/branch``, unless when not applicable. A bug in a + ``stable/branch`` will first have to be fixed in ``master``. + +#. Please file a launchpad_ blueprint for any significant code change and a bug + for any significant bug fix. See how to reference a bug or a blueprint in + the commit message here_. For simple changes, contributors may optionally + add the text "TrivialFix" to the commit message footer to indicate to + reviewers a bug is not required. + +.. _OpenStack Kolla Git: https://git.openstack.org/cgit/openstack/kolla/ +.. _launchpad: https://bugs.launchpad.net/kolla +.. _here: https://wiki.openstack.org/wiki/GitCommitMessages + +Please use the existing sandbox repository, available at +https://git.openstack.org/cgit/openstack-dev/sandbox, for learning, understanding +and testing the `Gerrit Workflow`_. + +.. _Gerrit Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow + +Adding a new service +==================== + +Kolla aims to both containerise and deploy all services within the OpenStack +"big tent". This is a constantly moving target as the ecosystem grows, so these +guidelines aim to help make adding a new service to Kolla a smooth experience. + +The image +--------- +Kolla follows Docker best practices +(https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) +when designing and implementing services where at all possible. + +We use ``jinja2`` templating syntax to help manage the volume and complexity +that comes with maintaining multiple Dockerfiles for multiple different base +operating systems. + +Images should be created under the ``docker`` directory. OpenStack services +should inherit from the provided ``openstack-base`` image, while supporting and +infrastructure services (e.g. mongodb) should inherit from ``base``. + +Services consisting of only one service should be placed in an image named the +same as that service, e.g. ``horizon``. Services that consist of multiple +processes generally use a base image and child images, e.g. ``glance-base``, +``glance-api``, and ``glance-registry``. + +Jinja2 'blocks' are employed throughout the Dockerfile's to help operators +customise various stages of the build (refer to +https://docs.openstack.org/kolla/latest/image-building.html#dockerfile-customisation) + +Some of these blocks are free form however, there are a subset that should be +common to every Dockerfile. The overall structure for a multi container service +is as follows:: + + FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }} + LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}" + + {% block << service >>_header %}{% endblock %} + + {% import "macros.j2" as macros with context %} + + << binary specific steps >> + + << source specific steps >> + + << common steps >> + + {% block << service >>_footer %}{% endblock %} + {% block footer %}{% endblock %} + +.. NOTE:: + The generic footer block ``{% block footer %}{% endblock %}`` should not be + included in base images (e.g. glance-base). diff --git a/doc/source/contributor/bug-triage.rst b/doc/source/contributor/bug-triage.rst new file mode 100644 index 000000000..d5d24ca15 --- /dev/null +++ b/doc/source/contributor/bug-triage.rst @@ -0,0 +1,8 @@ +========== +Bug triage +========== + +The triage of Kolla bugs follows the OpenStack-wide process documented +on `BugTriage <https://wiki.openstack.org/wiki/BugTriage>`_ in the wiki. +Please reference `Bugs <https://wiki.openstack.org/wiki/Bugs>`_ in the +wiki for further details. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 000000000..13430a481 --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,17 @@ +============ +Development +============ + +Contributing +------------ + +This guide is to tell someone who would like to contribute to +Kolla project. Following this guide to propose your first patch for Kolla. +And we are welcome everyone to join our project! + +.. toctree:: + :maxdepth: 2 + + CONTRIBUTING.rst + running-tests + bug-triage diff --git a/doc/source/contributor/running-tests.rst b/doc/source/contributor/running-tests.rst new file mode 100644 index 000000000..e60671c9f --- /dev/null +++ b/doc/source/contributor/running-tests.rst @@ -0,0 +1,116 @@ +.. _running-tests: + +============= +Running tests +============= + +Kolla contains a suite of tests in the +``tests`` and ``kolla/tests`` directories. + +Any proposed code change in gerrit is automatically rejected by the OpenStack +Jenkins server [#f1]_ if the change causes test failures. + +It is recommended for developers to run the test suite before submitting patch +for review. This allows to catch errors as early as possible. + +Preferred way to run the tests +------------------------------ + +The preferred way to run the unit tests is using ``tox``. It executes tests in +isolated environment, by creating separate virtualenv and installing +dependencies from the ``requirements.txt`` and ``test-requirements.txt`` files, +so the only package you install is ``tox`` itself: + +.. code-block:: console + + $ pip install tox + +See `the unit testing section of the Testing wiki page`_ for more information. +Following are some simple examples. + +To run the Python 2.7 tests: + +.. code-block:: console + + $ tox -e py27 + +To run the style tests: + +.. code-block:: console + + $ tox -e pep8 + +To run multiple tests separate items by commas: + +.. code-block:: console + + $ tox -e py27,py35,pep8 + +.. _the unit testing section of the Testing wiki page: https://wiki.openstack.org/wiki/Testing#Unit_Tests + +Running a subset of tests +------------------------- + +Instead of running all tests, you can specify an individual directory, file, +class or method that contains test code, i.e. filter full names of tests by a +string. + +To run the tests located only in the ``kolla/tests`` +directory use: + +.. code-block:: console + + $ tox -e py27 kolla.tests + +To run the tests of a specific file say ``kolla/tests/test_set_config.py``: + +.. code-block:: console + + $ tox -e py27 test_set_config + +To run the tests in the ``ConfigFileTest`` class in +the ``kolla/tests/test_set_config.py`` file: + +.. code-block:: console + + $ tox -e py27 test_set_config.ConfigFileTest + +To run the ``ConfigFileTest.test_delete_path_not_exists`` test method in +the ``kolla/tests/test_set_config.py`` file: + +.. code-block:: console + + $ tox -e py27 test_set_config.ConfigFileTest.test_delete_path_not_exists + + +Coverage Report Generation +-------------------------- + +In order to get coverage report for Kolla, run the below command. + +.. code-block:: console + + $ tox -e cover + +Debugging unit tests +-------------------- + +In order to break into the debugger from a unit test we need to insert +a breaking point to the code: + +.. code-block:: python + + import pdb; pdb.set_trace() + +Then run ``tox`` with the debug environment as one of the following:: + + tox -e debug + tox -e debug test_file_name.TestClass.test_name + +For more information see the `oslotest documentation +<https://docs.openstack.org/oslotest/latest/user/features.html#debugging-with-oslo-debug-helper>`_. + + +.. rubric:: Footnotes + +.. [#f1] See https://docs.openstack.org/infra/system-config/jjb.html diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..b5635defd --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,54 @@ +.. + Copyright 2014-2015 OpenStack Foundation + All Rights Reserved. + + 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. + +================================= +Welcome to Kolla's documentation! +================================= + +Kolla's mission is to provide production-ready containers and deployment tools +for operating OpenStack clouds. + +This documentation is for the Kolla container images. The following subprojects +are available to help deploy Kolla: + +* `kolla-ansible <https://docs.openstack.org/kolla-ansible/latest/>`_ +* `kolla-kubernetes <https://docs.openstack.org/kolla-kubernetes/latest/>`_ + +Site Notes +========== + +This documentation is continually updated and may not represent the state of +the project at any specific prior release. To access documentation for a +previous release of kolla, append the OpenStack release name to the URL, for +example: + + https://docs.openstack.org/kolla/mitaka/ + +Administrator Guide +=================== + +.. toctree:: + :maxdepth: 2 + + admin/index + +Contributor Guide +================= + +.. toctree:: + :maxdepth: 2 + + contributor/index |