Accessing Bluemix Services In Containers

Share: Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditEmail this to someonePrint this page

bluemixDocker

Bluemix has recently added support for docker containers. The new container service allows us to create containers from the huge library of preconfigured Docker images, known as Docker Hub. These containers are lightweight fast, and highly versatile. One of the first questions developers ask when they start working with containers, is how can I bind services from the bluemix catalog to my container? Currently Bluemix supports binding applications to containers. Binding an app container will take the chosen app’s VCAP_SERVICES environment variable and append it to the container’s environment variables. The VCAP_SERVICES variable is a JSON string containing all the information and credentials for the services and apis bound to an application. This appending process allows the container to parse this data and access all the services bound to the app.

Parsing JSON with Bash

Once an app is bound to a container the container has access to the service connection data in JSON format. We just need to parse it. Many existing Docker images use environment variables to link to external services like databases. A great example of this is the Docker official WordPress image. The WordPress image reads in a specific set of environment variable for establishing a connection to a MySQL DB. TheWordPress image has no idea what VCAP_SERVICES are, so we need to find a clean way to parse the VCAP_SERVICE JSON and export credentials as env variables that WordPress can understand.  If your container has a scripting language like node, or python you could write up scripts using pre-existing JSON parsing libraries and export the parsed data. However, we want a solution that can run on even the most lightweight images, with little to no dependencies. This way we can reuse this model on every image. For this reason we will do it all using Bash commands and shell scripts. JSON parsing with Bash is not easy so we use a script called JSON.sh, this script takes a JSON string and flattens it out into a format that is much easier to parse using grep.

Here is an example of what JSON.sh can do:

Given the following VCAP_SERVICES

We can pipe $VCAP_SERVICES into JSON.sh like this (the -b flag only shows leaf nodes):

With the JSON in this format pulling out the desired data is easy with a grep command. Lets say we want the clearDB name we grep like this:

Next we use sed to remove the JSON.sh header:

Finally just need to get rid of those quotes using tr:

To make this entire process much simpler I wrote a small script (vcap_parse.sh) that takes in the ‘path’ to the desired variable as input and outputs the variable’s value. You can checkout the code here.

Notice the notation for how we reached this value at cleardb[0].credentials.name using

Export the parsed data

Using this script and your knowledge of the VCAP_SERVICES structure you can quickly parse for your desired variables. Now all that’s left is to export them as environment variables so that the Docker image can see and use them.
In theWordPress example we need to export the following values:

  • WORDPRESS_DB_HOST
  • WORDPRESS_DB_USER
  • WORDPRESS_DB_PASSWORD
  • WORDPRESS_DB_NAME

We have all the necessary values in the VCAP_SERVICES JSON from earlier, and with the vcap_parse.sh script, exporting will be trivial. Exporting the database credentials in the WordPress example happens in a script called vcap_export.sh. vcap_export.sh calls vcap_parse.sh four times and exports the each result as an environment variable specified by the wordpress image. If you were trying to set the connection for something like a drupal container you would modify the export names to be the names specified in the drupal image docs.

Here are the contents of vcap_export.sh:

(Note: The Host line is appended with :3306 as required by the WordPress image)

I will explain more about what the last two lines of vcap_export.sh do at the end of the next section. For now just know that all the Variables are set and WordPress can communicate with the clearDB instance. (if you would like to use a mySQL db other than clearDB you will need to modify vcap_export.sh to parse out the correct credentials, this example uses variables specific to clearDB.)

Bringing it all together

We now know how to parse and export, all that’s left is to add this workflow into our image’s Dockerfile so that the services are parsed and exported before our image starts up. Instead of forking and modifying the existing base image we can use the Dockerfile FROM command to add this parsing and exportation process as a layer on top of the original unaltered WordPress image.

Here is the Dockerfile I created for the WordPress example:

Let’s break this down. The FROM command tells the build process that we will start with the wordpress:latest image and add on from there. The next line downloads the JSON.sh script from github and saves it to /usr/local/bin/JSON.sh using the ADD command. JSON.sh needs a chmod u+x to get executed, so that is what the next line is doing. The next two lines copy the vcap_parse.sh script and save it to the container root, followed by another chmod u+x. The next two lines do the exact same thing but for the vcap_export.sh script.

The last line overrides the ENTRYPOINT set by the WordPress image to use /vcap_export.sh as the new ENTRYPOINT. we must do this so that the db credential exportation happens before WordPress starts. We will eventually have to call the entrypoint we overrode. this is done by calling it at the end of vcap_export.sh. That is what these lines were doing:

This is not necessary for every image but you will most likely have to replace an endpoint for most images. Now the WordPress image will run as if nothing changed and will be able to get connection data from the environment variables that came from binding an app to your container. Just remember to always call entry points you override, they can be found at the end of your base image.

Summary of the steps

  1. Create Dockerfile with a FROM <desired image name>
  2. ADD the JSON.sh script and RUN chmod u+x on it
  3. COPY the vcap_parse.sh and vcap_export.sh to root and RUN chmod u+x on both
  4. Override the <Desired image name> ENTRYPOINT to call vcap_export.sh.
  5. Follow the pattern in vcap_export.sh to export the variables that the image requires.
  6. Be sure to call the ENTRYPOINT you overrode and the commands after it.

Once you have everything configured using this model you can build the image, tag it, push it to your bluemix registry and deploy it from bluemix. Make sure you bind an app that has the services your container image requires, otherwise the export will fail.

Remember that we used an example for connecting clearDB to WordPress, but this technique can be modified and used to bind any Bluemix Service (not just DB’s) to any Docker image that reads in variables through environment variables.

All the code used in this image can be found Here, and the example WordPress image is hosted on dockerhub Here

 

If you would like to try out the modified WordPress image follow the WordPress on Bluemix Containers Tutorial HERE

Share: Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditEmail this to someonePrint this page
Miguel Clement

Miguel Clement

Miguel is a Computer Science Senior at Texas A&M Univeristy. He joined the jStart Emerging Technology Team in January 2015 and has been exploring the cutting edge ever since.
Miguel Clement
Miguel Clement

7 comments

Leave a Reply

Your email address will not be published. Required fields are marked *