Introduction

In the "Up and Running with the OpenShift Ansible Broker" post by Jesus Rodriguez, we saw how you can leverage the OpenShift Ansible Broker to easily provision services on OpenShift Container Platform. In this post, we're going to explore developing an Ansible Playbook Bundle (APB) to manage services.

APBs leverage the power of Ansible to allow you to define your application in the same language you would define your infrastructure. Most commonly, APBs are used to orchestrate pre-certified containers while also using Ansible to provision on and off-platform services while also allowing you to package your application management logic in a container image. With APBs you can define how to install and uninstall your application with the flexibility provided by Ansible.

This tutorial will give a user a walkthrough on developing APBs to deploy a MediaWiki and PostgreSQL service. Once provisioned, we simplify this process and focus on just the APB development. We're going to assume that MediaWiki and PostgreSQL are already containerized and can run under the restricted Security Context Constraint (SCC) in OpenShift. These container images can be found on RHCC (MediaWiki 1.23 and PostgreSQL 9.5).

Creating MediaWiki APB

To start, we will install the APB tooling. Then run:

apb init mediawiki-apb

At this point you will see the following file structure:

mediawiki-apb/

├── apb.yml

├── Dockerfile

├── playbooks

│ ├── deprovision.yml

│ └── provision.yml

└── roles

├── deprovision-mediawiki-apb

│ └── tasks

│ └── main.yml

└── provision-mediawiki-apb

└── tasks

└── main.yml

APB Spec

apb.yml is the declaration of the APB spec. In here, we will list all relevant application specific information including: OpenShift Service Catalog metadata, all of the APB's plans, and input parameters to prompt the user when provisioning. Looking at apb.yml, we are free to edit the default plan that is created by the tooling. Go ahead and edit the file to match below.

# apb.yml

version: 1.0

name: mediawiki-apb

description: This APB deploys Mediawiki123.

bindable: False

async: optional

metadata:

  displayName: Mediawiki (APB)

plans:

  - name: default

    description: This plan deploys a Mediawiki instance

    free: True

    metadata: {}

    parameters:

      - name: mediawiki_db_schema

        default: mediawiki

        type: string

        title: Mediawiki DB Schema

        required: True

      - name: mediawiki_site_name

        default: MediaWiki

        type: string

        title: Mediawiki Site Name

        required: True

      - name: mediawiki_site_lang

        default: en

        type: string

        title: Mediawiki Site Language

        required: True

      - name: mediawiki_admin_user

        default: admin

        type: string

        title: Mediawiki Admin User

        required: True

      - name: mediawiki_admin_pass

        type: string

        title: Mediawiki Admin User Password

        required: True

Note the parameters section; our MediaWiki container image will expect these parameters as environment variables to be used and configured on startup. Now that we have defined our APB's parameters, we can reference them as environment variables to be injected into the container from the deploymentConfig.

Provisioning

First, we need to edit the provision role for the APB. apb init makes this easy by leaving us commented blocks of code that we can work from.

We want three standard resources to be created by our APB: A service, a deploymentConfig, and a route. Start by opening up roles/provision-mediawiki-apb/tasks/main.yml and uncommenting the deploymentConfig resource so we can add necessary environment variables to the MediaWiki deployment. Once you're finished editing, your deploymentConfig should look like this:

- name: create deployment config

  openshift_v1_deployment_config:

    name: mediawiki

    namespace: '{{ namespace }}'

    labels:

      app: mediawiki

      service: mediawiki

    replicas: 1

    selector:

      app: mediawiki

      service: mediawiki

    spec_template_metadata_labels:

      app: mediawiki

      service: mediawiki

    containers:

    - env:

      - name: MEDIAWIKI_DB_SCHEMA

        value: "{{ mediawiki_db_schema }}"

      - name: MEDIAWIKI_SITE_NAME

        value: "{{ mediawiki_site_name }}"

      - name: MEDIAWIKI_SITE_LANG

        value: "{{ mediawiki_site_lang }}"

      - name: MEDIAWIKI_ADMIN_USER

        value: "{{ mediawiki_admin_user }}"

      - name: MEDIAWIKI_ADMIN_PASS

        value: "{{ mediawiki_admin_pass }}"

      - name: MEDIAWIKI_SITE_SERVER

      image: docker.io/ansibleplaybookbundle/mediawiki123:latest

      name: mediawiki

      ports:

      - container_port: 8080

        protocol: TCP

