Chapter 2. CLI Tooling

2.1. 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.

2.2. Installing the Tool

2.2.1. Prerequisites

2.2.1.1. Docker Daemon

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

2.2.1.2. 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):

Warning

This is effectively cluster root and should only be used in a development setting.

Copy to Clipboard Toggle word wrap

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

$ 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:

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

Run the following command:

Copy to Clipboard Toggle word wrap

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

$ 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.

2.2.2. Installing via RPM

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

Copy to Clipboard Toggle word wrap

sudo yum install apb

$ sudo yum install apb

2.2.3. Verifying the Installation

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

Copy to Clipboard Toggle word wrap

apb help

$ 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

2.3. Typical Workflows

2.3.1. 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.

Copy to Clipboard Toggle word wrap

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

$ 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:

Copy to Clipboard Toggle word wrap

apb push --namespace <namespace>

$ apb push --namespace <namespace>

2.3.2. 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:

Copy to Clipboard Toggle word wrap

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 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

2.4. APB Creation Commands

2.4.1. `init`

Description

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

Usage

Copy to Clipboard Toggle word wrap

apb init [OPTIONS] NAME

$ apb init [OPTIONS] NAME

Arguments

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

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--force`	Force re-init and overwrite the directory
`--async {required,optional,unsupported}`	Specify asynchronous operation on application. Usually defaulted to `optional`.
`--bindable`	Generate an application with bindable settings
`--skip-provision`	Do not generate provision playbook and role
`--skip-deprovision`	Do not generate deprovision playbook and role
`--skip-bind`	Do not generate bind playbook and role
`--skip-unbind`	Do not generate unbind playbook and role
`--skip-roles`	Do not generate any roles

Note

Async bind and unbind is an experimental feature and is not supported or enabled by default.

Examples

Create directory my-new-apb:

Copy to Clipboard Toggle word wrap

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

$ 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:

Copy to Clipboard Toggle word wrap

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

$ 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:

Copy to Clipboard Toggle word wrap

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

$ 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

2.4.2. `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

Copy to Clipboard Toggle word wrap

apb prepare [OPTIONS]

