Chapter 2. Setting up the Fuse Console on OpenShift 4.x

On OpenShift 4.x, setting up the Fuse Console involves installing and deploying it. You have these options for installing and deploying the Fuse Console:

Optionally, you can customize role-based access control (RBAC) for the Fuse Console as described in Section 2.3, “Role-based access control for the Fuse Console on OpenShift 4.x”.

2.1. Installing and deploying the Fuse Console on OpenShift 4.x by using the OperatorHub

To install the Fuse Console on OpenShift 4.x, you can use the Fuse Console Operator provided in the OpenShift OperatorHub. To deploy the Fuse Console, you create an instance of the installed operator.

Prerequisites

Role-based access control for the Fuse Console on OpenShift 4.x

Procedure

To install and deploy the Fuse Console:

  1. Log in to the OpenShift console in your web browser as a user with cluster admin access.
  2. Click Operators and then click OperatorHub.
  3. In the search field window, type Fuse Console to filter the list of operators.
  4. Click Fuse Console Operator.
  5. In the Fuse Console Operator install window, click Install.

    The Create Operator Subscription form opens.

    • For Update Channel, select 7.10.x.
    • For Installation Mode, accept the default (a specific namespace on the cluster).

      Note that after you install the operator, when you deploy the Fuse Console, you can choose to monitor applications in all namespaces on the cluster or to monitor applications only in the namespace in which the Fuse Console operator is installed.

    • For Installed Namespace, select the namespace in which you want to install the Fuse Console Operator.
    • For the Update Approval, you can select Automatic or Manual to configure how OpenShift handles updates to the Fuse Console Operator.

      • If you select Automatic updates, when a new version of the Fuse Console Operator is available, the OpenShift Operator Lifecycle Manager (OLM) automatically upgrades the running instance of the Fuse Console without human intervention.
      • If you select Manual updates, when a newer version of an Operator is available, the OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Fuse Console Operator updated to the new version.
  6. Click Install.

    OpenShift installs the Fuse Console Operator in the current namespace.

  7. To verify the installation, click Operators and then click Installed Operators. You can see the Fuse Console in the list of operators.
  8. To deploy the Fuse Console by using the OpenShift web console:

    1. In the list of Installed Operators, under the Name column, click Fuse Console.
    2. On the Operator Details page under Provided APIs, click Create Instance.

      Accept the configuration default values or optionally edit them.

      For Replicas, if you want to increase the Fuse Console performance (for example, in a high availability environment), you can increase the number of pods allocated to the Fuse Console.

      For Rbac (role-based access control), only specify a value in the config Map field if you want to customize the default RBAC behavior and if the ConfigMap file already exists in the namespace in which you installed the Fuse Console Operator. For more information about RBAC, see Role-based access control for the Fuse Console on OpenShift 4.x.

      For Nginx, see Performance tuning for Fuse Console Operator installation.

    3. Click Create.

      The Fuse Console Operator Details page opens and shows the status of the deployment.

  9. To open the Fuse Console:

    1. For a namespace deployment: In the OpenShift web console, open the project in which you installed the Fuse Console operator, and then select Overview. In the Project Overview page, scroll down to the Launcher section and click the Fuse Console link.

      For a cluster deployment, in the OpenShift web console’s title bar, click the grid icon ( mf os grid icon ). In the popup menu, under Red Hat applications, click the Fuse Console URL link.

    2. Log into the Fuse Console.

      An Authorize Access page opens in the browser listing the required permissions.

    3. Click Allow selected permissions.

      The Fuse Console opens in the browser and shows the Fuse application pods that you have authorization to access.

  10. Click Connect for the application that you want to view.

    A new browser window opens showing the application in the Fuse Console.

2.2. Installing and deploying the Fuse Console on OpenShift 4.x by using the command line

