Rocket.Chat Ansible Playbook Bundle Development & Deployment Tutorial

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 walk-through on developing an APB to deploy the Rocket.Chat service. To simplify this process and focus on just the APB development, we’re going to assume that Rocket.Chat and MongoDB are already containerized and can run under the restricted Security Context Constraint (SCC) in OpenShift. These container images can be found on RHCC (RocketChat and MongoDB).

If you’re only interested in deploying the published RocketChat APB you can skip to the end of this tutorial.

Creating RocketChat APB

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

apb init rocketchat-apb

At this point you will see the following file structure:

rocketchat-apb/
├── apb.yml
├── Dockerfile
├── playbooks
│   ├── deprovision.yml
│   └── provision.yml
└── roles
    ├── deprovision-rocketchat-apb
    │   └── tasks
    │       └── main.yml
    └── provision-rocketchat-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-rocketchat-apb An Ansible Role defining which tasks are run on provision
roles/deprovision-rocketchat-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.

version: 1.0
name: rocketchat-apb
description: This APB deploys RocketChat backed by MongoDB
bindable: False
async: optional
metadata: 
  documentationUrl: https://rocket.chat
  imageUrl: https://github.com/RocketChat/Rocket.Chat.Artwork/blob/master/Logos/rocketcat.png?raw=true
  dependencies: ['registry.connect.redhat.com/rocketchat/rocketchat:latest', 'registry.access.redhat.com/rhscl/mongodb-32-rhel7']
  displayName: RocketChat (APB)
  longDescription: An APB that deploys RocketChat to OpenShift backed by MongoDB
plans:
  - name: default
    description: This plan deploys a single RocketChat application backed by MongoDB
    free: True
    metadata:
      displayName: Default
      longDescription: This plan provides a RocketChat application backed by MongoDB
      cost: $0.00
    parameters: 
      - name: mongodb_user
        default: rocketchat
        type: string
        title: MongoDB Username
        required: True
      - name: mongodb_pass
        default: changeme
        type: string
        title: MongoDB Password
        required: True
      - name: mongodb_name
        default: rocketchat
        type: string
        title: MongoDB Database Name
        required: True
      - name: mongodb_admin_pass
        default: changeme
        type: string
        title: MongoDB Admin Password
        required: True

For information on configuring metadata for your application, see here.

Note the parameters section; our Rocket.Chat 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-rocketchat-apb/tasks/main.yml and uncommenting the deploymentConfig resource so necessary information for attaching a persistentVolume to the Rocket.Chat deployment. Once you’re finished editing, your deploymentConfig should look like this:

- name: create deployment config
  openshift_v1_deployment_config:
    name: rocketchat
    namespace: '{{ namespace }}'
    labels:
      app: rocketchat
      service: rocketchat
    replicas: 1
    selector:
      app: rocketchat
      service: rocketchat
    spec_template_metadata_labels:
      app: rocketchat
      service: rocketchat
    containers:
    - env:
      - name: ROOT_URL
      - name: MONGO_URL
        value: "mongodb://0.0.0.0:27017/{{ mongodb_name }}"
      image: registry.connect.redhat.com/rocketchat/rocketchat
      name: rocketchat
      ports:
      - container_port: 3000
        name: rocketchat-3000
        protocol: TCP
    - env:
      - name: MONGODB_USER
        value: "{{ mongodb_user }}"
      - name: MONGODB_PASSWORD
        value: "{{ mongodb_pass }}"
      - name: MONGODB_DATABASE
        value: "{{ mongodb_name }}"
      - name: MONGODB_ADMIN_PASSWORD
        value: "{{ mongodb_admin_pass }}"
      image: registry.access.redhat.com/rhscl/mongodb-32-rhel7
      volume_mounts:
      - mount_path: /data/db
        name: mongo-storage
      name: db
      ports:
      - container_port: 27017
        protocol: TCP
        name: mongo-27017
    volumes:
    - name: mongo-storage
      persistent_volume_claim:
        claim_name: mongo-storage

In the deploymentConfig, you’ll see the environment variables expected by Rocket.Chat have been set to the parameter fields defined in apb.yml. We also added a persistentVolumeClaim to the deploymentConfig named mongo-storage. This means we will need to create a persistentVolumeClaim resource as well.

The only value we haven’t set yet is the ROOT_URL 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 rocketchat route
  openshift_v1_route:
    name: rocketchat
    namespace: '{{ namespace }}'
    spec_port_target_port: rocketchat-3000
    labels:
      app: rocketchat
      service: rocketchat
    to_name: rocketchat
  register: route

- name: create persistent volume claim for mongo
  k8s_v1_persistent_volume_claim:
    name: mongo-storage
    namespace: '{{ namespace }}'
    state: present
    access_modes:
      - ReadWriteOnce
    resources_requests:
      storage: 1Gi

