Ansible Guide

This guide documents the process to setup and manage a new Ansible role.

Ansible Roles

Ansible roles are a collection of Ansible vars_files, tasks, and handlers packaged into a single package for easy distribution and reuse.

Refer to the upstream Ansible Roles documentation for details.

Ansible Galaxy

Ansible galaxy is an online hub for finding, reusing and sharing Ansible Content. We use it to share and pull down Ansible roles.

Molecule

Molecule is a test framework for testing Ansible roles. We use it to ensure the role supports all supported distros.

Requirements

In a virtualenv install.

pip install ansible docker-py molecule

Set up an Ansible Role

  1. Create a repo to store the role

  2. Init role using Ansible galaxy:

    # Replace ROLE_NAME with the name of your role
    ansible-galaxy init ROLE_NAME --force
    
    .. note::
    
       The ``ansible-galaxy`` command creates a directory named ROLE_NAME so
       call it from outside the repo directory and pass it the name of the
       repository.
    
  3. Change directory into the ROLE_NAME directory

  4. Create a .gitignore:

    .molecule/
    .tox/
    __pycache__/
    *.pyc
    
  5. Add molecule test:

    molecule init scenario -r ROLE_NAME
    
  6. Add molecule test to tox.ini:

    [tox]
    minversion = 1.6
    envlist =
        molecule
    skipsdist=true
    
    [testenv:coala]
    basepython = python2
    deps =
        ansible
        docker-py
        molecule
    passenv = *
    commands =
        ./molecule.sh
    
  7. Add molecule.sh script

    Replace ROLE_NAME with the name of your role.

    #!/bin/bash
    # SPDX-License-Identifier: EPL-1.0
    ##############################################################################
    # Copyright (c) 2018 The Linux Foundation and others.
    #
    # All rights reserved. This program and the accompanying materials
    # are made available under the terms of the Eclipse Public License v1.0
    # which accompanies this distribution, and is available at
    # http://www.eclipse.org/legal/epl-v10.html
    ##############################################################################
    
    # If running in Jenkins we need to symlink the workspace so that
    # ansible can pick up the role.
    if [ ! -z "$JENKINS_URL" ]; then
        ln -sf "$WORKSPACE" ../ROLE_NAME
    fi
    
    molecule test --destroy=always
    
  8. Make molecule.sh script executable:

    chmod +x molecule.sh
    
  9. Run molecule test:

    tox -e molecule
    

    Note

    Resolve any molecule test errors before moving on.

  10. Edit meta information in meta/main.yml

  11. Edit README.md with relevant information about the new role

  12. Git commit the repo:

    git add .
    git commit -sm "Add role ROLE_NAME"