Home OpenStack-Ansible Developer Documentation
If you would like to contribute towards a role to introduce an OpenStack service or an infrastructure service to support an OpenStack deployment, the OpenStack-Ansible project would welcome that contribution and your assistance in maintaining it.
Most OpenStack services will follow a common series of stages to install or update a service deployment. This is apparent when you review tasks/main.yml for existing roles.
There may be other specialized steps required by some services but most of the roles will perform all of these at a minimum. Begin by reviewing a role for a service that has something in common with your service and think about how you can fit most of the common service setup and configuration steps into that model.
Hint
Following the patterns you find in other roles can help ensure your role is easier to use and maintain.
Steps to writing the role:
You can review roles which may be currently in development by checking our specs repository and unmerged specs on review.openstack.org. If you do not find a spec for the role, propose a blueprint/spec (see also the spec template) outlining the new Role. By proposing a draft spec you can help the OpenStack-Ansible community keep track of what roles are being developed and perhaps connect you with others who may be interested and able to help you in the process.
Create a source repository (e.g. on Github) to start your work on the Role.
Generate the reference directory structure for an Ansible role which is the necessary subset of the documented Best Practice. You might use Ansible Galaxy tools to do this for you (e.g. ansible-galaxy init). You may additionally want to include directories such as docs and examples and tests for your role.
Generate a meta/main.yml right away. This file is important to Ansible to ensure your dependent roles are installed and available and provides others with the information they will need to understand the purpose of your role.
Develop task files for each of the install stages in turn, creating any handlers and templates as needed. Ensure that you notify handlers after any task which impacts the way the service would run (such as configuration file modifications). Also take care that file ownership and permissions are appropriate.
Hint
Fill in variable defaults, libraries, and prerequisites as you discover a need for them. You can also develop documentation for your role at the same time.
Include your role on the deploy host. See also Adding Galaxy roles.
Perform any other host preparation (such as the tasks performed by the bootstrap-aio.yml playbook). This includes any preparation tasks that are particular to your service.
Generate files to include your service in the Ansible inventory using env.d and conf.d files for use on your deploy host.
Hint
You can follow examples from other roles, making the appropriate modifications being sure that group labels in env.d and conf.d files are consistent.
Generate secrets, if any, as described in the Install Guide. You can append your keys to an existing user_secrets.yml file or add a new file to the openstack_deploy directory to contain them. Provide overrides for any other variables you will need at this time as well, either in user_variables.yml or another file. This is explained in more depth under Extending OpenStack-Ansible.
If your service is installed from source or relies on python packages which need to be installed from source, specify a repository for the source code of each requirement by adding a file to your deploy host under playbooks/defaults/repo_packages in the OpenStack-Ansible source repository and following the pattern of files currently in that directory. You could also simply add an entry to an existing file there. Be sure to run the repo-build.yml play later so that wheels for your packages will be included in the repository infrastructure.
Make any required adjustments to the load balancer configuration (e.g. modify playbooks/vars/configs/haproxy_config.yml in the OpenStack-Ansible source repository on your deploy host) so that your service can be reached through a load balancer, if appropriate, and be sure to run the haproxy-install.yml play later so your changes will be applied.
Put together a service install playbook file for your role. This can also be modeled from any existing service playbook that has similar dependencies to your service (database, messaging, storage drivers, container mount points, etc.). A common place to keep playbook files in a Galaxy role is in an examples directory off the root of the role.
Hint
If you adhere to the pattern of isolating your role’s extra deployment requirements (secrets and var files, HAProxy yml fragments, repo_package files, etc.) in their own files it makes it easy for you to automate these additional steps when testing your role.