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.

Important

At this time, the Use Session Clustering functionality is available as technology preview (not supported). The clustering is Off by default. The current operator version uses the DNS Membership Provider which is limited due to DNS limitations. InetAddress.getAllByName() results are cached and as a result, session replications may not work while scaling up.

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.

Important

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

  1. Navigate to the ‘Operators’ tab, found in the menu on the left-hand side
  2. This will open OpenShift OperatorHub. From here, search for JWS and select the ‘JWS Operator’
  3. A new menu should appear - Select your desired Capacity Level and then click ‘Install’ at the top to install the Operator.

  4. 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.
  5. 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

  1. 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

  2. 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
    Note

    The 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

  3. Create a subscription object YAML file, for example jws-operator-sub.yaml. Configure your Subscription 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 be redhat-operators.

  4. 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>
    NAMEDISPLAYVERSIONREPLACES PHASE

    jws-operator.V1.0.0

    JBoss Web Server Operator

    1.0.0

    Succeeded

4.1.3. Deploying an existing JWS image

  1. 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
  2. Prepare your image and push it to the desired location. In this example it is pushed to quay.io/<USERNAME>/tomcat-demo:latest

  3. Create a Custom Resource WebServer .yaml file. In this example a file called webservers_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

  4. 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
    Note

    The 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

  5. 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

  1. In the left hand menu, click ‘Operators’ → ‘Installed Operators’
  2. Underneath ‘Operator Details’ select the ‘Actions’ menu, and then click ‘Uninstall Operator’
  3. 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

  1. 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
    Note

    In 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, use openshift-operators in place of <project_name>.

  2. Delete the operator’s subscription using the following command: 

    $   oc delete subscription jws-operator -n <project_name>
    Note

    In 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, use openshift-operators in place of <project_name>.

  3. 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
    Note

    In 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, use openshift-operators in place of <project_name>.

4.1.5. Additional resources

For additional information on Operators, you may refer to the formal OpenShift Documentation:

What are Operators?

And

Openshift Container Platform