Add Ansible Role creation documentation

Change-Id: I4746492508dada3852ae50bcc7d4507c20ef1cb2
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

diff --git a/docs/_static/molecule.sh b/docs/_static/molecule.sh
new file mode 100644 (file)
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 (file)
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 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,7 @@ Guides:
    :maxdepth: 2
 
    best-practices
+   ansible
    gerrit
    gpg
    jenkins