openstack-ansible/doc/source/developer-docs/extending.rst

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/<directory>.

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.