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