On OpenShift 4.x, you can choose one of these deployment options to install and deploy the Fuse Console from the command line:

  • cluster - The Fuse Console can discover and connect to Fuse applications deployed across multiple namespaces (projects) on the OpenShift cluster. To deploy this template, you must have the administrator role for the OpenShift cluster.
  • cluster with role-based access control - The cluster template with configurable role-based access control (RBAC). For more information, see Role-based access control for the Fuse Console on OpenShift 4.x.
  • namespace - The Fuse Console has access to a specific OpenShift project (namespace). To deploy this template, you must have the administrator role for the OpenShift project.
  • namespace with role-based access control - The namespace template with configurable RBAC. For more information, see Role-based access control for the Fuse Console on OpenShift 4.x.

To view a list of the parameters for the Fuse Console templates, run the following OpenShift command:

oc process --parameters -f https://raw.githubusercontent.com/jboss-fuse/application-templates/application-templates-2.1.0.fuse-sb2-7_10_0-00015-redhat-00001/fuse-console-namespace-os4.json

Prerequisites

Procedure

  1. Verify that the Fuse Console image stream is installed by using the following command to retrieve a list of all templates:

    oc get template -n openshift
  2. Optionally, if you want to update the already installed image stream with new release tags, use the following command to import the Fuse Console image to the openshift namespace:

    oc import-image fuse7/fuse-console-rhel8:1.10 --from=registry.redhat.io/fuse7/fuse-console-rhel8:1.10 --confirm -n openshift
  3. Obtain the Fuse Console APP_NAME value by running the following command:

    oc process --parameters -f TEMPLATE-FILENAME

    where TEMPLATE-FILENAME is one of the following templates:

  4. From the certificate that you generated in Securing the Fuse Console on OpenShift 4.x, create the secret and mount it in the Fuse Console by using the following command (where APP_NAME is the name of the Fuse Console application).

    oc create secret tls APP_NAME-tls-proxying --cert server.crt --key server.key
  5. Create a new application based on your local copy of the Fuse Console template by running the following command (where myproject is the name of your OpenShift project, mytemp is the path to the local directory that contains the Fuse Console template, and myhost is the hostname to access the Fuse Console:

    • For the cluster template:

      oc new-app -n myproject -f {templates-base-url}/fuse-console-cluster-os4.json  -p ROUTE_HOSTNAME=myhost”
    • For the cluster with RBAC template:

      oc new-app -n myproject -f {templates-base-url}/fuse-console-cluster-rbac.yml -p ROUTE_HOSTNAME=myhost”
    • For the namespace template:

      {templates-base-url}/fuse-console-namespace-os4.json
    • For the namespace with RBAC template:

      oc new-app -n myproject -f {templates-base-url}/fuse-console-namespace-rbac.yml
  6. To configure the Fuse Console so that it can open the OpenShift Web console, set the OPENSHIFT_WEB_CONSOLE_URL environment variable by running the following command:

    oc set env dc/${APP_NAME} OPENSHIFT_WEB_CONSOLE_URL=`oc get -n openshift-config-managed cm console-public -o jsonpath={.data.consoleURL}`
  7. Obtain the status and the URL of your Fuse Console deployment by running this command:

    oc status
  8. To access the Fuse Console from a browser, use the URL that is returned in Step 7 (for example, https://fuse-console.192.168.64.12.nip.io).

2.2.1. Generating a certificate to secure the Fuse Console on OpenShift 4.x

On OpenShift 4.x, to keep the connection between the Fuse Console proxy and the Jolokia agent secure, a client certificate must be generated before the Fuse Console is deployed. The service signing certificate authority private key must be used to sign the client certificate.

You must follow this procedure only if you are installing and deploying the Fuse Console by using the command line. If you are using the Fuse Console Operator, it handles this task for you.

Important

You must generate and sign a separate client certificate for each OpenShift cluster. Do not use the same certificate for more than one cluster.

Prerequisites

  • You have cluster admin access to the OpenShift cluster.
  • If you are generating certificates for more than one OpenShift cluster and you previously generated a certificate for a different cluster in the current directory, do one of the following to ensure that you generate a different certificate for the current cluster:

    • Delete the existing certificate files (for example, ca.crt, ca.key, and ca.srl) from the current directory.
    • Change to a different working directory. For example, if your current working directory is named cluster1, create a new cluster2 directory and change your working directory to it:

      mkdir ../cluster2

      cd ../cluster2

Procedure

  1. Login to OpenShift as a user with cluster admin access:

    oc login -u <user_with_cluster_admin_role>
  2. Retrieve the service signing certificate authority keys, by executing the following commands:

    • To retrieve the certificate:

      oc get secrets/signing-key -n openshift-service-ca -o "jsonpath={.data['tls\.crt']}" | base64 --decode > ca.crt
    • To retrieve the private key:

      oc get secrets/signing-key -n openshift-service-ca -o "jsonpath={.data['tls\.key']}" | base64 --decode > ca.key
  3. Generate the client certificate, as documented in Kubernetes certificates administration, using either easyrsa, openssl, or cfssl.

    Here are the example commands using openssl:

    1. Generate the private key:

      openssl genrsa -out server.key 2048
    2. Write the CSR config file.

      cat <<EOT >> csr.conf
        [ req ]
        default_bits = 2048
        prompt = no
        default_md = sha256
        distinguished_name = dn
      
        [ dn ]
        CN = fuse-console.fuse.svc
      
        [ v3_ext ]
        authorityKeyIdentifier=keyid,issuer:always
        keyUsage=keyEncipherment,dataEncipherment,digitalSignature
        extendedKeyUsage=serverAuth,clientAuth
      EOT

      Here, the values in the CN parameter refers to the application name and the namespace that the application uses.

    3. Generate the CSR:

      openssl req -new -key server.key -out server.csr -config csr.conf
    4. Issue the signed certificate:

      openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 10000 -extensions v3_ext -extfile csr.conf

Next steps

You need this certificate to create the secret for the Fuse Console as described in Installing and deploying the Fuse Console on OpenShift 4.x by using the command line.

2.3. Role-based access control for the Fuse Console on OpenShift 4.x

The Fuse Console offers role-based access control (RBAC) that infers access according to the user authorization provided by OpenShift. In the Fuse Console, RBAC determines a user’s ability to perform MBean operations on a pod.

For information on OpenShift authorization see the “Using RBAC to define and apply permissions” section of the OpenShift documentation.

Role-based access is enabled by default when you use the Operator to install the Fuse Console on OpenShift.

If you want to implement role-based access for the Fuse Console by installing it with a template, you must use one of the templates that are configurable with RBAC (fuse-console-cluster-rbac.yml or fuse-console-namespace-rbac.yml) to install the Fuse Console as described in Installing and deploying the Fuse Console on OpenShift 4.x by using the command line.

Fuse Console RBAC leverages the user’s verb access on a pod resource in OpenShift to determine the user’s access to a pod’s MBean operations in the Fuse Console. By default, there are two user roles for the Fuse Console:

  • admin

    If a user can update a pod in OpenShift, then the user is conferred the admin role for the Fuse Console. The user can perform write MBean operations in the Fuse Console for the pod.

  • viewer

    If a user can get a pod in OpenShift, then the user is conferred the viewer role for the Fuse Console. The user can perform read-only MBean operations in the Fuse Console for the pod.

Note

If you used a non-RBAC template to install the Fuse Console, only OpenShift users that are granted the update verb on the pod resource are authorized to perform the Fuse Console MBeans operations. Users that are granted the get verb on the pod resource can view the pod but they cannot perform any Fuse Console operations.

2.3.1. Determining access roles for the Fuse Console on OpenShift 4.x

The Fuse Console role-based access control is inferred from a user’s OpenShift permissions for a pod. To determine the Fuse Console access role granted to a particular user, obtain the OpenShift permissions granted to the user for a pod.

Prerequisites

  • You know the user’s name.
  • You know the pod’s name.

Procedure

  • To determine whether a user has the Fuse Console admin role for the pod, run the following command to see whether the user can update the pod on OpenShift:

    oc auth can-i update pods/<pod> --as <user>

    If the response is yes, the user has the Fuse Console admin role for the pod. The user can perform write MBean operations in the Fuse Console for the pod.

  • To determine whether a user has the Fuse Console viewer role for the pod, run the following command to see whether the user can get a pod on OpenShift:

    oc auth can-i get pods/<pod> --as <user>

    If the response is yes, the user has the Fuse Console viewer role for the pod. The user can perform read-only MBean operations in the Fuse Console for the pod. Depending on the context, the Fuse Console prevents the user with the viewer role from performing a write MBean operation, by disabling an option or by displaying an "operation not allowed for this user" message when the user attempts a write MBean operation.

    If the response is no, the user is not bound to any Fuse Console roles and the user cannot view the pod in the Fuse Console.

2.3.2. Customizing role-based access to the Fuse Console on OpenShift 4.x

If you use the OperatorHub to install the Fuse Console, role-based access control (RBAC) is enabled by default as described in Role-based access control for the Fuse Console on OpenShift 4.x. If you want to customize the Fuse Console RBAC behavior, before you deploy the Fuse Console, you must provide a ConfigMap file (that defines the custom RBAC behavior). You must place the custom ConfigMap file in the same namespace in which you installed the Fuse Console Operator.

If you use the command line templates to install the Fuse Console, the deployment-cluster-rbac.yml and deployment-namespace-rbac.yml templates create a ConfigMap that contains the configuration file (ACL.yml). The configuration file defines the roles allowed for MBean operations.

Prerequisite

  • You installed the Fuse Console by using the OperatorHub or by using one of the Fuse Console RBAC templates (deployment-cluster-rbac.yml or deployment-namespace-rbac.yml)

Procedure

To customize the Fuse Console RBAC roles:

  1. If you installed the Fuse Console by using the command line, the installation templates include a default ConfigMap file and so you can skip to the next step.

    If you installed the Fuse Console by using the OperatorHub, before you deploy the Fuse Console create a RBAC ConfigMap:

    1. Make sure the current OpenShift project is the project to which you want to install the Fuse Console. For example, if you want to install the Fuse Console in the fusetest project, run this command:

      oc project fusetest
    2. To create a Fuse Console RBAC ConfigMap file from a template, run this command:

      oc process -f https://raw.githubusercontent.com/jboss-fuse/application-templates/2.1.x.sb2.redhat-7-8-x/fuse-console-operator-rbac.yml -p APP_NAME=fuse-console | oc create -f -
  2. Open the ConfigMap in an editor by running the following command:

    oc edit cm $APP_NAME-rbac

    For example:

    oc edit cm fuse-console-rbac
  3. Edit the file.
  4. Save the file to apply the changes. OpenShift automatically restarts the Fuse Console pod.

2.3.3. Disabling role-based access control for the Fuse Console on OpenShift 4.x

If you installed the Fuse Console by using the command line and you specified one of the Fuse Console RBAC templates, the Fuse Console’s HAWTIO_ONLINE_RBAC_ACL environment variable passes the role-based access control (RBAC) ConfigMap configuration file path to the OpenShift server. If the HAWTIO_ONLINE_RBAC_ACL environment variable is not specified, RBAC support is disabled and only users that are granted the update verb on the pod resource (in OpenShift) are authorized to call MBeans operations on the pod in the Fuse Console.

Note that when you use the OperatorHub to install the Fuse Console. role-based access is enabled by default and the HAWTIO_ONLINE_RBAC_ACL environment variable does not apply.

Prerequisite

You installed the Fuse Console by using the command line and you specified one of the Fuse Console RBAC templates (deployment-cluster-rbac.yml or deployment-namespace-rbac.yml).

Procedure

To disable role-based access for the Fuse Console:

  1. In OpenShift, edit the Deployment Config resource for the Fuse Console.
  2. Delete the entire HAWTIO_ONLINE_RBAC_ACL environment variable definition.

    (Note that only clearing its value is not sufficient).

  3. Save the file to apply the changes. OpenShift automatically restarts the Fuse Console pod.

2.4. Upgrading the Fuse Console on OpenShift 4.x

Red Hat OpenShift 4.x handles updates to operators, including the Red Hat Fuse operators. For more information see the Operators OpenShift documentation.

In turn, operator updates can trigger application upgrades, depending on how the application is configured.

For Fuse Console applications, you can also trigger an upgrade to an application by editing the .spec.version field of the application custom resource definition.

Prerequisite

  • You have OpenShift cluster admin permissions.

Procedure

To upgrade a Fuse Console application:

  1. In a terminal window, use the following command to change the .spec.version field of the application custom resource definition:

    oc patch -n <project-name> <custom-resource-name> --type='merge' -p '{"spec":{"version":"1.7.1"}}'

    For example:

    oc patch -n myproject hawtio/example-fuseconsole --type='merge' -p '{"spec":{"version":"1.7.1"}}'
  2. Check that the application’s status has updated:

     oc get -n myproject hawtio/example-fuseconsole

    The response shows information about the application, including the version number:

    NAME                  AGE   URL                                        IMAGE
    example-fuseconsole   1m    https://fuseconsole.192.168.64.38.nip.io   docker.io/fuseconsole/online:1.7.1

    When you change the value of the .spec.version field, OpenShift automatically redeploys the application.

  3. To check the status of the redeployment that is triggered by the version change:

    oc rollout status deployment.v1.apps/example-fuseconsole

    A successful deployment shows this response:

    deployment "example-fuseconsole" successfully rolled out

2.5. Tuning the performance of the Fuse Console on OpenShift 4.x

By default, the Fuse Console uses the following Nginx settings:

  • clientBodyBufferSize: 256k
  • proxyBuffers: 16 128k
  • subrequestOutputBufferSize: 10m

Note: For descriptions of these settings, see the Nginx documentation: http://nginx.org/en/docs/dirindex.html

To tune performance of the Fuse Console, you can set any of the clientBodyBufferSize, proxyBuffers, and subrequestOutputBufferSize environment variables. For example, if you are using the Fuse Console to monitor numerous pods and routes (for instance, 100 routes in total), you can resolve a loading timeout issue by setting the Fuse Console’s subrequestOutputBufferSize environment variable to between 60m to 100m.

How you set these environment variables depends on how you installed the Fuse Console on Openshift 4.x:

  • By using the Fuse Console Operator
  • By using a Fuse Console template

2.5.1. Performance tuning for Fuse Console Operator installation

On Openshift 4.x, you can set the Nginx performance tuning environment variables before or after you deploy the Fuse Console. If you do so afterwards, OpenShift redeploys the Fuse Console.

Prerequisites

Procedure

You can set the environment variables before or after you deploy the Fuse Console.

  • To set the environment variables before you deploy the Fuse Console:

    1. In the OpenShift web console, in a project that has the Fuse Console Operator installed, select Operators> Installed Operators> Red Hat Integration - Fuse Console.
    2. Click the Hawtio tab, and then click Create Hawtio.
    3. On the Create Hawtio page, in the Form view, scroll down to the Config> Nginx section.
    4. Expand the Nginx section and then set the environment variables. For example:

      • clientBodyBufferSize: 256k
      • proxyBuffers: 16 128k
      • subrequestOutputBufferSize: 100m
    5. Save the configuration.
    6. Click Create to deploy the Fuse Console.
    7. After the deployment completes, open the Deployments> fuse-console page, and then click Environment to verify that the environment variables are in the list.
  • To set the environment variables after you deploy the Fuse Console:

    1. In the OpenShift web console, open the project in which the Fuse Console is deployed.
    2. Select Operators> Installed Operators> Red Hat Integration - Fuse Console.
    3. Click the Hawtio tab, and then click fuse-console.
    4. Select Actions> Edit Hawtio.
    5. In the Editor window, scroll down to the spec section.
    6. Under the spec section, add a new nginx section and specify one or more environment variables, for example:

      apiVersion: hawt.io/v1alpha1
      kind: Hawtio
      metadata:
        name: fuse-console
      spec:
        type: Namespace
        nginx:
          clientBodyBufferSize: 256k
          proxyBuffers: 16 128k
          subrequestOutputBufferSize: 100m
      .
      .
      .
    7. Click Save.

      OpenShift redeploys the Fuse Console.

    8. After the redeployment completes, open the Workloads> Deployments> fuse-console page, and then click Environment to see the environment variables in the list.

2.5.2. Performance tuning for Fuse Console template installation

On Openshift 4.x, you can set the Nginx performance tuning environment variables before or after you deploy the Fuse Console. If you do so afterwards, OpenShift redeploys the Fuse Console.

Prerequisites

Procedure

You can set the environment variables before or after you deploy the Fuse Console.

  • To set the environment variables before you deploy the Fuse Console:

    1. Determine which Fuse Console template that you want to use:

      • Cluster template (fuse-console-cluster-os4.json)
      • Cluster template with configurable RBAC (fuse-console-cluster-rbac.yml)
      • Namespace template (fuse-console-namespace-os4.json)
      • Namespace template with configurable RBAC (fuse-console-namespace-rbac.yml)
    2. Edit the local copy of the Fuse Console template that you want to use for the Fuse Console to include the NGINX_CLIENT_BODY_BUFFER_SIZE, NGINX_PROXY_BUFFERS, and/or NGINX_SUBREQUEST_OUTPUT_BUFFER_SIZE environment variables as shown in the following example:

      apiVersion: v1
      kind: DeploymentConfig
      metadata:
        name: fuse-console
      spec:
        template:
          spec:
            containers:
            - env:
              - name: NGINX_CLIENT_BODY_BUFFER_SIZE
                value: 256k
              - name: NGINX_PROXY_BUFFERS
                value: 16 128k
              - name: NGINX_SUBREQUEST_OUTPUT_BUFFER_SIZE
                value: 100m
    3. Save your changes.
    4. Follow the steps for installing and deploying the Fuse Console as as described in Setting up the Fuse Console on OpenShift 4.x.
  • To set the environment variables after you deploy the Fuse Console:

    1. In a Terminal window, login to the OpenShift cluster.
    2. Open the project in which the Fuse Console is deployed. For example, if the Fuse Console is deployed in the myfuse project, use the following command:

      oc project myfuse

    3. Obtain the name for the Fuse Console deployment:

      oc get deployments

      This command returns a list of the deployments running in the current project. For example:

      NAME                        READY   UP-TO-DATE   AVAILABLE    AGE
      fuse-console                1/1     1               1           114m
    4. Run one or more of the following commands to set the environment variables for the Fuse Console deployment:

      oc set env dc/fuse-console NGINX_CLIENT_BODY_BUFFER_SIZE="256k"
      
      oc set env dc/fuse-console NGINX_PROXY_BUFFERS="16 128k"
      
      oc set env dc/fuse-console NGINX_SUBREQUEST_OUTPUT_BUFFER_SIZE="10m"

      OpenShift redeploys the Fuse Console.

    5. After the redeployment completes, verify the environment variables settings:

      1. Obtain the Fuse Console pod name:

        oc get pods
      2. Run the following command to view the environment settings

        oc exec <fuse-console-podname> -- cat /opt/app-root/etc/nginx.d/nginx-gateway.conf | grep "Performance tuning" -A 3

        For example, if the pod name is fuse-console-6646cbbd4c-9rplg, run this command:

        oc exec fuse-console-6646cbbd4c-9rplg -- cat /opt/app-root/etc/nginx.d/nginx-gateway.conf | grep "Performance tuning" -A 3