APB Development & Testing - Part 1

Introduction

Do you know what the OpenShift Service Catalog is? Let me introduce you to the world of APB development.

In the OpenShift Origin 3.7 version, you can use this feature to provision applications in a project in a more user-friendly way.

Service catalog contains two kinds of objects, one is based on templates and the other one uses an Ansible automation execution model. This second model is known as an APB (Ansible Playbook Bundle) and the focus of this model is to further the deployment of the static templates to support the complex deployments like DDBB clusters, the bind applications between them, and a long list of other capabilities. This post will describe the ways to develop those bundles in the right way and test to ensure they are maintainable.

Development Environment

First of all, we need some resources to bootstrap the wheel. This is the main repository and you could find many useful resources, but let's get started with a summary of the needs:

• OpenShift Origin to work in local
  • Minishift or oc cluster
• OpenShift Service Catalog activated
• Modify some tweaks that come by default
• APB binary
• Ansible friendly IDE

Hands-on

To get started, we must begin downloading and starting the local environment, just execute these commands:

mkdir ~/dev && cd ~/dev

wget https://raw.githubusercontent.com/openshift/ansible-service-broker/master/scripts/run_latest_build.sh

chmod 755 run_latest_build.sh

ORIGIN_VERSION=v3.7.1 ./run_latest_build.sh

Note: This requires that you have Docker properly working on your laptop.

Now let's change from system:admin user; the broker needs another user to interact with it.

oc adm policy add-cluster-role-to-user cluster-admin developer

oc login -u developer

Furthermore, we must modify the configuration of the Ansible Service Broker app:

oc edit cm/broker-config -n ansible-service-broker

This will prompt the config map to be edited, just change the sandbox_role field from edit to admin:

...

...

  openshift:

    host: ""

    ca_file: ""

    bearer_token_file: ""

    image_pull_policy: "IfNotPresent"

    sandbox_role: "admin"

    namespace: "ansible-service-broker"

    keep_namespace: false

    keep_namespace_on_error: true

...

...

This change will allow the broker to add permissions to other resources. Now we must delete the pod or just perform a rollout to change the configmap.

oc rollout latest dc/asb -n ansible-service-broker

Great, during the re-creation of the pod we will install the APB client.

sudo dnf -y copr enable @ansible-service-broker/ansible-service-broker-latest

sudo dnf install apb apb-base-scripts apb-container-scripts -y

Now we are ready to start working on Ansible Playbook Bundles.

Ansible Playbook Bundle Internals

Ansible Playbook Bundle works as an engine to parse the apb.yml file and prepare all the data to be sent to the broker. When an execution is triggered, a pod is created in a namespace, and the name could vary depending on how you trigger the execution. We have 3 ways:

• WebUI
  • Behaviour: Will provision the bundle in your project or other that you choose, with the name based on patterns for the Ansible pod.
  • Tips: Needs to be tested at least before publishing a new release.
• Shell using apb push
  • Behaviour: Will provision the bundle in your project or other that you choose, with the name based on --project argument. This way of work uses the Broker's Route to interact with it.
  • Tips: Not bad at testing, good for troubleshooting.
• Shell using apb test
  • Behaviour: Will execute all the steps, create a new Project, deploy the bundle on it, erase the resources, and delete the project. This way of work didn't use the Broker's Route.
  • Tips: Good for testing, bad for troubleshooting.

In the flow that the events follow, the engine raises up a pod that will execute all Ansible related actions, hence the engine injects all the info in the pod, including the Ansible code, variables, modules, etc. and in addition will pass through the "action" that APB will execute. This "action" is an Ansible Playbook Bundle engine reserved variable/word that will say to the engine what Playbook must execute.

Let's take a look at a provision.yml

---

- name: "[PROMETHEUS-APB][PROVISION] Provision application Prometheus APB"

  hosts: localhost

  gather_facts: false

  connection: local

  vars:

    state: 'present'

    mode: 'provision'

  roles:

    - role: ansible.kubernetes-modules

      install_python_requirements: no

    - role: ansibleplaybookbundle.asb-modules

    - role: prometheus-apb

      playbook_debug: false

Most importantly, check out the roles that you are executing, kubernetes-modules and asb-modules allow you to provision resources on k8s and OpenShift and also interact with the broker. Those modules don't run any effective task, they will just load the modules in order to be used by Ansible. Then the last role calls our bundle's main.yml and starts the execution.

As a result, this is a graph of the flow in the MongoDB-APB example:

Preparing the Field

To start creating our first Ansible Playbook Bundle we need to bootstrap the APB client with a folder structure: Just execute apb init <module-name>-apb --bindable. The suffix "-apb" is important, because, by default, the broker configuration will accept on the whitelist all the elements in the local registry that finish with it, otherwise, you will not see the APB on the catalog after the push.

Consequently, this is the folder tree that this command generates:

As you see, we have a Playbook and a related role; is quite obvious what every playbook file will do.

Let's see how the apb.yml file looks:

version: 1.0

name: mongodb-apb

description: Deploy MongoDB app on your Openshift Project

bindable: True

async: optional

metadata:

  documentationUrl: https://access.redhat.com

  imageUrl: http://nightdeveloper.net/wp-content/uploads/2014/12/mongo_db.png

  displayName: MongoDB (APB)

  providerDisplayName: "Red Hat, Inc."

  longDescription: MongoDB is a document database with the scalability and flexibility that you want with the querying and indexing that you need. This APB will cover an standalone and HA deployment.

plans:

  - name: ephemeral

    description: This default plan deploys mongodb-apb

    free: True

    metadata:

      displayName: Ephemeral

      longDescription: This plan will deploy a MongoDB standalone or HA instance/s using ephemeral storage

      cost: €0.00

    parameters:

      - ....

....

....

• version will say to the engine which version must be used to parse this APB file, and is not related to the software that will deploy the APB.
• bindable will define this APB as a resource that you could bind from other application.
• async will determine if the bind will be done at provision time or later.
• Inside of metadata there are so many possible parameters, all of them are aesthetic and not functional but useful for the user, more info here.
• Plans are an especially relevant section that will contain all the plans and also the parameters for every plan you want.
• Parameters have many options to be combined, take a look here for more info.

Check out a complete sample to see how it looks and figure out how to make them yours.

When you finish, execute apb prepare where the apb.yml are located and as a result, you will see that the Dockerfile has changed. It now contains a new entry below the label com.redhat.apb.spec, this big hash is the content of apb.yml in Base64.

I also recommend adding couple of lines to the Dockerfile to COPY your plugins and ansible.cfg to a the APB base container to extend the capabilities of the APB.

Part 1 Conclusion

In conclusion, to start on the Ansible Playbook Bundle development you need a previous work that will allow you a good base to start off quickly. Ansible Service Catalog with the Broker and the Bundles provides an automation layer above the traditional templates that will give you some extras capabilities like clustering, service binding, integration with external systems, etc.