From 5493fb64e11d2ec961c440dbeb9a71b033f3be0b Mon Sep 17 00:00:00 2001 From: chenxing Date: Mon, 24 Jul 2017 22:10:58 +0800 Subject: Rearrange existing documentation to fit the new standard layout For more detail, see the doc migration spec. http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html Partially-Implements: blueprint queens-doc-restructure Co-Authored-By: Kurt Taylor Change-Id: Iab93bf023a13b953a31152b91d4fea0fa75bf2d0 --- doc/CONTRIBUTING.rst | 88 ---- doc/bug-triage.rst | 8 - doc/conf.py | 90 ---- doc/image-building.rst | 453 --------------------- doc/index.rst | 66 --- doc/running-tests.rst | 116 ------ doc/source/admin/image-building.rst | 453 +++++++++++++++++++++ doc/source/admin/index.rst | 18 + .../template-override/opendaylight-source.rst | 27 ++ doc/source/admin/template-override/ovs-dpdk.rst | 31 ++ doc/source/conf.py | 90 ++++ doc/source/contributor/CONTRIBUTING.rst | 88 ++++ doc/source/contributor/bug-triage.rst | 8 + doc/source/contributor/index.rst | 17 + doc/source/contributor/running-tests.rst | 116 ++++++ doc/source/index.rst | 54 +++ doc/template-override/opendaylight-source.rst | 27 -- doc/template-override/ovs-dpdk.rst | 31 -- 18 files changed, 902 insertions(+), 879 deletions(-) delete mode 100644 doc/CONTRIBUTING.rst delete mode 100644 doc/bug-triage.rst delete mode 100644 doc/conf.py delete mode 100644 doc/image-building.rst delete mode 100644 doc/index.rst delete mode 100644 doc/running-tests.rst create mode 100644 doc/source/admin/image-building.rst create mode 100644 doc/source/admin/index.rst create mode 100644 doc/source/admin/template-override/opendaylight-source.rst create mode 100644 doc/source/admin/template-override/ovs-dpdk.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/contributor/CONTRIBUTING.rst create mode 100644 doc/source/contributor/bug-triage.rst create mode 100644 doc/source/contributor/index.rst create mode 100644 doc/source/contributor/running-tests.rst create mode 100644 doc/source/index.rst delete mode 100644 doc/template-override/opendaylight-source.rst delete mode 100644 doc/template-override/ovs-dpdk.rst (limited to 'doc') diff --git a/doc/CONTRIBUTING.rst b/doc/CONTRIBUTING.rst deleted file mode 100644 index 7b6ce18f4..000000000 --- a/doc/CONTRIBUTING.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _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/bug-triage.rst b/doc/bug-triage.rst deleted file mode 100644 index d5d24ca15..000000000 --- a/doc/bug-triage.rst +++ /dev/null @@ -1,8 +0,0 @@ -========== -Bug triage -========== - -The triage of Kolla bugs follows the OpenStack-wide process documented -on `BugTriage `_ in the wiki. -Please reference `Bugs `_ in the -wiki for further details. diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index d4a23cab2..000000000 --- a/doc/conf.py +++ /dev/null @@ -1,90 +0,0 @@ -# -*- 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/image-building.rst b/doc/image-building.rst deleted file mode 100644 index 4eb9d8d7e..000000000 --- a/doc/image-building.rst +++ /dev/null @@ -1,453 +0,0 @@ -.. _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 -`_, -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= \ - --password= && subscription-manager attach --pool - -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:: - - [-plugin-] - -Where ```` is the image that the plugin should be installed into, and -```` 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:: - - [-additions-] - -Where ```` is the image that the plugin should be installed into, and -```` 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 `_ and `how to - configure Docker with BTRFS back end `_. - -#. 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 -`_. - -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/index.rst b/doc/index.rst deleted file mode 100644 index dafbca516..000000000 --- a/doc/index.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. - 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 `_ -* `kolla-kubernetes `_ - -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/ - - -Kolla Overview -============== - -.. toctree:: - :maxdepth: 1 - - image-building - -Developer Docs -============== - -.. toctree:: - :maxdepth: 1 - - CONTRIBUTING - running-tests - bug-triage - -Template Override Docs -====================== - -.. toctree:: - :maxdepth: 1 - :glob: - - template-override/* diff --git a/doc/running-tests.rst b/doc/running-tests.rst deleted file mode 100644 index e60671c9f..000000000 --- a/doc/running-tests.rst +++ /dev/null @@ -1,116 +0,0 @@ -.. _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 -`_. - - -.. rubric:: Footnotes - -.. [#f1] See https://docs.openstack.org/infra/system-config/jjb.html 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 +`_, +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= \ + --password= && subscription-manager attach --pool + +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:: + + [-plugin-] + +Where ```` is the image that the plugin should be installed into, and +```` 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:: + + [-additions-] + +Where ```` is the image that the plugin should be installed into, and +```` 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 `_ and `how to + configure Docker with BTRFS back end `_. + +#. 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 +`_. + +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 `_ in the wiki. +Please reference `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 +`_. + + +.. 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 `_ +* `kolla-kubernetes `_ + +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 diff --git a/doc/template-override/opendaylight-source.rst b/doc/template-override/opendaylight-source.rst deleted file mode 100644 index 61a3415ba..000000000 --- a/doc/template-override/opendaylight-source.rst +++ /dev/null @@ -1,27 +0,0 @@ -================== -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/template-override/ovs-dpdk.rst b/doc/template-override/ovs-dpdk.rst deleted file mode 100644 index e47cfe0ff..000000000 --- a/doc/template-override/ovs-dpdk.rst +++ /dev/null @@ -1,31 +0,0 @@ -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 -- cgit v1.2.3