From cc91ec2bc5fb459c014e50965a5f00d55af74095 Mon Sep 17 00:00:00 2001 From: Thanh Ha Date: Wed, 7 Feb 2018 21:16:28 -0500 Subject: [PATCH] Add Ansible Role creation documentation Change-Id: I4746492508dada3852ae50bcc7d4507c20ef1cb2 Signed-off-by: Thanh Ha --- docs/_static/molecule.sh | 18 ++++++++ docs/ansible.rst | 110 +++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 129 insertions(+) create mode 100644 docs/_static/molecule.sh create mode 100644 docs/ansible.rst diff --git a/docs/_static/molecule.sh b/docs/_static/molecule.sh new file mode 100644 index 0000000..4fc2c7a --- /dev/null +++ b/docs/_static/molecule.sh @@ -0,0 +1,18 @@ +#!/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 diff --git a/docs/ansible.rst b/docs/ansible.rst new file mode 100644 index 0000000..540974a --- /dev/null +++ b/docs/ansible.rst @@ -0,0 +1,110 @@ +.. _lfreleng-docs-ansible: + +############# +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 `ansible-role`_ for documentation on Ansible roles. + +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. + +.. code-block:: bash + + 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 of the repo directory and pass it the name of the + repo. + +#. 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`` script + + Replace ROLE_NAME with the name of your role. + + .. literalinclude:: _static/molecule.sh + :language: bash + :emphasize-lines: 15 + +#. 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 role +#. Git commit the repo:: + + git add . + git commit -sm "Add role ROLE_NAME" + +.. _ansible-role: https://docs.ansible.com/ansible/latest/playbooks_reuse_roles.html diff --git a/docs/index.rst b/docs/index.rst index b3a462d..47d9248 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Guides: :maxdepth: 2 best-practices + ansible gerrit gpg jenkins -- 2.16.6