OpenStack Ansible Deployment Scripts
====================================

The repository contains several helper scripts to manage gate jobs,
install base requirements, and update repository information. Invoke
these scripts from the top-level directory of the repository. For
example:

.. code:: bash

   $ scripts/<script_name>.sh

Bootstrapping
^^^^^^^^^^^^^

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. Create the necessary
partitions, directories, and configurations. Configurable via environment
variables to work with Jenkins.

bootstrap-ansible.sh
--------------------

The ``bootstrap-ansible.sh`` script installs Ansible including core and extras
module repositories and Galaxy roles.

Configurable environment variables:

* ``ANSIBLE_GIT_RELEASE`` - Version of Ansible to install.
* ``ANSIBLE_ROLE_FILE`` - Galaxy roles to install. Defaults to
  contents of ``ansible-role-requirements.yml`` file.

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.

Gating
^^^^^^

gate-check-commit.sh
--------------------

The ``gate-check-commit.sh`` script executes a suite of tests necessary for
each commit to the repository. By default, the script runs the bootstrap
scripts, builds an *all-in-one* deployment of OSAD, and runs various Tempest
tests on it.

Configurable environment variables:

* ``BOOTSTRAP_AIO`` - Boolean (yes/no) to run AIO bootstrap script. Defaults
  to ``yes``.
* ``BOOTSTRAP_AIO`` - Boolean (yes/no) to run Ansible bootstrip script.
  Defaults to ``yes``.
* ``RUN_TEMPEST`` - Boolean (yes/no) to run Tempest tests. Defaults to
  ``yes``.

gate-check-docs.sh
------------------

The ``gate-check-docs.sh`` script invokes Sphinx to build the HTML
documentation from RST source.

gate-check-lint.sh
------------------

The ``gate-check-lint.sh`` script executes a suite of tests necessary for each
commit to the repository to verify correct YAML and Python syntax.

All files that begin with a Python shebang pass through *flake8* which ignores
the following rules due to Ansible conventions:

 * F403 - 'from ansible.module_utils.basic import \*'
 * H303 - No wildcard imports

Ansible playbooks pass through ``ansible-playbook --syntax-check``
and ``ansible-lint``.

run-tempest.sh
--------------

The ``run-tempest.sh`` script runs Tempest tests from the first utility
container. The ``check-gate-commit.sh`` script usually invokes this
script after it completes the OSAD deployment.

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``.