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.
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 RoleBinding
s 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
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
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
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 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
bootstrap
Description
Requests the Ansible Service Broker 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 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
remove
Description
Removes one (or all) APBs from the broker.
Usage
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
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 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
help
Description
Displays a help message
Usage
apb help
Examples
apb help
apb -h