Playbook To Image

A Source-to-Image (S2I) builder image for packaging Ansible playbooks as a self-executing container.

Usage

Prerequisites: an OpenShiftv3 cluster or s2i binary

In this workflow we build a new image with our playbook, setup secrets (private ssh key, for example) and create a job to run our playbook image.

1. Build: Add your playbook to the image. This will create a new image with your playbook sourcecode

• Using OpenShift. In this example we instruct the build script to install the OpenShift CLI so it's available from our playbook:

    oc new-build -e INSTALL_OC=true \
       docker.io/aweiteka/playbook2image~https://github.com/PLAYBOOK/REPO.git
  

• Using docker:

  1. Using the example Dockerfile, create a Dockerfile in the playbook repository.

  2. Build the image

      docker build -t IMAGE_NAME . -f Dockerfile.example
     

• Using s2i CLI tool:

    sudo s2i build https://github.com/PLAYBOOK/REPO.git docker.io/aweiteka/playbook2image NEW_PLAYBOOK_IMAGE_NAME
  

1. Run: as an OpenShift Job or with docker via command line

• Using OpenShift:

  1. Create a secret for our ssh private key

      oc secrets new-sshauth sshkey --ssh-privatekey=$HOME/.ssh/id_rsa
     

  2. Create a new job. Download the sample-job.yaml file, edit and create the job.

      oc create -f sample-job.yaml
     

• Using Docker (example command):

    sudo docker run \
         -v ~/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa \
         -e OPTS="--become --user cloud-user" \
         -e PLAYBOOK_FILE=PATH_TO_PLAYBOOK \
         -e INVENTORY_URL=URL \
         IMAGE_FROM_BUILD_STEP
  

Runtime Environment Variable Options

A container run from a playbook2image image needs at least these configured options:

1. An inventory. You must specify it using one of these three options: INVENTORY_FILE to point to a local path inside the container, INVENTORY_URL to download a static inventory file, or DYNAMIC_SCRIPT_URL to download a dynamic inventory script.
2. A playbook to run, set via PLAYBOOK_FILE.
3. ssh keys mounted into the container (by default these should be in /opt/app-root/src/.ssh).

Below is a list of available options. Ansible itself also allows its configuration to be controlled via environment variables and some of these are specially relevant for playbook2image's use case so they are also highligted here (starting with ANSIBLE_*):

INVENTORY_FILE

Path to the location of the inventory file within the container. It can be a relative path pointing to an inventory provided in the source, or an absolute path to an inventory mounted in the container via a volume.

INVENTORY_URL

URL to inventory file. This is downloaded into the container.

DYNAMIC_SCRIPT_URL

URL to dynamic inventory script. This is downloaded into the container. If the dynamic inventory script is python see PYTHON_REQUIREMENTS.

PLAYBOOK_FILE

Relative path to playbook file relative to project source. This is mounted in the container at /opt/app-root/src/PLAYBOOK_FILE.

ALLOW_ANSIBLE_CONNECTION_LOCAL (optional)

If set to false all ansible_connection=local settings in the inventory will be removed. This can help when you want to use an existing inventory file that uses local connections to a host: it is likely that an ssh connection is a better fit when running from a container.

PYTHON_REQUIREMENTS (optional, default 'requirements.txt')

Relative path to python dependency requirements.txt file to support dynamic inventory script.

ANSIBLE_PRIVATE_KEY_FILE (optional, e.g. '/opt/app-root/src/.ssh/id_rsa/ssh-privatekey')

Container path to mounted private SSH key. For OpenShift this must match the secret volumeMount (see mountPath in sample-job.yaml). For docker this must match the bindmount container path, e.g. -v ~/.ssh/id_rsa:/opt/app-root/src/.ssh/id_rsa.

OPTS (optional)

List of options appended to ansible-playbook command. An example of commonly used options:

OPTS="-vvv --become --user cloud-user"

VAULT_PASS (optional)

ansible-vault passphrase for decrypting files. This is written to a file and used to decrypt ansible-vault files.

ANSIBLE_HOST_KEY_CHECKING=False

Disable host key checking. See documentation

WORK_DIR (optional)

If not specified ansible-playbook will run from ${APP_HOME} directory (/opt/app-root/src) where the target repository is mounted. When relative or absolute path is specified in WORK_DIR, ansible-playbook will be launched from WORK_DIR directory. That might come in handy for example if you have roles or ansible.cfg in non-root of the repository.

Build time Environment Variable Options

These options are passed in when building the application (e.g. oc new-build or docker build or s2i)

INSTALL_OC (optional)

If specified during build (e.g. oc new-build -e INSTALL_OC=true ...) the oc OpenShift client binary is downloaded and installed into the resulting image.

Contribute

S2I project documentation

• OpenShift docs

• Creating S2I images blog post

To run tests you will need to install the s2i binary.

Running tests

sudo make test