Deploying microservices to IBM Cloud Kubernetes Service

duration 1 hour

Prerequisites:

Explore how to deploy microservices to IBM Cloud Kubernetes Service.

What you’ll learn

You will learn how to deploy two microservices in Open Liberty containers to a Kubernetes cluster on IBM Cloud.

Kubernetes is an open source container orchestrator that automates many tasks involved in deploying, managing, and scaling containerized applications. If you would like to learn more about Kubernetes, check out the Deploying microservices to Kubernetes guide.

Different cloud-based solutions are available to run your Kubernetes workloads. A cloud-based infrastructure enables you to focus on developing your microservices without worrying about low-level infrastructure details for deployment. Using a cloud helps you to easily scale and manage your microservices in a high-availability setup.

The IBM Cloud Kubernetes Service is part of IBM’s public cloud offerings. It provides a hosted Kubernetes cluster where you can deploy your microservices. In this guide, you will use it with the IBM Cloud Container Registry, which is a private registry that is used to store and distribute your container images.

The two microservices you will deploy are called system and inventory. The system microservice returns the JVM system properties of the running container. It also returns the pod’s name in the HTTP header, making replicas easy to distinguish from each other. The inventory microservice adds the properties from the system microservice to the inventory. This configuration demonstrates how to establish communication between pods inside a cluster.

Additional prerequisites

Before you begin, the following additional tools need to be installed:

  • Docker: You need a containerization software for building containers. Kubernetes supports various container types, but you will use Docker in this guide. For installation instructions, refer to the official Docker documentation.

  • kubectl: You need the Kubernetes command-line tool kubectl to interact with your Kubernetes cluster. See the official Install and Set Up kubectl documentation for information about downloading and setting up kubectl on your platform.

  • IBM Cloud CLI: You will use the IBM Cloud CLI to interact with IBM Cloud. To install the IBM Cloud CLI for your platform, run one of the following commands:

Open command prompt as an administrator and run the following command.

powershell -command "Set-ExecutionPolicy Unrestricted; iex(New-Object Net.WebClient).DownloadString('https://clis.cloud.ibm.com/install/powershell')"
curl -fsSL https://clis.cloud.ibm.com/install/osx | sh
curl -fsSL https://clis.cloud.ibm.com/install/linux | sh
  • IBM Cloud Container Registry plug-in: To install the container registry plug-in, run the following command:

    ibmcloud plugin install container-registry
  • IBM Cloud Kubernetes Service plug-in: To install the Kubernetes registry plug-in, run the following command:

    ibmcloud plugin install kubernetes-service

Getting started

The fastest way to work through this guide is to clone the Git repository and use the projects that are provided inside:

git clone https://github.com/openliberty/guide-cloud-ibm.git
cd guide-cloud-ibm

The start directory contains the starting project that you will build upon.

The finish directory contains the finished project that you will build.

Before you begin, make sure you have all the necessary prerequisites.

Creating a Kubernetes cluster on IBM Cloud

Before you can deploy your microservices, you must create a Kubernetes cluster on IBM Cloud.

Configuring IBM Cloud CLI

Log in to IBM Cloud by using the ibmcloud command line. When you are prompted to select a region, for example, choose us-south. This allows you to create a free cluster, which is limited to specific regions. Note that if you are using a federated user ID, you will have to use the --sso flag to get a one-time code for single sign-on.

ibmcloud login

Provisioning a cluster

To create a Kubernetes cluster, you need Administrator access to IBM Cloud Kubernetes Service. To confirm that you have Administrator access, navigate to the IBM Cloud Dashboard. Then, navigate to Manage > Access (IAM) > Users > [Your Username] > Access Policies and confirm that Administrator is listed as a policy for all resources in the account or for the Kubernetes service.

Once you have confirmed that you have appropriate permissions, use the following command to provision a cluster.

ibmcloud ks cluster create classic --name guide-cluster

This command provisions a free cluster that expires in a month if you do not delete it.

The 'flavor' flag was not specified. So a free cluster will be created.
Creating cluster...
OK
Cluster created with ID [cluster-id]

Check the current status of your cluster.

ibmcloud ks clusters

Wait until your cluster is in the normal state before proceeding. It will start off in the deploying state.

Name            ID                     State       Created          Workers   Location   Version       Resource Group Name   Provider
guide-cluster   bpp5ge4f0ck66fue46vg   deploying   4 minutes ago    1         par01      1.16.8_1526   Default               classic

Next, it will transition to the pending state.

Name            ID                     State    Created          Workers   Location   Version       Resource Group Name   Provider
guide-cluster   bpp5ge4f0ck66fue46vg   pending  16 minutes ago   1         par01      1.16.8_1526   Default               classic

