example-apb/
├── Dockerfile
├── apb.yml
└── roles/
│ └── example-apb-openshift
│ ├── defaults
│ │ └── main.yml
│ └── tasks
│ └── main.yml
└── playbooks/
└── provision.yml
└── deprovision.yml
└── bind.yml
└── unbind.yml
×
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.
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:
-
Preparation
-
APB initialization
-
APB spec file
-
Actions (provision, deprovision, bind, unbind)
-
-
Build
-
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
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
OKD 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.
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 OKD resources, perhaps through
calling oc create commands or leveraging Ansible modules. The end result is
that the APB runs Ansible to talk to OKD 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:
Figure 2. Listing Available APBs
An OKD user is interested in provisioning a
service into their project, so they interact with the service catalog by
accessing the OKD UI (web console or CLI) to discover any APBs that
are already available.
The service catalog requests a list of APBs from the OAB
to show the user.
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).
The OAB returns the discovered list to the service
catalog, to be viewed by the user in the OKD UI.
Figure 3. Deploying a Chosen APB
The user now chooses an APB from the discovered list
provided by the service catalog.
The service catalog communicates with the OAB that the
user has requested use of the chosen APB.
The OAB initiates the image pull from the appropriate
container image registry.
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 OKD cluster in a temporary namespace:
$ oc run $IMAGE $METHOD $VARS ansible-playbook ${METHOD}.yaml ${VARS}
To break this command down further:
-
The
oc runcommand runs the APB image. -
In the short-lived container that is created as a result, Ansible is launched using the
ansible-playbookcommand, which runs the appropriate playbook (for example, provision.yaml) to execute the requested action. This creates OKD resources in the user’s project. -
The container exits at the end of the run, and the temporary namespace is removed.
As a result, the user views via the OKD UI
that their requested service has been successfully provisioned in their project.