openstack-ansible/doc/source/developer-docs/extending.rst
Jesse Pretorius 24e63abeb2 Fix 'D001 Line too long' documentation lint failures
Change-Id: I4522fe318541dac7f4ff4e45d72d4cd8869420ba
2016-07-13 21:32:31 +00:00

312 lines
10 KiB
ReStructuredText

`Home <index.html>`_ OpenStack-Ansible Developer Documentation
Extending OpenStack-Ansible
===========================
The OpenStack-Ansible project provides a basic OpenStack environment, but
many deployers will wish to extend the environment based on their needs. This
could include installing extra services, changing package versions, or
overriding existing variables.
Using these extension points, deployers can provide a more 'opinionated'
installation of OpenStack that may include their own software.
Including OpenStack-Ansible in your project
-------------------------------------------
Including the openstack-ansible repository within another project can be
done in several ways.
1. A git submodule pointed to a released tag.
2. A script to automatically perform a git checkout of
openstack-ansible
When including OpenStack-Ansible in a project, consider using a parallel
directory structure as shown in the `ansible.cfg files`_ section.
Also note that copying files into directories such as `env.d`_ or
`conf.d`_ should be handled via some sort of script within the extension
project.
ansible.cfg files
-----------------
You can create your own playbook, variable, and role structure while still
including the OpenStack-Ansible roles and libraries by putting an
``ansible.cfg`` file in your ``playbooks`` directory.
The relevant options for Ansible 1.9 (included in OpenStack-Ansible)
are as follows:
``library``
This variable should point to
``openstack-ansible/playbooks/library``. Doing so allows roles and
playbooks to access OpenStack-Ansible's included Ansible modules.
``roles_path``
This variable should point to
``openstack-ansible/playbooks/roles``. This allows Ansible to
properly look up any OpenStack-Ansible roles that extension roles
may reference.
``inventory``
This variable should point to
``openstack-ansible/playbooks/inventory``. With this setting,
extensions have access to the same dynamic inventory that
OpenStack-Ansible uses.
Note that the paths to the ``openstack-ansible`` top level directory can be
relative in this file.
Consider this directory structure::
my_project
|
|- custom_stuff
| |
| |- playbooks
|- openstack-ansible
| |
| |- playbooks
The variables in ``my_project/custom_stuff/playbooks/ansible.cfg`` would use
``../openstack-ansible/playbooks/<directory>``.
env.d
-----
The ``/etc/openstack_deploy/env.d`` directory sources all YAML files into the
deployed environment, allowing a deployer to define additional group mappings.
This directory is used to extend the environment skeleton, or modify the
defaults defined in the ``playbooks/inventory/env.d`` directory.
See also `Understanding Container Groups`_ in Appendix H.
.. _Understanding Container Groups: ../install-guide/app-custom-layouts.html#understanding-container-groups
conf.d
------
Common OpenStack services and their configuration are defined by
OpenStack-Ansible in the
``/etc/openstack_deploy/openstack_user_config.yml`` settings file.
Additional services should be defined with a YAML file in
``/etc/openstack_deploy/conf.d``, in order to manage file size.
See also `Understanding Host Groups`_ in Appendix H.
.. _Understanding Host Groups: ../install-guide/app-custom-layouts.html#understanding-host-groups
user\_*.yml files
-----------------
Files in ``/etc/openstack_deploy`` beginning with ``user_`` will be
automatically sourced in any ``openstack-ansible`` command. Alternatively,
the files can be sourced with the ``-e`` parameter of the ``ansible-playbook``
command.
``user_variables.yml`` and ``user_secrets.yml`` are used directly by
OpenStack-Ansible. Adding custom variables used by your own roles and
playbooks to these files is not recommended. Doing so will complicate your
upgrade path by making comparison of your existing files with later versions
of these files more arduous. Rather, recommended practice is to place your own
variables in files named following the ``user_*.yml`` pattern so they will be
sourced alongside those used exclusively by OpenStack-Ansible.
Ordering and Precedence
+++++++++++++++++++++++
``user_*.yml`` variables are just YAML variable files. They will be sourced
in alphanumeric order by ``openstack-ansible``.
.. _adding-galaxy-roles:
Adding Galaxy roles
-------------------
Any roles defined in ``openstack-ansible/ansible-role-requirements.yml``
will be installed by the
``openstack-ansible/scripts/bootstrap-ansible.sh`` script.
Setting overrides in configuration files
----------------------------------------
All of the services that use YAML, JSON, or INI for configuration can receive
overrides through the use of a Ansible action plugin named ``config_template``.
The configuration template engine allows a deployer to use a simple dictionary
to modify or add items into configuration files at run time that may not have a
preset template option. All OpenStack-Ansible roles allow for this
functionality where applicable. Files available to receive overrides can be
seen in the ``defaults/main.yml`` file as standard empty dictionaries (hashes).
Practical guidance for using this feature is available in the `Install Guide`_.
This module has been `submitted for consideration`_ into Ansible Core.
.. _Install Guide: ../install-guide/configure-openstack.html
.. _submitted for consideration: https://github.com/ansible/ansible/pull/12555
Build the environment with additional python packages
+++++++++++++++++++++++++++++++++++++++++++++++++++++
The system will allow you to install and build any package that is a python
installable. The repository infrastructure will look for and create any
git based or PyPi installable package. When the package is built the repo-build
role will create the sources as Python wheels to extend the base system and
requirements.
While the packages pre-built in the repository-infrastructure are
comprehensive, it may be needed to change the source locations and versions of
packages to suit different deployment needs. Adding additional repositories as
overrides is as simple as listing entries within the variable file of your
choice. Any ``user_.*.yml`` file within the "/etc/openstack_deployment"
directory will work to facilitate the addition of a new packages.
.. code-block:: yaml
swift_git_repo: https://private-git.example.org/example-org/swift
swift_git_install_branch: master
Additional lists of python packages can also be overridden using a
``user_.*.yml`` variable file.
.. code-block:: yaml
swift_requires_pip_packages:
- virtualenv
- virtualenv-tools
- python-keystoneclient
- NEW-SPECIAL-PACKAGE
Once the variables are set call the play ``repo-build.yml`` to build all of the
wheels within the repository infrastructure. When ready run the target plays to
deploy your overridden source code.
Module documentation
++++++++++++++++++++
These are the options available as found within the virtual module
documentation section.
.. code-block:: yaml
module: config_template
version_added: 1.9.2
short_description: >
Renders template files providing a create/update override interface
description:
- The module contains the template functionality with the ability to
override items in config, in transit, through the use of a simple
dictionary without having to write out various temp files on target
machines. The module renders all of the potential jinja a user could
provide in both the template file and in the override dictionary which
is ideal for deployers who may have lots of different configs using a
similar code base.
- The module is an extension of the **copy** module and all of attributes
that can be set there are available to be set here.
options:
src:
description:
- Path of a Jinja2 formatted template on the local server. This can
be a relative or absolute path.
required: true
default: null
dest:
description:
- Location to render the template to on the remote machine.
required: true
default: null
config_overrides:
description:
- A dictionary used to update or override items within a configuration
template. The dictionary data structure may be nested. If the target
config file is an ini file the nested keys in the ``config_overrides``
will be used as section headers.
config_type:
description:
- A string value describing the target config type.
choices:
- ini
- json
- yaml
Example task using the "config_template" module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: yaml
- name: Run config template ini
config_template:
src: test.ini.j2
dest: /tmp/test.ini
config_overrides: {{ test_overrides }}
config_type: ini
Example overrides dictionary(hash)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: yaml
test_overrides:
DEFAULT:
new_item: 12345
Original template file "test.ini.j2"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: ini
[DEFAULT]
value1 = abc
value2 = 123
Rendered on disk file "/tmp/test.ini"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: ini
[DEFAULT]
value1 = abc
value2 = 123
new_item = 12345
In this task the ``test.ini.j2`` file is a template which will be rendered and
written to disk at ``/tmp/test.ini``. The **config_overrides** entry is a
dictionary(hash) which allows a deployer to set arbitrary data as overrides to
be written into the configuration file at run time. The **config_type** entry
specifies the type of configuration file the module will be interacting with;
available options are "yaml", "json", and "ini".
Discovering Available Overrides
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All of these options can be specified in any way that suits your deployment.
In terms of ease of use and flexibility it's recommended that you define your
overrides in a user variable file such as
``/etc/openstack_deploy/user_variables.yml``.
The list of overrides available may be found by executing:
.. code-block:: bash
find . -name "main.yml" -exec grep '_.*_overrides:' {} \; \
| grep -v "^#" \
| sort -u
--------------
.. include:: navigation.txt