Deploying a microservice to Kubernetes using Open Liberty Operator

duration 30 minutes

Prerequisites:

Explore how to deploy a microservice to Kubernetes using Open Liberty Operator.

What you’ll learn

You will learn how to deploy a cloud-native application with a microservice to Kubernetes using the Open Liberty Operator.

Kubernetes is a container orchestration system. It streamlines the DevOps process by providing an intuitive development pipeline. It also provides integration with multiple tools to make the deployment and management of cloud applications easier. You can learn more about Kubernetes by checking out the Deploying microservices to Kubernetes guide.

Kubernetes operators provide an easy way to automate the management and updating of applications by abstracting away some of the details of cloud application management. To learn more about operators, check out this Operators tech topic article.

The application in this guide consists of one microservice, system. The system microservice returns the JVM system properties of its host.

You will deploy the system microservice by using the Open Liberty Operator. The Open Liberty Operator packages, deploys, and manages Open Liberty applications on Kubernetes-based clusters. The Open Liberty Operator watches Open Liberty resources and creates various Kubernetes resources, including Deployments, Services, and Routes, depending on the configurations. The Operator then continuously compares the current state of the resources, the desired state of application deployment, and reconciles them when necessary.

Additional prerequisites

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

Use Docker Desktop, where a local Kubernetes environment is pre-installed and enabled. If you do not see the Kubernetes tab, then upgrade to the latest version of Docker Desktop.

Complete the setup for your operating system:

After you complete the Docker setup instructions for your operating system, ensure that Kubernetes (not Swarm) is selected as the orchestrator in Docker Preferences.

Use Docker Desktop, where a local Kubernetes environment is pre-installed and enabled. If you do not see the Kubernetes tab, then upgrade to the latest version of Docker Desktop.

Complete the setup for your operating system:

After you complete the Docker setup instructions for your operating system, ensure that Kubernetes (not Swarm) is selected as the orchestrator in Docker Preferences.

You will use Minikube as a single-node Kubernetes cluster that runs locally in a virtual machine. Make sure you have kubectl installed. If you need to install kubectl, see the kubectl installation instructions. For Minikube installation instructions, see the Minikube documentation.

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-openliberty-operator-intro.git
cd guide-openliberty-operator-intro

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.

Starting and preparing your cluster for deployment

Start your Kubernetes cluster.

Start your Docker Desktop environment.

Ensure that Kubernetes is running on Docker Desktop and that the context is set to docker-desktop.

Run the following command from a command-line session:

minikube start

Next, validate that you have a healthy Kubernetes environment by running the following command from the active command-line session.

kubectl get nodes

This command should return a Ready status for the master node.

You do not need to do any other step.

Run the following command to configure the Docker CLI to use Minikube’s Docker daemon. After you run this command, you will be able to interact with Minikube’s Docker daemon and build new images directly to it from your host machine:

eval $(minikube docker-env)

Installing the Operator

Before you can deploy your microservice, you must install the Open Liberty Operator. You should read the official installation document on the GitHub repository.

First, install Custom Resource Definitions (CRDs) for the Open Liberty Operator by running the following command:

kubectl apply -f https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-crd.yaml

Custom Resources extend the Kubernetes API and enhance its functionality.

Set environment variables for namespaces for the Operator by running the following commands:

set OPERATOR_NAMESPACE=default
set WATCH_NAMESPACE=\"\"
OPERATOR_NAMESPACE=default
WATCH_NAMESPACE='""'

Next, run the following commands to install cluster-level role-based access:

curl https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-rbac-watch-all.yaml -o openliberty-app-rbac-watch-all.yaml

powershell -Command "(gc .\openliberty-app-rbac-watch-all.yaml) -replace 'OPEN_LIBERTY_OPERATOR_NAMESPACE', '%OPERATOR_NAMESPACE%' | Out-File -encoding ASCII .\openliberty-app-rbac-watch-all.yaml"

kubectl apply -f .\openliberty-app-rbac-watch-all.yaml
curl -L https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-rbac-watch-all.yaml \
  | sed -e "s/OPEN_LIBERTY_OPERATOR_NAMESPACE/${OPERATOR_NAMESPACE}/" \
  | kubectl apply -f -

