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¶
Create a repo to store the role
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.
Change directory into the ROLE_NAME directory
Create a .gitignore:
.molecule/ .tox/ __pycache__/ *.pyc
Add molecule test:
molecule init scenario -r ROLE_NAME
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
Add
molecule.sh
scriptReplace 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
Make
molecule.sh
script executable:chmod +x molecule.sh
Run molecule test:
tox -e molecule
Note
Resolve any molecule test errors before moving on.
Edit meta information in
meta/main.yml
Edit
README.md
with relevant information about the new roleGit commit the repo:
git add . git commit -sm "Add role ROLE_NAME"