openstack/kolla-ansible
Code Issues Proposed changes

Merge "Upgrade the rst convention of the Contributor Guide"

Browse Source
This commit is contained in:
Zuul 2018-03-22 06:58:35 +00:00 committed by Gerrit Code Review
commit bc5c9560a5
4 changed files with 251 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -7,37 +7,37 @@ How To Contribute
Basics Basics
====== ======
#. Our source code is hosted on `OpenStack Kolla-Ansible Git`_. Bugs should be #. Our source code is hosted on `OpenStack Kolla-Ansible Git
filed on launchpad_. <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 #. 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 of development. Kolla project has a strict policy of only allowing backports
in ``stable/branch``, unless when not applicable. A bug in a in ``stable/branch``, unless when not applicable. A bug in a
``stable/branch`` will first have to be fixed in ``master``. ``stable/branch`` will first have to be fixed in ``master``.
#. Please file a launchpad_ blueprint for any significant code change and a bug #. Please file a `blueprint of kolla-ansible <https://blueprints.launchpad.net/kolla-ansible>`__
for any significant bug fix or add a TrivialFix tag for simple changes. 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_ 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. #. 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 Development Environment
======================= =======================
Please follow our :doc:`/user/quickstart` to deploy your environment and test Please follow our :doc:`/user/quickstart` to deploy your environment and test
your changes. your changes.
Please use the existing sandbox repository, available at Please use the existing sandbox repository, available at `sandbox
https://git.openstack.org/cgit/openstack-dev/sandbox, for learning, understanding <https://git.openstack.org/cgit/openstack-dev/sandbox>`_, for learning, understanding
and testing the `Gerrit Workflow`_. and testing the `Gerrit Workflow
<https://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.
.. _Gerrit Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow
Adding a new service 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 template file in ``ansible/roles/common/templates`` with the following
content: content:
.. code:: .. path ansible/roles/common/templates/cron-logrotate-PROJECT.conf.j2
.. code-block:: none
"/var/log/kolla/PROJECT/*.log" "/var/log/kolla/PROJECT/*.log"
{ {
} }
.. end
- For OpenStack services there should be an entry in the ``services`` list - For OpenStack services there should be an entry in the ``services`` list
in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``. in the ``cron.json.j2`` template file in ``ansible/roles/common/templates``.
@ -114,18 +117,18 @@ that Kolla uses throughout that should be followed.
- All YAML data files should start with three dashes (``---``). - 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 - ``Register``: Involves registering the service with Keystone, creating
endpoints, roles, users, etc. endpoints, roles, users, etc.
- ``Config``: Distributes the config files to the nodes to be pulled into - ``Config``: Distributes the config files to the nodes to be pulled into
the container on startup. the container on startup.
- ``Bootstrap``: Creating the database (but not tables), database user for - ``Bootstrap``: Creating the database (but not tables), database user for
the service, permissions, etc. the service, permissions, etc.
- ``Bootstrap Service``: Starts a one shot container on the host to create - ``Bootstrap Service``: Starts a one shot container on the host to create
the database tables, and other initial run time config. the database tables, and other initial run time config.
- ``Start``: Start the service(s). - ``Start``: Start the service(s).

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

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

65
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. Kolla-ansible contains a suit of tests in the ``tests`` directory.
Any proposed code change in gerrit is automatically rejected by the OpenStack Any proposed code change in gerrit is automatically rejected by the
Jenkins server [#f1]_ if the change causes test failures. `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 It is recommended for developers to run the test suite before submitting patch
for review. This allows to catch errors as early as possible. 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 .. code-block:: console
$ pip install tox pip install tox
See `the unit testing section of the Testing wiki page`_ for more information. .. end
Following are some simple examples.
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: To run the Python 2.7 tests:
.. code-block:: console .. code-block:: console
$ tox -e py27 tox -e py27
.. end
To run the style tests: To run the style tests:
.. code-block:: console .. code-block:: console
$ tox -e pep8 tox -e pep8
.. end
To run multiple tests separate items by commas: To run multiple tests separate items by commas:
.. code-block:: console .. 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 Running a subset of tests
------------------------- -------------------------
@ -59,48 +66,58 @@ directory use:
.. code-block:: console .. code-block:: console
$ tox -e py27 kolla-ansible.tests tox -e py27 kolla-ansible.tests
.. end
To run the tests of a specific file 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 .. 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 To run the tests in the ``ModuleArgsTest`` class in
the ``kolla-ansible/tests/test_kolla_docker.py`` file: the ``kolla-ansible/tests/test_kolla_docker.py`` file:
.. code-block:: console .. 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 To run the ``ModuleArgsTest.test_module_args`` test method in
the ``kolla-ansible/tests/test_kolla_docker.py`` file: the ``kolla-ansible/tests/test_kolla_docker.py`` file:
.. code-block:: console .. 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 Debugging unit tests
------------------------ --------------------
In order to break into the debugger from a unit test we need to insert In order to break into the debugger from a unit test we need to insert
a breaking point to the code: a breaking point to the code:
.. code-block:: python .. code-block:: python
import pdb; pdb.set_trace() import pdb; pdb.set_trace()
Then run ``tox`` with the debug environment as one of the following:: .. end
tox -e debug Then run ``tox`` with the debug environment as one of the following:
tox -e debug test_file_name.TestClass.test_name
For more information see the `oslotest documentation .. code-block:: console
tox -e debug
tox -e debug test_file_name.TestClass.test_name
.. end
For more information, see the `oslotest documentation
<https://docs.openstack.org/oslotest/latest/user/features.html#debugging-with-oslo-debug-helper>`_. <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

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

