195 lines
5.9 KiB
ReStructuredText
195 lines
5.9 KiB
ReStructuredText
`Home <index.html>`_ OpenStack-Ansible Developer Documentation
|
|
|
|
Included Scripts
|
|
================
|
|
|
|
The repository contains several helper scripts to manage gate jobs,
|
|
install base requirements, and update repository information. Execute
|
|
these scripts from the root of the repository clone. For example:
|
|
|
|
.. code:: bash
|
|
|
|
$ scripts/<script_name>.sh
|
|
|
|
Bootstrapping
|
|
^^^^^^^^^^^^^
|
|
|
|
bootstrap-ansible.sh
|
|
--------------------
|
|
|
|
The ``bootstrap-ansible.sh`` script installs Ansible including `core`_ and
|
|
`extras`_ module repositories and Galaxy roles.
|
|
|
|
While there are several configurable environment variables which this script
|
|
uses, the following are commonly used:
|
|
|
|
* ``ANSIBLE_GIT_RELEASE`` - The version of Ansible to install.
|
|
|
|
* ``ANSIBLE_ROLE_FILE`` - The location of a yaml file which ansible-galaxy can
|
|
consume which specifies which roles to download and install. The default
|
|
value for this is ``ansible-role-requirements.yml``.
|
|
|
|
The script also creates the ``openstack-ansible`` wrapper tool that provides
|
|
the variable files to match ``/etc/openstack_deploy/user_*.yml`` as
|
|
arguments to ``ansible-playbook`` as a convenience.
|
|
|
|
.. _core: https://github.com/ansible/ansible-modules-core
|
|
.. _extras: https://github.com/ansible/ansible-modules-extras
|
|
|
|
bootstrap-aio.sh
|
|
----------------
|
|
|
|
The ``bootstrap-aio.sh`` script prepares a host for an `All-In-One`_ (AIO)
|
|
deployment for the purposes of development and gating. The script creates the
|
|
necessary partitions, directories, and configurations. The script can be
|
|
configured using environment variables - more details are provided on the
|
|
`All-In-One`_ page.
|
|
|
|
.. _All-In-One: quickstart-aio
|
|
|
|
Development and Testing
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
run-playbooks.sh
|
|
----------------
|
|
|
|
The ``run-playbooks`` script is designed to be executed in development and
|
|
test environments and is also used for automated testing. It executes actions
|
|
which are definitely **not** suitable for production environments and must
|
|
therefore **not** be used for that purpose.
|
|
|
|
In order to scope the playbook execution there are several ``DEPLOY_``
|
|
environment variables available near the top of the script. These are used
|
|
by simply exporting an override before executing the script. For example,
|
|
to skip the execution of the Ceilometer playbook, execute:
|
|
|
|
.. code-block:: bash
|
|
|
|
export DEPLOY_CEILOMETER='no'
|
|
|
|
The default MaxSessions setting for the OpenSSH Daemon is 10. Each Ansible
|
|
fork makes use of a Session. By default Ansible sets the number of forks to 5,
|
|
but the ``run-playbooks.sh`` script sets the number of forks used based on the
|
|
number of CPU's on the deployment host up to a maximum of 10.
|
|
|
|
If a developer wishes to increase the number of forks used when using this
|
|
script, override the FORKS environment variable. For example:
|
|
|
|
.. code-block:: bash
|
|
|
|
export FORKS=20
|
|
|
|
run-tempest.sh
|
|
--------------
|
|
|
|
The ``run-tempest.sh`` script runs Tempest tests from the first utility
|
|
container. This is primarily used for automated gate testing, but may also be
|
|
used through manual execution.
|
|
|
|
Configurable environment variables:
|
|
|
|
* ``TEMPEST_SCRIPT_PARAMETERS`` - Defines tests to run. Values are passed to
|
|
``openstack_tempest_gate.sh`` script, defined in the ``os_tempest`` role.
|
|
Defaults to ``scenario heat_api cinder_backup``.
|
|
|
|
Lint Tests
|
|
----------
|
|
|
|
Python coding conventions are tested using `PEP8`_, with the following
|
|
convention exceptions:
|
|
|
|
* F403 - 'from ansible.module_utils.basic import \*'
|
|
* H303 - No wildcard imports
|
|
|
|
Testing may be done locally by executing:
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e pep8
|
|
|
|
Bash coding conventions are tested using `Bashate`_, with the following
|
|
convention exceptions:
|
|
|
|
* E003: Indent not multiple of 4. We prefer to use multiples of 2 instead.
|
|
* E006: Line longer than 79 columns. As many scripts are deployed as templates
|
|
and use jinja templating, this is very difficult to achieve. It is
|
|
still considered a preference and should be a goal to improve
|
|
readability, within reason.
|
|
* E040: Syntax error determined using `bash -n`. As many scripts are deployed
|
|
as templates and use use jinja templating, this will often fail. This
|
|
test is reasonably safely ignored as the syntax error will be
|
|
identified when executing the resulting script.
|
|
|
|
Testing may be done locally by executing:
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e bashate
|
|
|
|
Ansible is lint tested using `ansible-lint`_.
|
|
|
|
Testing may be done locally by executing:
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e ansible-lint
|
|
|
|
Ansible playbook syntax is tested using ansible-playbook.
|
|
|
|
Testing may be done locally by executing:
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e ansible-syntax
|
|
|
|
A consolidated set of all lint tests may be done locally by executing:
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e linters
|
|
|
|
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
|
|
.. _Bashate: https://github.com/openstack-dev/bashate
|
|
.. _ansible-lint: https://github.com/willthames/ansible-lint
|
|
|
|
Documentation Build
|
|
-------------------
|
|
|
|
Documentation is developed in reStructuredText_ (RST) and compiled into
|
|
HTML using Sphinx.
|
|
|
|
Documentation may be built locally by executing:
|
|
|
|
.. code-block:: bash
|
|
|
|
tox -e docs
|
|
|
|
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
|
|
|
|
Gating
|
|
^^^^^^
|
|
|
|
Every commit to OpenStack-Ansible is verified by OpenStack-CI through the
|
|
following jobs:
|
|
|
|
* ``gate-openstack-ansible-docs``: This job executes the
|
|
`Documentation Build`_.
|
|
|
|
* ``gate-openstack-ansible-linters``: This job executes the `Lint Tests`_.
|
|
|
|
* ``gate-openstack-ansible-dsvm-commit``: This job executes the
|
|
``gate-check-commit.sh`` script which executes a convergence test and then a
|
|
functional test.
|
|
|
|
The convergence test is the execution of an AIO build
|
|
which aims to test the primary code path for a functional environment. The
|
|
functional test then executes OpenStack's Tempest testing suite to verify
|
|
that the environment that has deployed successfully actually works.
|
|
|
|
While this script is primarily developed and maintained for use in
|
|
OpenStack-CI, it can be used in other environments.
|
|
|
|
--------------
|
|
|
|
.. include:: navigation.txt
|