Introducing the Payara Kubernetes Operator

When using Kubernetes, for more complex scenarios it is not enough to start the deployment or service. You also need to execute some commands within the containers to perform some configuration or initialization of the environment.

To automate configuration or the process of initializing an environment, you can write a Kubernetes operator.The Payara Kubernetes Operator, released as a Proof of Concept or Minimum Viable Product (MVP) in our June Payara Platform release, helps you to set up a Payara cluster using the Deployment Group feature of the Payara Server.

When Do You Need the Operator?

In most cases, you do not need the Kubernetes Operator to create a clustered environment within Kubernetes and the Payara Platform products.

When you need the Full Profile for your application, you can run it on the Payara Server domain server itself.  The cluster mode needs to be set to Kubernetes (see thedocumentation).  This way, several domains join the same cluster and data can be shared between them. However, replicating HTTP session data is restricted to a single domain in Payara Server, so when you cluster in Kubernetes by running multiple DAS servers, you need to use the Payara Kubernetes Operator and Payara Server's Deployment Group functionality.

Using the Deployment Group functionality of Payara Server allows you to have a cluster of instances. Setting these up within Kubernetes requires some additional actions - and the reason we created the Payara Kubernetes Operator to simplify the process.

What About Clustering with Payara Micro in Kubernetes?

When you use Payara Micro, just run the multiple instances specifying the option --clustermode kubernetes and theDomain Data Grid will cluster automatically. Data and HTTP sessions are distributed between the different instances without the need for any additional configuration or action.  You can specify the namespace and service name if you want to create multiple, separate clusters.

Installing the Payara Kubernetes Operator

We have packaged the Payara Kubernetes Operator in a Container image and placed it on the Payara Docker Hub. You can download the image with the command:

docker pull payara/payara-operator:latest

This container needs to be deployed within the Kubernetes cluster. The Kubernetes descriptor required to do this is available in the GitHub repository (payara-operator.yaml). This YAML file assumes you have built the Payara Operator yourself, for more information on what needs to be changed have a look at thedocumentation.

In addition to the installation of the operator, you also need the definition of a Custom Resource Document uploaded in the cluster. This document describes the structure of the YAML file that will be used by the Payara Kubernetes Operator to prepare your cluster.  You can do this with the command:

kubectl apply -f define-payara-domain-resource.yaml

You can read more about the installation at the documentation page.

What Does the Payara Kubernetes Operator Do?

As mentioned, the Payara Kubernetes Operator automates the creation of a Deployment Group with several instances within Kubernetes.  Based on a Custom Resource Document example to create such a Deployment Group, we explain what the operator does.

apiVersion: poc.payara.fish/v1alpha
kind: Domain
metadata:
  name: test
spec:
  application-image: k8s-demo:0.5
  instance-image: server-node-k8s:5.2021.2
  instances: 2
  application: testapp.war
  cpu: 2000
  memory: 512
  config-script: /opt/payara/k8s/test-script
  verbose: false

Based on the above document, the following steps are performed:

• A Kubernetes Deployment is created based on the image name defined in the application-image property. This image must be based on Payara Server and must start Payara Server when the container starts.
• When the Domain server is up and running, a configuration for the Payara instances is created based on the default-config with the name <name>-config (test-config in our example) when it does not already exist. If it does not exist, the JVM options are adapted so they are suited for running within a containerized environment
  (-XX:+UseContainerSupport and -XX:MaxRAMPercentage).
• A Deployment Group is created with the name <name>-dg if it does not exist already.
• The config-script property (if defined) is executed through the asadmin command tool in multimode.
• The application testapp.war is deployed to the Deployment Group. The property application can specify the filename as a relative path from /opt/payara/k8s/ or an absolute file within the Application Image.
• A Deployment and Service is prepared with the instance-image as container. This must contain (for the moment) a slightly adapted version of the Payara payara/server-node image so it works flawlessly with the Payara Kubernetes Operator in Kubernetes. The values of the properties instances, cpu, and memory, are used to define the size of your cluster.
• If you also define the property max-instances, a Horizontal Pod scaler is defined for the Payara instances so that your cluster size follows the load on your environment. The property cpu-target can be used to define the switch point for the scaler (default value is 80%).

Conclusion

An initial version of the Payara Kubernetes Operator is released to make it easier to set up a Deployment Group within Kubernetes. Once the Payara Kubernetes Operator is installed, it allows you to define an environment that uses the Payara Server Deployment Group to run your application and have HTTP session replication available. For other scenarios, a Docker image properly configured with the Kubernetes discovery mode is sufficient and recommended.

We would like to get your feedback on this first version so that we can take it into account for our future development of the Payara Kubernetes Operator. Please leave your comments on using the Payara Kubernetes Operator below, or through filing an issue on GitHub: