CLI Tooling

Overview

The apb CLI tool helps Ansible Playbook Bundle (APB) authors create, build, and publish their APBs to container registries. It enforces best practices and takes care of the details so they should be easy to deploy.

Installing the Tool

Prerequisites

Docker Daemon

The docker daemon must be correctly installed and running on the system.

Access Permissions

The apb tool requires you to be logged in as a tokened cluster user; the default system:admin system user is not sufficient because it does not have a token that can be used for the tool’s authentication. In addition, there are a number of local roles (project-scoped) and cluster roles (cluster-wide) that must exist to permit the full breadth of the apb tool’s functions (see Cluster and Local RBAC).

The easiest option is to ensure the user has the cluster-admin cluster role. To add this role to another user, you can run the following as a user that already has such permissions (for example, the system:admin default system user):

$ oc adm policy add-cluster-role-to-user cluster-admin <user>
$ oc login -u <user> <openshift_server>

If you would like a more strictly permissioned environment, an OpenShift template is provided that by default will permission a user called developer. The template must be run by a user with sufficient permissions to create the various roles. The developer user does not have such permissions, but the system:admin user is sufficient.

To run the template:

1. Download the openshift-permissions.template.yaml file locally.

2. Run the following command:

   $ oc process -f openshift-permissions.template.yaml \
     -p BROKER_NAMESPACE=openshift-ansible-service-broker \
     -p GLOBAL_IMAGE_PROJECT=default \
     [-p USER=<your_desired_user>] \ (1)
     | oc create -f -

   1	By default, the template will permission the developer user. You can optionally use the -p flag to override this default value with your desired user.

Running From a Container

To run the apb tool from a container:

1. Pull the container:

   $ docker pull docker.io/ansibleplaybookbundle/apb-tools[:<tag>]

   There are three tags to choose from:

   • latest: more stable, less frequent releases.

   • nightly: following upstream commits, installed from RPM.

   • canary: following upstream commits, installed from source build.

1. Choose one of the following:

   1. Create an alias in your .bashrc or somewhere else for your shell:

      alias apb='docker run --rm --privileged -v $PWD:/mnt -v $HOME/.kube:/.kube -v /var/run/docker.sock:/var/run/docker.sock -u $UID docker.io/ansibleplaybookbundle/apb-tools'

   2. If you would prefer to use atomic rather than an alias:

      $ atomic run docker.io/ansibleplaybookbundle/apb-tools init my_apb

1. Start working by running the command:

   $ apb init my_apb

   The first run may take awhile if you did not pull the image beforehand.

Installing via RPM

For RHEL or CentOS 7:

$ su -c 'wget https://copr.fedorainfracloud.org/coprs/g/ansible-service-broker/ansible-service-broker-latest/repo/epel-7/group_ansible-service-broker-ansible-service-broker-latest-epel-7.repo -O /etc/yum.repos.d/ansible-service-broker.repo'
$ sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum -y install apb

For Fedora 26 or Fedora 27:

$ sudo dnf -y install dnf-plugins-core
$ sudo dnf -y copr enable @ansible-service-broker/ansible-service-broker-latest
$ sudo dnf -y install apb

Installing from Source

Installing from Source: Python/VirtualEnv

1. Clone the following repository:

   $ git clone https://github.com/fusor/ansible-playbook-bundle.git

2. Install python-virtualenv, create a virtualenv, and activate it:

   $ sudo dnf install -y python-virtualenv
   $ virtualenv /tmp/apb
   $ source /tmp/apb/bin/activate

3. Install requirements and run the setup script (requires python):

   $ cd ansible-playbook-bundle && pip install -U setuptools && pip install -r src/requirements.txt && python setup.py install

4. Optionally, if actively developing on the project, install the testing requirements:

   $ pip install -r src/test-requirements.txt

5. If needed, reactivate the apb virtualenv in other shell sessions using:

   $ source /tmp/apb/bin/activate

Installing from Source: Tito

Alternatively, you can use tito to install:

# tito build --test --rpm -i

Verifying the Installation

Run apb help to make sure the tool is installed correctly:

$ apb help
usage: apb [-h] [--debug] [--project BASE_PATH]
           {init,help,prepare,push,bootstrap,list,remove,build} ...
APB tooling for assisting in building and packaging APBs.
optional arguments:
  -h, --help            show this help message and exit
  --debug               Enable debug output
  --project BASE_PATH, -p BASE_PATH
                        Specify a path to your project. Defaults to CWD.
subcommand:
  {init,help,prepare,push,bootstrap,list,remove,build}
    init                Initialize the directory for APB development
    help                Display this help message
    prepare             Prepare an ansible-container project for APB packaging
    push                Push local APB spec to an OAB
    bootstrap           Tell OAB to reload APBs from the
                        container repository
    list                List APBs from the target OAB
    remove              Remove APBs from the target OAB
    build               Build and package APB container

Typical Workflows

Local Registry

In order to use the OpenShift Container Registry to source APBs, you must have configured the OpenShift Ansible broker to use the local_openshift type registry adapter. See the config section for more information.

$ apb init my-new-apb
$ cd my-new-apb
$ apb build
$ apb push
$ apb list

If you are using a namespace other than the default openshift namespace to host your APBs, then you can use the following command:

