How to Use OpenWhisk Docker Actions on IBM Bluemix

Microservices are being widely adopted for the development of today’s apps. The OpenWhisk platform embraces this approach, providing out-of-the-box-functionality to support JavaScript and Swift. However, if you want to use OpenWhisk for non-JavaScript / non-Swift projects or need additional libraries to implement your app’s events, working with Docker actions seems to be a reasonable choice.

From this tutorial, learn how to create an OpenWhisk Docker action and deploy it to IBM Bluemix OpenWhisk.

Prerequisites

To follow this guide, you need:

• IBM Bluemix account with OpenWhisk activated
• Local Docker installation
• Docker Hub account

In the guide, janesmith is used as the Docker Hub login and janes_password as the Docker Hub password.

Setting up the OpenWhisk CLI

First, install the OpenWhisk CLI from pip or your system package manager if it has any.

For your credentials and installation instructions, sign in to the Bluemix console and see this page.

If you are also working with OpenWhisk locally, remember to set the remote apihost property for the Bluemix service: openwhisk.ng.bluemix.net.

Preparing a Docker image

To create a new OpenWhisk Docker action, run:

$ wsk sdk install docker

Make sure that you use the Bluemix service because a local installation won’t work. The template project will be located in the dockerSkeleton folder. It consists of two parts:

• A Node.js HTTP server handling interaction with the OpenWhisk service is in the server folder.
• A C program for producing the response is in the client directory.

You can use the provided Node.js server with necessary tuning if required and place all business logic in an external program or rewrite the whole thing using the language of your choice. You can find more “Hello, World!” actions featuring different languages at my GitHub account.

Your Docker image has to start a HTTP server handling two requests:

• POST /init. The endpoint is called after the container is started and serves the purpose of initializing the action. It is relevant only for language-specific actions where it is used to specify the code to be executed. For Docker actions, you should be OK just always responding with 200.
• POST /run. The endpoint is called on action invocation. Parameters are provided in the JSON body under the value key.

The generated Docker skeleton automatically handles HTTP interaction for you. In the run action, it calls an external program, specifying the payload parameter value as the only argument, and responds with content written in stdout by the program. If the programming language of your choice does not have a lightweight, easy-to-use HTTP server implementation, it makes sense to use the Node.js server from the skeleton app with appropriate modifications if needed.

After you finish preparing your Docker image, build it with this command:

$ docker build -t janesmith/IMAGE_NAME .

Then, you can test your application by running a Docker container in one terminal session with docker run janesmith/IMAGE_NAME and checking it with curl in another with:

$ curl -H "Content-Type: application/json" -d '{"value":{"YOUR":"PAYLOAD"}}' DOCKER_HOST:8080/run

Deploying a Docker image

Now, you have a Docker image that is ready for uploading. To do so, follow these steps:

1. Log in with your Docker Hub credentials:

   $ docker login -u janesmith -p janes_password

2. Upload the image to Docker Hub with:

   $ docker push janesmith/IMAGE_NAME

   where IMAGE_NAME is the name of the repository you want to upload your image to.

   You might find useful the buildAndPush.sh script that builds the container in the current directory and pushes it to Docker Hub. Usage:

   $ ./buildAndPush.sh janesmith/IMAGE_NAME

3. Deploy the image to OpenWhisk with:

   $ wsk action update --docker ACTION janesmith/IMAGE_NAME

   where ACTION is the name of the OpenWhisk action that uses the Docker image.

When the Docker image is uploaded to the OpenWhisk server, you can test your action with this command:

$ wsk action invoke -b -r -p PARAM_NAME PARAM_VALUE ACTION

where:

• PARAM_NAME is the name of the parameter, and PARAM_VALUE is its value.
• -b makes the invocation blocking, so the result is displayed in the console.
• -r skips the unnecessary details and shows only the invocation result.
• -p specifies the parameters to pass to the action.

(You can have several -p parameters or none at all.)

More on OpenWhisk? Read this:

• Introduction to IBM Bluemix OpenWhisk
• IBM Bluemix OpenWhisk 101: Developing a Microservice