OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

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

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

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

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:

$ sudo yum install apb

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

Async bind and unbind is an experimental feature and is not supported or enabled by default.
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
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:

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

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

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

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

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

$ apb bootstrap

remove

Description

Removes one (or all) APBs from the OAB.

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

$ apb remove --id ca91b61da8476984f18fc13883ae2fdb

If you need an ID of an APB, use:

$ 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
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
$ apb relist

Other Commands

help

Description

Displays a help message.

Usage
$ apb help
Examples
$ apb help
$ apb -h