Chapter 3. Writing APBs

In this tutorial, you will walk through the creation of some sample Ansible Playbook Bundles (APBs). You will create actions for them to allow provision, deprovision, bind, and unbind. You can find more information about the design of APBs in the Design topic. More in-depth information about writing APBs is available in the Reference topic.

Before getting started creating your own APBs, you must set up your development environment:

In this tutorial, you will create an APB for a containerized hello world application. You will work through a basic APB that will mirror the APB hello-world-apb.

The brand new APB created in the last section does not do much in its current state. For that, you must add some actions. The actions supported are:

You will add each of these actions in the following sections. But before beginning:

3.1.4.1. Provision

During the apb init process, two parts of the provision task were stubbed out. The playbook, playbooks/provision.yml, and the associated role in roles/provision-my-test-apb:

my-test-apb
├── apb.yml
├── Dockerfile
├── playbooks
│   └── provision.yml 1
└── roles
    └── provision-my-test-apb
        └── tasks
            └── main.yml 2

1

Inspect this playbook.

2

Edit this role.

The playbooks/provision.yml file is the Ansible playbook that will be run when the provision action is called from the OAB. You can change the playbook, but for now you can just leave the code as is.

playbooks/provision.yml

- name: my-test-apb playbook to provision the application
  hosts: localhost
  gather_facts: false
  connection: local
  roles:
  - role: ansible.kubernetes-modules
    install_python_requirements: no
  - role: ansibleplaybookbundle.asb-modules
  - role: provision-my-test-apb
    playbook_debug: false

The playbook will execute on localhost and execute the role provision-my-test-apb. This playbook works on its local container created by the service broker. The ansible.kubernetes-modules role allow you to use the kubernetes-modules to create your OpenShift Container Platform resources. The asb-modules provide additional functionality for use with the OAB.

Currently, there are no tasks in the role. The contents of the roles/provision-my-test-apb/tasks/main.yml only contains comments showing common resource creation tasks. ou can currently execute the provision task, but since there are no tasks to perform, it would simply launch the APB container and exit without deploying anything.

You can try this now by clicking on the my-test APB and deploying it to the getting-started project using the web console:

Figure 3.2. Provisioning my-test

When the provision is executing, a new namespace is created with the name dh-my-test-apb-prov-<random>. In development mode, it will persist, but usually this namespace would be deleted after successful completion. If the APB fails provisioning, the namespace will persist by default.

By looking at the pod resources, you can see the log for the execution of the APB. To view the pod’s logs:

1. Find the namespaces by either using the web console to view all namespaces and sort by creation date, or using the following command:

   $ oc get ns
   NAME                                STATUS    AGE
   ansible-service-broker              Active    1h
   default                             Active    1h
   dh-my-test-apb-prov-<random>        Active    4m

2. Switch to the project:

   $ oc project dh-my-test-apb-prov-<random>
   Now using project "dh-my-test-apb-prov-<random>" on server "<cluster_host>:<port>".

3. Get the pod name:

   $ oc get pods
   NAME             READY     STATUS      RESTARTS   AGE
   <apb_pod_name>   0/1       Completed   0          3m

4. View the logs:

   $ oc logs -f <apb_pod_name>
   ...
   + ansible-playbook /opt/apb/actions/provision.yml --extra-vars '{"_apb_plan_id":"default","namespace":"getting-started"}'
   PLAY [my-test-apb playbook to provision the application] ***********************
   TASK [ansible.kubernetes-modules : Install latest openshift client] *************
   skipping: [localhost]
   TASK [ansibleplaybookbundle.asb-modules : debug] *******************************
   skipping: [localhost]
   PLAY RECAP *********************************************************************
   localhost                  : ok=0    changed=0    unreachable=0    failed=0

3.1.4.1.1. Creating a Deploying Configuration

At the minimum, your APB should deploy the application pods. You can do this by specifying a deployment configuration:

