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.
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.
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-toolsThere 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.
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
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.
Alternatively you can use tito to install.
tito build --test --rpm -iRun 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
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.
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 listIf 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>
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 listInitializes a directory structure for a new apb. Also creates example files for the new APB with sensible defaults.
apb init [OPTIONS] NAMENAME: Name of the APB and directory to be created
| 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 |
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.ymlCreate 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.ymlCreate 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.ymlCompiles 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.
apb prepare [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" |
Writes the label for the spec field in Dockerfile
apb prepareWrites the label for the spec field in Dockerfile-custom
apb prepare --dockerfile Dockerfile-customBuilds the image for the APB.
Similar to running apb prepare and docker build with a tag.
apb build [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" |
Build the image and use the name field from apb.yml as the tag.
apb buildBuild the image and use the tag docker.io/my-org/my-new-apb.
apb build --tag docker.io/my-org/my-new-apbBuild the image using the file "Dockerfile-custom" as the Dockerfile definition.
apb build --dockerfile Dockerfile-customUploads 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.
apb push [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 |
Push to the local OpenShift registry
apb pushPush to the Ansible Service Broker development endpoint
apb push --push-to-brokerPush to the local OpenShift registry under namespace leto
apb push --namespace letoRuns the APB unit tests.
apb test [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 |
Run the tests
apb testRun the tests but use a specific tag on the built image
apb test --tag docker.io/my-org/my-new-apbLists all the APBs the broker has loaded
apb list [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 |
Basic list of APBs including name, ID, and description
apb listList verbose pretty printed specs
apb list -v List all the json output
apb list -v -o jsonRequests the Ansible Service Broker to reload all APBs from the registries.
apb bootstrap [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 |
Basic reload of APBs
apb bootstrapRemoves one (or all) APBs from the broker.
apb remove [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 |
Remove an APB that was pushed to the internal registry using apb push
$ pwd
/home/user/my-test-apb
$ apb remove -lRemove all APBs from internal registry (assumes all APBs are named *-apb)
$ apb remove -l --allRemove 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 ca91b61da8476984f18fc13883ae2fdbDeleting 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 applicationRemove all APB specs from the broker
apb remove --allForces service catalog to relist the provided services to match the broker.
apb relist [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 |
apb relistDisplays a help message
apb helpapb helpapb -h