openstack/kolla-ansible
Code Issues Proposed changes

Upgrade the rst convention of the Contributor Guide

Browse Source 
We upgrade the rst convention by following Documentation Contributor
Guide[1].

[1] https://docs.openstack.org/doc-contrib-guide/

Change-Id: I065ceb2f4d455412efeb502e7073e2cb7bc96996
Partially-Implements: blueprint optimize-the-documentation-format
This commit is contained in:
chenxing 2018-01-25 15:21:37 +08:00 committed by Chason Chan
parent b66ebff65e
commit e471549e77
4 changed files with 251 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/source/contributor/CONTRIBUTING.rst
View File

@ -7,37 +7,37 @@ How To Contribute
Basics
======
#. Our source code is hosted on `OpenStack Kolla-Ansible Git`_. Bugs should be
filed on launchpad_.
#. Our source code is hosted on `OpenStack Kolla-Ansible Git
<https://git.openstack.org/cgit/openstack/kolla-ansible/>`_. Bugs should be
filed on `launchpad <https://bugs.launchpad.net/kolla-ansible>`_.
#. Please follow OpenStack `Gerrit Workflow`_ to contribute to Kolla.
#. Please follow OpenStack `Gerrit Workflow
<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`__
to contribute to Kolla-ansible.
#. 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 or add a TrivialFix tag for simple changes.
See how to reference a bug or a blueprint in the commit message here_
#. Please file a `blueprint of kolla-ansible <https://blueprints.launchpad.net/kolla-ansible>`__
for any significant code change and a bug for any significant bug fix,
or add a ``TrivialFix`` tag to commit message for simple changes.
See how to reference a bug or a blueprint in the `commit message
<https://wiki.openstack.org/wiki/GitCommitMessages>`_.
#. TrivialFix tags or bugs are not required for documentation changes.
.. _OpenStack Kolla-Ansible Git: https://git.openstack.org/cgit/openstack/kolla-ansible/
.. _launchpad: https://bugs.launchpad.net/kolla-ansible
.. _here: https://wiki.openstack.org/wiki/GitCommitMessages
Development Environment
=======================
Please follow our :doc:`/user/quickstart` to deploy your environment and test
your changes.
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
Please use the existing sandbox repository, available at `sandbox
<https://git.openstack.org/cgit/openstack-dev/sandbox>`_, for learning, understanding
and testing the `Gerrit Workflow
<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
Adding a new service
====================
@ -86,12 +86,15 @@ that Kolla uses throughout that should be followed.
template file in ``ansible/roles/common/templates`` with the following
content:
.. code::
.. path ansible/roles/common/templates/cron-logrotate-PROJECT.conf.j2
.. code-block:: none
"/var/log/kolla/PROJECT/*.log"
{
}
.. end
- For OpenStack services there should be an entry in the ``services`` list
in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``.
@ -114,7 +117,7 @@ that Kolla uses throughout that should be followed.
- All YAML data files should start with three dashes (``---``).
Other than the above, most roles follow the following pattern:
Other than the above, most service roles abide by the following pattern:
- ``Register``: Involves registering the service with Keystone, creating
endpoints, roles, users, etc.

36
doc/source/contributor/kolla-for-openstack-development.rst
View File

@ -14,10 +14,10 @@ submitting a patch to Heat using Kolla as an example.
Only source containers are supported.
.. WARNING::
.. warning::
Kolla dev mode is intended for OpenStack hacking/development only. Do not
use this in production!
Kolla dev mode is intended for OpenStack hacking or development only.
Do not use this in production!
Enabling Kolla "dev mode"
-------------------------
@ -25,16 +25,22 @@ Enabling Kolla "dev mode"
To enable dev mode for all supported services, set in
``/etc/kolla/globals.yml``:
::
.. path /etc/kolla/globals.yml
.. code-block:: none
kolla_dev_mode: true
.. end
To enable it just for heat, set:
::
.. path /etc/kolla/globals.yml
.. code-block:: none
heat_dev_mode: true
.. end
Usage
-----
@ -44,33 +50,41 @@ container's virtualenv under the location expected by the service on startup.
After making code changes, simply restart the container to pick them up:
::
.. code-block:: console
docker restart heat_api
.. end
Debugging
---------
``remote_pdb`` can be used to perform debugging with Kolla containers. First,
make sure it is installed in the container in question:
::
.. code-block:: console
docker exec -it -u root heat_api pip install remote_pdb
.. end
Then, set your breakpoint as follows:
::
.. code-block:: none
from remote_pdb import RemotePdb
RemotePdb('127.0.0.1', 4444).set_trace()
.. end
Once you run the code(restart the container), pdb can be accessed using
``socat``:
::
.. code-block:: console
socat readline tcp:127.0.0.1:4444
For more information on remote_pdb, see
https://pypi.python.org/pypi/remote-pdb.
.. end
Learn more information about `remote_pdb
<https://pypi.python.org/pypi/remote-pdb>`_.

