Chapter 4. JWS Operator
4.1. JBoss Web Server Operator
4.1.1. OpenShift Operators
The Operator Framework is a toolkit to manage Kubernetes native applications, called Operators, in an effective, automated, and scalable way. Operators make it easy to manage complex stateful applications on top of Kubernetes. All Operators are based around 3 key components: The Operator SDK, The Operator Lifecycle Manager, and OperatorHub.io. These tools allow you to develop your own operators, manage any operators you are using on your Kubernetes cluster, and discover or share any Operators the community creates.
The Red Hat JBoss Web Server project provides an Operator to manage its OpenShift images. This section covers how to build, test, and package the OpenShift Operator for JWS.
For full instructions on cluster setup please refer to the Openshift Documentation subsection ‘Install’
Additionally, The JWS operator uses different environment variables than the JWS-on-OpenShift setup. A full listing of these parameters can be found here.
At this time, the 'Use Session Clustering' functionality is not fully supported.
This guide covers installation, deployment, and deletion of the JWS Operator in detail. For a faster, but less detailed, guide Please refer to the quickstarts guide.
Currently, we only support JWS 5.4 images. Images older than 5.4 are NOT supported.
4.1.2. Installing the JWS Operator
This section covers the installation of the JWS Operator on the OpenShift Container Platform.
4.1.2.1. Prerequisites
-
OpenShift Container Platform cluster using an account with
cluster admin
permissions (web console only) - OpenShift Container Platform cluster using an account with operator installation permissions
-
oc
tool installed on your local system (CLI only)
4.1.2.2. Installing the JWS Operator - web console
- Navigate to the ‘Operators’ tab, found in the menu on the left-hand side
- This will open OpenShift OperatorHub. From here, search for JWS and select the ‘JWS Operator’
- A new menu should appear - Select your desired Capacity Level and then click ‘Install’ at the top to install the Operator.
You are now able to set up the operator installation. You will specify the following 3 options:
- Installation Mode: Specify a specific namespace on your cluster to install. If you do not specify this, it will install the operator to all namespaces on your cluster by default.
- Update Channel: The JWS operator is currently available only through one channel.
- Approval Strategy: You can choose Automatic or Manual updates. If you choose Automatic updates for an installed Operator, when a new version of that Operator is available, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention. If you select Manual updates, when a newer version of an Operator is available, OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version.
-
Click ‘Install’ at the bottom. If you selected
Manual Approval Strategy
, you must approve the install plan before installation is complete. The JWS Operator will now appear in the ‘Installed Operators’ section of the ‘Operators’ tab.
4.1.2.3. Installing the JWS Operator - command line interface
Inspect the JWS operator to verify its supported installModes and available channels using the following commands:
$ oc get packagemanifests -n openshift-marketplace | grep jws jws-operator Red Hat Operators 16h
$ oc describe packagemanifests jws-operator -n openshift-marketplace | grep "Catalog Source" Catalog Source: redhat-operators
An OperatorGroup is an OLM resource that selects target namespaces in which to generate required RBAC access for all Operators in the same namespace as the OperatorGroup.
The namespace to which you subscribe the Operator must have an OperatorGroup that matches the InstallMode of the Operator, either the AllNamespaces or SingleNamespace mode. If the Operator you intend to install uses the AllNamespaces, then the openshift-operators namespace already has an appropriate OperatorGroup in place.
However, if the Operator uses the SingleNamespace mode, exactly one OperatorGroup has to be created in that namespace. To check actual list of OperatorGroups use the following command:
$ oc get operatorgroups -n <project_name>
Example of an output for OperatorGroup listing:
NAME AGE mygroup 17h
NoteThe web console version of this procedure handles the creation of the OperatorGroup and Subscription objects automatically behind the scenes for you when choosing SingleNamespace mode.
Create an OperatorGroup object YAML file, for example:
OperatorGroupExample.yaml
:apiVersion: operators.coreos.com/v1 kind: OperatorGroup metadata: name: <operatorgroup_name> namespace: <project_name> spec: targetNamespaces: - <project_name>
<project_name> is the namespace of the project where you install the operator (oc project -q). <operatorgroup_name> is the name of the OperatorGroup.
Create the OperatorGroup object using the following command:
$ oc apply -f OperatorGroupExample.yaml
Create a subscription object YAML file, for example
jws-operator-sub.yaml
. Configure yourSubscription
object YAML file to look as follows:apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: jws-operator namespace: <project_name> spec: channel: alpha name: jws-operator source: redhat-operators sourceNamespace: openshift-marketplace
<project_name> is the namespace of the project where you install the operator (oc project -q). to install in all namespace use openshift-operators.
The
source
is the Catalog Source. This is the value from the$ oc describe packagemanifests jws-operator -n openshift-marketplace | grep "Catalog Source:"
command we ran in step 1 of this section. The value should beredhat-operators
.Create the
Subscription
object from the YAML file with the following command:$ oc apply -f jws-operator-sub.yaml
To verify a successful installation, run the following command:
$ oc get csv -n <project_name>
NAME DISPLAY VERSION REPLACES PHASE jws-operator.V1.0.0
JBoss Web Server Operator
1.0.0
Succeeded
4.1.3. Deploying an existing JWS image
Ensure your operator is installed with the following command:
$ oc get deployment.apps/jws-operator NAME READY UP-TO-DATE AVAILABLE AGE jws-operator 1/1 1 1 15h
Or if you need a more detailed output:
$ oc describe deployment.apps/jws-operator
-
Prepare your image and push it to the desired location. In this example it is pushed to
quay.io/<USERNAME>/tomcat-demo:latest
Create a
Custom Resource
WebServer .yaml file. In this example a file calledwebservers_cr.yaml
is used. Your file should follow this format:apiVersion: web.servers.org/v1alpha1 kind: WebServer metadata: name: example-image-webserver spec: # Add fields here applicationName: jws-app replicas: 2 webImage: applicationImage: quay.io/<USERNAME>/tomcat-demo:latest
Deploy your webapp, from the directory in which you created it, with the following command:
$ oc apply -f webservers_cr.yaml webserver/example-image-webserver created
NoteThe operator will create a route automatically. You can verify the route with the following command:
$ oc get routes
For more information on routes, please see the OpenShift documentation
If you need delete the
webserver
you created in step 4:$ oc delete webserver example-image-webserver
OR
$ oc delete -f webservers_cr.yaml
4.1.4. Deleting Operators from a cluster
4.1.4.1. Prerequisites
- OpenShift Container platform cluster with admin privileges (Alternatively, you can circumvent this requirement by following these instructions )
-
oc
tool installed on your local system (CLI only)
4.1.4.2. Deleting an operator from a cluster - web console
-
In the left hand menu, click ‘Operators’
‘Installed Operators’ - Underneath ‘Operator Details’ select the ‘Actions’ menu, and then click ‘Uninstall Operator’
- Selecting this option will remove the Operator, any Operator deployments, and Pods. HOWEVER removing the Operator will not remove any of its custom resource definitions or custom resources, including CRDs or CRs. If your operator has deployed applications on the cluster or configured off-cluster resources, these will continue to run and need to be cleaned up manually.
4.1.4.3. Deleting an operator from a cluster - command line interface
Check the current version of the subscribed operator in the
currentCSV
field by using the following command:$ oc get subscription jws-operator -n <project_name> -o yaml | grep currentCSV f:currentCSV: {} currentCSV: jws-operator.v1.0.0
NoteIn the above command,
<project_name>
refers to the namespace of the project where you installed the operator. If your operator was installed to all namespaces, useopenshift-operators
in place of<project_name>
.Delete the operator’s subscription using the following command:
$ oc delete subscription jws-operator -n <project_name>
NoteIn the above command,
<project_name>
refers to the namespace of the project where you installed the operator. If your operator was installed to all namespaces, useopenshift-operators
in place of<project_name>
.Delete the CSV for the operator in the target namespace using the currentCSV value from the previous step, using the following command:
$ oc delete clusterserviceversion <currentCSV> -n <project_name>
where
<currentCSV>
is the value obtained in step 1$ oc delete clusterserviceversion jws-operator.v1.0.0 clusterserviceversion.operators.coreos.com "jws-operator.v1.0.0" deleted
NoteIn the above command,
<project_name>
refers to the namespace of the project where you installed the operator. If your operator was installed to all namespaces, useopenshift-operators
in place of<project_name>
.
4.1.5. Additional resources
For additional information on Operators, you may refer to the formal OpenShift Documentation:
And