1. One of the first tasks that is commented out in the provision-my-test-apb/tasks/main.yml file is the creation of the deployment configuration. You can uncomment it or paste the following:

   Note

   Normally, you would replace the image: value with your own application image.

   - name: create deployment config
     openshift_v1_deployment_config:
       name: my-test
       namespace: '{{ namespace }}' 1
       labels: 2
         app: my-test
         service: my-test
       replicas: 1 3
       selector: 4
         app: my-test
         service: my-test
       spec_template_metadata_labels:
         app: my-test
         service: my-test
       containers: 5
       - env:
         image: docker.io/ansibleplaybookbundle/hello-world:latest
         name: my-test
         ports:
         - container_port: 8080
           protocol: TCP

   1

   Designates which namespace the deployment configuration should be in.

   2

   Used to help organize, group, and select objects.

   3

   Specifies that you only want one pod.

   4

   The selector section is a labels query over pods.

   5

   This containers section specifies a container with a hello-world application running on port 8080 on TCP. The image is stored at docker.io/ansibleplaybookbundle/hello-world.

   For more information, Writing APBs: Reference has more detail, and you can see the ansible-kubernetes-modules documentation for a full accounting of all fields.

2. Build and push the APB:

   $ apb build
   $ apb push

3. Provision the APB using the web console.

4. After provisioning, there will be a new running pod and a new deployment configuration. Verify by checking your OpenShift Container Platform resources:

   $ oc project getting-started
   $ oc get all
   NAME         REVISION   DESIRED   CURRENT   TRIGGERED BY
   dc/my-test   1          1         1         config
   
   NAME           DESIRED   CURRENT   READY     AGE
   rc/my-test-1   1         1         1         35s
   
   NAME                 READY     STATUS    RESTARTS   AGE
   po/my-test-1-2pw4t   1/1       Running   0          33s

   You will also be able to see the deployed application in the web console on the project’s Overview page.

The only way to use this pod in its current state is to use:

$ oc describe pods/<pod_name>

to find its IP address and access it directly. If there were multiple pods, they would be accessed separately. To treat them like a single host, you need to create a service, described in the next section.

Tip

To clean up before moving on and allow you to provision again, you can delete the getting-started project and recreate it or create a new one.

3.1.4.1.2. Creating a Service

You will want to use multiple pods, load balance them, and create a service so that a user can access them as a single host:

1. Modify the provision-my-test-apb/tasks/main.yml file and add the following:

   - name: create my-test service
     k8s_v1_service:
       name: my-test
       namespace: '{{ namespace }}'
       labels:
         app: my-test
         service: my-test
       selector:
         app: my-test
         service: my-test
       ports:
         - name: web
           port: 80
           target_port: 8080

   The selector section will allow the my-test service to include the correct pods. The ports will take the target port from the pods (8080) and expose them as a single port for the service (80). Notice the application was running on 8080 but has now been made available on the default HTTP port of 80.

   The name field of the port allows you to specify this port in the future with other resources. More information is available in the k8s_v1_service module.

2. Build and push the APB:

   $ apb build
   $ apb push

3. Provision the APB using the web console.

After provisioning, you will see a new service in the web console or CLI. In the web console, you can click on the new service under Networking in the application on the Overview page or under Applications Services. The service’s IP address will be shown which you can use to access the load balanced application.

To view the service information from the command line, you can do the following:

$ oc project getting-started
$ oc get services
$ oc describe services/my-test

The describe command will show the IP address to access the service. However, using an IP address for users to access your application is not generally what you want. Instead, you should create a route, described in the next section.

Tip

To clean up before moving on and allow you to provision again, you can delete the getting-started project and recreate it or create a new one.

3.1.4.1.3. Creating a Route

You can expose external access to your application through a reliable named route:

1. Modify the provision-my-test-apb/tasks/main.yml file and adding the following:

   - name: create my-test route
     openshift_v1_route:
       name: my-test
       namespace: '{{ namespace }}'
       labels:
         app: my-test
         service: my-test
       to_name: my-test
       spec_port_target_port: web

   The to_name is the name of the target service. The spec_port_target_port refers to the name of the target service’s port. More information is available in the openshift_v1_route module.

2. Build and push the APB:

   $ apb build
   $ apb push

3. Provision the APB using the web console.

After provisioning, you will see the new route created. On the web console’s Overview page for the getting-started project, you will now see an active and clickable route link listed on the application. Clicking on the route or visiting the URL will bring up the hello-world application.

You can also view the route information from the CLI:

$ oc project getting-started

$ oc get routes
NAME      HOST/PORT                                   PATH      SERVICES   PORT      TERMINATION   WILDCARD
my-test   my-test-getting-started.172.17.0.1.nip.io             my-test    web                     None

$ oc describe routes/my-test
Name:			my-test
Namespace:		getting-started
...

At this point, your my-test application is fully functional, load balanced, scalable, and accessible. You can compare your finished APB to the hello-world APB in the hello-world-apb example repository.