$ apb prepare [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--dockerfile DOCKERFILE, -f DOCKERFILE`	Writes the APB spec to the target file name instead of a file named *Dockerfile*

Examples

Writes the label for the spec field in the Dockerfile:

Copy to Clipboard Toggle word wrap

apb prepare

$ apb prepare

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

Copy to Clipboard Toggle word wrap

apb prepare --dockerfile Dockerfile-custom

$ apb prepare --dockerfile Dockerfile-custom

2.4.3. `build`

Description

Builds the image for the APB.

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

Usage

Copy to Clipboard Toggle word wrap

apb build [OPTIONS]

$ apb build [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--tag TAG`	Sets the tag of the built image to a string in the format `<registry>/<org>/<name>`
`--registry`	Registry portion of the tag of the image (e.g., `docker.io`)
`--org, -o`	User or organization portion of the tag of the image

Examples

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

Copy to Clipboard Toggle word wrap

apb build

$ apb build

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

Copy to Clipboard Toggle word wrap

apb build --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>:

Copy to Clipboard Toggle word wrap

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

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

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

Copy to Clipboard Toggle word wrap

apb build --dockerfile Dockerfile-custom

$ apb build --dockerfile Dockerfile-custom

2.4.4. `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 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

Copy to Clipboard Toggle word wrap

apb push [OPTIONS]

$ apb push [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--broker BROKER_URL`	Route to the OAB
`--namespace NAMESPACE`	Namespace to push to the OpenShift Container Registry
`--openshift, -o`	Use the OpenShift Container Registry
`--dockerfile DOCKERFILE, -f DOCKERFILE`	*Dockerfile* to build internal registry image. Usually defaults to `Dockerfile` but can be set to any file name.
`--secure`	Use secure connection to OAB
`--username USERNAME`	Basic authentication user name to be used in broker communication
`--password PASSWORD`	Basic authentication password to be used in broker communication
`--no-relist`	Do not relist the catalog after pushing an APB to the broker
`--broker-name`	Name of the ServiceBroker Kubernetes resource

Examples

Push to the OAB development endpoint:

Copy to Clipboard Toggle word wrap

apb push

$ apb push

Push to the local OpenShift Container Registry:

Copy to Clipboard Toggle word wrap

apb push

$ apb push

Push to the local OpenShift Container Registry under namespace myproject:

Copy to Clipboard Toggle word wrap

apb push --namespace myproject

$ apb push --namespace myproject

2.4.5. `test`

Description

Runs the APB unit tests.

Usage

Copy to Clipboard Toggle word wrap

apb test [OPTIONS]

$ apb test [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--tag TAG`	Sets the tag of the built image to a string in the format `<registry>/<org>/<name>`

Examples

Run the tests:

Copy to Clipboard Toggle word wrap

apb test

$ apb test

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

Copy to Clipboard Toggle word wrap

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

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

2.5. Broker Utility Commands

2.5.1. `list`

Description

Lists all the APBs the broker has loaded.

Usage

Copy to Clipboard Toggle word wrap

apb list [OPTIONS]

$ apb list [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--broker BROKER_URL`	Route to the OAB
`--secure`	Use secure connection to OAB
`--verbose, -v`	Output verbose spec information from OAB
`--output {yaml,json}, -o {yaml,json}`	Specify verbose output format in yaml (default) or json
`--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME`	Specify the basic authentication user name to be used
`--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD`	Specify the basic authentication password to be used

Examples

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

Copy to Clipboard Toggle word wrap

apb list

$ apb list

List verbose, easily readable specs:

Copy to Clipboard Toggle word wrap

apb list -v

$ apb list -v

List all the JSON output:

Copy to Clipboard Toggle word wrap

apb list -v -o json

$ apb list -v -o json

2.5.2. `bootstrap`

Description

Requests the OAB to reload all APBs from the registries.

Usage

Copy to Clipboard Toggle word wrap

apb bootstrap [OPTIONS]

$ apb bootstrap [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--broker BROKER_URL`	Route to the OAB
`--secure`	Use secure connection to OAB
`--no-relist`	Do not relist the catalog after bootstrapping the broker
`--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME`	Specify the basic authentication user name to be used
`--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD`	Specify the basic authentication password to be used
`--broker-name BROKER_NAME`	Name of the ServiceBroker Kubernetes resource

Examples

Basic reload of APBs:

Copy to Clipboard Toggle word wrap

apb bootstrap

$ apb bootstrap

2.5.3. `remove`

Description

Removes one (or all) APBs from the OAB.

Usage

Copy to Clipboard Toggle word wrap

apb remove [OPTIONS]

$ apb remove [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--broker BROKER_URL`	Route to the OAB
`--secure`	Use secure connection to OAB
`--all`	Remove all stored APBs
`--id ID`	ID of APB to remove
`--secure`	Use secure connection to OAB
`--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME`	Specify the basic authentication user name to be used
`--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD`	Specify the basic authentication password to be used
`--no-relist`	Do not relist the catalog after deletion

Examples

Remove an APB using an ID:

Copy to Clipboard Toggle word wrap

apb remove --id ca91b61da8476984f18fc13883ae2fdb

$ apb remove --id ca91b61da8476984f18fc13883ae2fdb

Note

If you need an ID of an APB, use:

Copy to Clipboard Toggle word wrap

apb list

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

Remove all APBs:

Copy to Clipboard Toggle word wrap

apb remove --all

$ apb remove --all

2.5.4. `relist`

Description

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

Usage

Copy to Clipboard Toggle word wrap

apb relist [OPTIONS]

$ apb relist [OPTIONS]

Options

Option, Shorthand	Description
`--help, -h`	Show help message
`--broker-name BROKER_NAME`	Name of the ServiceBroker Kubernetes resource
`--secure`	Use secure connection to OAB
`--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME`	Specify the basic authentication user name to be used
`--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD`	Specify the basic authentication password to be used

Examples

Copy to Clipboard Toggle word wrap

apb relist

$ apb relist

2.6. Other Commands

2.6.1. `help`

Description

Displays a help message.

Usage

Copy to Clipboard Toggle word wrap

apb help

$ apb help

Examples

Copy to Clipboard Toggle word wrap

apb help

$ apb help

Copy to Clipboard Toggle word wrap

apb -h

$ apb -h

2.1. Overview

2.2. Installing the Tool

2.2.1. Prerequisites

2.2.1.1. Docker Daemon

2.2.1.2. Access Permissions

2.2.2. Installing via RPM

2.2.3. Verifying the Installation

2.3. Typical Workflows

2.3.1. Local Registry

2.3.2. Remote Registry

2.4. APB Creation Commands

2.4.1. init

Description

Usage

Arguments

Options

Examples

2.4.2. prepare

Description

Usage

Options

Examples

2.4.3. build

Description

Usage

Options

Examples

2.4.4. push

Description

Usage

Options

Examples

2.4.5. test

Description

Usage

Options

Examples

2.5. Broker Utility Commands

2.5.1. list

Description

Usage

Options

Examples

2.5.2. bootstrap

Description

Usage

Options

Examples

2.5.3. remove

Description

Usage

Options

Examples

2.5.4. relist

Description

Usage

Options

Examples

2.6. Other Commands

2.6.1. help

Description

Usage

Examples

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

2.4.1. `init`

2.4.2. `prepare`

2.4.3. `build`

2.4.4. `push`

2.4.5. `test`

2.5.1. `list`

2.5.2. `bootstrap`

2.5.3. `remove`

2.5.4. `relist`

2.6.1. `help`