59
doc/source/contributor/running-tests.rst
View File

@ -6,8 +6,9 @@ Running tests
Kolla-ansible contains a suit of tests in the ``tests`` directory.
Any proposed code change in gerrit is automatically rejected by the OpenStack
Jenkins server [#f1]_ if the change causes test failures.
Any proposed code change in gerrit is automatically rejected by the
`OpenStack Jenkins server <https://docs.openstack.org/infra/system-config/jjb.html>`__
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.
@ -22,30 +23,36 @@ so the only package you install is ``tox`` itself:
.. code-block:: console
$ pip install tox
pip install tox
See `the unit testing section of the Testing wiki page`_ for more information.
Following are some simple examples.
.. end
For more information, see `the unit testing section of the Testing wiki page
<https://wiki.openstack.org/wiki/Testing#Unit_Tests>`_. For example:
To run the Python 2.7 tests:
.. code-block:: console
$ tox -e py27
tox -e py27
.. end
To run the style tests:
.. code-block:: console
$ tox -e pep8
tox -e pep8
.. end
To run multiple tests separate items by commas:
.. code-block:: console
$ tox -e py27,py34,pep8
tox -e py27,py35,pep8
.. _the unit testing section of the Testing wiki page: https://wiki.openstack.org/wiki/Testing#Unit_Tests
.. end
Running a subset of tests
-------------------------
@ -59,31 +66,39 @@ directory use:
.. code-block:: console
$ tox -e py27 kolla-ansible.tests
tox -e py27 kolla-ansible.tests
.. end
To run the tests of a specific file
say ``kolla-ansible/tests/test_kolla_docker.py``:
``kolla-ansible/tests/test_kolla_docker.py``:
.. code-block:: console
$ tox -e py27 test_kolla_docker
tox -e py27 test_kolla_docker
.. end
To run the tests in the ``ModuleArgsTest`` class in
the ``kolla-ansible/tests/test_kolla_docker.py`` file:
.. code-block:: console
$ tox -e py27 test_kolla_docker.ModuleArgsTest
tox -e py27 test_kolla_docker.ModuleArgsTest
.. end
To run the ``ModuleArgsTest.test_module_args`` test method in
the ``kolla-ansible/tests/test_kolla_docker.py`` file:
.. code-block:: console
$ tox -e py27 test_kolla_docker.ModuleArgsTest.test_module_args
tox -e py27 test_kolla_docker.ModuleArgsTest.test_module_args
.. end
Debugging unit tests
------------------------
--------------------
In order to break into the debugger from a unit test we need to insert
a breaking point to the code:
@ -92,15 +107,17 @@ a breaking point to the code:
import pdb; pdb.set_trace()
Then run ``tox`` with the debug environment as one of the following::
.. end
Then run ``tox`` with the debug environment as one of the following:
.. code-block:: console
tox -e debug
tox -e debug test_file_name.TestClass.test_name
For more information see the `oslotest documentation
.. end
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

139
doc/source/contributor/vagrant-dev-env.rst
View File

@ -42,56 +42,96 @@ choice. Various downloads can be found at the `Vagrant downloads
Install required dependencies as follows:
On CentOS::
For CentOS 7 or later:
.. code-block:: console
sudo yum install ruby-devel libvirt-devel zlib-devel libpng-devel gcc \
qemu-kvm qemu-img libvirt libvirt-python libvirt-client virt-install \
bridge-utils git
On Ubuntu 16.04 or later::
.. end
sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt libvirt-dev nfs-kernel-server zlib1g-dev libpng12-dev gcc git
For Ubuntu 16.04 or later:
.. note:: Many distros ship outdated versions of Vagrant by default. When in
.. code-block:: console
sudo apt-get install vagrant ruby-dev ruby-libvirt python-libvirt \
libvirt-dev nfs-kernel-server zlib1g-dev libpng12-dev gcc git
.. end
.. note::
Many distros ship outdated versions of Vagrant by default. When in
doubt, always install the latest from the downloads page above.
Next install the hostmanager plugin so all hosts are recorded in ``/etc/hosts``
(inside each vm)::
(inside each vm):
.. code-block:: console
vagrant plugin install vagrant-hostmanager
If you are going to use VirtualBox, then install vagrant-vbguest::
.. end
If you are going to use VirtualBox, then install vagrant-vbguest:
.. code-block:: console
vagrant plugin install vagrant-vbguest
.. end
Vagrant supports a wide range of virtualization technologies. If VirtualBox is
used, the vbguest plugin will be required to install the VirtualBox Guest
Additions in the virtual machine::
Additions in the virtual machine:
.. code-block:: console
vagrant plugin install vagrant-vbguest
.. end
This documentation focuses on libvirt specifics. To install vagrant-libvirt
plugin::
plugin:
.. code-block:: console
vagrant plugin install --plugin-version ">= 0.0.31" vagrant-libvirt
.. end
Some Linux distributions offer vagrant-libvirt packages, but the version they
provide tends to be too old to run Kolla. A version of >= 0.0.31 is required.
To use libvirt from Vagrant with a low privileges user without being asked for
a password, add the user to the libvirt group::
a password, add the user to the libvirt group:
.. code-block:: console
sudo gpasswd -a ${USER} libvirt
newgrp libvirt
.. end
Setup NFS to permit file sharing between host and VMs. Contrary to the rsync
method, NFS allows both way synchronization and offers much better performance
than VirtualBox shared folders. On CentOS::
than VirtualBox shared folders. For CentOS:
#. Add the virtual interfaces to the internal zone:
.. code-block:: console
# Add the virtual interfaces to the internal zone
sudo firewall-cmd --zone=internal --add-interface=virbr0
sudo firewall-cmd --zone=internal --add-interface=virbr1
# Enable nfs, rpc-bind and mountd services for firewalld
.. end
#. Enable nfs, rpc-bind and mountd services for firewalld:
.. code-block:: console
sudo firewall-cmd --permanent --zone=internal --add-service=nfs
sudo firewall-cmd --permanent --zone=internal --add-service=rpc-bind
sudo firewall-cmd --permanent --zone=internal --add-service=mountd
@ -100,30 +140,50 @@ than VirtualBox shared folders. On CentOS::
sudo firewall-cmd --permanent --add-port=111/udp
sudo firewall-cmd --permanent --add-port=111/tcp
sudo firewall-cmd --reload
# Start required services for NFS
.. end
#. Start required services for NFS:
.. code-block:: console
sudo systemctl restart firewalld
sudo systemctl start nfs-server
sudo systemctl start rpcbind.service
.. end
Ensure your system has libvirt and associated software installed and setup
correctly. On CentOS::
correctly. For CentOS:
.. code-block:: console
sudo systemctl start libvirtd
sudo systemctl enable libvirtd
Find a location in the system's home directory and checkout Kolla repos::
.. end
Find a location in the system's home directory and checkout Kolla repos:
.. code-block:: console
git clone https://git.openstack.org/openstack/kolla-ansible
git clone https://git.openstack.org/openstack/kolla
.. end
Both repos must share the same parent directory so the bootstrap code can
locate them.
Developers can now tweak the Vagrantfile or bring up the default **all-in-one**
CentOS 7-based environment::
CentOS 7-based environment:
.. code-block:: console
cd kolla-ansible/contrib/dev/vagrant && vagrant up
.. end
The command ``vagrant status`` provides a quick overview of the VMs composing
the environment.
@ -131,10 +191,14 @@ Vagrant Up
==========
Once Vagrant has completed deploying all nodes, the next step is to launch
Kolla. First, connect with the **operator** node::
Kolla. First, connect with the **operator** node:
.. code-block:: console
vagrant ssh operator
.. end
To speed things up, there is a local registry running on the operator. All
nodes are configured so they can use this insecure repo to pull from, and use
it as a mirror. Ansible may use this registry to pull images from.
@ -150,42 +214,63 @@ like ``vagrant destroy``.
Building images
---------------
Once logged on the **operator** VM call the ``kolla-build`` utility::
Once logged on the **operator** VM call the ``kolla-build`` utility:
.. code-block:: console
kolla-build
``kolla-build`` accept arguments as documented in `Building Container Images`_.
.. end
``kolla-build`` accept arguments as documented in `Building Container Images
<https://docs.openstack.org/kolla/latest/admin/image-building.html>`_.
It builds Docker images and pushes them to the local registry if the **push**
option is enabled (in Vagrant this is the default behaviour).
Deploying OpenStack with Kolla
------------------------------
Deploy **all-in-one** with::
To deploy **all-in-one**:
.. code-block:: console
sudo kolla-ansible deploy
Deploy multinode
On Centos 7::
.. end
To deploy multinode:
For Centos 7:
.. code-block:: console
sudo kolla-ansible deploy -i /usr/share/kolla-ansible/ansible/inventory/multinode
On Ubuntu 16.04 or later::
.. end
For Ubuntu 16.04 or later:
.. code-block:: console
sudo kolla-ansible deploy -i /usr/local/share/kolla-ansible/ansible/inventory/multinode
Validate OpenStack is operational::
.. end
Validate OpenStack is operational:
.. code-block:: console
kolla-ansible post-deploy
. /etc/kolla/admin-openrc.sh
openstack user list
Or navigate to http://172.28.128.254/ with a web browser.
.. end
Or navigate to ``http://172.28.128.254/`` with a web browser.
Further Reading
===============
All Vagrant documentation can be found at
`Vagrant documentation` <https://www.vagrantup.com/docs/>`__.
`Vagrant documentation <https://www.vagrantup.com/docs/>`_.
.. _Building Container Images: https://docs.openstack.org/kolla/latest/admin/image-building.html