my-test-apb/
├── apb.yml
├── Dockerfile
├── playbooks
│   └── deprovision.yml 1
└── roles
    └── deprovision-my-test-apb
        └── tasks
            └── main.yml 2

- name: my-test-apb playbook to deprovision the application
  hosts: localhost
  gather_facts: false
  connection: local
  roles:
  - role: ansible.kubernetes-modules
    install_python_requirements: no
  - role: ansibleplaybookbundle.asb-modules
  - role: deprovision-my-test-apb
    playbook_debug: false

- openshift_v1_route:
    name: my-test
    namespace: '{{ namespace }}'
    state: absent

- k8s_v1_service:
    name: my-test
    namespace: '{{ namespace }}'
    state: absent

- openshift_v1_deployment_config:
    name: my-test
    namespace: '{{ namespace }}'
    state: absent

my-apb/
├── ...
├── playbooks/
    ├── test.yml
    └── vars/
        └── test_defaults.yml

- name: test media wiki abp
  hosts: localhost
  gather_facts: false
  connection: local

  roles:
  - role: ansible.kubernetes-modules 1
    install_python_requirements: no

  post_tasks:
  - name: Load default variables for testing 2
    include_vars: test_defaults.yaml
  - name: create project for namespace
    openshift_v1_project:
      name: '{{ namespace }}'
  - name: Run the provision role. 3
    include_role:
      name: provision-mediawiki-apb
  - name: Run the verify role. 4
    include_role:
      name: verify-mediawiki-apb

my-apb/
├── ...
└── roles/
    ├── ...
    └── verify_<name>
        ├── defaults
             └── defaults.yml
        └── tasks
            └── main.yml

 - name: url check for media wiki
   uri:
     url: "http://{{ route.route.spec.host }}"
     return_content: yes
   register: webpage
   failed_when: webpage.status != 200

 - name: url check for media wiki
   uri:
     url: "http://{{ route.route.spec.host }}"
     return_content: yes
   register: webpage

  - name: Save failure for the web page
    asb_save_test_result:
      fail: true
      msg: "Could not reach route and retrieve a 200 status code. Recieved status - {{ webpage.status }}"
    when: webpage.status != 200

  - fail:
      msg: "Could not reach route and retrieve a 200 status code. Recieved status - {{ webpage.status }}"
    when: webpage.status != 200

  - name: Save test pass
    asb_save_test_result:
      fail: false
    when: webpage.status == 200

$ apb test

While the Getting Started topic provides a step by step walkthrough on creating your first Ansible Playbook Bundle (APB), this topic provides more in-depth reference material. The fundamental components that make up an APB are explained in further detail to help an experienced APB developer get a better understanding of each individual component within an APB.

For completed APB examples, you can browse APBs in the ansibleplaybookbundle organization on GitHub.

The following shows an example directory structure of an APB:

example-apb/
├── Dockerfile
├── apb.yml
└── roles/
│   └── example-apb-openshift
│       ├── defaults
│       │   └── main.yml
│       └── tasks
│           └── main.yml
└── playbooks/
    └── provision.yml
    └── deprovision.yml
    └── bind.yml
    └── unbind.yml

The APB spec file is located at apb.yml and is where the outline of your application is declared. The following is an example APB spec:

  version: 1.0
  name: example-apb
  description: A short description of what this APB does
  bindable: True
  async: optional 1
  metadata:
    documentationUrl: <link_to_documentation>
    imageUrl: <link_to_url_of_image>
    dependencies: ['<registry>/<organization>/<dependency_name_1>', '<registry>/<organization>/<dependency_name_2>']
    displayName: Example App (APB)
    longDescription: A longer description of what this APB does
    providerDisplayName: "Red Hat, Inc."
  plans:
    - name: default
      description: A short description of what this plan does
      free: true
      metadata:
        displayName: Default
        longDescription: A longer description of what this plan deploys
        cost: $0.00
      parameters:
        - name: parameter_one
          required: true
          default: foo_string
          type: string
          title: Parameter One
          maxlength: 63
        - name: parameter_two
          required: true
          default: true
          title: Parameter Two
          type: boolean

parameters:
  - name: my_param
    title: My Parameter
    type: enum
    enum: ['X', 'Y', 'Z']
    required: True
    default: X
    display_type: select
    display_group: Group 1

The Dockerfile is what is used to actually build the APB image. As a result, sometimes you will need to customize it for your own needs. For example, if running a playbook that requires interactions with PostgreSQL, you may want to install the required packages by adding the yum install command:

