APB CLI Tool

apb is a tool for helping 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.

Installation
Typical Workflows
- Local Registry
- Remote Registry
APB Commands
- Creating APBs
  - init
  - prepare
  - build
  - push
  - test
- Broker Utilities
  - list
  - bootstrap
  - remove
  - relist
- Other
  - help

Installing the apb tool

Prerequisites

Docker must be correctly installed and running on the system.

NOTE: If you are working with a minishift cluster and the ansible-service-broker addon, you must first configure your shell to use the minishift Docker daemon. This can be done with eval $(minishift docker-env). For more info, see minishift's documentation for working with its docker registry.

Running from a container

NOTE: You must configure your host networking to allow traffic between your container and the minishift vm if you are using minishift. Execute setup-network.sh to setup necessary iptables rules.

Pull the container:

docker pull docker.io/ansibleplaybookbundle/apb-tools

There are three tags to choose from:

latest: more stable, less frequent releases
nightly: following upstream commits, installed from RPM
canary: following upstream commits, installed from source build

Copy the apb-docker-run.sh script into your PATH and make sure it's executable:

cp $APB_CHECKOUT/scripts/apb-docker-run.sh $YOUR_PATH_DIR/apb && chmod +x $YOUR_PATH_DIR/apb

You should be able to start working by running apb init my_apb. The first run may take awhile if you did not pull the image.

RPM Installation

For RHEL or CentOS 7:

su -c 'wget https://copr.fedorainfracloud.org/coprs/g/ansible-service-broker/ansible-service-broker-latest/repo/epel-7/group_ansible-service-broker-ansible-service-broker-latest-epel-7.repo -O /etc/yum.repos.d/ansible-service-broker.repo'

sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum -y install apb

For Fedora 26 or Fedora 27:

sudo dnf -y install dnf-plugins-core
sudo dnf -y copr enable @ansible-service-broker/ansible-service-broker-latest
sudo dnf -y install apb

Installing from source

Installing from source - Python/VirtualEnv

Clone this repo

git clone https://github.com/fusor/ansible-playbook-bundle.git

Install python-virtualenv, create a virtualenv, and activate it.

sudo dnf install -y python-virtualenv
virtualenv /tmp/apb
source /tmp/apb/bin/activate

Install requirements and run the setup script (requires python)

cd ansible-playbook-bundle && pip install -U setuptools && pip install -r src/requirements.txt && python setup.py install

Optionally, if actively developing on the project, install the testing requirements:

pip install -r src/test-requirements.txt

Reactivate the apb virtualenv in other shell sessions using source /tmp/apb/bin/activate if needed.

Installing from source - Tito

Alternatively you can use tito to install.

tito build --test --rpm -i

Test APB Tooling

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 Ansible Service Broker
    bootstrap           Tell Ansible Service Broker to reload APBs from the
                        container repository
    list                List APBs from the target Ansible Service Broker
    remove              Remove APBs from the target Ansible Service Broker
    build               Build and package APB container

Access Permissions