Finally, it will transition to the normal state. It may take a while for the IBM Cloud Kubernetes Service to prepare your cluster.

Name            ID                     State    Created      Workers   Location   Version       Resource Group Name   Provider
guide-cluster   bpp5ge4f0ck66fue46vg   normal   1 hour ago   1         par01      1.16.8_1526   Default               classic

Once your cluster is ready, connect kubectl to the cluster.

ibmcloud ks cluster config --cluster guide-cluster

Verify that you’re connected to the cluster by checking the cluster’s nodes.

kubectl get nodes
NAME           STATUS    ROLES     AGE       VERSION
10.70.200.73   Ready     <none>    1h        v1.16.8+IKS

Deploying microservices to IBM Cloud Kubernetes Service

In this section, you will learn how to deploy two microservices in Open Liberty containers to a Kubernetes cluster on IBM Cloud. You will build and containerize the system and inventory microservices, push them to a container registry, and then deploy them to your Kubernetes cluster.

Building and containerizing the microservices

The first step of deploying to Kubernetes is to build and containerize your microservices.

The starting Java project, which you can find in the start directory, is a multi-module Maven project. It’s made up of the system and inventory microservices. Each microservice resides in its own directory, start/system and start/inventory. Each of these directories also contains a Dockerfile, which is necessary for building Docker images. If you’re unfamiliar with Dockerfiles, check out the Containerizing Microservices guide.

To build these microservices, navigate to the start directory and run the following command:

mvn package

Next, run the docker build commands to build container images for your application:

docker build -t system:1.0-SNAPSHOT system/.
docker build -t inventory:1.0-SNAPSHOT inventory/.

The -t flag in the docker build command allows the Docker image to be labeled (tagged) in the name[:tag] format. The tag for an image describes the specific image version. If the optional [:tag] tag is not specified, the latest tag is created by default.

During the build, you’ll see various Docker messages describing what images are being downloaded and built. When the build finishes, run the following command to list all local Docker images:

docker images

Verify that the system:1.0-SNAPSHOT and inventory:1.0-SNAPSHOT images are listed among them, for example:

REPOSITORY                                   TAG
system                                       1.0-SNAPSHOT
inventory                                    1.0-SNAPSHOT
icr.io/appcafe/open-liberty                  full-java11-openj9-ubi

If you don’t see the system:1.0-SNAPSHOT and inventory:1.0-SNAPSHOT images, then check the Maven build log for any potential errors.

Pushing the images to a container registry

Pushing the images to a registry enables the cluster to create pods by using your container images. It’s a private repository so only users with access to your IBM Cloud account will have access to these images.

The registry you will use is called IBM Cloud Container Registry. Use the container registry plug-in to create a namespace for your container images. The namespace must be unique within IBM Cloud for the region you selected, so choose something relevant that you’ll remember for the duration of the guide.

ibmcloud cr namespace-add [your-namespace]

Use the plug-in again to log in to the container registry and find out your registry name, for example, us.icr.io.

ibmcloud cr login
Logging 'docker' in to 'us.icr.io'...
Logged in to 'us.icr.io'.

Next, tag your container images with the relevant data about your registry. Remember to replace us.icr.io to your registry and [your-namespace] with the namespace you created earlier in the guide.

docker tag system:1.0-SNAPSHOT us.icr.io/[your-namespace]/system:1.0-SNAPSHOT
docker tag inventory:1.0-SNAPSHOT us.icr.io/[your-namespace]/inventory:1.0-SNAPSHOT

Finally, push your images to the registry. Remember to replace us.icr.io to your registry and [your-namespace] with the namespace you created earlier in the guide.

docker push us.icr.io/[your-namespace]/system:1.0-SNAPSHOT
docker push us.icr.io/[your-namespace]/inventory:1.0-SNAPSHOT

Deploying the microservices

Now that your container images are built, deploy them using a Kubernetes resource definition.

A Kubernetes resource definition is a YAML file that contains a description of all your deployments, services, or any other resources that you want to deploy. All resources can also be deleted from the cluster by using the same YAML file that you used to deploy them. For this guide, the kubernetes.yaml resource definition file is provided for you. If you are interested in learning more about the Kubernetes resource definition, check out the Deploying microservices to Kubernetes guide.

Update the kubernetes.yaml file in the start directory.
kubernetes.yaml

kubernetes.yaml

 1apiVersion: apps/v1
 2kind: Deployment
 3metadata:
 4  name: system-deployment
 5  labels:
 6    app: system
 7spec:
 8  selector:
 9    matchLabels:
10      app: system
11  template:
12    metadata:
13      labels:
14        app: system
15    spec:
16      containers:
17      - name: system-container
18        image: us.icr.io/[your-namespace]/system:1.0-SNAPSHOT
19        ports:
20        - containerPort: 9080
21---
22apiVersion: apps/v1
23kind: Deployment
24metadata:
25  name: inventory-deployment
26  labels:
27    app: inventory
28spec:
29  selector:
30    matchLabels:
31      app: inventory
32  template:
33    metadata:
34      labels:
35        app: inventory
36    spec:
37      containers:
38      - name: inventory-container
39        image: us.icr.io/[your-namespace]/inventory:1.0-SNAPSHOT
40        ports:
41        - containerPort: 9080
42---
43apiVersion: v1
44kind: Service
45metadata:
46  name: system-service
47spec:
48  type: NodePort
49  selector:
50    app: system
51  ports:
52  - protocol: TCP
53    port: 9080
54    targetPort: 9080
55    nodePort: 31000
56---
57apiVersion: v1
58kind: Service
59metadata:
60  name: inventory-service
61spec:
62  type: NodePort
63  selector:
64    app: inventory
65  ports:
66  - protocol: TCP
67    port: 9080
68    targetPort: 9080
69    nodePort: 32000

The image is the name and tag of the container image that you want to use for the container. Update the system image and the inventory image fields to point to your system and inventory container images. Remember to replace us.icr.io with your registry and [your-namespace] with the namespace you created earlier in the guide.

Run the following commands to deploy the resources as defined in the kubernetes.yaml file:

kubectl apply -f kubernetes.yaml

When the apps are deployed, run the following command to check the status of your pods:

kubectl get pods

If all the pods are healthy and running, you see an output similar to the following:

NAME                                    READY     STATUS    RESTARTS   AGE
system-deployment-6bd97d9bf6-4ccds      1/1       Running   0          15s
inventory-deployment-645767664f-nbtd9   1/1       Running   0          15s

Finding the microservice’s IP address and ports

The service used to expose your deployments has a type of NodePort service that enables you to access these services from outside of your cluster through a specific port. In this case, nodePort is not specified and the ports are randomized so you must obtain the ports before you make requests to the services. You must also obtain the public IP address of your cluster. Other ways to expose your services are available, such as by using a LoadBalancer service type or an Ingress resource. In production, you typically use an Ingress resource.

First, find the public IP address of your cluster.

ibmcloud ks workers --cluster guide-cluster

Take note of the Public IP in the command’s output. You will substitute this value as the hostname into commands later in this guide.

OK
ID                                                       Public IP         Private IP       Flavor   State    Status   Zone    Version
kube-bpp5ge4f0ck66fue46vg-guidecluste-default-00000048   159.122.179.207   10.144.188.209   free     normal   Ready    mil01   1.16.8_1526

Get the node port of the system microservice.

kubectl get service system-service -o jsonpath="{.spec.ports[0].nodePort}{'\n'}"

Get the node port of the inventory microservice.

kubectl get service inventory-service -o jsonpath="{.spec.ports[0].nodePort}{'\n'}"

Take note of the IP address and ports. They are required to make the HTTP requests.

Making requests to the microservices

To make a request to the system and inventory microservices, curl or visit the following URLs to access your microservices, substituting the appropriate hostname and node ports:

  • http://[hostname]:[system-node-port]/system/properties

  • http://[hostname]:[inventory-node-port]/inventory/systems/system-service

The first URL returns system properties and the name of the pod in an HTTP header called X-Pod-Name. To view the header, you can use the -I option in the curl when making a request to the http://[hostname]:[system-node-port]/system/properties URL. The second URL adds properties from system-service to the inventory.

Testing microservices that are running on IBM Cloud

A few tests are included for you to test the basic functionality of the microservices. If a test fails, then you might have introduced a bug into the code. To run the tests, wait until all pods are in the ready state before proceeding further. The default properties that are defined in the pom.xml file are:

Property Description

cluster.ip

IP or hostname for your cluster

system.kube.service

Name of the Kubernetes Service wrapping the system pods, system-service by default.

system.node.port

The NodePort of the Kubernetes Service system-service, 31000 by default.

inventory.node.port

The NodePort of the Kubernetes Service inventory-service, 32000 by default.

Use the following command to run the integration tests against your cluster. Substitute [hostname], [system-node-port] and [inventory-node-port] with the appropriate values.

mvn failsafe:integration-test -Dcluster.ip=[hostname] -Dsystem.node.port=[system-node-port] -Dinventory.node.port=[inventory-node-port]

If the tests pass, you’ll see an output similar to the following for each service respectively:

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.system.SystemEndpointIT
Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.673 sec - in it.io.openliberty.guides.system.SystemEndpointIT