$ apb push --namespace <namespace>

Remote Registry

OAB can also be configured to use a remote registry and organization such as docker.io/ansibleplaybookbundle or your own personal account. In order to use this for developing APBs, you can build and push to your remote registry and then bootstrap to reload your APBs:

$ apb init my-new-apb
$ cd my-new-apb
$ apb build --tag docker.io/my-org/my-new-apb
$ docker push docker.io/my-org/my-new-apb
$ apb bootstrap
$ apb list

APB Creation Commands

init

Description

Initializes a directory structure for a new APB. Also creates example files for the new APB with sensible defaults.

Usage

$ apb init [OPTIONS] NAME

Arguments

NAME: Name of the APB and directory to be created.

Options

Examples

Create directory my-new-apb:

$ apb init my-new-apb
# my-new-apb/
# ├── apb.yml
# ├── Dockerfile
# ├── playbooks
# │   ├── deprovision.yml
# │   └── provision.yml
# └── roles
#     ├── deprovision-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     └── provision-my-new-apb
#         └── tasks
#             └── main.yml

Create directory my-new-apb, but skip generating deprovision playbook and roles:

$ apb init my-new-apb --skip-deprovision
# my-new-apb/
# ├── apb.yml
# ├── Dockerfile
# ├── playbooks
# │   └── provision.yml
# └── roles
#     └── provision-my-new-apb
#         └── tasks
#             └── main.yml

Create directory my-new-apb, overwriting any old versions. The APB will be configured to be bindable and set async to optional:

$ apb init my-new-apb --force --bindable --async optional
# my-new-apb/
# ├── apb.yml
# ├── Dockerfile
# ├── playbooks
# │   ├── bind.yml
# │   ├── deprovision.yml
# │   ├── provision.yml
# │   └── unbind.yml
# └── roles
#     ├── bind-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     ├── deprovision-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     ├── provision-my-new-apb
#     │   └── tasks
#     │       └── main.yml
#     └── unbind-my-new-apb
#         └── tasks
#             └── main.yml

prepare

Description

Compiles the APB into base64 encoding and writes it as a label to the Dockerfile.

This will allow the OAB to read the APB metadata from the registry without downloading the images. This command must be run from inside the APB directory. Running the build command will automatically run prepare as well, meaning you generally do not need to run prepare by itself.

Usage

$ apb prepare [OPTIONS]

Options

Examples

Writes the label for the spec field in the Dockerfile:

$ apb prepare

Writes the label for the spec field in Dockerfile-custom:

$ apb prepare --dockerfile Dockerfile-custom

build

Description

Builds the image for the APB.

Similar to running apb prepare and docker build with a tag.

Usage

$ apb build [OPTIONS]

Options

Examples

Build the image and use the name field from apb.yml as the tag:

$ apb build

Build the image and use the tag docker.io/my-org/my-new-apb:

$ apb build --tag docker.io/my-org/my-new-apb

Build the image and use the tag docker.io/my-org/<my-apb-name>:

$ apb build --registry docker.io --org my-org

Build the image using the file Dockerfile-custom as the Dockerfile definition:

$ apb build --dockerfile Dockerfile-custom

push

Description

Uploads the APB to an OpenShift Container Registry or a broker mock registry where it will be read by the OAB.

When using the broker’s mock registry, the spec is uploaded and will be displayed in OKD, but OKD will pull the image from the registry normally. Usually that means the registry where oc cluster up was performed.

When using the OpenShift Container Registry, the image is uploaded to OKD directly.

Usage

$ apb push [OPTIONS]

Options

Examples

Push to the OAB development endpoint:

$ apb push

Push to the local OpenShift Container Registry:

$ apb push

Push to the local OpenShift Container Registry under namespace myproject:

$ apb push --namespace myproject

test

Description

Runs the APB unit tests.

Usage

$ apb test [OPTIONS]

Options

Examples

Run the tests:

$ apb test

Run the tests but use a specific tag on the built image:

$ apb test --tag docker.io/my-org/my-new-apb

Broker Utility Commands

list

Description

Lists all the APBs the broker has loaded.

Usage

$ apb list [OPTIONS]

Options

Examples

Basic list of APBs including name, ID, and description:

$ apb list

List verbose, easily readable specs:

$ apb list -v

List all the JSON output:

$ apb list -v -o json

bootstrap

Description

Requests the OAB to reload all APBs from the registries.

Usage

$ apb bootstrap [OPTIONS]

Options

Examples

Basic reload of APBs:

$ apb bootstrap

remove

Description

Removes one (or all) APBs from the OAB.

Usage

$ apb remove [OPTIONS]

Options

Examples

Remove an APB using an ID:

$ apb remove --id ca91b61da8476984f18fc13883ae2fdb

$ apb list
ID                                NAME                     DESCRIPTION
ca91b61da8476984f18fc13883ae2fdb  dh-etherpad-apb          Note taking web application

Remove all APBs:

$ apb remove --all

relist

Description

Forces service catalog to relist the provided services to match the broker.

Usage

$ apb relist [OPTIONS]

Options

Examples

$ apb relist

Other Commands

help

Description

Displays a help message.

Usage

$ apb help

Examples

$ apb help

$ apb -h