Ansible roles development
This document describes the conventions and process used by the OME team for developing, maintaining and releasing its Ansible roles.
The set of rules and procedures described below applies to the official OME roles registered in https://github.com/ome/ansible-roles.
Source code
The source code of an Ansible role should be maintained under version control using Git and hosted on GitHub under the ome organization. The Git repositories should be named as ansible-role-<ROLENAME>.
Each directory layout should minimally follow the standard Ansible role layout including other files and folders for testing and deployment. A typical role structure is shown below:
defaults/ # Default variables
handlers/ # Handlers
meta/ # Role metadata
main.yml # Dependencies and Galaxy metadata
molecule/ # Test
tasks/ # Main list of tasks to be executed
main.yml
templates/ # Role templates
.travis.yml # CI/deployment configuration file
README.md
Versioning
Ansible roles must follow the PEP440 scheme for versioning. Final releases must also be compliant with Semantic Versioning i.e. a final version must be expressed as MAJOR.MINOR.PATCH where:
the MAJOR version must be incremented when incompatible API changes are made,
the MINOR version must be incremented when functionality is added in a backwards-compatible manner, and
the PATCH version must be incremented when backwards-compatible bug fixes are made.
Final releases must be tagged with a tag matching the version i.e. MAJOR.MINOR.PATCH with no prefix.
Testing and Continuous Integration
For each Ansible role, a molecule
folder should be configured allowing
the testing to be tested using Molecule. One or more scenarios should be
configured using at least a Docker driver if possible. A generic
molecule
folder can be initialized using the following command:
molecule init scenario -r ansible-role-<NAME> -s default -d docker
Continuous Integration of Ansible roles is performed using Travis CI.
Note
OME Ansible roles are getting progressively upgraded from Molecule 1.x to Molecule 2.x. New roles must be configured using Molecule 2.x.
Distribution and support
All core OME Ansible roles should be deployed to Ansible Galaxy under the openmicroscopy organization. All roles must support RHEL/CentOS 7 as a primary platform. New roles should also include Ubuntu 18.04 as a supported platform whenever possible.
The Galaxy role name should be openmicroscopy.<ROLENAME>. For overriding the
default name derived from the GitHub repository name, the role_name variable
should be set in meta/main.yml
. For role names composed of multiple
words, note that the Galaxy import process will convert hyphens to underscores.
Ansible playbooks can consume these roles using a requirements.yml
file - see
https://github.com/ome/prod-playbooks/blob/master/requirements.yml
and https://github.com/IDR/deployment/blob/master/ansible/requirements.yml
for examples of such files.
The release of an Ansible role and its deployment to Galaxy release happens by triggering a role import in Galaxy using the Travis integration on each release tag.
A PGP-signed tag of form x.y.z should be created for the released version using scc tag-release or git tag -s and pushed to the upstream repository:
$ git tag -s x.y.z -m "<tag message>"
$ git push origin x.y.z