The only value we haven't set yet is the MEDIAWIKI_SITE_SERVER environment variable. To set this, we need to get the fully qualified route of where the application will exist on OpenShift. Let's uncomment the route and service resources that were generated and move the route before the deploymentConfig resource so we can store and use it. Your provision role should now look like this:

- name: create mediawiki service

  k8s_v1_service:

    name: mediawiki

    namespace: '{{ namespace }}'

    labels:

      app: mediawiki

      service: mediawiki

    selector:

      app: mediawiki

      service: mediawiki

    ports:

      - name: web

        port: 8080

        target_port: 8080
- name: create mediawiki route
 openshift_v1_route:
 name: mediawiki
 namespace: '{{ namespace }}'
 spec_port_target_port: web
 labels:
 app: mediawiki
 service: mediawiki
 to_name: mediawiki
 state: present
 register: route
- name: create deployment config
 openshift_v1_deployment_config:
 name: mediawiki
 namespace: '{{ namespace }}'
 labels:
 app: mediawiki
 service: mediawiki
 replicas: 1
 selector:
 app: mediawiki
 service: mediawiki
 spec_template_metadata_labels:
 app: mediawiki
 service: mediawiki
 containers:
 - env:
 - name: MEDIAWIKI_DB_SCHEMA
 value: "{{ mediawiki_db_schema }}"
 - name: MEDIAWIKI_SITE_NAME
 value: "{{ mediawiki_site_name }}"
 - name: MEDIAWIKI_SITE_LANG
 value: "{{ mediawiki_site_lang }}"
 - name: MEDIAWIKI_ADMIN_USER
 value: "{{ mediawiki_admin_user }}"
 - name: MEDIAWIKI_ADMIN_PASS
 value: "{{ mediawiki_admin_pass }}"
 - name: MEDIAWIKI_SITE_SERVER
 value: '{{ route.route.spec.host }}'
 image: docker.io/ansibleplaybookbundle/mediawiki123:latest
 name: mediawiki
 ports:
 - container_port: 8080
 protocol: TCP
 

Note that we used register when we created the route to store the output of the route creation. We then use this output as the value for the MEDIAWIKI_SITE_SERVER environment variable as {{ route.route.spec.host }}.

Deprovisioning

By default, we recommend that an APB author provide a basic deprovision role. This allows a service consumer to delete the service from the OpenShift Service Catalog and the APB's corresponding resources to be properly deleted. apb init provides a skeleton deprovision role with commented resources just like the provision role. Uncomment the service, route, and deploymentconfig resources in the deprovision task like so:

- openshift_v1_route:

    name: mediawiki

    namespace: '{{ namespace }}'

    state: absent
- k8s_v1_service:
 name: mediawiki
 namespace: '{{ namespace }}'
 state: absent
- openshift_v1_deployment_config:
 name: mediawiki
 namespace: '{{ namespace }}'
 state: absent
 

This will properly delete all created resources in the APB's namespace.

Building and Testing

Now that our APB is ready to be tested, we can build and push the image to be deployed by the OpenShift Ansible Broker. For this tutorial, I am assuming your Broker is configured to source APB's from the internal OpenShift registry (Please refer to this guide to configure the OpenShift Ansible Broker with the local_openshift registry adapter). It is also important that you are currently logged in as a user which has cluster-admin privileges. This user can not be system:admin since there is no authentication token associated with that user.

To push your image onto the OpenShift registry, type:

apb push

In versions 1.1.2 and prior, you must add the openshift flag:

apb push --openshift

This command will automatically tag and build your image and push it to the internal OpenShift Container Registry. It will then bootstrap the broker and relist the service catalog. Refreshing the webUI will display your new APB in the console. You can now deploy your application by clicking on it and filling out the respective parameters to deploy MediaWiki.

