Skill Level: Beginner

Basic familiarity with git, Bluemix, and Kubernetes.

Learn how to bind a Bluemix service to your Kubernetes application using the Watson Conversation Service as an example.



  1. Install the Bluemix Container Service command line utilities

    1. Download and install the latest Bluemix CLI. (Check out the official documentation here.)
    2. Login to Bluemix using the command.
      bx login
    3. Install the Container Service plugin.
      bx plugin install container-service -r Bluemix
    4. Verify that you have the container-service plugin installed.
      bluemix plugin list
    5. Initialize the Container Service Plugin.
      bx cs init
    6. Install the latest Kubernetes command line.
  2. Create a cluster

    A Kubernetes pod refers to one or more containers. These pods run on clusters. For this example we will provision a cluster in Bluemix’s free tier.

    1. Run the following command to create your cluster. (For this recipe we chose the name Kate which will be used later on in the recipe when configuring the pipeline.)
      bx cs cluster-create --name Kate
    2. The command will return:
    3. Use bx cs clusters to see the defined clusters.

      Once the cluster reaches the deployed state you can provision pods, but they will be enqueued until the cluster’s pods are finished provisioning. Note that it takes approximately 15 minutes for the cluster to be fully provisioned and ready to accept the sample pods.

      Name    ID                                 State     Created                    Workers   
      Kate    d20f6c096ce6483ab3f65556d3db41b7   deployed  2017-03-16T17:17:39+0000   1 
    4. Use bx cs workers Kate to see the provisioned workers.
    5. Set the Kubernetes environment to work with your cluster once your cluster is deployed.
      • Run bx cs cluster-config Kate to generate your environment configuration as below:

        Downloading cluster config for Kate
        The configuration for Kate was downloaded successfully. Export environment variables to start using Kubernetes.

        export KUBECONFIG=/home/rak/.bluemix/plugins/container-service/clusters/Kate/kube-config-prod-dal10-Kate.yml

      • Set the KUBECONFIG environment variable by copying and pasting the last output line.

    Note this step creates a free cluster with a single worker. Create a Softlayer account if you want to create large, multi-worker clusters.

  3. Create a Watson Conversation Service Instance

    1. Create the Watson Conversation service.
      bx service create conversation free conversation-service-car
    2. Verify that the service instance is created.
      bx service list
    3. Obtain the ID of your cluster.
      bx cs clusters
    4. Bind the service instance to your cluster.
      bx cs cluster-service-bind <cluster-ID> default conversation-service-car
  4. Look Under the Hood

    Skip this step and come back later if you want to get the application up as quickly as possible.
    Now that you have created and bound a service instance to your cluster, lets take a deeper look at what is happening behind the scenes.

    • Binding the conversation-service-car service to your cluster creates a Kubernets secret named binding-conversation-service-car.
    • The secret contains a key named binding with its data being a JSON string of the form
    • The secret is mapped into the container as the environment variable CONVERSATION_SERVICE_CAR through the Kubernetes pod configuration.
                - name: CONVERSATION_SERVICE_CAR
                      name: binding-conversation-service-car
                      key: binding
    • The watson-conversation-simple sample expects the service credentials to be set in the environment variables CONVERSATION_USERNAME and CONVERSATION_PASSWORD.
    • We set these in the container enviroment using the run-server.sh script when the container is started. In this sample we parse them from the CONVERSATION_SERVICE_CAR environment variable using the jq utility:
      export CONVERSATION_USERNAME=$(echo "$CONVERSATION_SERVICE_CAR" | jq -r '.username')


    • You can see the defined secrets in the Kubernetes dashboard by running kubctrl proxy and accessing


  5. Train Watson

    The Watson Conversation service stores its training data in workspaces. In this step, you will import the training data provided by the watson-developer-cloud/conversation-simple sample workspace.

    1. Download the workspace definition locally.
      curl https://raw.githubusercontent.com/watson-developer-cloud/conversation-simple/master/training/car_workspace.json >/tmp/car_workspace.json
    2. In your browser, navigate to your Bluemix console.
    3. From the All Items tab, click the newly created Conversation service in the Services list.


    4. On the Service Details page, click Launch tool.


    5. Click the Import workspace icon in the Conversation service tool. Choose the file /tmp/car_workspace.json you downloaded in step 4.1.


    6. Select Everything (Intents, Entities, and Dialog) and then click Import. The car dashboard workspace is created.


    7. Go Back to workspaces using the menu at the top of the page.


    8. Choose View Details from the Car_Dashboard_Current workspace overflow menu.


    9. Copy the Workspace ID to your clipboard.


  6. Create a Kubernetes Configuration Map with the Workspace ID

    1. Create a Kubernetes configuration map.
      kubectl create configmap car-dashboard-config --from-literal=workspace_id=<WorkSpace ID from step 4.8>
    2. Verify the configuration is set.
      kubectl get configmaps car-dashboard-config -o yaml
  7. Deploy the Pod and Check Out the Watson Conversation Sample

    The pod you will deploy in this step contains the watson-developer-cloud/conversation-simple sample. The IBMCloudDevOps/watson-conversation-simple-kube repository repository contains the Dockerfile and other support files for building the image, as well as the Kubernetes configuration file.

    1. Clone the IBMCloudDevOps/watson-conversation-simple-kube repository.
      git clone https://github.com/IBMCloudDevOps/watson-conversation-simple-kube.git
    2. Change to the project directory and deploy the pod.
      cd watson-conversation-simple-kube
      kubectl create -f car-dashboard-pod.yml
    3. Identify the Public IP address of your worker.
      bx cs workers Kate
    4. Identify the external port your pod is listening on. Note: The bot-son container listens on port 3000. Kubernetes maps this a publically addressable port.
      kubectl get services bot-son
    5. Access the Watson Conversation sample using http://<IP Address>:<Port>


  8. Closing Thoughts

    The new Bluemix Container Service allows you to access an extensive services library from a scalable Kubernetes environment you can rely on. Now you know the secret too.



    Jesse Antoszyk is a Software Engineer with IBM Cloud.

    Adam King is a Senior Software Engineer with IBM Cloud.

Join The Discussion