1. Documentation
×

Introduction

About This Guide

This guide outlines the design concepts and workflow of Ansible Playbook Bundles (APBs), shows how to install and use the apb CLI tooling, and provides a tutorial and reference material on writing your own APBs.

Design Overview

An APB is a lightweight application definition that borrows several concepts from the Nulecule and Atomicapp projects, namely the concept of a short-lived container with the sole purpose of orchestrating the deployment of the intended application. For the case of APBs, this short-lived container is the APB itself: a container with an Ansible runtime environment plus any files required to assist in orchestration, such as playbooks, roles, and extra dependencies.

The OpenShift Ansible broker (OAB) is an implementation of the Open Service Broker (OSB) API that manages applications defined by APBs. The OAB is supported and deployed by default starting in OpenShift Origin 3.7.

Specification of an APB is intended to be lightweight, consisting of several named playbooks and a metadata file to capture information such as parameters to pass into the application.

Workflow

The APB workflow is broken up into the following steps:

  1. Preparation

    1. APB initialization

    2. APB spec file

    3. Actions (provision, deprovision, bind, unbind)

  2. Build

  3. Deploy

Preparation

You must prepare your APB’s directory structure and spec file before you can build and deploy it. The Getting Started topic provides a step by step tutorial on creating your first APB, while the following sections briefly cover this workflow.

APB Initialization

The apb init command creates the required skeleton directory structure and a few required files (for example, the apb.yml spec file) for the APB.

The following shows an example directory structure of an APB:

Directory Structure
example-apb/
├── Dockerfile
├── apb.yml
└── roles/
│   └── example-apb-openshift
│       ├── defaults
│       │   └── main.yml
│       └── tasks
│           └── main.yml
└── playbooks/
    └── provision.yml
    └── deprovision.yml
    └── bind.yml
    └── unbind.yml

APB Spec File

An APB spec file (apb.yml) must be edited for your specific application. For example, the default spec file after running apb init looks as follows:

version: 1.0
name: my-test-apb
description: This is a sample application generated by apb init
bindable: False
async: optional
metadata: (1)
  displayName: my-test
plans:
  - name: default
    description: This default plan deploys my-test-apb
    free: True
    metadata: {}
    parameters: [] (2)
1 The metadata field is optional and used when integrating with the OpenShift Origin service catalog.
2 For APBs that do not have any parameters, the parameters field should be blank.

See the Reference topic for a fully-defined example APB spec file.

Actions

The following are the actions for an APB. At a minimum, an APB must implement the provision and deprovision actions:

provision.yml

Playbook called to handle installing application to the cluster.

deprovision.yml

Playbook called to handle uninstalling.

bind.yml

Playbook to grant access to another service to use this service, such as generating credentials.

unbind.yml

Playbook to revoke access to this service.

test.yml

(Optional) Playbook to test that the APB is vaild.

The required named playbooks correspond to methods defined by the OSB API. For example, when the OAB needs to provision an APB it will execute provision.yml.

After the required named playbooks have been generated, the files can be used directly to test management of the application. A developer may want to work with this directory of files, make tweaks, run, repeat until they are happy with the behavior. They can test the playbooks by invoking Ansible directly with the playbook and any required variables.

Build

The build step is responsible for building a container image from the named playbooks for distribution. Packaging combines a base image containing an Ansible runtime with Ansible artifacts and any dependencies required to run the playbooks.

The result is a container image with an ENTRYPOINT set to take in several arguments, one of which is the method to execute, such as provision and deprovision.

OpenShift ContainerPlatform APB DevelopmentGuide 463015 1117 Build
Figure 1. APB Build

Deploy

Deploying an APB means invoking the container and passing in the name of the playbook to execute along with any required variables. It is possible to invoke the APB directly without going through the OAB. Each APB is packaged so its ENTRYPOINT will invoke Ansible when run. The container is intended to be short-lived, coming up to execute the Ansible playbook for managing the application then exiting.

In a typical APB deploy, the APB container will provision an application by running the provision.yml playbook, which executes an Ansible role. The role is responsible for creating the OpenShift Origin resources, perhaps through calling oc create commands or leveraging Ansible modules. The end result is that the APB runs Ansible to talk to OpenShift Origin to orchestrate the provisioning of the intended application.

The following diagrams illustrate this deployment flow in two phases: a user discovering a list of available APBs and then requesting their chosen APB be provisioned to their project:

OpenShift ContainerPlatform APB DevelopmentGuide 463015 1117 Deploy p1
Figure 2. Listing Available APBs

redcircle 1 An OpenShift Origin user is interested in provisioning a service into their project, so they interact with the service catalog by accessing the OpenShift Origin UI (web console or CLI) to discover any APBs that are already available.

redcircle 2 The service catalog requests a list of APBs from the OAB to show the user.

redcircle 3 The OAB searches all configured container registries (the cluster’s OpenShift Container Registry or any other remote registry) for any APBs (images with a specific label, for example LABEL=apb-1.0).

redcircle 4 The OAB returns the discovered list to the service catalog, to be viewed by the user in the OpenShift Origin UI.

OpenShift ContainerPlatform APB DevelopmentGuide 463015 1117 Deploy p2
Figure 3. Deploying a Chosen APB

redcircle 5 The user now chooses an APB from the discovered list provided by the service catalog.

redcircle 6 The service catalog communicates with the OAB that the user has requested use of the chosen APB.

redcircle 7 The OAB initiates the image pull from the appropriate container registry.

redcircle 8 After the image is pulled, the OAB defers the logic for orchestrating the application to the APB. The service is deployed by running the APB container with a few parameters. To do so, the following command is issued against the OpenShift Origin cluster in a temporary namespace:

$ oc run $IMAGE $METHOD $VARS ansible-playbook ${METHOD}.yaml ${VARS}

To break this command down further:

  1. The oc run command runs the APB image.

  2. In the short-lived container that is created as a result, Ansible is launched using the ansible-playbook command, which runs the appropriate playbook (for example, provision.yaml) to execute the requested action. This creates OpenShift Origin resources in the user’s project.

  3. The container exits at the end of the run, and the temporary namespace is removed.

redcircle 9 As a result, the user views via the OpenShift Origin UI that their requested service has been successfully provisioned in their project.