apb-examples

A repository of example ansible-playbook bundles (APBs)

APB Documentation

Documents to get started on writing APBs.

Index

Requirements
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
RUN chmod -R g=u /opt/{ansible,apb}

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 Token      : WoCG534Mh9O2AyT_mFn3uKQ6R9-fuk_Rsr-oF4K8Pqw
OpenShift Namespace  : my-apb (via `--extra-vars`)
APB Image Entrypoint : /usr/bin/entrypoint.sh
APB Action           : provision

To get your OpenShift Token, type oc whoami -t

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_TOKEN=WoCG534Mh9O2AyT_mFn3uKQ6R9-fuk_Rsr-oF4K8Pqw" \
   my-apb \
   provision \
   --extra-vars 'namespace=my-apb'

Contributing a new APB to apb-examples

Create a new directory for the app and add playbooks
Make a pull request
Someone will ACK your PR in the review thread
Someone will then Merge your PR
After merging, create an automated build for the APB in dockerhub
Under Build Settings, create a build tagged 'latest' and 'canary'
Link the APB build to the apb-base container by adding 'ansibleplaybookbundle/apb-base' as a Repository Link

Getting Help

#asbroker - freenode
Email Us

oatakan/apb-examples