Writing APBs: Reference

Overview

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.

Directory Structure

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

APB Spec File

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

Top-level Structure

Metadata

Plans

Plans are declared as a list. This section explains what each field in a plan describes.

Plan Metadata

Parameters

Each item in the parameters section can have several fields. The name field is required. The order of the parameters will be displayed in sequential order in the form in the OKD web console.

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

When using a long list of parameters, it can be useful to use a shared parameter list. For an example of this, see the rhscl-postgresql-apb.

APB Spec Versioning

The APB spec uses semantic versioning with the format of x.y where x is a major release and y is a minor release.

The current spec version is 1.0.

Major Version

The APB spec will increment the major version whenever an API breaking change is introduced to the spec. Some examples include:

• Introduction or deletion of a required field.

• Changing the YAML format.

• New features.

Minor Version

The APB spec will increment the minor version whenever a non-breaking change is introduced to the spec. Some examples include:

• Introduction or deletion of an optional field.

• Spelling change.

• Introduction of new options to an existing field.

Dockerfile

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

APB Actions (Playbooks)

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

• provision

• deprovision

• bind

• unbind

• test

For an action to be valid, there must be a valid file in the playbooks/ directory named .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

Working With Common Resources

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

Service

The following is a sample Ansible task to create a service named hello-world. The namespace variable in an APB will be provided by the OAB when launched from the web console.

Provision

- 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

Deprovision

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

Deployment Configuration

The following is a sample Ansible task to create a deployment configuration for the image docker.io/ansibleplaybookbundle/hello-world which maps to service hello-world.

Provision

- 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

Deprovision

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

Route

The following is an example of creating a route named hello-world which maps to the service hello-world.

Provision

- 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

Deprovision

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

Persistent Volume

The following is an example of creating a persistent volume claim (PVC) resource and deployment configuration that uses it.

Provision

# 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

In addition to the resource, add your volume to the deployment configuration declaration:

- 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

Deprovision

- 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

Optional Variables

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

Working with Remote Clusters

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:

• Developing against an OKD cluster that exists on a remote host.

• Developing APBs on a machine that does not have access to the docker daemon.

If a developer meets any of these criteria, use the following workflow to publish images to the internal OKD 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.

Pushing APBs

To use the apb push command when working with a remote OKD cluster:

1. Ensure the base64-encoded APB spec is a label in the Dockerfile. This is usually done using the apb prepare command. If you do not have the apb tooling installed, you can run:

   $ cat apb.yml | base64

   This will return the base64-encoded apb.yml, which you can copy and paste into the Dockerfile under the LABEL "com.redhat.apb.spec" like:

   LABEL "com.redhat.apb.spec"=\
   "dmVyc2lvbjogMS4wCm5hbWU6IG1lZGlhd2lraS1hcGIKZGVzY3JpcHRpb246IE1lZGlhd2lraSBh\
   cGIgaW1wbGVtZW50YXRpb24KYmluZGFibGU6IEZhbHNlCmFzeW5jOiBvcHRpb25hbAptZXRhZGF0\
   YToKICBkb2N1bWVudGF0aW9uVXJsOiBodHRwczovL3d3dy5tZWRpYXdpa2kub3JnL3dpa2kvRG9j\
   dW1lbnRhdGlvbgogIGxvbmdEZXNjcmlwdGlvbjogQW4gYXBiIHRoYXQgZGVwbG95cyBNZWRpYXdp\
   a2kgMS4yMwogIGRlcGVuZGVuY2llczogWydkb2NrZXIuaW8vYW5zaWJsZXBsYXlib29rYnVuZGxl\
   L21lZGlhd2lraTEyMzpsYXRlc3QnXQogIGRpc3BsYXlOYW1lOiBNZWRpYXdpa2kgKEFQQilmZGZk\
   CiAgY29uc29sZS5vcGVuc2hpZnQuaW8vaWNvbkNsYXNzOiBpY29uLW1lZGlhd2lraQogIHByb3Zp\
   ZGVyRGlzcGxheU5hbWU6ICJSZWQgSGF0LCBJbmMuIgpwbGFuczoKICAtIG5hbWU6IGRlZmF1bHQK\
   ICAgIGRlc2NyaXB0aW9uOiBBbiBBUEIgdGhhdCBkZXBsb3lzIE1lZGlhV2lraQogICAgZnJlZTog\
   VHJ1ZQogICAgbWV0YWRhdGE6CiAgICAgIGRpc3BsYXlOYW1lOiBEZWZhdWx0CiAgICAgIGxvbmdE\
   ZXNjcmlwdGlvbjogVGhpcyBwbGFuIGRlcGxveXMgYSBzaW5nbGUgbWVkaWF3aWtpIGluc3RhbmNl\
   IHdpdGhvdXQgYSBEQgogICAgICBjb3N0OiAkMC4wMAogICAgcGFyYW1ldGVyczoKICAgICAgLSBu\
   YW1lOiBtZWRpYXdpa2lfZGJfc2NoZW1hCiAgICAgICAgZGVmYXVsdDogbWVkaWF3aWtpCiAgICAg\
   ICAgdHlwZTogc3RyaW5nCiAgICAgICAgdGl0bGU6IE1lZGlhd2lraSBEQiBTY2hlbWEKICAgICAg\
   ICBwYXR0ZXJuOiAiXlthLXpBLVpfXVthLXpBLVowLTlfXSokIgogICAgICAgIHJlcXVpcmVkOiBU\
   cnVlCiAgICAgIC0gbmFtZTogbWVkaWF3aWtpX3NpdGVfbmFtZQogICAgICAgIGRlZmF1bHQ6IE1l\
   ZGlhV2lraQogICAgICAgIHR5cGU6IHN0cmluZwogICAgICAgIHRpdGxlOiBNZWRpYXdpa2kgU2l0\
   ZSBOYW1lCiAgICAgICAgcGF0dGVybjogIl5bYS16QS1aXSskIgogICAgICAgIHJlcXVpcmVkOiBU\
   cnVlCiAgICAgICAgdXBkYXRhYmxlOiBUcnVlCiAgICAgIC0gbmFtZTogbWVkaWF3aWtpX3NpdGVf\
   bGFuZwogICAgICAgIGRlZmF1bHQ6IGVuCiAgICAgICAgdHlwZTogc3RyaW5nCiAgICAgICAgdGl0\
   bGU6IE1lZGlhd2lraSBTaXRlIExhbmd1YWdlCiAgICAgICAgcGF0dGVybjogIl5bYS16XXsyLDN9\
   JCIKICAgICAgICByZXF1aXJlZDogVHJ1ZQogICAgICAtIG5hbWU6IG1lZGlhd2lraV9hZG1pbl91\
   c2VyCiAgICAgICAgZGVmYXVsdDogYWRtaW4KICAgICAgICB0eXBlOiBzdHJpbmcKICAgICAgICB0\
   aXRsZTogTWVkaWF3aWtpIEFkbWluIFVzZXIgKENhbm5vdCBiZSB0aGUgc2FtZSB2YWx1ZSBhcyBB\
   ZG1pbiBVc2VyIFBhc3N3b3JkKQogICAgICAgIHJlcXVpcmVkOiBUcnVlCiAgICAgIC0gbmFtZTog\
   bWVkaWF3aWtpX2FkbWluX3Bhc3MKICAgICAgICB0eXBlOiBzdHJpbmcKICAgICAgICB0aXRsZTog\
   TWVkaWF3aWtpIEFkbWluIFVzZXIgUGFzc3dvcmQKICAgICAgICByZXF1aXJlZDogVHJ1ZQogICAg\
   ICAgIGRpc3BsYXlfdHlwZTogcGFzc3dvcmQK"

2. Populate the internal OKD registry with your built APB image.

   This is normally handled by the apb push command. In order to build your image without using the docker CLI, you can take advantage of the S2I functionality of OKD.

   By default, the OAB is configured to look for published APBs in the openshift project, which is a global namespace that exposes its images and image streams to be available to any authenticated user on the cluster. You can take advantage of this by using the oc new-app command in the openshift project to build your image:

   $ oc new-app <path_to_bundle_source> \
       --name <bundle_name> \
       -n openshift

   After a couple of minutes, you should see your image in the internal registry:

   $ oc get images | grep <bundle_name>
   sha256:b2dcb4b95e178e9b7ac73e5ee0211080c10b24260f76cfec30b89e74e8ee6742   172.30.1.1:5000/openshift/<bundle_name>@sha256:b2dcb4b95e178e9b7ac73e5ee0211080c10b24260f76cfec30b89e74e8ee6742

