APB Development Tutorial – MediaWiki 1.23 + PostgreSQL 9.5

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
file/directory description
apb.yml   The APB spec declaration
Dockerfile   The APB’s Dockerfile
playbooks/provision.yml   An Ansible Playbook defining the APB’s provision action
playbooks/deprovision.yml   An Ansible Playbook defining the APB’s deprovision action
roles/provision-mediawiki-apb   An Ansible Role defining which tasks are run on provision
roles/deprovision-mediawiki-apb   An Ansible Role defining which tasks are run on deprovision

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.

Categories
Containers, Kubernetes, OpenShift Container Platform, OpenShift Origin, Service Catalog
Tags
, , ,