Results:

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.inventory.InventoryEndpointIT
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.222 sec - in it.io.openliberty.guides.inventory.InventoryEndpointIT

Results:

Tests run: 4, Failures: 0, Errors: 0, Skipped: 0

Deploying a new version of system microservice

Optionally, you might want to make changes to your microservice and redeploy the updated version. In this section, you will bump the version of the system microservice to 2.0-SNAPSHOT and redeploy the new version of the microservice.

Use Maven to repackage your microservice:

mvn package

Next, build the new version of the container image as 2.0-SNAPSHOT:

docker build -t system:2.0-SNAPSHOT system/.

Since you built a new image, you need to push it to the repository again. In the following docker and kubectl commands, remember to replace us.icr.io with your registry and [your-namespace] with the namespace you created earlier in the guide.

Tag your container image with the relevant data about your registry.

docker tag system:2.0-SNAPSHOT us.icr.io/[your-namespace]/system:2.0-SNAPSHOT

Push your image to the registry.

docker push us.icr.io/[your-namespace]/system:2.0-SNAPSHOT

Update the system-deployment deployment to use the new container image that you just pushed to the registry:

kubectl set image deployment/system-deployment system-container=us.icr.io/[your-namespace]/system:2.0-SNAPSHOT

Use the following command to find the name of the pod that is running the system microservice.

kubectl get pods
NAME                                       READY    STATUS    RESTARTS   AGE
inventory-app-ibm-open-l-994778cf7-fdkb5   1/1      Running   0          5m
system-app-ibm-open-libe-85c85949c-lb49d   1/1      Running   0          23s

In this case, the system microservice is running in the pod called system-app-ibm-open-libe-85c85949c-lb49d. Substitute the name of your pod into the following command to see more details about the pod.

kubectl describe pod [pod-name]

Substitute the [pod-name] to your pod name into the following command. Run the command to view your pod events. Observe that the pod is using the new container image system:2.0-SNAPSHOT.

kubectl get event --field-selector involvedObject.name=[pod-name]
LAST SEEN   TYPE     REASON      OBJECT                                         MESSAGE
12m         Normal   Scheduled   pod/system-app-ibm-open-libe-85c85949c-lb49d   Successfully assigned default/system-app-ibm-open-libe-85c85949c-lb49d to 10.144.182.122
12m         Normal   Pulling     pod/system-app-ibm-open-libe-85c85949c-lb49d   Pulling image "us.icr.io/[your-namespace]/system:2.0-SNAPSHOT"
12m         Normal   Pulled      pod/system-app-ibm-open-libe-85c85949c-lb49d   Successfully pulled image "us.icr.io/[your-namespace]/system:2.0-SNAPSHOT" in 6.8103423s
12m         Normal   Created     pod/system-app-ibm-open-libe-85c85949c-lb49d   Created container ibm-open-liberty
12m         Normal   Started     pod/system-app-ibm-open-libe-85c85949c-lb49d   Started container ibm-open-liberty

Tearing down the environment

When you no longer need your deployed microservices, you can delete all Kubernetes resources by running the kubectl delete command:

kubectl delete -f kubernetes.yaml

Remove your images from your container registry. Remember to replace us.icr.io to your registry and [your-namespace] with the namespace you created earlier in the guide.

ibmcloud cr image-rm us.icr.io/[your-namespace]/system:1.0-SNAPSHOT
ibmcloud cr image-rm us.icr.io/[your-namespace]/system:2.0-SNAPSHOT
ibmcloud cr image-rm us.icr.io/[your-namespace]/inventory:1.0-SNAPSHOT

Remove the namespace you created in your container registry.

ibmcloud cr namespace-rm [your-namespace]

Log out of your container registry. Remember to replace us.icr.io to your registry.

docker logout us.icr.io
docker logout registry.ng.bluemix.net

Remove your IKS cluster.

ibmcloud ks cluster rm --cluster guide-cluster

Log out of the ibmcloud command line tool.

ibmcloud logout

Great work! You’re done!

You just deployed two microservices to IBM Cloud. You also learned how to use the kubectl command to deploy your microservices on a Kubernetes cluster.

Guide Attribution

Deploying microservices to IBM Cloud Kubernetes Service by Open Liberty is licensed under CC BY-ND 4.0

Copied to clipboard
Copy code block
Copy file contents

Prerequisites:

Nice work! Where to next?

What did you think of this guide?

Extreme Dislike Dislike Like Extreme Like

What could make this guide better?

Raise an issue to share feedback

Create a pull request to contribute to this guide

Need help?

Ask a question on Stack Overflow

Like Open Liberty? Star our repo on GitHub.

Star