@ -42,87 +42,147 @@ choice. Various downloads can be found at the `Vagrant downloads
Install required dependencies as follows: Install required dependencies as follows:
On CentOS:: For CentOS 7 or later:
sudo yum install ruby-devel libvirt-devel zlib-devel libpng-devel gcc \ .. code-block:: console
qemu-kvm qemu-img libvirt libvirt-python libvirt-client virt-install \
bridge-utils git
On Ubuntu 16.04 or later:: 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
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 For Ubuntu 16.04 or later:
doubt, always install the latest from the downloads page above.
.. 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`` Next install the hostmanager plugin so all hosts are recorded in ``/etc/hosts``
(inside each vm):: (inside each vm):
vagrant plugin install vagrant-hostmanager .. code-block:: console
If you are going to use VirtualBox, then install vagrant-vbguest:: vagrant plugin install vagrant-hostmanager
vagrant plugin 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 Vagrant supports a wide range of virtualization technologies. If VirtualBox is
used, the vbguest plugin will be required to install the VirtualBox Guest used, the vbguest plugin will be required to install the VirtualBox Guest
Additions in the virtual machine:: Additions in the virtual machine:
vagrant plugin install vagrant-vbguest .. code-block:: console
vagrant plugin install vagrant-vbguest
.. end
This documentation focuses on libvirt specifics. To install vagrant-libvirt This documentation focuses on libvirt specifics. To install vagrant-libvirt
plugin:: plugin:
vagrant plugin install --plugin-version ">= 0.0.31" vagrant-libvirt .. 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 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. 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 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:
sudo gpasswd -a ${USER} libvirt .. code-block:: console
newgrp libvirt
sudo gpasswd -a ${USER} libvirt
newgrp libvirt
.. end
Setup NFS to permit file sharing between host and VMs. Contrary to the rsync 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 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 #. Add the virtual interfaces to the internal zone:
sudo firewall-cmd --zone=internal --add-interface=virbr0
sudo firewall-cmd --zone=internal --add-interface=virbr1 .. code-block:: console
# Enable nfs, rpc-bind and mountd services for firewalld
sudo firewall-cmd --permanent --zone=internal --add-service=nfs sudo firewall-cmd --zone=internal --add-interface=virbr0
sudo firewall-cmd --permanent --zone=internal --add-service=rpc-bind sudo firewall-cmd --zone=internal --add-interface=virbr1
sudo firewall-cmd --permanent --zone=internal --add-service=mountd
sudo firewall-cmd --permanent --zone=internal --add-port=2049/udp .. end
sudo firewall-cmd --permanent --add-port=2049/tcp
sudo firewall-cmd --permanent --add-port=111/udp #. Enable nfs, rpc-bind and mountd services for firewalld:
sudo firewall-cmd --permanent --add-port=111/tcp
sudo firewall-cmd --reload .. code-block:: console
# Start required services for NFS
sudo systemctl restart firewalld sudo firewall-cmd --permanent --zone=internal --add-service=nfs
sudo systemctl start nfs-server sudo firewall-cmd --permanent --zone=internal --add-service=rpc-bind
sudo systemctl start rpcbind.service sudo firewall-cmd --permanent --zone=internal --add-service=mountd
sudo firewall-cmd --permanent --zone=internal --add-port=2049/udp
sudo firewall-cmd --permanent --add-port=2049/tcp
sudo firewall-cmd --permanent --add-port=111/udp
sudo firewall-cmd --permanent --add-port=111/tcp
sudo firewall-cmd --reload
.. 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 Ensure your system has libvirt and associated software installed and setup
correctly. On CentOS:: correctly. For CentOS:
sudo systemctl start libvirtd .. code-block:: console
sudo systemctl enable libvirtd
Find a location in the system's home directory and checkout Kolla repos:: sudo systemctl start libvirtd
sudo systemctl enable libvirtd
git clone https://git.openstack.org/openstack/kolla-ansible .. end
git clone https://git.openstack.org/openstack/kolla
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 Both repos must share the same parent directory so the bootstrap code can
locate them. locate them.
Developers can now tweak the Vagrantfile or bring up the default **all-in-one** Developers can now tweak the Vagrantfile or bring up the default **all-in-one**
CentOS 7-based environment:: CentOS 7-based environment:
cd kolla-ansible/contrib/dev/vagrant && vagrant up .. 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 command ``vagrant status`` provides a quick overview of the VMs composing
the environment. the environment.
@ -131,9 +191,13 @@ Vagrant Up
========== ==========
Once Vagrant has completed deploying all nodes, the next step is to launch 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:
vagrant ssh operator .. code-block:: console
vagrant ssh operator
.. end
To speed things up, there is a local registry running on the operator. All 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 nodes are configured so they can use this insecure repo to pull from, and use
@ -150,42 +214,63 @@ like ``vagrant destroy``.
Building images Building images
--------------- ---------------
Once logged on the **operator** VM call the ``kolla-build`` utility:: Once logged on the **operator** VM call the ``kolla-build`` utility:
kolla-build .. code-block:: console
``kolla-build`` accept arguments as documented in `Building Container Images`_. kolla-build
.. 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** It builds Docker images and pushes them to the local registry if the **push**
option is enabled (in Vagrant this is the default behaviour). option is enabled (in Vagrant this is the default behaviour).
Deploying OpenStack with Kolla Deploying OpenStack with Kolla
------------------------------ ------------------------------
Deploy **all-in-one** with:: To deploy **all-in-one**:
sudo kolla-ansible deploy .. code-block:: console
Deploy multinode sudo kolla-ansible deploy
On Centos 7::
sudo kolla-ansible deploy -i /usr/share/kolla-ansible/ansible/inventory/multinode .. end
On Ubuntu 16.04 or later:: To deploy multinode:
sudo kolla-ansible deploy -i /usr/local/share/kolla-ansible/ansible/inventory/multinode For Centos 7:
Validate OpenStack is operational:: .. code-block:: console
kolla-ansible post-deploy sudo kolla-ansible deploy -i /usr/share/kolla-ansible/ansible/inventory/multinode
. /etc/kolla/admin-openrc.sh
openstack user list
Or navigate to http://172.28.128.254/ with a web browser. .. end
For Ubuntu 16.04 or later:
.. code-block:: console
sudo kolla-ansible deploy -i /usr/local/share/kolla-ansible/ansible/inventory/multinode
.. end
Validate OpenStack is operational:
.. code-block:: console
kolla-ansible post-deploy
. /etc/kolla/admin-openrc.sh
openstack user list
.. end
Or navigate to ``http://172.28.128.254/`` with a web browser.
Further Reading Further Reading
=============== ===============
All Vagrant documentation can be found at 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