FROM ansibleplaybookbundle/apb-base
MAINTAINER Ansible Playbook Bundle Community

LABEL "com.redhat.apb.spec"=\
"<------------base64-encoded-spec------------>"


COPY roles /opt/ansible/roles
COPY playbooks /opt/apb/actions
RUN chmod -R g=u /opt/{ansible,apb}


### INSTALL THE REQUIRED PACKAGES
RUN yum -y install python-boto postgresql && yum clean all

USER apb

An action for an APB is the command that the APB is run with. The standard actions that are supported are:

For an action to be valid, there must be a valid file in the playbooks/ directory named <action>.yml. These playbooks can do anything, which also means that you can technically create any action you would like. For example, the mediawiki-apb has playbook creating an update action.

Most APBs will normally have a provision action to create resources and a deprovision action to destroy the resources when deleting the service.

The bind and unbind actions are used when the coordinates of one service needs to be made available to another service. This is often the case when creating a data service and making it available to an application. Currently, the coordinates are made available during the provision.

To properly make your coordinates available to another service, use the asb_encode_binding module. This module should be called at the end of the APB’s provision role, and it will return bind credentials to the OpenShift Ansible broker (OAB):

- name: encode bind credentials
  asb_encode_binding:
    fields:
      EXAMPLE_FIELD: foo
      EXAMPLE_FIELD2: foo2

This section describes a list of common OpenShift Container Platform resources that are created when developing APBs. See the Ansible Kubernetes Module for a full list of available resource modules.

- name: create hello-world service
  k8s_v1_service:
    name: hello-world
    namespace: '{{ namespace }}'
    labels:
      app: hello-world
      service: hello-world
    selector:
      app: hello-world
      service: hello-world
    ports:
      - name: web
        port: 8080
        target_port: 8080

- k8s_v1_service:
    name: hello-world
    namespace: '{{ namespace }}'
    state: absent

- name: create deployment config
  openshift_v1_deployment_config:
    name: hello-world
    namespace: '{{ namespace }}'
    labels:
      app: hello-world
      service: hello-world
    replicas: 1
    selector:
      app: hello-world
      service: hello-world
    spec_template_metadata_labels:
      app: hello-world
      service: hello-world
    containers:
    - env:
      image: docker.io/ansibleplaybookbundle/hello-world:latest
      name: hello-world
      ports:
      - container_port: 8080
        protocol: TCP

- openshift_v1_deployment_config:
    name: hello-world
    namespace: '{{ namespace }}'
    state: absent

- name: create hello-world route
  openshift_v1_route:
    name: hello-world
    namespace: '{{ namespace }}'
    spec_port_target_port: web
    labels:
      app: hello-world
      service: hello-world
    to_name: hello-world

- openshift_v1_route:
    name: hello-world
    namespace: '{{ namespace }}'
    state: absent

# Persistent volume resource
- name: create volume claim
  k8s_v1_persistent_volume_claim:
    name: hello-world-db
    namespace: '{{ namespace }}'
    state: present
    access_modes:
      - ReadWriteOnce
    resources_requests:
      storage: 1Gi

- name: create hello-world-db deployment config
  openshift_v1_deployment_config:
    name: hello-world-db
    ---
    volumes:
    - name: hello-world-db
      persistent_volume_claim:
        claim_name: hello-world-db
      test: false
      triggers:
      - type: ConfigChange

- openshift_v1_deployment_config:
    name: hello-world-db
    namespace: '{{ namespace }}'
    state: absent

- k8s_v1_persistent_volume_claim:
    name: hello-world-db
    namespace: '{{ namespace }}'
    state: absent

You can add optional variables to an APB by using environment variables. To pass variables into an APB, you must escape the variable substitution in your .yml files.

For example, consider the following roles/provision-etherpad-apb/tasks/main.yml file in the etherpad-apb:

- name: create mariadb deployment config
  openshift_v1_deployment_config:
    name: mariadb
    namespace: '{{ namespace }}'
    ...
    - env:
      - name: MYSQL_ROOT_PASSWORD
        value: '{{ mariadb_root_password }}'
      - name: MYSQL_DATABASE
        value: '{{ mariadb_name }}'
      - name: MYSQL_USER
        value: '{{ mariadb_user }}'
      - name: MYSQL_PASSWORD
        value: '{{ mariadb_password }}'

Variables for the APB are defined in the roles/provision-etherpad-apb/defaults/main.yml file:

