apb-examples

A repository of example ansible-playbook bundles (APBs)

APB Documentation

Documents to get started on writing APBs.

• Introduction
• Getting Started 'Hello-World' APB
• Developer's Guide

Index

• Requirements
  • Directory Structure
    • Minimal
    • With Optional Files
    • Example Files
  • Dockerfile Validation
  • Building the APB
  • Running the APB
• Contributing
• Getting Help

Requirements

Review all of the documents linked above. It details how the APB tooling may help in creating APBs. Be sure to complete all of the requirements below.

APB Name Example

The name my-apb will be used as an example for the rest of this document.

Directory Structure

Required Minimal Structure

The directory structure of my-apb APB, with all it's required files, would look like the following:

my-apb/
├── apb.yml
├── Dockerfile
├── playbooks
│   └── provision.yml
│   └── deprovision.yml
└── roles
    └── my-apb-openshift
        ├── defaults
        │   └── main.yml
        ├── tasks
            └── main.yml

Directory Structure with Optional Files

The directory structure with optional/additional files, may look like this:

my-apb/
├── apb.yml
├── Dockerfile
├── playbooks
│   └── provision.yml
│   └── deprovision.yml
└── roles
    └── my-apb-openshift
        ├── defaults
        │   └── main.yml
        ├── files
        │   └── <my-apb files>    (optional)
        ├── README                (optional)
        ├── tasks
        │   └── main.yml
        └── templates             (optional)
            └── <template files>

Example Files

Dockerfile

FROM ansibleplaybookbundle/apb-base

LABEL "com.redhat.apb.version"="0.1.0"
LABEL "com.redhat.apb.spec"="some-long-blob-value"

ADD playbooks /opt/apb/actions
ADD roles /opt/ansible/roles

USER apb

• Hello World Dockerfile

Spec File (apb.yml)

id: 12345678-abcd-efgh-ijkl-mnopqrstuvwx
name: my-apb
image: my-org/my-apb
description: "my-apb description"
bindable: false
async: optional
parameters: []

• Hello World apb.yml

provision.yml

- name: my-apb provision
  hosts: localhost
  gather_facts: false
  connection: local
  roles:
  - role: ansible.kubernetes-modules
    install_python_requirements: no
  - role: my-apb-openshift
    playbook_debug: false

• Hello World provision.yml

deprovision.yml

TODO

Other Files

For examples of other files, review the hello-world-apb repo

Dockerfile Validation

APB's Dockerfile contain a LABEL that specifies the base64 encoded value of the APB's spec file, namely its apb.yml file, which looks as like this:

LABEL "com.redhat.apb.spec"="<base64-encoded-apb.yml-file-blob-value>"

This value is generated by running the apb prepare command inside the APB source folder. Before submitting a PR, be sure to run the apb prepare command so that the APB's Dockerfile is up-to-date with its apb.yml spec file.

Building the APB

To build my-apb, execute the following command

$ cd my-apb
$ docker build -t my-apb .

Running the APB

To run my-apb, make sure that a test OpenShift/Origin cluster is accessible.

For example, assuming the below environment...

OpenShift URL        : `https://172.17.0.1.nip.io:8443`
OpenShift User       : foo
OpenShift Pwd        : bar
OpenShift Namespace  : my-apb (via `--extra-vars`)
APB Image Entrypoint : /usr/bin/entrypoint.sh
APB Action           : provision

The following command can be executed to provision the my-apb:

$ docker run \
--entrypoint /usr/bin/entrypoint.sh \
-e "OPENSHIFT_TARGET=https://172.17.0.1.nip.io:8443" \
-e "OPENSHIFT_USER=foo" \
-e "OPENSHIFT_PASS=bar"  \
   my-apb \
   provision \
   --extra-vars 'namespace=my-apb'

Contributing to apb-examples

• Complete all the requirements
• Make a pull request
• Fix any conflicts (if any)
• Someone will ACK your PR in the review thread
• Someone will then Merge your PR

Getting Help

• #asbroker - freenode
• Email Us