The apb tool requires you to be logged in as a tokened cluster user (system:admin 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 RoleBindings and ClusterRoleBindings that must exist to permit the full breadth of the apb tool's functions.

The easiest option is to ensure the user has the cluster-admin ClusterRoleBinding. To be clear, 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>

If you would like a more strictly permissioned environment, we have an Openshift Template available that can be applied with the following command:

oc process -f templates/openshift-permissions.template.yaml -p USER=<your_desired_user> | oc create -f -.

By default, the template will permission the developer user. If that is your user, it is safe to leave off the -p flag, which overrides the default value. Obviously, this command must be run by a user with sufficient permissions to create the various roles. The developer account does not have such permissions. oc login -u system:admin should be sufficient.

Typical Workflows

Local Registry

In order to use the internal OpenShift Docker Registry to source APBs, you must have configured the Ansible Service Broker to use the local_openshift type registry adapter. Please 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

Ansible Service Broker can also be configured to use a remote registry and org 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 Commands

Creating APBs

init
prepare
build
push
test

Broker Utilities

list
bootstrap
remove
relist

Other

help

`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

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

`prepare`

Description

Compiles the apb into base64 encoding and writes it as a label to the Dockerfile.

This will allow the Ansible Service Broker 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 don't 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 filename instead of a file named "Dockerfile"

Examples

Writes the label for the spec field in 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
--dockerfile DOCKERFILE, -f DOCKERFILE	Writes the apb spec to the target filename instead of a file named "Dockerfile"

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 using the file "Dockerfile-custom" as the Dockerfile definition.

apb build --dockerfile Dockerfile-custom

`push`

Description

Uploads the APB to a local openshift registry or a broker mock registry where it will be read by the Ansible Service Broker.

When using the broker's mock registry, the spec is uploaded and will be displayed in OpenShift, but OpenShift will pull the image from the registry normally. Usually that means the docker registry where oc cluster up was performed.

When using the local openshift registry, the image is uploaded to OpenShift directly.

Usage

apb push [OPTIONS]

Options

Option, shorthand	Description
--help, -h	Show help message
--broker BROKER_URL	Route to the Ansible Service Broker
--namespace NAMESPACE	Namespace to push to internal OpenShift registry
--registry-service-name REG_SVC_NAME	Name of service for the internal OpenShift registry
--registry-route REG_ROUTE	Name of service for the internal OpenShift registry
--registry-namespace REG_NAMESPACE	Name of service for the internal OpenShift registry
--dockerfile DOCKERFILE, -f DOCKERFILE	Dockerfile to build internal registry image. Usually defaults to "Dockerfile" but can be set to any filename
--secure	Use secure connection to Ansible Service Broker
--username USERNAME	Basic auth username to be used in broker communication
--password PASSWORD	Basic auth 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 k8s resource
--push-to-broker	Use the OpenShift Ansible Broker mock registry endpoint

Examples

Push to the local OpenShift registry

apb push

Push to the Ansible Service Broker development endpoint

apb push --push-to-broker

Push to the local OpenShift registry under namespace leto

apb push --namespace leto

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

apb list [OPTIONS]

Options

Option, shorthand	Description
--help, -h	Show help message
--broker BROKER_URL	Route to the Ansible Service Broker
--secure	Use secure connection to Ansible Service Broker
--verbose, -v	Output verbose spec information from Ansible Service Broker
--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 auth username to be used
--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD	Specify the basic auth password to be used

Examples

Basic list of APBs including name, ID, and description

apb list

List verbose pretty printed specs

apb list -v

List all the json output

apb list -v -o json

apb bootstrap [OPTIONS]

Options

Option, shorthand	Description
--help, -h	Show help message
--broker BROKER_URL	Route to the Ansible Service Broker
--secure	Use secure connection to Ansible Service Broker
--no-relist	Do not relist the catalog after bootstrapping the broker
--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME	Specify the basic auth username to be used
--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD	Specify the basic auth password to be used
--broker-name BROKER_NAME	Name of the ServiceBroker k8s resource

Examples

Basic reload of APBs

apb bootstrap

apb remove [OPTIONS]

Options

Option, shorthand	Description
--help, -h	Show help message
--broker BROKER_URL	Route to the Ansible Service Broker
--secure	Use secure connection to Ansible Service Broker
--all	Remove all stored APBs
--local, -l	Remove APB from internal registry (apb push'ed APB)
--id ID	ID of APB to remove
--secure	Use secure connection to Ansible Service Broker
--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME	Specify the basic auth username to be used
--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD	Specify the basic auth password to be used
--no-relist	Do not relist the catalog after deletion

Examples

Remove an APB that was pushed to the internal registry using apb push

$ pwd
/home/user/my-test-apb
$ apb remove -l

Remove all APBs from internal registry (assumes all APBs are named *-apb)

$ apb remove -l --all

Remove an APB using an ID (This only removes the spec from the broker. It does not remove the image itself from the remote registry.)

apb remove --id ca91b61da8476984f18fc13883ae2fdb
oc delete clusterserviceclass ca91b61da8476984f18fc13883ae2fdb

Deleting the clusterserviceclass removes the associated APB from the Service Catalog.

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

Remove all APB specs from the broker

apb remove --all

apb relist [OPTIONS]

Options

Option, shorthand	Description
--help, -h	Show help message
--broker-name BROKER_NAME	Name of the ServiceBroker k8s resource
--secure	Use secure connection to Ansible Service Broker
--username BASIC_AUTH_USERNAME, -u BASIC_AUTH_USERNAME	Specify the basic auth username to be used
--password BASIC_AUTH_PASSWORD, -p BASIC_AUTH_PASSWORD	Specify the basic auth password to be used

Examples

apb relist

apb help

Examples

apb help

apb -h