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')"
Prerequisites:
Explore how to deploy microservices to IBM Cloud Kubernetes Service (IKS).
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.
There are different cloud-based solutions for running 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.
IBM Cloud Kubernetes Service (IKS) is part of IBM’s public cloud offerings. It provides a hosted Kubernetes cluster where you can deploy your microservices. You will use it with IBM Cloud Container Registry, a private registry 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 demonstrates how communication can be established between pods inside a cluster.
You will use Helm to deploy these microservices to IBM Cloud using Open Liberty Helm charts. Helm is a package manager for Kubernetes. It uses templates to generate Kubernetes yaml files and then deploys and manages them as releases in your cluster.
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.
Helm: You will use the Helm Command Line Interface (CLI) to manage releases in your Kubernetes cluster. Download Helm and see the official Installing Helm documentation for information about setting up helm
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:
WINDOWS
MAC
LINUX
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
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 can deploy your microservices, you must create a Kubernetes cluster on IBM Cloud.
Log in to IBM Cloud by using the ibmcloud
command line. When you are prompted to select a region, 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
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 IKS 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
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.
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
Run the following command to download or update to the latest Open Liberty Docker image:
docker pull openliberty/open-liberty:kernel-java8-openj9-ubi
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
openliberty/open-liberty kernel-java8-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 registry enables the cluster to create pods by using your container images. Since it’s a private repository, 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.
ibmcloud cr login
Next, tag your container images with the relevant data about your registry. Remember to replace [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 [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
Helm is a package manager for Kubernetes. It allows you to create a package called a chart. You can install a chart on your cluster as a release and then manage the release using Helm.
Add the ibm-charts
repository to your local list of Helm repositories. Adding the repository allows you to use the ibm-open-liberty
chart.
helm repo add ibm-charts https://raw.githubusercontent.com/IBM/charts/master/repo/stable/
Use Helm to deploy the system
microservice. Remember to replace [your-namespace]
with the namespace you created earlier in the guide.
WINDOWS
MAC
LINUX
helm install system-app ^
--set image.repository=us.icr.io/[your-namespace]/system ^
--set image.tag=1.0-SNAPSHOT ^
--set image.pullSecret=default-us-icr-io ^
--set service.name=system-service ^
--set service.port=9080 ^
--set service.targetPort=9080 ^
--set ssl.enabled=false ^
ibm-charts/ibm-open-liberty
helm install system-app \
--set image.repository=us.icr.io/[your-namespace]/system \
--set image.tag=1.0-SNAPSHOT \
--set image.pullSecret=default-us-icr-io \
--set service.name=system-service \
--set service.port=9080 \
--set service.targetPort=9080 \
--set ssl.enabled=false \
ibm-charts/ibm-open-liberty
Use Helm to deploy the inventory
microservice. Remember to replace [your-namespace]
with the namespace you created earlier in the guide.
WINDOWS
MAC
LINUX
helm install inventory-app ^
--set image.repository=us.icr.io/[your-namespace]/inventory ^
--set image.tag=1.0-SNAPSHOT ^
--set image.pullSecret=default-us-icr-io ^
--set service.name=inventory-service ^
--set service.port=9080 ^
--set service.targetPort=9080 ^
--set ssl.enabled=false ^
ibm-charts/ibm-open-liberty
helm install inventory-app \
--set image.repository=us.icr.io/[your-namespace]/inventory \
--set image.tag=1.0-SNAPSHOT \
--set image.pullSecret=default-us-icr-io \
--set service.name=inventory-service \
--set service.port=9080 \
--set service.targetPort=9080 \
--set ssl.enabled=false \
ibm-charts/ibm-open-liberty
After you run helm install
, an output is displayed providing instructions on how to access your deployed microservices. Ignore these instructions for now, you will learn how to access your microservices in the next section.
The string literal after helm install
specifies the release name, which must be unique. This is the name that Helm uses to identify this specific deployment of your chart. The following table gives an overview for each of the parameters specified using --set
.
Parameter | Description |
| The name of your Docker image including registry/repository prefix |
| The tag for your Docker image |
| The image pull secret, since the container registry is private |
| The name of the service |
| The port exposed by the service |
| The port exposed by the pod |
| Specify if SSL is enabled |
Use the following command to find the status of the pods running the system
and inventory
microservices. Wait until the status of both microservices is Running
.
kubectl get pods
NAME READY STATUS RESTARTS AGE
inventory-app-ibm-open-l-5c586b9cfc-h5zmg 1/1 Running 0 23s
system-app-ibm-open-libe-84976bccfb-r22lj 1/1 Running 0 23s
The service used to expose our deployments has a type of NodePort
. This means you can access these services from outside of your cluster via a specific port. In this case, since nodePort
is not specified, the ports are randomized so you must obtain the ports before making requests to the services. You must also obtain the public IP address of our cluster. Note that there are other ways to expose your services such as using a LoadBalancer
service type or using an Ingress
. In production, you would most likely use an Ingress
.
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. This will be the hostname you substitute 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.
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 http://[hostname]:[system-node-port]/system/properties
. The second URL adds properties from system-service
to the inventory.
A few tests are included for you to test the basic functionality of the microservices. If a test failure occurs, then you might have introduced a bug into the code. To run the tests, wait for all pods to be in the ready state before proceeding further. The default properties that are defined in the pom.xml
are:
Property | Description |
---|---|
| IP or hostname for your cluster |
| Name of the Kubernetes Service wrapping the |
| The NodePort of the Kubernetes Service |
| The NodePort of the Kubernetes Service |
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
Optionally, you might want to make changes to your microservice and learn how to redeploy the updated version of your microservice. In this section, you will bump the version of the system
microservice to 2.0-SNAPSHOT
and redeploy the new version of the microservice. You can redeploy a microservice using Helm to upgrade the release.
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, it will have to be pushed to the repository again.
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
Use Helm to redeploy the system
microservice.
WINDOWS
MAC
LINUX
helm upgrade ^
--set image.repository=us.icr.io/[your-namespace]/system ^
--set image.tag=2.0-SNAPSHOT ^
--set image.pullSecret=default-us-icr-io ^
--set service.name=system-service ^
--set service.port=9080 ^
--set service.targetPort=9080 ^
--set ssl.enabled=false ^
system-app ibm-charts/ibm-open-liberty
helm upgrade \
--set image.repository=us.icr.io/[your-namespace]/system \
--set image.tag=2.0-SNAPSHOT \
--set image.pullSecret=default-us-icr-io \
--set service.name=system-service \
--set service.port=9080 \
--set service.targetPort=9080 \
--set ssl.enabled=false \
system-app ibm-charts/ibm-open-liberty
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-5c586b9cfc-h5zmg 1/1 Running 0 5m
system-app-ibm-open-libe-84976bccfb-r22lj 1/1 Running 0 23s
Observe that in this case the system
microservice is running in the pod called system-app-ibm-open-libe-84976bccfb-r22lj
. Substitute the name of your pod into the following command to see more details about the pod.
kubectl describe pod [pod-name]
View the events at the bottom of the command’s output. Observe that the pod is using the new container image system:2.0-SNAPSHOT
.
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 10m default-scheduler Successfully assigned default/system-app-ibm-open-libe-7f44456d97-mvjb8 to 10.144.188.209
Normal Pulling 10m kubelet, 10.144.188.209 Pulling image "us.icr.io/[your-namespace]/system:1.0-SNAPSHOT"
Normal Pulled 10m kubelet, 10.144.188.209 Successfully pulled image "us.icr.io/[your-namespace]/system:1.0-SNAPSHOT"
Normal Created 10m kubelet, 10.144.188.209 Created container ibm-open-liberty
Normal Started 10m kubelet, 10.144.188.209 Started container ibm-open-liberty
Warning Unhealthy 9m58s kubelet, 10.144.188.209 Readiness probe failed: Get http://172.30.200.205:9080/: dial tcp 172.30.200.205:9080: connect: connection refused
When you no longer need your deployed microservices, you can delete them with the following Helm commands:
helm uninstall system-app
helm uninstall inventory-app
Remove the namespace you created in your container registry.
ibmcloud cr namespace-rm [your-namespace]
Log out of your container 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
You have just deployed two microservices to IBM Cloud. You have learned to use Helm to install your microservices on a Kubernetes cluster using the Open Liberty helm chart.
Deploying microservices to IBM Cloud Kubernetes Service (IKS) by Open Liberty is licensed under CC BY-ND 4.0
Thank you for your feedback!
Raise an issue to share feedback
Create a pull request to contribute to this guide
Ask a question on Stack Overflow