$ docker pull docker.io/ansibleplaybookbundle/apb[:<tag>]
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.
To run the apb tool from a container:
Pull the container:
$ docker pull docker.io/ansibleplaybookbundle/apb[:<tag>]
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.
Choose one of the following:
Create an alias in your .bashrc or somewhere else for your shell:
alias apb='docker run --rm --privileged -v $PWD:/mnt -v $HOME/.kube:/.kube -v /var/run/docker.sock:/var/run/docker.sock -u $UID docker.io/ansibleplaybookbundle/apb'
If you would prefer to use atomic rather than an alias:
$ atomic run docker.io/ansibleplaybookbundle/apb init my_apb
Start working by running the command:
$ apb init my_apb
The first run may take awhile if you did not pull the image beforehand.
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 the following repository:
$ 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
If needed, reactivate the apb virtualenv in other shell sessions using:
$ source /tmp/apb/bin/activate
Alternatively, you can use tito to
install:
# tito build --test --rpm -i
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 container
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
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>
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
initInitializes a directory structure for a new APB. Also creates example files for the new APB with sensible defaults.
$ apb init [OPTIONS] NAME
NAME: Name of the APB and directory to be created.
| 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 |
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
prepareCompiles 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.
$ apb prepare [OPTIONS]
| Option, Shorthand | Description |
|---|---|
|
Show help message |
|
Writes the APB spec to the target file name instead of a file named Dockerfile |
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
buildBuilds the image for the APB.
Similar to running apb prepare and docker build with a tag.
$ apb build [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 |
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
pushUploads 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 Origin, but OpenShift Origin 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 Origin directly.
$ apb push [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 |
Push to the OAB development endpoint:
$ apb push
Push to the local OpenShift Container Registry:
$ apb push -o
Push to the local OpenShift Container Registry under namespace myproject:
$ apb push -o --namespace myproject
testRuns the APB unit tests.
$ apb test [OPTIONS]
| Option, Shorthand | Description |
|---|---|
|
Show help message |
|
Sets the tag of the built image to a string in the format |
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
listLists all the APBs the broker has loaded.
$ apb list [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 |
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
bootstrapRequests the OAB to reload all APBs from the registries.
$ apb bootstrap [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 |
Basic reload of APBs:
$ apb bootstrap
removeRemoves one (or all) APBs from the OAB.
$ apb remove [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 |
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
relistForces service catalog to relist the provided services to match the broker.
$ apb relist [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 |
$ apb relist