You may have heard about Kubernetes and Docker already and want to know if there’s a pipeline available for developers working on microservices.

Microservice Builder makes the deployment stage much easier once set up for those who aren’t yet Kubernetes wizards by providing a pipeline that enables developers to quickly become productive: focusing on writing great application code rather than setting up “DevOps” pipelines for Kubernetes themselves.

In this blog post I’ll be covering how to do exactly that for Node.js deployments specifically, although this should work with any containerized application as well.

Note that as of March 2018, you should instead be using Microclimate which has superseded Microservice Builder. After deploying Microclimate, you’ll want to either create a new Node.js project using the UI we provide (as part of the “portal”), or import your existing project. The pipeline will be set up (as demonstrated below) and you’ll still need a Jenkinsfile. 

We’ve made it easy at IBM to use Microservice Builder when deploying to IBM Cloud Private, but you can take advantage of this tutorial whether you’re deploying to IBM Cloud Private or another Kubernetes target.

You’ll have the following in place by the end of this guide:

1. A Jenkins pipeline that will build and deploy your application to the Kubernetes cluster it’s running on:

Pipeline all green

2. Working Node.js code that satisfies the criteria to be deployed using Microservice Builder – has a Jenkinsfile with content such as:


@Library('MicroserviceBuilder') _
microserviceBuilderPipeline {
 image = 'ibm-nodejs-sample'


3. A Git repository that’s being watched for changes by Microservice Builder:

Watching the repository

 The pipeline in action


This covers committing to a watched Git repository, triggering the Jenkins pipeline, and the change making its way into our cluster as a Node.js application deployment.

What we’ll need

  • A Linux or macOS environment is recommended.
  • A browser – we’ll be using Google Chrome.
  • kubectl (details below).
  • jq (details below).
  • A Kubernetes cluster (e.g. IBM Cloud Private). Minikube should also work too, as should IBM Cloud Private with Vagrant.
    • For IBM Cloud Private, head to the IBM Cloud Private Welcome Page and proceed until you’ve got a cluster set up on your machine(s) – you’ll only need one node and you can follow the install instructions. You’ll know you’re ready when you see the following:
  • Familiarity with Git is recommended.
  • Code to deploy! You’ll want a Dockerfile, a Helm chart or an application definition Kubernetes can understand, and a listen server.
  • If you don’t want to use IBM Cloud Private, you should be able to use all of the features here on Bluemix or a local Minikube deployment, so long as you can configure and access the Helm charts for Microservice Builder.

TL;DR version?

  • Push a containerized app’s code up to a Git repository that’s in a Git organization that Microservice Builder will watch – you’ll need a Jenkinsfile in this repository.
  • Install Microservice Builder into your Kubernetes cluster using the app center.
  • Access the pipeline at port 31000, click “Scan organization now” (or set up web hooks), “Scan repository now”, and watch as the pipeline kicks off and is all green.
  • It’s built and deployed: visit your application’s frontend in the web browser on the Kubernetes cluster.
  • Every subsequent Git commit to a configurable deployment branch will be automatically used to build and deploy your app to the cluster.

Why Microservice Builder?

  • Provides a Jenkins/Docker/Git/Kubernetes based pipeline for continuous delivery.
  • Developers can focus on writing microservices as opposed to learning Kubernetes intricacies: write more Node.js code.
  • Lowers the bar of entry for developers to deploy using Kubernetes.

Grabbing some code

We can obtain sample code to deploy in a number of straightforward ways and the critical files for a project to be deployable with Microservice Builder are as follows:

  • Jenkinsfile: for the Microservice Builder pipeline to work (also where configurations can be made).
  • Dockerfile: our application needs to be a “containerized” one.
  • The Helm chart (chart.yaml, values.yaml, templates/deployment.yaml and templates/service.yaml).

Example 1: use an existing project

You can use the IBM Cloud Private Node.js sample code: clone it to your laptop or don’t do anything for now as we can fork it into a configured Git organization later.

Example 2: yo nodeserver

Yeoman generator (entirely Node.js). Best used in combination with straight Helm and kubectl.

npm install -g generator-nodeserver
yo nodeserver

Example 3: bx dev (“idt”) create

Written in Go and not guaranteed to work on all platforms that Node.js does. More advanced and covers more use cases, such as deploying.

export DESIRED_VERSION=v2.4.1
curl -sL | bash

You’ll want to set the DESIRED_VERSION (for Helm) to match the version of Helm running on the server. As with yo nodeserver there are prompts for us to follow so we can create a Node.js application.

Setting up the org and repository for Microservice Builder to watch

Follow the instructions for setting up the Git organization and repository until you have the following:

  • A OAuth Application token, mine’s a secret.
  • A Github Application ID (aka a “Client ID”), mine is 1d21508da85ce1ded76d.
  • A Github Application secret (aka a “Client Secret”), mine’s a secret.
  • A Github org, mine is called adam-msb-blog-tester.
  • A Github repository with our code to deploy, mine is called watch-this-repo.

I recommend adding the contents into a text file you’ll also be keeping safe as we’ll be providing these values as parameters for the next important step.

Pushing your code up to a repository

The easiest thing to do here is to fork the sample I mentioned into your organization.

Forking the sample into watched org

Or set up a repository locally, put your yo nodeserver or idt create provided code in here and then push it up to your repository and organization.

In the folder where your code is, you’d need to initialize the repository, add the remote, then commit and push your code up, for example (and this is exactly as we’re given when creating a Git repository using the web UI):

git init
git commit -m "first commit"
git remote add origin
git push -u origin master

You can go ahead and fork or push your code up to the repository that’s in the organization that Microservice Builder is watching.

Installing the Microservice Builder pipeline

With your Git repository and org set up, we’ll configure the Microservice Builder pipeline next.

It’s a lot quicker to set up than the Git org and repository – Microservice Builder is available in the app center for IBM Cloud Private.

Access the catalog:

IBM Cloud Private catalog

Then search for “microservice” and you’ll see the following two installs are available:

It’s the “ibm-microservicebuilder-pipeline” chart we’ll be using in this tutorial and we’ll be needing the details from the Github application we’ve created.

Click anywhere on the tile to be taken to the documentation for the Helm chart.

At the bottom right you’ll see a big blue “Configure” button – so click that and we can proceed to fill in the details using our Github information.

MSB pipeline form

There’s lots we can configure but we should only care about the following values for now. These are all under the first section titled “Github”:

  • URL: or your GHE URL
  • RepoPattern: repositories with a name matching this pattern will be checked, built and deployed by Microservice Builder. Change this to “.*” (that’s “dot asterisk”) to build anything pushed up to a repository in the organization.
  • Orgs: the name of the organization to watch.
  • OAuth.User: the name of the user that we created an OAuth token for.
  • OAuth.Token: this is the personal access token you definitely made a copy of earlier! From the application details we recorded earlier.
  • App.Id: also known as the client ID. From the application details we recorded earlier.
  • App.Secret: also known as the client secret. From the application details we recorded earlier.
  • Admins: this can be the same value as the OAuth.User.

In this example the values are as follows.

Pipeline deploy with no secrets

Make sure you fill in the app secret and the OAuth token values as well.

Click “Install” and you should get a success prompt – if all went well we’re ready to access the pipeline that’s been configured to watch our repository!

The pipeline's installed

We can then visit the pipeline in our web browser. It’ll be at the master or proxy URL and, by default, port 31000 ( in this example, where is where I can view the IBM Cloud Private dashboard).

We’ll need to authorize the application when prompted, and then we’ll see the main Jenkins page once it’s started up.

It's Jenkins

Here’s the organization that’s picked up with Microservice Builder:
Watched organization
This is how an empty repository without a Jenkinsfile would look:

Scan this org next

Not so fast – we need to enable our Microservice Builder pipeline to pull from the private registry next.

This is also covered at the pipeline documentation for Microservice Builder and involves adding the admin.registrykey secret.

By using the pipeline you’ll be pushing your application as a Docker image to the IBM Cloud Private Docker registry – the secret is used to authenticate with it so that problems don’t occur when pulling the image to be run on pods.Back to building and deploying.

You know you’re ready to go when there are no problems with the Jenkins slave pods when you do:

kubectl get pods

Our first build and deploy!

From the Jenkins interface, we want to scan the organization now and our repository will be picked up.

If you’re having trouble at this stage, configure the job and take a look at the “repository pattern” that this job will be watching.

If you’ve followed the above steps correctly, you’ll see your application has been built and deployed successfully!

Green for successful stages, Red for ones that failed – and you can cancel the pipeline at any time as I did the first time around.

Deploy with MSB complete

Viewing your deployment

At the end of the console log for the build (in this case #2), we can see:

Release "ibm-nodejs-sample" does not exist. Installing it now.
NAME:   ibm-nodejs-sample
LAST DEPLOYED: Thu Oct 26 18:42:44 2017
NAMESPACE: default

==> v1beta1/Deployment
ibm-nodejs-sample-ibm-no  1        1        1           0          2s

==> v1/Service
NAME                      CLUSTER-IP  EXTERNAL-IP  PORT(S)         AGE
ibm-nodejs-sample-ibm-no  <nodes>      3000:30952/TCP  2s

The Node.js sample can be viewed in the web browser.

export SAMPLE_NODE_PORT=$(kubectl get --namespace default -o jsonpath="{.spec.ports[0].nodePort}" services ibm-nodejs-sample-ibm-no)
export SAMPLE_NODE_IP=$(kubectl get nodes --namespace default -o jsonpath="{.items[0].status.addresses[0].address}")

echo "Open your web browser at http://${SAMPLE_NODE_IP}:${SAMPLE_NODE_PORT}"


These are the notes for the sample itself (provided in the Helm chart). Any Helm install will have the “RESOURCES:” information for you to use.

Accessing your deployment

  • With IBM Cloud Private you can use the menu to navigate for “Workloads” then “Services“, find the service for what you’ve just deployed and then click on the HTTP endpoint button.

Sample and node port

  • You can also determine the endpoint from an optional notes.txt file in the Helm chart (like with the IBM Cloud Private Node.js sample).
  • You can also determine the endpoint from the output of the “helm upgrade” command in the Jenkins job. The IP address and NodePort values are what you’ll need.

How to continue using Microservice Builder once it’s set up?

  • Nobody needs to do the above again! It’s all configured for developers to use.
  • Subsequent commits will be built and deployed for you. You can set up web hooks as well so the application’s automatically deployed.
  • Developers push code up to to the repository that’s being watched: by default what’s pushed to “master” will be deployed (this is configurable in the pipeline).
  • Developers can kick off a manual build/deploy by navigating to the Jenkins instance in their browser.


  • This example makes use of the fact that the pipeline  looks for a Dockerfile and will build and deploy that.
  • The presence of the Jenkinsfile allows the Jenkins job to recognise this as being something that can be built and deployed.
  • Getting set up is a pain – many steps for a user to follow. Once set up, it’s easy for developers to use – making code changes, pushing it up, having the changeset be deployed.
  • You can customise the pipeline by setting up deployment branches and modifying the pipeline itself – you can change the pipeline definition and kill the pod for it to return with the changes taking effect.

Where to go from here

Join The Discussion

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