Think 2021: New tools have the developer ecosystem and IBM building together Learn more

Use UrbanCode to deploy microservices on IBM Cloud

IBM UrbanCode Deploy is a tool that helps you automate application deployments throughout your cloud environments. It is designed to make rapid feedback and continuous delivery in agile development relatively easy while providing the audit trails, versioning, and approval paths you need in a production-level system.

UrbanCode Deploy provides:

  • Automated, consistent deployments and rollbacks of applications
  • Automated provisioning, updating, and de-provisioning of cloud environments
  • Orchestration of changes across servers, tiers, and components
  • Configuration and security differences across environments
  • Clear visibility as to what is being deployed where and who has changed what components
  • Integration with middleware, provisioning, and service virtualization

In this tutorial, I’ll explain the build-and-deploy toolchain of microservices, starting with the standard tools you need:

  • JIRA to create and assign tasks, report bugs, and manage releases
  • GitLab to manage source code
  • Jenkins to build the orchestrator
  • UrbanCode Deploy, the deployment tool

I will be focusing primarily on UrbanCode Deploy.

Let’s start by examining a typical microservices architecture.

The architecture and pipeline

Typically, a microservices architecture is one in which multiple microservices each perform a single unit of work, while a web component consumes all the data provided by these microservices and shows it to the user. Each microservice will have its own build pipeline to build and deploy to the development environment automatically.

Let’s look at this in a bit more detail.

The microservices architecture

In this scenario, one common database and cache service hold the common data across the various microservices.

Figure 1. A typical microservices architecture
A typical microservices architecture

My goal in this article is to describe how you can configure UrbanCode Deploy to deploy these microservices to hybrid cloud environments.

Since each microservice will have its own build pipeline, let’s look at that next.

Build-and-deploy pipeline

Based on the branching strategy, the code gets deployed to the target environment. I will be doing this using a GitLab repository where webhooks are configured to automatically trigger a build in Jenkins.

The Jenkins job is configured to build a Java™ or Node application, perform code quality using SonarQube (the open-source platform for continuous inspection of code quality), and store the artifacts in IBM UrbanCode Deploy.

The version of the artifact generated is tagged with the Jenkins build number to have traceability with the Jenkins build that created the artifact. This version number will be useful in creating the snapshots in UrbanCode Deploy.

Next, I’ll demonstrate how to configure Jenkins for auto-build.

Configure Jenkins for auto-build

Running builds as soon as code is pushed can be important because it enables you to detect problems quickly and locate them more easily. To automatically run builds, Jenkins listens for POST requests at a Hook URL.

In Jenkins, you enable the option to build when a change is pushed to the GitLab repository as shown:

Figure 2. Build Triggers
Build Trigger

Copy the GitLab CI Service URL, go to the corresponding GitLab Project, click Settings > Webhooks, and paste the URL into the field. Click Add Webhook and test it, as shown:

Figure 3. GitLab configuration
GitLab configuration

Configure the GitLab system to build when code is pushed to a certain branch. Add the same filter in Jenkins.

Configure UrbanCode Deploy

In this section, I will show you how to create a deployment pattern, which involves:

  • Defining the component template
  • Creating a component, application, environment, and environment-specific variables
  • Generating a manifest file
  • Defining the application process

All the microservices in this example have the same build-and-deploy process. This helps when you want to create build-and-deploy pipelines automatically when a new microservice is created. From a deployment perspective, this is achieved by creating a component template that will be used by all of the microservices deployed to IBM Cloud.

Define the component template

Let’s create a component template for IBM Cloud deployment called “IBM CloudDeployTemplate”:

Figure 4. UrbanCode Deploy components
UrbanCode Deploy components

Whenever a new microservice deployment is needed, a component is created using this template. The template will have the following four processes defined:

  • IBM CloudPush deploys the application to the cloud
  • ApplicationStart starts an IBM Cloud application
  • ApplicationStop stops the application
  • ApplicationDelete deletes the application