Finally, run the following commands to install the Operator:

curl https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-operator.yaml -o openliberty-app-operator.yaml

powershell -Command "(gc .\openliberty-app-operator.yaml) -replace 'OPEN_LIBERTY_WATCH_NAMESPACE', '%WATCH_NAMESPACE%' | Out-File -encoding ASCII .\openliberty-app-operator.yaml"

kubectl apply -n %OPERATOR_NAMESPACE% -f .\openliberty-app-operator.yaml
curl -L https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-operator.yaml \
  | sed -e "s/OPEN_LIBERTY_WATCH_NAMESPACE/${WATCH_NAMESPACE}/" \
  | kubectl apply -n ${OPERATOR_NAMESPACE} -f -

To check that the Open Liberty Operator has been installed successfully, run the following command to view all the supported API resources that are available through the Open Liberty Operator:

kubectl api-resources --api-group=apps.openliberty.io

Look for the following output, which shows the custom resource definitions (CRDs) that can be used by the Open Liberty Operator:

NAME                      SHORTNAMES         APIGROUP              NAMESPACED   KIND
openlibertyapplications   olapp,olapps       apps.openliberty.io   true         OpenLibertyApplication
openlibertydumps          oldump,oldumps     apps.openliberty.io   true         OpenLibertyDump
openlibertytraces         oltrace,oltraces   apps.openliberty.io   true         OpenLibertyTrace

Each CRD defines a kind of object that can be used, which is specified in the previous example by the KIND value. The SHORTNAME value specifies alternative names that you can substitute in the configuration to refer to an object kind. For example, you can refer to the OpenLibertyApplication object kind by one of its specified shortnames, such as olapps.

The openlibertyapplications CRD defines a set of configurations for deploying an Open Liberty-based application, including the application image, number of instances, and storage settings. The Open Liberty Operator watches for changes to instances of the OpenLibertyApplication object kind and creates Kubernetes resources that are based on the configuration that is defined in the CRD.

Deploying the system microservice to Kubernetes

To deploy the system microservice, you must first package the microservice, then create and build a runnable container image of the packaged microservice.

Packaging the microservice

Ensure that you are in the start directory and run the following command to package the system microservice:

mvn clean package

Building the image

Run the following command to download or update to the latest Open Liberty Docker image:

docker pull icr.io/appcafe/open-liberty:full-java11-openj9-ubi

Next, run the docker build command to build the container image for your application:

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

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.

Normally, you must push your image to a container registry before you can deploy it on any cloud environment. You can skip this step because you are working with a local Kubernetes environment.

Now you’re ready to deploy the image.

Deploying the image

You can configure the specifics of the Open Liberty Operator-controlled deployment with a YAML configuration file.

Create the deploy.yaml configuration file in the start directory.
deploy.yaml

deploy.yaml

 1# tag::system[]
 2apiVersion: apps.openliberty.io/v1beta2
 3# tag::olapp[]
 4kind: OpenLibertyApplication
 5# end::olapp[]
 6metadata:
 7  name: system
 8  labels:
 9    name: system
10spec:
11  # tag::sysImage[]
12  applicationImage: system:1.0-SNAPSHOT
13  # end::sysImage[]
14  # tag::service[]
15  service:
16    # tag::servicePort[]
17    port: 9080
18    # end::servicePort[]
19  # end::service[]
20  # tag::expose[]
21  expose: true
22  # end::expose[]
23  route:
24    pathType: ImplementationSpecific
25  # tag::systemEnv[]
26  env:
27    - name: WLP_LOGGING_MESSAGE_FORMAT
28      value: "json"
29    - name: WLP_LOGGING_MESSAGE_SOURCE
30      value: "message,trace,accessLog,ffdc,audit"
31  # end::systemEnv[]
32  # tag::healthProbes[]
33  # tag::startupProbe[]
34  probes:
35    startup:
36      failureThreshold: 12
37      httpGet:
38        path: /health/started
39        port: 9080
40        scheme: HTTP
41      initialDelaySeconds: 30
42      periodSeconds: 2
43      timeoutSeconds: 10
44  # end::startupProbe[]
45  # tag::livenessProbe[]
46    liveness:
47      failureThreshold: 12
48      httpGet:
49        path: /health/live
50        port: 9080
51        scheme: HTTP
52      initialDelaySeconds: 30
53      periodSeconds: 2
54      timeoutSeconds: 10
55  # end::livenessProbe[]
56  # tag::readinessProbe[]
57    readiness:
58      failureThreshold: 12
59      httpGet:
60        path: /health/ready
61        port: 9080
62        scheme: HTTP
63      initialDelaySeconds: 30
64      periodSeconds: 2
65      timeoutSeconds: 10
66  # end::readinessProbe[]
67  # end::healthProbes[]
68# end::system[]

