30 minutes
Prerequisites:
Explore how to deploy a microservice to Kubernetes using Open Liberty Operator.
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.
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.
WINDOWS
MAC
LINUX
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:
Set up Docker for Windows.
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:
Set up Docker for Mac.
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.
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-introThe 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.
Start your Kubernetes cluster.
WINDOWS
MAC
LINUX
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 startNext, validate that you have a healthy Kubernetes environment by running the following command from the active command-line session.
kubectl get nodesThis command should return a Ready status for the master node.
WINDOWS
MAC
LINUX
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)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.yamlCustom Resources extend the Kubernetes API and enhance its functionality.
Set environment variables for namespaces for the Operator by running the following commands:
WINDOWS
MAC
LINUX
set OPERATOR_NAMESPACE=default
set WATCH_NAMESPACE=\"\"OPERATOR_NAMESPACE=default
WATCH_NAMESPACE='""'Next, run the following commands to install cluster-level role-based access:
WINDOWS
MAC
LINUX
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.yamlcurl -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:
WINDOWS
MAC
LINUX
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.yamlcurl -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.ioLook 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 OpenLibertyTraceEach 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.
To deploy the system microservice, you must first package the microservice, then create and build a runnable container image of the packaged microservice.
Ensure that you are in the start directory and run the following command to package the system microservice:
mvn clean packageRun the following command to download or update to the latest Open Liberty Docker image:
docker pull icr.io/appcafe/open-liberty:full-java11-openj9-ubiNext, 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.
You can configure the specifics of the Open Liberty Operator-controlled deployment with a YAML configuration file.
Create thedeploy.yamlconfiguration file in thestartdirectory.deploy.yaml
deploy.yaml
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.yamlNext, run the following command to view your newly created OpenLibertyApplications resources:
kubectl get OpenLibertyApplicationsYou 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 10sA 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/systemThis 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
...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 9080Visit 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.yamlYou 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 thedeploy.yamlconfiguration 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.yamlRun the following command to check status of the pods:
kubectl describe podsLook 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=12Run the following command to set up port forwarding to access the system service:
kubectl port-forward svc/system 9080Visit 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.
When you no longer need your deployed microservice, you can delete all resources by running the following command:
kubectl delete -f deploy.yamlTo uninstall the Open Liberty Operator, run the following commands:
WINDOWS
MAC
LINUX
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.yamlOPERATOR_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.yamlYou 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.
Deploying a microservice to Kubernetes using Open Liberty Operator by Open Liberty is licensed under CC BY-ND 4.0
Prerequisites:
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