You’ll need to define the following environmental variables for the component. Follow these steps to create them:

  1. Under the Configuration tab, click Environment Property Definition.
  2. Click Add Property as shown in Figure 5 and define the environment variable.
  3. Provide the Name, Label, and Default value (if any) for the environment variable and click Save.

    Figure 5. Defining the environment variable
    Defining the environment variable

Create the following set of environment variables which will be used in the process execution:

  • CF_API—the Cloud Foundry API to connect to
  • CF_ORG—the IBM Cloud organization where the deployment should happen
  • CF_SPACE—the IBM Cloud space where the deployment should happen
  • CF_USER—the user ID through which the deployment should happen
  • CF_DOMAIN—the IBM Cloud domain where the deployment should happen
  • ENV—the environment name where the deployment should happen

All these variables should be defined as the component environment variable.

You’ll also need to define the following component-specific variables (as shown in Figure 6):

  • MEMORY—the memory needed by the component
  • INSTANCE—the number of instances

Component-specific variables are restricted to a component and will remain same across environments. To create a component variable:

  1. Click the Configuration tab and select the Properties link.
  2. Click Add Property like you did in the earlier step.
  3. Save the property definition.

    Figure 6. Component property
    Component property

The sample process for deploying a typical Liberty application with Slack integration is shown in Figure 7. You can see that application artifacts are downloaded, custom server.xml is generated, and the application is pushed to IBM Cloud. The Slack channel is notified of the success or failure of the process. You can use the following steps as a reference, but the deployment steps for each of the microservices may vary based on your architecture and customization.

Figure 7. UrbanCode Deploy component process
UrbanCode Deploy component process

Create components

For each microservice, you’ll create a separate component in UrbanCode Deploy and during creation, you’ll select the component template that you created earlier.

Figure 8. Create component
Create component

Each component may default to the component template property values. Sometimes you may need to override these values at the component level—for example, if the template has the memory allocation of the application set to 1GB and one of your microservices needs 4GB. In that case, you can override the template value at the UrbanCode Deploy component level to 4GB.

Create an application

Once the components are created, you need to create an application that will contain multiple hybrid components with different deployment models. To create an application in UrbanCode Deploy:

  1. Click the Application tab.
  2. Click Create Application and a pop-up window will appear.
  3. Fill in the application Name, Teams, and Notification Scheme (if defined).
  4. Click Save after filling in those details.

    Figure 9. Create an application
    Create an application

Once you’ve created the application, start adding components as follows:

  1. Go to the Components tab within the application.
  2. Click Add Component and a pop-up window will appear.
  3. Start searching for existing components, select it, and click Save.
  4. Repeat these steps for each application component and click Save for each.

    Figure 10. Add components
    Add components

Create environments

Now let’s create multiple environments based on our project needs (see Figure 11):

  1. Click Create Environment under the Environments tab and a new pop-up will appear.
  2. Fill in the name of the environment and provide a brief description.
  3. If you have an existing blueprint for an environment, select it.
  4. If you need approval workflow process to deploy to a given environment, check the Require Approval option.
  5. Select the color to identify the environment and click Save.

This will create a new environment.

Figure 11. Create environments
Create environments

Once an environment is created, you will need to associate resources (agents) based on the environment where the deployment needs to be made.

Next, you’ll add resources to the environments. If your application components need to be deployed to multiple servers, then you will need to configure resource mapping carefully.

  1. Click the Resource tab on the main header and click Create Top-Level Group. (You will need admin rights to create this object.)
  2. Provide the name of the Group: As a best practice, provide the name of the UrbanCode Deploy Application as the Group resource name
  3. If you have multiple environment deployments with agents installed in each environment, then click Actions -> Add Group under the Top-Level resource created. For example, if you have a database deployment to a database server and an application deployment to IBM Cloud, you will create two groups.
  4. Under each group, click Actions > Add Agent to add the corresponding UrbanCode Deploy Agent to the group.
  5. Under Agent, click Actions > Add to map the components to the UrbanCode Deploy agent where the component needs to be deployed.
  6. Once all the components of the applications are mapped to UrbanCode Deploy agents, go to your application and select the environment that you have created.
  7. Click Add Base Resources and add the resource that you just created in these steps.
  8. Repeat these steps for each environment you have created for the application.