3. Bootstrap the OAB. This is normally also handled by the apb push or apb bootstrap command. The apb bootstrap command is preferable for this step because it will also relist the service catalog without having to wait five to ten minutes.

   If you do not have the apb tooling installed, you can alternatively perform the following:

   1. Get the route name for the broker:

      $ oc get route -n ansible-service-broker
      NAME       HOST/PORT                                                      PATH      SERVICES   PORT        TERMINATION   WILDCARD
      asb-1338   asb-1338-ansible-service-broker.172.17.0.1.nip.io              asb        port-1338   reencrypt     None

   2. Get the list of supported paths for the broker:

      $ curl -H "Authorization: Bearer $(oc whoami -t)" -k \
          https://asb-1338-ansible-service-broker.172.17.0.1.nip.io/
          {
            "paths": [
              "/apis",
              "/ansible-service-broker/", (1)
              "/healthz",
              "/healthz/ping",
              "/healthz/poststarthook/generic-apiserver-start-informers",
              "/metrics"
            ]
          }

      1	This path provides the v2/bootstrap and v2/catalog paths.

   3. Curl the v2/bootstrap path using the value found from the previous step:

      $ curl -H "Authorization: Bearer $(oc whoami -t)" -k -X POST \
          https://asb-1338-ansible-service-broker.172.17.0.1.nip.io/ansible-service-broker/v2/bootstrap (1)
      {
        "spec_count": 38,
        "image_count": 109
      }

      1	Replace ansible-service-broker if it differs from the value found in the previous step.

      The oc whoami -t command should return a token and the authenticated user must have permissions as described in Access Permissions.

1. Verify the new APB exists in the OAB. This is normally the functionality of the apb list command. If you do not have the apb tooling installed, you can alternatively perform the following:

   1. Curl the v2/catalog path using the route and supported path name gathered from the previous v2/bootstrap step:

      $ curl -H "Authorization: Bearer $(oc whoami -t)" -k \
          https://asb-1338-ansible-service-broker.172.17.0.1.nip.io/ansible-service-broker/v2/catalog

      You should see a list of all bootstrapped APB specs and one that is labeled localregistry-<bundle_name>. Use |grep <bundle_name> to help find it, since the output is in JSON.

Running APBs

Due to the limitations when working with remote clusters, you may want the same functionality as the apb run command without having to rely on the apb push command being successful. This is because apb run implicitly performs apb push first before attempting to provision the application.

In order to work around this:

1. Follow the steps described in Pushing APBs to push your image onto the internal OKD registry. After the image exists, you should be able to see it with:

   $ oc get images | grep <bundle_name>
   sha256:bfaa73a5e15bf90faec343c7d5f8cc4f952987afdbc3f11a24c54c037528d2ed   172.30.1.1:5000/openshift/<bundle_name>@sha256:bfaa73a5e15bf90faec343c7d5f8cc4f952987afdbc3f11a24c54c037528d2ed

2. To provision, use the oc run command to launch the APB:

   $ oc new-project <target_namespace>
   $ oc create serviceaccount apb
   $ oc create rolebinding apb --clusterrole=admin --serviceaccount=<target_namespace>:apb
   $ oc run <pod_name> \
         --env="POD_NAME=<pod_name>" \
         --env="POD_NAMESPACE=<target_namespace>" \
         --image=<pull_spec> \ (1)
         --restart=Never \
         --attach=true \
         --serviceaccount=apb \
         -- <action> -e namespace=<target_namespace> -e cluster=openshift

   1	Use the pull specification for the image shown when running oc get images from the previous step, since the registry will determine the fully-qualified domain name (FQDN).

Working With the Restricted SCC

When building an OKD 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 OKD-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

Using a ConfigMap Within an APB

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

Customizing Error Messages

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.