Binding to PostgreSQL

Now that we have a basic Mediawiki APB developed, we want to be able to bind it to a database. To do this, let's create a basic PostgreSQL APB. I will not rehash all of the previous steps here, but instead simply paste the APB spec and provision role.

APB Spec

version: 1.0

name: postgresql-apb

description: RHSCL PostgreSQL APB

bindable: true

async: optional

metadata:

  displayName: PostgreSQL (APB)

plans:

  - name: default

    description: A single DB server with no persistent storage

    free: true

    metadata:

      displayName: Default

    parameters:

      - name: postgresql_database

        default: admin

        type: string

        title: PostgreSQL Database Name

        required: true

      - name: postgresql_password

        type: string

        description: A random alphanumeric string if left blank

        title: PostgreSQL Password

      - name: postgresql_user

        default: admin

        title: PostgreSQL User

        type: string

        maxlength: 63

        required: true

Note how we set bindable: to true. This means that the broker will know that our application can be bound to and we will need to provide the binding credentials at the end of our provision role.

Provision Role

- name: Create postgresql service

  k8s_v1_service:

    name: postgresql

    namespace: '{{ namespace }}'

    labels:

      app: postgresql

      service: postgresql

    selector:

      app: postgresql

      service: postgresql

    ports:

    - name: port-5432

      port: 5432

      protocol: TCP

      target_port: 5432

  register: postgres_service
- name: Create postgresql deployment config
 openshift_v1_deployment_config:
 name: postgresql
 namespace: '{{ namespace }}'
 labels:
 app: postgresql
 service: postgresql
 replicas: 1
 selector:
 app: postgresql
 service: postgresql
 spec_template_metadata_labels:
 app: postgresql
 service: postgresql
 containers:
 - env:
 - name: POSTGRESQL_PASSWORD
 value: '{{ postgresql_password }}'
 - name: POSTGRESQL_USER
 value: '{{ postgresql_user }}'
 - name: POSTGRESQL_DATABASE
 value: '{{ postgresql_database }}'
 image: registry.access.redhat.com/rhscl/posgresql-95-rhel7
 name: postgresql
 ports:
 - container_port: 5432
 protocol: TCP
 termination_message_path: /dev/termination-log
 working_dir: /
 triggers:
 - type: ConfigChange
- name: Wait for postgres to come up
 wait_for:
 port: 5432
 host: "{{ postgres_service.service.spec.cluster_ip }}"
 timeout: 300
- name: encode bind credentials
 asb_encode_binding:
 fields:
 DB_TYPE: postgres
 DB_HOST: postgresql
 DB_PORT: "5432"
 DB_USER: "{{ postgresql_user }}"
 DB_PASSWORD: "{{ postgresql_password }}"
 DB_NAME: "{{ postgresql_database }}"
 

The important thing to note in the provision role is the final task asb_encode_binding. This is used on bindable applications to expose the secret fields to the broker. These variables will be injected as environment variables to the MediaWiki application container once bound. Also note that we have no need for a route in this instance, so we only create a service resource.

We will now push this image to the internal OpenShift registry:

apb push

You can now successfully bind PostgreSQL to MediaWiki in the web console.

Troubleshooting

APB not displaying in the web console

If you do not see your APB in the OpenShift web console after apb push, a good way to debug is to type:

apb list

Look at the output and check if your APB is listed. If it is, that means the OpenShift Ansible Broker knows about your APB and it is part of its list of bootstrapped APB specs. If it does not show up then try running:

apb bootstrap

If the bootstrap is successful, and you now see your APB, but you do not see it in the web console, then try typing:

apb relist

This will trigger the service catalog to get full list of bootstrapped APB specs.

Conclusion

At the end of this tutorial, you should be able to fully bind and provision the MediaWiki/PostgreSQL APBs from the web console. I hope this gives you a better understanding of building an APB from the ground up and using the APB tooling to make it easier for a developer to create and test APBs.