Now UrbanCode Deploy is aware of the component-to-server mapping for each environment.

Figure 12. Add resources
Add resources

Create environment-specific variables

Once the environment is created and resources have been mapped, you can start adding the environment variables to the environment as defined in the component template. If there are environment variables that are not part of the component template and should be accessible by all the components, then you should define those environment variables.

To create the environment variable:

  1. Click your application and click the environment where you need to create the variable.
  2. Click the Configuration tab and select Environment Properties.
  3. Click Add Property (a new pop-up window will appear).
  4. Fill in the following details: a. Add the variable name. b. One-line description: This message will be displayed when you hover over the help icon in the List environment window. c. Select the Secure option if you are storing sensitive information like passwords; UrbanCode Deploy will encrypt the data and you will not be able to see this value in the deploy logs. d. Value represents the value of the environment variable. e. Click Save.

The variables will be listed as shown in Figure 13.

Figure 13. Create environment variables
Create environment variables

Generate the manifest file by environment

A manifest file is a template file that contains the key name and the value that will be dynamically populated during the deployment by the UrbanCode Deploy process.

For example, the route of the application should be different for different environments. If the pattern to be followed is <ENV>-<APPNAME>, then the value of the <ENV> should be picked up from the environment-specific variable and <APPNAME> should be picked up from the component-specific name in UrbanCode Deploy.

Define the application process

Once you have defined an application and created the environment and mapped the resources, you need to create the application process that defines the order of deployment for multiple components in the application.

Figure 14. Create an application process
Create an application process

It is a good idea to create a single application process for each component individually—a process that will deploy all the components in one go.

Integrate UrbanCode Deploy with Jenkins

Many development teams use Jenkins for continuous integration, but also need to coordinate the deployment of builds through environments, so they use Jenkins to create those builds and then pass the new builds to UrbanCode Deploy for deployment. UrbanCode Deploy provides a plug-in for Jenkins that allows Jenkins to invoke UrbanCode Deploy as a post-build action from which deployment can be triggered. (Read “Integrating Jenkins and IBM UrbanCode Deploy” for complete instructions on activating this plug-in.)

Once you install the plug-in, you will see a new post-build action to publish artifacts to UrbanCode Deploy. Select this step and configure the values as shown in Figure 15:

Figure 15. Jenkins post-build step to create version number
Jenkins post-build step to create version number

Provide the Component name and the Version number. This step will copy the artifacts provided in the field Base Artifact Directory to UrbanCode Deploy and version it with the number provided in Version field.

If you need to deploy this version of the artifact, then add in the following details:

Figure 16. Jenkins post-build step to deploy
Jenkins post-build step to deploy

Provide the UrbanCode Deploy application name created in the previous step. Provide the Environment and Application Process information from previous sections to deploy to the corresponding environment.

Deploy microservices

Most development projects follow the “build once, deploy many” approach and this example is no exception.

After a successful Jenkins job execution, the deployable version of the microservice will be stored in UrbanCode Deploy. You can use the same version of the artifact and deploy it to a higher environment (such as pre-production and production) after testing it successfully in lower environments (dev and test environments). To do this, select the application in UrbanCode Deploy and click play (the arrow button next to the environment).

Figure 17. Redeploy an application
Redeploy an application

Next, select the application process that you want to use from the drop-down menu. If you need to deploy multiple microservices in one go, then you can create snapshots in UrbanCode Deploy that contain the tested versions of the microservice and deploy them all at once.

Figure 18. Deploy multiple microservices
Deploy multiple microservices


In this tutorial, you’ve learned how to create an UrbanCode Deploy component template and application and how to add components. You have also learned how to integrate Jenkins with UrbanCode Deploy and trigger multiple microservice deployments from Jenkins and UrbanCode Deploy. For instructions on activating this UrbanCode Deploy/Jenkins plug-in, see “Integrating Jenkins and IBM UrbanCode Deploy.”