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):
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:
- Download the openshift-permissions.template.yaml file locally.
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
-pflag 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.7-rpms channel:
$ sudo yum install apb
2.2.3. 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 container2.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.
$ 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>
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:
$ 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
$ apb init [OPTIONS] NAME
Arguments
NAME: Name of the APB and directory to be created.
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
| Force re-init and overwrite the directory |
|
|
Specify asynchronous operation on application. Usually defaulted to |
|
| Generate an application with bindable settings |
|
| Do not generate provision playbook and role |
|
| Do not generate deprovision playbook and role |
|
| Do not generate bind playbook and role |
|
| Do not generate unbind playbook and role |
|
| 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
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
$ apb prepare [OPTIONS]
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
| 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
2.4.3. 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 |
|---|---|
|
| Show help message |
|
|
Sets the tag of the built image to a string in the format |
|
|
Registry portion of the tag of the image (e.g., |
|
| 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
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
$ apb push [OPTIONS]
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
| Route to the OAB |
|
| Namespace to push to the OpenShift Container Registry |
|
| Use the OpenShift Container Registry |
|
|
Dockerfile to build internal registry image. Usually defaults to |
|
| Use secure connection to OAB |
|
| Basic authentication user name to be used in broker communication |
|
| Basic authentication password to be used in broker communication |
|
| Do not relist the catalog after pushing an APB to the broker |
|
| 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
2.4.5. test
Description
Runs the APB unit tests.
Usage
$ apb test [OPTIONS]
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
|
Sets the tag of the built image to a string in the format |
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
2.5. Broker Utility Commands
2.5.1. list
Description
Lists all the APBs the broker has loaded.
Usage
$ apb list [OPTIONS]
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
| Route to the OAB |
|
| Use secure connection to OAB |
|
| Output verbose spec information from OAB |
|
| Specify verbose output format in yaml (default) or json |
|
| Specify the basic authentication user name to be used |
|
| 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
2.5.2. bootstrap
Description
Requests the OAB to reload all APBs from the registries.
Usage
$ apb bootstrap [OPTIONS]
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
| Route to the OAB |
|
| Use secure connection to OAB |
|
| Do not relist the catalog after bootstrapping the broker |
|
| Specify the basic authentication user name to be used |
|
| Specify the basic authentication password to be used |
|
| Name of the ServiceBroker Kubernetes resource |
Examples
Basic reload of APBs:
$ apb bootstrap
2.5.3. remove
Description
Removes one (or all) APBs from the OAB.
Usage
$ apb remove [OPTIONS]
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
| Route to the OAB |
|
| Use secure connection to OAB |
|
| Remove all stored APBs |
|
| ID of APB to remove |
|
| Use secure connection to OAB |
|
| Specify the basic authentication user name to be used |
|
| Specify the basic authentication password to be used |
|
| 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
2.5.4. relist
Description
Forces service catalog to relist the provided services to match the broker.
Usage
$ apb relist [OPTIONS]
Options
| Option, Shorthand | Description |
|---|---|
|
| Show help message |
|
| Name of the ServiceBroker Kubernetes resource |
|
| Use secure connection to OAB |
|
| Specify the basic authentication user name to be used |
|
| Specify the basic authentication password to be used |
Examples
$ apb relist
2.6. Other Commands
2.6.1. help
Description
Displays a help message.
Usage
$ apb help
Examples
$ apb help
$ apb -h