playbook_debug: no
mariadb_root_password: "{{ lookup('env','MYSQL_ROOT_PASSWORD') | default('admin', true) }}"
mariadb_name: "{{ lookup('env','MYSQL_DATABASE') | default('etherpad', true) }}"
mariadb_user: "{{ lookup('env','MYSQL_USER') | default('etherpad', true) }}"
mariadb_password: "{{ lookup('env','MYSQL_PASSWORD') | default('admin', true) }}"
etherpad_admin_password: "{{ lookup('env','ETHERPAD_ADMIN_PASSWORD') | default('admin', true) }}"
etherpad_admin_user: "{{ lookup('env','ETHERPAD_ADMIN_USER') | default('etherpad', true) }}"
etherpad_db_host: "{{ lookup('env','ETHERPAD_DB_HOST') | default('mariadb', true) }}"
state: present

When developing APBs, there are a few factors which could prevent the developer from using the full development lifecycle that the apb tooling offers. Primarily, these factors are:

If a developer meets any of these criteria, use the following workflow to publish images to the internal OpenShift Container Platform registry so that the broker can bootstrap the image (the process of loading APB specs into the broker). The following sections show how to do these steps with the apb tooling and without.

When building an OpenShift Container Platform image, it is important that you do not have your application running as the root user when at all possible. When running under the restriced security context, the application image is launched with a random UID. This causes problems if your application folder is owned by the root user.

A good way to work around this is to add a user to the root group and make the application folder owned by the root group. See OpenShift Container Platform-Specific Guidelines for details on supporting arbitrary user IDs.

The following is a Dockerfile example of a node application running in /usr/src. This command would be run after the application is installed in /usr/src and the associated environment variables set:

ENV USER_NAME=haste \
    USER_UID=1001 \
    HOME=/usr/src

RUN useradd -u ${USER_UID} -r -g 0 -M -d /usr/src -b /usr/src -s /sbin/nologin -c "<username> user" ${USER_NAME} \
               && chown -R ${USER_NAME}:0 /usr/src \
               && chmod -R g=u /usr/src /etc/passwd
USER 1001

There is a temporary workaround for creating ConfigMaps from Ansible due to a bug in the Ansible modules.

One common use case for ConfigMaps is when the parameters of an APB will be used within a configuration file of an application or service. The ConfigMap module allows you to mount a ConfigMap into a pod as a volume, which can be used to store the configuration file. This approach allows you to also leverage the power of Ansible’s template module to create a ConfigMap out of APB paramters.

The following is an example of creating a ConfigMap from a Jinja template mounted into a pod as a volume:

- name: Create hastebin config from template
  template:
    src: config.js.j2
    dest: /tmp/config.js

- name: Create hastebin configmap
  shell: oc create configmap haste-config --from-file=haste-config=/tmp/config.js

<snip>

- name: create deployment config
  openshift_v1_deployment_config:
    name: hastebin
    namespace: '{{ namespace }}'
    labels:
      app: hastebin
      service: hastebin
    replicas: 1
    selector:
      app: hastebin
      service: hastebin
    spec_template_metadata_labels:
      app: hastebin
      service: hastebin
    containers:
    - env:
      image: docker.io/dymurray/hastebin:latest
      name: hastebin
      ports:
      - container_port: 7777
        protocol: TCP
      volumeMounts:
        - mountPath: /usr/src/haste-server/config
          name: config
    - env:
      image: docker.io/modularitycontainers/memcached:latest
      name: memcached
      ports:
      - container_port: 11211
        protocol: TCP
    volumes:
      - name: config
        configMap:
          name: haste-config
          items:
            - key: haste-config
              path: config.js

A default error message is returned in the web console when a provision call fails. For example:

Error occurred during provision. Please contact administrator if the issue persists.

To provide more information for troubleshooting purposes should a failure occur, you can write custom error messages for your APB that the web console can check for and return to the user.

Kubernetes allows pods to log fatal events to a termination log. The log file location is set by the terminationMessagePath field in a pod’s specification and defaults to /dev/termination-log.

The broker checks this termination log for any messages that were written to the file and passes the content to the service catalog. In the event of a failure, the web console sdisplays these messages.

The following is an example of how this can be done in an APB utilizing a CloudFormation template:

- name: Writing Termination Message
  shell: echo "[CloudFormation Error] - {{ ansible_failed_result.msg }}" > /dev/termination-log

- fail: msg="[APB Failed Plain - '{{ _apb_plan_id }}'] "

If an error occurs, this example custom message is written to the default termination log path before it fails the pod.