The deploy.yaml file is configured to deploy one OpenLibertyApplication resource, system, which is controlled by the Open Liberty Operator.

The applicationImage parameter defines what container image is deployed as part of the OpenLibertyApplication CRD. This parameter follows the \<image-name\>[:tag] format. The parameter can also point to an image hosted on an external registry, such as Docker Hub. The system microservice is configured to use the image created from the earlier build.

The env parameter is used to specify environment variables that are passed to the container at runtime.

Additionally, the microservice includes the service and expose parameters. The service.port parameter specifies which port is exposed by the container, allowing the microservice to be accessed from outside the container. To access the microservice from outside of the cluster, it must be exposed by setting the expose parameter to true. After you expose the microservice, the Operator automatically creates and configures routes for external access to your microservice.

Run the following command to deploy the system microservice with the previously explained configuration:

kubectl apply -f deploy.yaml

Next, run the following command to view your newly created OpenLibertyApplications resources:

kubectl get OpenLibertyApplications

You can also replace OpenLibertyApplications with the shortname olapps.

Look for output that is similar to the following example:

NAME      IMAGE                  EXPOSED   RECONCILED   AGE
system    system:1.0-SNAPSHOT    true      True         10s

A RECONCILED state value of True indicates that the operator was able to successfully process the OpenLibertyApplications instances. Run the following command to view details of your microservice:

kubectl describe olapps/system

This example shows part of the olapps/system output:

Name:         system
Namespace:    default
Labels:       app.kubernetes.io/part-of=system
              name=system
Annotations:  <none>
API Version:  apps.openliberty.io/v1beta2
Kind:         OpenLibertyApplication

...

Accessing the microservice

To access the exposed system microservice, the service must be port-forwarded. Run the following command to set up port forwarding to access the system service:

kubectl port-forward svc/system 9080

Visit the microservice at http://localhost:9080/system/properties.

When you’re done trying out the microservice, press CTRL+C in the command line session where you ran the kubectl port-forward command to stop the port forwarding.

Run the following command to remove the deployed system microservice:

kubectl delete -f deploy.yaml

Specifying optional parameters

You can also use the Open Liberty Operator to implement optional parameters in your application deployment by specifying the associated CRDs in your deploy.yaml file. For example, you can configure the Kubernetes liveness, readiness and startup probes. Visit the Open Liberty Operator user guide to find all of the supported optional CRDs.

To configure the Kubernetes liveness, readiness and startup probes by using the Open Liberty Operator, specify the probes in your deploy.yaml file. The startup probe verifies whether deployed application is fully initialized before the liveness probe takes over. Then, the liveness probe determines whether the application is running and the readiness probe determines whether the application is ready to process requests. For more information about application health checks, see the Checking the health of microservices on Kubernetes guide.

Replace the deploy.yaml configuration file.
deploy.yaml

deploy.yaml

 1# tag::system[]
 2apiVersion: apps.openliberty.io/v1beta2
 3# tag::olapp[]
 4kind: OpenLibertyApplication
 5# end::olapp[]
 6metadata:
 7  name: system
 8  labels:
 9    name: system
10spec:
11  # tag::sysImage[]
12  applicationImage: system:1.0-SNAPSHOT
13  # end::sysImage[]
14  # tag::service[]
15  service:
16    # tag::servicePort[]
17    port: 9080
18    # end::servicePort[]
19  # end::service[]
20  # tag::expose[]
21  expose: true
22  # end::expose[]
23  route:
24    pathType: ImplementationSpecific
25  # tag::systemEnv[]
26  env:
27    - name: WLP_LOGGING_MESSAGE_FORMAT
28      value: "json"
29    - name: WLP_LOGGING_MESSAGE_SOURCE
30      value: "message,trace,accessLog,ffdc,audit"
31  # end::systemEnv[]
32  # tag::healthProbes[]
33  # tag::startupProbe[]
34  probes:
35    startup:
36      failureThreshold: 12
37      httpGet:
38        path: /health/started
39        port: 9080
40        scheme: HTTP
41      initialDelaySeconds: 30
42      periodSeconds: 2
43      timeoutSeconds: 10
44  # end::startupProbe[]
45  # tag::livenessProbe[]
46    liveness:
47      failureThreshold: 12
48      httpGet:
49        path: /health/live
50        port: 9080
51        scheme: HTTP
52      initialDelaySeconds: 30
53      periodSeconds: 2
54      timeoutSeconds: 10
55  # end::livenessProbe[]
56  # tag::readinessProbe[]
57    readiness:
58      failureThreshold: 12
59      httpGet:
60        path: /health/ready
61        port: 9080
62        scheme: HTTP
63      initialDelaySeconds: 30
64      periodSeconds: 2
65      timeoutSeconds: 10
66  # end::readinessProbe[]
67  # end::healthProbes[]
68# end::system[]

The health check endpoints /health/started, /health/live and /health/ready are already created for you.

Run the following command to deploy the system microservice with the new configuration:

kubectl apply -f deploy.yaml

Run the following command to check status of the pods:

kubectl describe pods

Look for the following output to confirm that the health checks are successfully applied and working:

Liveness:   http-get http://:9080/health/live delay=30s timeout=10s period=2s #success=1 #failure=12
Readiness:  http-get http://:9080/health/ready delay=30s timeout=10s period=2s #success=1 #failure=12
Startup:    http-get http://:9080/health/started delay=30s timeout=10s period=2s #success=1 #failure=12

Run the following command to set up port forwarding to access the system service:

kubectl port-forward svc/system 9080

Visit the microservice at http://localhost:9080/system/properties.

When you’re done trying out the microservice, press CTRL+C in the command line session where you ran the kubectl port-forward command to stop the port forwarding.

Tearing down the environment

When you no longer need your deployed microservice, you can delete all resources by running the following command:

kubectl delete -f deploy.yaml

To uninstall the Open Liberty Operator, run the following commands:

set OPERATOR_NAMESPACE=default
set WATCH_NAMESPACE=\"\"

kubectl delete -n %OPERATOR_NAMESPACE% -f .\openliberty-app-operator.yaml

kubectl delete -f .\openliberty-app-rbac-watch-all.yaml

kubectl delete -f https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-crd.yaml
OPERATOR_NAMESPACE=default
WATCH_NAMESPACE='""'

curl -L https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-operator.yaml \
  | sed -e "s/OPEN_LIBERTY_WATCH_NAMESPACE/${WATCH_NAMESPACE}/" \
  | kubectl delete -n ${OPERATOR_NAMESPACE} -f -

curl -L https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-rbac-watch-all.yaml \
  | sed -e "s/OPEN_LIBERTY_OPERATOR_NAMESPACE/${OPERATOR_NAMESPACE}/" \
  | kubectl delete -f -

kubectl delete -f https://raw.githubusercontent.com/OpenLiberty/open-liberty-operator/main/deploy/releases/0.8.2/kubectl/openliberty-app-crd.yaml

Great work! You’re done!

You just deployed a microservice running in Open Liberty to Kubernetes and configured the Kubernetes liveness, readiness and startup probes by using the Open Liberty Operator.

Guide Attribution

Deploying a microservice to Kubernetes using Open Liberty Operator by Open Liberty is licensed under CC BY-ND 4.0

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