Chapter 6. Setting up HawtIO on OpenShift 4
Chapter 6. Setting up HawtIO on OpenShift 4 Note While HawtIO Online should be able to discover Fuse 7 apps, the Camel plugin that is included only supports Camel 4.x models. It is most likely unusable to manage Fuse 7 Camel routes with the HawtIO 4. On OpenShift 4.x, setting up HawtIO involves installing and deploying it. The preferred mechanism for this installation is using the HawtIO Operator available from the OperatorHub ]). Optionally, you can customize role-based access control (RBAC) for HawtIO as described in xref:role-based-access-control-for-hawtio-on-openshift-4[ . 6.1. Installing and deploying HawtIO on OpenShift 4 by using the OperatorHub The HawtIO Operator is provided in the OpenShift OperatorHub for the installation of HawtIO. To deploy HawtIO you will have to deploy an instance of the installed operator as well as a HawtIO Custom Resource (CR). To install and deploy HawtIO: Log in to the OpenShift console in the web browser as a user with cluster admin access. Click Operators and then click OperatorHub . In the search field window, type HawtIO to filter the list of operators. Click HawtIO Operator . In the HawtIO Operator install window, click Install . The Create Operator Subscription form opens: For Update Channel , select stable-v1 . For Installation Mode , accept the default (a specific namespace on the cluster). Note This mode determines what namespaces the operator will monitor for HawtIO CRs. This is different to what namespaces HawtIO will monitor when it is fully deployed. The latter can be configured via the HawtIO CR. For Installed Namespace , select the namespace in which you want to install HawtIO Operator. For the Update Approval , select Automatic or Manual to configure how OpenShift handles updates to HawtIO Operator. If the Automatic updates option is selected and a new version of HawtIO Operator is available, the OpenShift Operator Lifecycle Manager (OLM) automatically upgrades the running instance of HawtIO without human intervention; If the Manual updates option is selected and a newer version of an Operator is available, the OLM only creates an update request. A Cluster Administrator must then manually approve the update request to have HawtIO Operator updated to the new version. Click Install and OpenShift installs HawtIO Operator into the current namespace. To verify the installation, click Operators and then click Installed Operators . HawtIO should be visible in the list of operators. To deploy HawtIO by using the OpenShift web console: In the list of Installed Operators , under the Name column, click HawtIO Operator . On the Operator Details page under Provided APIs , click Create HawtIO . Accept the configuration default values or optionally edit them. For Replicas , to increase HawtIO performance (for example, in a high availability environment), the number of pods allocated to HawtIO can be increased; For RBAC (role-based access control), only specify a value in the Config Map field if you want to customize the default RBAC behaviour and if the ConfigMap file already exists in the namespace in which you installed HawtIO Operator For Nginx , see Performance tuning for HawtIO Operator installation For Type , specify either: Cluster : for HawtIO to monitor all namespaces on the OpenShift cluster for any HawtIO-enabled applications; Namespace : for HawtIO to monitor only the HawtIO-enabled applications that have been deployed in the same namespace. Click Create . The HawtIO Operator Details page opens and shows the status of the deployment. To open HawtIO : For a namespace deployment: In the OpenShift web console, open the project in which the HawtIO operator is installed, and then select Overview . In the Project Overview page, scroll down to the Launcher section and click the HawtIO link. For a cluster deployment, in the OpenShift web console's title bar, click the grid icon. In the popup menu, under Red Hat Applications , click the HawtIO URL link. Log into HawtIO. An Authorize Access page opens in the browser listing the required permissions. Click Allow selected permissions . HawtIO opens in the browser and shows any HawtIO-enabled application pods that are authorized for access. Click Connect to view the monitored application. A new browser window opens showing the application in HawtIO. 6.2. Role-based access control for HawtIO on OpenShift 4 HawtIO offers role-based access control (RBAC) that infers access according to the user authorization provided by OpenShift. In HawtIO, 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 HawtIO on OpenShift. HawtIO 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 HawtIO. By default, there are two user roles for HawtIO: admin : if a user can update a pod in OpenShift, then the user is conferred the admin role for HawtIO. The user can perform write MBean operations in HawtIO for the pod. viewer : if a user can get a pod in OpenShift, then the user is conferred the viewer role for HawtIO. The user can perform read-only MBean operations in HawtIO for the pod. 6.2.1. Determining access roles for HawtIO on OpenShift 4 HawtIO role-based access control is inferred from a user's OpenShift permissions for a pod. To determine HawtIO access role granted to a particular user, obtain the OpenShift permissions granted to the user for a pod. Prerequisites : The user's name The pod's name Procedure : To determine whether a user has HawtIO 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 admin role for the pod. The user can perform write operations in HawtIO for the pod. To determine whether a user has HawtIO 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 viewer role for the pod. The user can perform read-only operations in HawtIO for the pod. Depending on the context, HawtIO 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 HawtIO roles and the user cannot view the pod in HawtIO. 6.2.2. Customizing role-based access to HawtIO on OpenShift 4 If you use the OperatorHub to install HawtIO, role-based access control (RBAC) is enabled by default. To customize HawtIO RBAC behaviour, before deployment of HawtIO, a ConfigMap resource (that defines the custom RBAC behaviour) must be provided. The name of this ConfigMap should be entered in the rbac configuration section of the HawtIO Custom Resource (CR). The custom ConfigMap resource must be added in the same namespace in which the HawtIO Operator has been installed. Prerequisite : The HawtIO Operator has been installed from the OperatorHub. Procedure : To customize HawtIO RBAC roles: Create an RBAC ConfigMap: Make sure the current OpenShift project is the project to which you want to install HawtIO. For example, to install HawtIO in the hawtio-test project, run this command: oc project hawtio-test Create a HawtIO RBAC ConfigMap file from the template, and run this command: oc process -f https://raw.githubusercontent.com/hawtio/hawtio-online/2.x/docker/ACL.yaml -p APP_NAME=custom-hawtio | oc create -f - Edit the new custom ConfigMap, using the command: oc edit ConfigMap custom-hawtio-rbac By saving the edits, the ConfigMap resource will be updated Create a new HawtIO CR, as described above, and edit the rbac section by adding the name of the new ConfigMap under the property configMap . Click Create . The operator should deploy a new version of HawtIO making use of the custom ConfigMap 6.3. Migrating from Fuse Console The version of the HawtIO Custom Resource Definition (CRD) has been upgraded in HawtIO from v1alpha1 to v1 . This means that upon install of the HawtIO operator, all existing Fuse-Console Custom Resources (CRs) will be upgraded to this new version. The current schema properties of the CRD remain unchanged. The CRD version property remains in the CRD but is no longer used by the HawtIO operator for installing HawtIO; it remains so that the Fuse-Console operator is still able to install Fuse-Console correctly. HawtIO and Fuse-Console should perform as separate and independent applications. 6.4. Upgrading HawtIO on OpenShift 4 Red Hat OpenShift 4.x handles updates to operators, including HawtIO operators. For more information see the Operators OpenShift documentation . In turn, the operator updates will trigger application upgrades, depending on how the application is configured. 6.5. Tuning the performance of HawtIO on OpenShift 4 By default, HawtIO uses the following Nginx settings: clientBodyBufferSize: 256k proxyBuffers: 16 128k subrequestOutputBufferSize: 10m Note For descriptions of these settings, see the Nginx documentation . To tune the performance of HawtIO, you can set any of the clientBodyBufferSize , proxyBuffers , and subrequestOutputBufferSize environment variables. For example, if you are using HawtIO to monitor numerous pods and routes (for instance, 100 routes in total), you can resolve a loading timeout issue by setting HawtIO's subrequestOutputBufferSize environment variable between 60m to 100m . 6.5.1. Performance tuning for HawtIO Operator installation On Openshift 4.x, you can set the Nginx performance tuning environment variables before or after you deploy HawtIO. If you do so afterwards, OpenShift redeploys HawtIO. Prerequisite : You must have cluster admin access to the OpenShift cluster. Procedure : You can set the environment variables before or after you deploy HawtIO. To set the environment variables before deploying HawtIO : In the OpenShift web console, in a project that has HawtIO Operator installed, select Operators> Installed Operators> HawtIO Operator . Click the HawtIO tab, and then click Create HawtIO . On the Create HawtIO page, in the Form view , scroll down to the Config> Nginx section. Expand the Nginx section and then set the environment variables. For example: clientBodyBufferSize: 256k proxyBuffers: 16 128k subrequestOutputBufferSize: 100m Click Create to deploy HawtIO. After the deployment completes, open the Deployments> HawtIO-console page, and then click Environment to verify that the environment variables are in the list. To set the environment variables after you deploy HawtIO : In the OpenShift web console, open the project in which HawtIO is deployed. Select Operators> Installed Operators> HawtIO Operator . Click the HawtIO tab, and then click HawtIO . Select Actions> Edit HawtIO . In the Editor window, scroll down to the spec section. Under the spec section, add a new nginx section and specify one or more environment variables, for example: apiVersion: hawt.io/v1 kind: HawtIO metadata: name: hawtio-console spec: type: Namespace nginx: clientBodyBufferSize: 256k proxyBuffers: 16 128k subrequestOutputBufferSize: 100m Click Save . OpenShift redeploys HawtIO. After the redeployment completes, open the Workloads> Deployments> HawtIO-console page, and then click Environment to see the environment variables in the list. 6.5.2. Performance tuning for viewing applications on HawtIO Enhanced performance tuning capability of HawtIO allows viewing of the applications with a large number of MBeans. To use this capability perform the following steps. Prerequisite : You must have cluster admin access to the OpenShift cluster. Procedure : Increase the memory limit for the applications. To increase the memory limits after deploying HawtIO : In the OpenShift web console, open the project in which HawtIO is deployed. Select Operators> Installed Operators> HawtIO Operator . Click the HawtIO tab, and then click HawtIO . Select Actions> Edit HawtIO . In the Editor window, scroll down to the spec.resources section. Update the values for both requests and limits to preferred amounts Click Save HawtIO should re-deploy using the new resource specification. 6.6. HawtIO CR properties This section includes all custom resource properties that can be customized, including branding, about and console links. auth : The authentication configuration | type: object clientCertCheckSchedule : CronJob schedule that defines how often the expiry of the certificate will be checked. Client rotation isn't enabled if the schedule isn't set | type: string clientCertCommonName : The generated client certificate CN | type: string clientCertExpirationDate : The generated client certificate expiration date | type: string | format: date-time clientCertExpirationPeriod : The duration in hours before the expiration date, during which the certification can be rotated. The default is set to 24 hours | type: integer config : The HawtIO console configuration | type: object about: The information to be displayed in the About page | type: object additionalInfo : The text for the description section | type: string copyright : The text for the copyright section | type: string imgSrc : The image displayed in the page. It can be a path, relative to the HawtIO status URL, or an absolute URL | type: string productInfo : List of product information | type: array items : The product information displayed in the About page | type: object | required: [ "name", "value" ] name : The name of the product information | type: string value : The value of the product information | type: string title : The title of the page | type: string branding : The UI branding | type: object appLogoUrl : The URL of the logo, that displays in the navigation bar. It can be a path, relative to the HawtIO status URL, or an absolute URL. | type: string appName : The application title, that usually displays in the Web browser tab. | type: string css : The URL of an external CSS stylesheet, that can be used to style the application. It can be a path, relative to the HawtIO status URL, or an absolute URL. | type: string favicon : The URL of the favicon, that usually displays in the Web browser tab. It can be a path, relative to the HawtIO status URL, or an absolute URL. | type: string disabledRoutes : Disables UI components with matching routes | type: array | items : type: string online : The OpenShift related configuration | type: object consoleLink : The configuration for the OpenShift Web console link. A link is added to the application menu when the HawtIO deployment is equal to 'cluster'. Otherwise, a link is added to the HawtIO project dashboard. | type: object imageRelativePath : The path, relative to the HawtIO status URL, for the icon used in front of the link in the application menu. It is only applicable when the HawtIO deployment type is equal to cluster . The image should be square and will be shown at 24x24 pixels. | type: string section : The section of the application menu in which the link should appear. It is only applicable when the HawtIO deployment type is equal to 'cluster'. | type: string text : The text display for the link | type: string projectSelector : The selector used to watch for projects. It is only applicable when the HawtIO deployment type is equal to 'cluster'. By default, all the projects the logged in user has access to are watched. The string representation of the selector must be provided, as mandated by the --selector , or -l , options from the kubectl get command. See: Kubernetes Labels and Selectors | type: string externalRoutes : List of external route names that will be annotated by the operator to access the console using the routes | type: array | items : type: string metadataPropagation : The configuration for which metadata on HawtIO custom resources to propagate to generated resources such as deployments, pods, services, and routes | type: object annotations : Annotations to propagate | type: array | items : type: string labels : Labels to propagate | type: array | items : type: string nginx : The Nginx runtime configuration type: object clientBodyBufferSize : The buffer size for reading client request body. Defaults to 256k . | type: string proxyBuffers : The number and size of the buffers used for reading a response from the proxied server, for a single connection. Defaults to 16 128k . | type: string subrequestOutputBufferSize : The size of the buffer used for storing the response body of a subrequest. Defaults to 10m . | type: string rbac : The RBAC configuration | type: object configMap : The name of the ConfigMap that contains the ACL definition. | type: string disableRBACRegistry : Disable performance improvement brought by RBACRegistry and revert to the classic behavior. Defaults to false . | type: boolean replicas : Number of desired pods. This is a pointer to distinguish between explicit zero and not specified. Defaults to 1. | type: integer | format: int32 resources : The HawtIO console compute resources | type: object claims : Claims lists the names of resources, defined in spec.resourceClaims, that are used by this container. This is an alpha field and requires enabling the DynamicResourceAllocation feature gate. This field is immutable. It can only be set for containers. | type: array | items : ResourceClaim references one entry in PodSpec.ResourceClaims. | type: object | required: [ "name" ] name : Name must match the name of one entry in pod.spec.resourceClaims of the Pod where this field is used. It makes that resource available inside a container. | type: string limits : Limits describes the maximum amount of compute resources allowed. See: Kubernetes Resource Management for Pods and Containers | type: object requests : Requests describes the minimum amount of compute resources required. If Requests is omitted for a container, it defaults to Limits if that is explicitly specified, otherwise to an implementation-defined value. Requests cannot exceed Limits. See: Kubernetes Resource Management for Pods and Containers | type: object route : Custom certificate configuration for the route (not necessary on most OpenShift installations). | type: object caCert : Ca certificate secret key selector | type: object | required: [ "key" ] key : The key of the secret to select from. Must be a valid secret key. | type: string name : Name of the referent. See: Kubernetes Names | type: string optional : Specify whether the Secret or its key must be defined | type: boolean certSecret : Name of the TLS secret with the custom certificate used for the route TLS termination | type: object name : Name of the referent. See: Kubernetes Names | type: string routeHostName : The edge host name of the route that exposes the HawtIO service externally. If not specified, it is automatically generated and is of the form: [-]. where is the default routing sub-domain as configured for the cluster. Note that the operator will recreate the route if the field is emptied, so that the host is re-generated. | type: string type : The deployment type. Defaults to cluster . | type: string cluster : HawtIO is capable of discovering and managing applications across all namespaces the authenticated user has access to. namespace : HawtIO is capable of discovering and managing applications within the deployment namespace. version : The HawtIO console container image version. Deprecated : Remains for legacy purposes in respect of older operators (<1.0.0) still requiring it for their installs. | type: string
auth can-i update pods/<pod> --as <user> auth can-i get pods/<pod> --as <user> project hawtio-test process -f https://raw.githubusercontent.com/hawtio/hawtio-online/2.x/docker/ACL.yaml -p APP_NAME=custom-hawtio | oc create -f - edit ConfigMap custom-hawtio-rbac apiVersion: hawt.io/v1 kind: HawtIO metadata: name: hawtio-console spec: type: Namespace nginx: clientBodyBufferSize: 256k proxyBuffers: 16 128k subrequestOutputBufferSize: 100m