Chapter 2. CLI Tooling

The APB CLI tool is provided by the apb package, which is available from the rhel-7-server-ose-3.7-rpms channel:

$ sudo yum install apb

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

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 --openshift
$ 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 -o --namespace <namespace>

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

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 require async:

$ apb init my-new-apb --force --bindable --async required
# 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

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

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

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 OpenShift Container Platform, but OpenShift Container Platform 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 OpenShift Container Platform directly.

Usage

$ apb push [OPTIONS]

Options

Examples

Push to the OAB development endpoint:

$ apb push

Push to the local OpenShift Container Registry:

$ apb push -o

Push to the local OpenShift Container Registry under namespace myproject:

$ apb push -o --namespace myproject

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

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

Description

Requests the OAB to reload all APBs from the registries.

Usage

$ apb bootstrap [OPTIONS]

Options

Examples

Basic reload of APBs:

$ apb bootstrap

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

Description

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

Usage

$ apb relist [OPTIONS]

Options

Examples

$ apb relist

Description

Displays a help message.

Usage

$ apb help

Examples

$ apb help

$ apb -h