Chapter 2. CLI Tooling

2.1. Overview
Copy link

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

2.2.1. Prerequisites
Copy link

2.2.1.1. Docker Daemon
Copy link

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

2.2.1.2. Access Permissions
Copy link

You must be logged in via oc as a user with cluster-admin permissions:

oc login -u <user> <openshift_server>

$ oc login -u <user> <openshift_server>

Copy to Clipboard

Toggle word wrap

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

Copy to Clipboard

Toggle word wrap

This permission requirement is so that the development lifecycle of the apb tool can function.

2.2.2. Installing via RPM
Copy link

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

$ sudo yum install apb

Copy to Clipboard

Toggle word wrap

2.2.3. Verifying the Installation
Copy link

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

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

Copy to Clipboard

Toggle word wrap

2.3. Typical Workflows
Copy link

2.3.1. Local Registry
Copy link

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

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

Copy to Clipboard

Toggle word wrap

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>

$ apb push -o --namespace <namespace>

Copy to Clipboard

Toggle word wrap

2.3.2. Remote Registry
Copy link

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

Copy to Clipboard

Toggle word wrap

2.4. APB Creation Commands
Copy link

2.4.1. init
Copy link

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

$ apb init [OPTIONS] NAME

Copy to Clipboard

Toggle word wrap

Arguments

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

Options

Expand

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

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

$ 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

Copy to Clipboard

Toggle word wrap

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

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

Copy to Clipboard

Toggle word wrap

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

$ 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

Copy to Clipboard

Toggle word wrap

2.4.2. prepare
Copy link

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]

$ apb prepare [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb prepare

Copy to Clipboard

Toggle word wrap

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

apb prepare --dockerfile Dockerfile-custom

$ apb prepare --dockerfile Dockerfile-custom

Copy to Clipboard

Toggle word wrap

2.4.3. build
Copy link

Description

Builds the image for the APB.

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

Usage

apb build [OPTIONS]

$ apb build [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb build

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

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

apb build --dockerfile Dockerfile-custom

$ apb build --dockerfile Dockerfile-custom

Copy to Clipboard

Toggle word wrap

2.4.4. push
Copy link

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]

$ apb push [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb push

Copy to Clipboard

Toggle word wrap

Push to the local OpenShift Container Registry:

apb push -o

$ apb push -o

Copy to Clipboard

Toggle word wrap

Push to the local OpenShift Container Registry under namespace myproject:

apb push -o --namespace myproject

$ apb push -o --namespace myproject

Copy to Clipboard

Toggle word wrap

2.4.5. test
Copy link

Description

Runs the APB unit tests.

Usage

apb test [OPTIONS]

$ apb test [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb test

Copy to Clipboard

Toggle word wrap

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

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

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

Copy to Clipboard

Toggle word wrap

2.5. Broker Utility Commands
Copy link

2.5.1. list
Copy link

Description

Lists all the APBs the broker has loaded.

Usage

apb list [OPTIONS]

$ apb list [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb list

Copy to Clipboard

Toggle word wrap

List verbose, easily readable specs:

apb list -v

$ apb list -v

Copy to Clipboard

Toggle word wrap

List all the JSON output:

apb list -v -o json

$ apb list -v -o json

Copy to Clipboard

Toggle word wrap

2.5.2. bootstrap
Copy link

Description

Requests the OAB to reload all APBs from the registries.

Usage

apb bootstrap [OPTIONS]

$ apb bootstrap [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb bootstrap

Copy to Clipboard

Toggle word wrap

2.5.3. remove
Copy link

Description

Removes one (or all) APBs from the OAB.

Usage

apb remove [OPTIONS]

$ apb remove [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb remove --id ca91b61da8476984f18fc13883ae2fdb

Copy to Clipboard

Toggle word wrap

Note

If you need an ID of an APB, use:

apb list

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

Copy to Clipboard

Toggle word wrap

Remove all APBs:

apb remove --all

$ apb remove --all

Copy to Clipboard

Toggle word wrap

2.5.4. relist
Copy link

Description

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

Usage

apb relist [OPTIONS]

$ apb relist [OPTIONS]

Copy to Clipboard

Toggle word wrap

Options

Expand

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

$ apb relist

Copy to Clipboard

Toggle word wrap

2.6. Other Commands
Copy link

2.6.1. help
Copy link

Description

Displays a help message.

Usage

apb help

$ apb help

Copy to Clipboard

Toggle word wrap

Examples

apb help

$ apb help

Copy to Clipboard

Toggle word wrap

apb -h

$ apb -h

Copy to Clipboard

Toggle word wrap

2.1. OverviewCopy linkLink copied to clipboard!

2.2. Installing the ToolCopy linkLink copied to clipboard!

2.2.1. PrerequisitesCopy linkLink copied to clipboard!

2.2.1.1. Docker DaemonCopy linkLink copied to clipboard!

2.2.1.2. Access PermissionsCopy linkLink copied to clipboard!

2.2.2. Installing via RPMCopy linkLink copied to clipboard!

2.2.3. Verifying the InstallationCopy linkLink copied to clipboard!

2.3. Typical WorkflowsCopy linkLink copied to clipboard!

2.3.1. Local RegistryCopy linkLink copied to clipboard!

2.3.2. Remote RegistryCopy linkLink copied to clipboard!

2.4. APB Creation CommandsCopy linkLink copied to clipboard!

2.4.1. initCopy linkLink copied to clipboard!

Description

Usage

Arguments

Options

Examples

2.4.2. prepareCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.4.3. buildCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.4.4. pushCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.4.5. testCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.5. Broker Utility CommandsCopy linkLink copied to clipboard!

2.5.1. listCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.5.2. bootstrapCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.5.3. removeCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.5.4. relistCopy linkLink copied to clipboard!

Description

Usage

Options

Examples

2.6. Other CommandsCopy linkLink copied to clipboard!

2.6.1. helpCopy linkLink copied to clipboard!

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.1. Overview
Copy link

2.2. Installing the Tool
Copy link

2.2.1. Prerequisites
Copy link

2.2.1.1. Docker Daemon
Copy link

2.2.1.2. Access Permissions
Copy link

2.2.2. Installing via RPM
Copy link

2.2.3. Verifying the Installation
Copy link

2.3. Typical Workflows
Copy link

2.3.1. Local Registry
Copy link

2.3.2. Remote Registry
Copy link

2.4. APB Creation Commands
Copy link

2.4.1. init
Copy link

2.4.2. prepare
Copy link

2.4.3. build
Copy link

2.4.4. push
Copy link

2.4.5. test
Copy link

2.5. Broker Utility Commands
Copy link

2.5.1. list
Copy link

2.5.2. bootstrap
Copy link

2.5.3. remove
Copy link

2.5.4. relist
Copy link

2.6. Other Commands
Copy link

2.6.1. help
Copy link