From 0ec7f7d850c2f6425ea56724b9d702011868c124 Mon Sep 17 00:00:00 2001 From: Nolan Brubaker Date: Sat, 16 May 2015 19:35:14 -0400 Subject: [PATCH] Add an extension section to the developer docs. This extension section provides guidance for deployers wanting to add their own services and configuration to os-ansible-deployment. This documentation also includes some recommendations for how projects sourcing os-ansible-deployment might be structured. Change-Id: I7ddac9ff2cab8b5a7cb9af1ba6bb3bdde64d60ea Implements: blueprint developer-docs --- doc/source/extending.rst | 119 +++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 2 files changed, 120 insertions(+) create mode 100644 doc/source/extending.rst diff --git a/doc/source/extending.rst b/doc/source/extending.rst new file mode 100644 index 0000000000..a389604f51 --- /dev/null +++ b/doc/source/extending.rst @@ -0,0 +1,119 @@ +Extending os-ansible-deployment +=============================== + +The os-ansible-deployment 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 os-ansible-deployment in your project +----------------------------------------------- + +Including the os-ansible-deployment 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 + os-ansible-deployment + +When including os-ansible-deployment 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 os-ansible-deployment roles and libaries by putting an +``ansible.cfg`` file in your ``playbooks`` directory. + +The relevant options for Ansible 1.9 (included in os-ansible-deployment) +are as follows: + + ``library`` + This variable should point to + ``os-ansible-deployment/playbooks/library``. Doing so allows roles and + playbooks to access os-ansible-deployment's included Ansible modules. + ``roles_path`` + This variable should point to + ``os-ansible-deployment/playbooks/roles``. This allows Ansible to + properly look up any os-ansible-deployment roles that extension roles + may reference. + ``inventory`` + This variable should point to + ``os-ansible-deployment/playbooks/inventory``. With this setting, + extensions have access to the same dynamic inventory that + os-ansible-deployment uses. + +Note that the paths to the ``os-ansible-deployment`` top level directory can be +relative in this file. + +Consider this directory structure:: + + my_project + | + |- custom_stuff + | | + | |- playbooks + |- os-ansible-deployment + | | + | |- playbooks + +The variables in ``my_project/custom_stuff/playbooks/ansible.cfg`` would use +``../os-ansible-deployment/playbooks/``. + + +env.d +----- + +The os-ansible-deployment default environment, including container and host +group mappings, resides in ``/etc/openstack_deploy/openstack_environment.yml``. + +The ``/etc/openstack_deploy/env.d`` directory sources all YAML files into the +deployed environment, allowing a deployer to define additional group mappings +without having to edit the ``openstack_environment.yml`` file, which is +controlled by the os-ansible-deployment project itself. + +conf.d +------ + +Common OpenStack services and their configuration are defined by +os-ansible-deployment 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. + + +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 +os-ansible-deployment; adding custom values here is not recommended. + +``user_extras_variables.yml`` and ``users_extras_secrets.yml`` are provided +and can contain deployer's custom values, but deployers can add any other +files they wish to include new configuration, or override existing. + +Ordering and Precedence ++++++++++++++++++++++++ + +``user_*.yml`` variables are just YAML variable files. They will be sourced +in alphanumeric order by ``openstack-ansible``. + +Adding Galaxy roles +------------------- + +Any roles defined in ``os-ansible-deployment/ansible-role-requirements.yml`` +will be installed by the +``os-ansible-deployment/scripts/bootstrap-ansible.sh`` script. diff --git a/doc/source/index.rst b/doc/source/index.rst index 7d6bd9d1a3..556137701a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -18,6 +18,7 @@ Contents: :maxdepth: 2 playbooks + extending Indices and tables