- name: create deployment config
  openshift_v1_deployment_config:
    name: rocketchat
    namespace: '{{ namespace }}'
    labels:
      app: rocketchat
      service: rocketchat
    replicas: 1
    selector:
      app: rocketchat
      service: rocketchat
    spec_template_metadata_labels:
      app: rocketchat
      service: rocketchat
    containers:
    - env:
      - name: ROOT_URL
        value: "{{ route.route.spec.host }}"
      - name: MONGO_URL
        value: "mongodb://0.0.0.0:27017/{{ mongodb_name }}"
      image: registry.connect.redhat.com/rocketchat/rocketchat
      name: rocketchat
      ports:
      - container_port: 3000
        name: rocketchat-3000
        protocol: TCP
    - env:
      - name: MONGODB_USER
        value: "{{ mongodb_user }}"
      - name: MONGODB_PASSWORD
        value: "{{ mongodb_pass }}"
      - name: MONGODB_DATABASE
        value: "{{ mongodb_name }}"
      - name: MONGODB_ADMIN_PASSWORD
        value: "{{ mongodb_admin_pass }}"
      image: registry.access.redhat.com/rhscl/mongodb-32-rhel7
      volume_mounts:
      - mount_path: /data/db
        name: mongo-storage
      name: db
      ports:
      - container_port: 27017
        protocol: TCP
        name: mongo-27017
    volumes:
    - name: mongo-storage
      persistent_volume_claim:
        claim_name: mongo-storage

- name: create rocketchat service
  k8s_v1_service:
    name: rocketchat
    namespace: '{{ namespace }}'
    labels:
      app: rocketchat
      service: rocketchat
    selector:
      app: rocketchat
      service: rocketchat
    ports:
      - name: rocketchat-3000
        port: 3000
        target_port: 3000

- name: create mongo service
  k8s_v1_service:
    name: db
    namespace: '{{ namespace }}'
    labels:
      app: rocketchat
      service: db
    selector:
      app: rocketchat
      service: db
    ports:
      - name: mongo-27017
        port: 27017
        target_port: 27017

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 ROOT_URL environment variable as {{ route.route.spec.host }}. We also created two individual service declarations for Mongo and RocketChat for each container in the pod.

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: rocketchat
    namespace: '{{ namespace }}'
    state: absent

- k8s_v1_service:
    name: rocketchat
    namespace: '{{ namespace }}'
    state: absent

  k8s_v1_persistent_volume_claim:
    name: mongo-storage
    namespace: '{{ namespace }}'
    state: absent

- openshift_v1_deployment_config:
    name: rocketchat
    namespace: '{{ namespace }}'
    state: absent

This will remove 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 APBs 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 into 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, push it to the internal OpenShift registry, bootstrap the Broker, and relist the Service Catalog. Refreshing the Service Catalog will display your new APB in the console. You can now deploy your service by clicking on it and filling out the respective parameters to deploy Rocket.Chat.

Troubleshooting

APB Not Displaying in the Service Catalog

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

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

apb bootstrap

If the bootstrap is successful and you now see your APB but don’t see it in the Service Catalog then try:

apb relist

This will trigger the Service Catalog to get the full list of bootstrapped APB specs.

Configuring OpenShift Ansible Broker to deploy RocketChat APB from RHCC

In order to use images published by ISVs (in this instance rocketchat-apb), we need to append the OpenShift Ansible Broker’s registry configuration with the openshift registry adapter pointing to registry.connect.redhat.com. To do this, please make sure that your OpenShift Ansible Broker’s configuration has the following:

registry:
  - name: isv-registry
    type: openshift
    user: <RH_user>
    pass: <RH_pass>
    url: http://registry.connect.redhat.com
    images:
      - rocketchat/rocketchat-apb
    white_list:
      - ".*-apb$"

<RH_user> and <RH_pass> should be replaced with your credentials to authenticate against RHCC. The important thing to note is the images portion of the config. We have to manually define the images that we want to see from the ISV registry. In this case, we’re adding rocketchat/rocketchat-apb.

If you already have an OpenShift cluster up, you can access the OpenShift Ansible Broker’s configuration by typing (in the broker’s namespace):

oc edit configmap broker-config

Saving your changes should deploy a newer pod for the Broker. Once the pod is ready, you can type:

apb relist

You should now be able to see and deploy the RocketChat APB from the OpenShift Service Catalog.

Conclusion

I hope this helps developers see how easy it is to take complex applications and deploy them using APBs. This tutorial showed you how to create a RocketChat APB from scratch using Red Hat signed images and also showed you how to configure the OpenShift Ansible Broker to deploy the Red Hat signed RocketChat APB from the Red Hat Container Catalog.

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