Hawtio Operator

A Kubernetes operator, based on the Operator SDK, that operates Hawtio Online.

Upgrading

See Upgrading Guide when you are upgrading your hawtio-operator installation.

Resources

The Hawtio Custom Resource Definition (CRD) defines the Custom Resource (CR) that the operator uses to configure a Hawtio-Online operand, e.g.:

apiVersion: hawt.io/v1
kind: Hawtio
metadata:
  name: hawtio-online
spec:
  # The deployment type, either "cluster" or "namespace":
  # - 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.
  type: cluster
  # The number of desired replicas
  replicas: 1
  # 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:
  #   <name>[-<namespace>].<suffix>
  # where <suffix> 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.
  routeHostName: hawtio-online.hawt.io
  # The compute resources required by the deployment
  resources:
    limits:
      cpu: "1"
      memory: 200Mi
    requests:
      cpu: 200m
      memory: 32Mi

Note

The version property present in previous versions of the CRD is no longer applicable and any CRs applied to the cluster, containing this property, will have it automatically removed.

Overriding the Version of Hawtio-Online

Unlike previous versions of the operator, the version of the Hawtio-Online operand is now specified during the building of the operator. Therefore, it should be unnecessary to specify this version of the container image. However, should an override be required then it is possible to add extra environment variables to the deployment resource of this operator. Specifically:

• IMAGE_VERSION: Adding this environment variable will override the version / tag of the Hawtio-Online container image, eg. 2.1.0-20240725;
• IMAGE_REPOSITORY: Adding this environment variable will override the image name / repository of the Hawtio-Online container image, eg. quay.io/hawtio/online;
• GATEWAY_IMAGE_VERSION: Adding this environment variable will override the version / tag of the 'Hawtio-Online-Gateway' container image, eg. 2.1.0-20240725;
• GATEWAY_IMAGE_REPOSITORY: Adding this environment variable will override the image name / repository of the Hawtio-Online-Gateway container image, eg. quay.io/hawtio/gateway.

Features

The operator covers the following cases:

• Creation
  • Create Deployment, ConfigMap, Service and Route resources
  • Create a service account as OAuth client in namespace deployment
  • Create an OAuth client in cluster deployment
  • Create a Secret containing a client certificate used to authenticate to Jolokia endpoints
• Update
  • Reconcile the Deployment container image with any overriding environment variables
  • Reconcile the Route host from the routeHostName field
  • Support emptying the routeHostName field (recreate the Route to re-generate the host)
  • Reconcile the replicas field into the Deployment
  • Reconcile the resources field into the Deployment
  • Support changing deployment type from / to namespace or cluster
  • Remove previous Route host from the OAuth client in cluster deployment
  • Trigger a rollout deployment on ConfigMap changes
• Deletion
  • Remove the Deployment, ConfigMap, Service and Route resources
  • Remove the service account as OAuth client in namespace deployment
  • Remove the route URL from the OAuth client authorized redirect URIs in cluster deployment
  • Remove the generated client certificate Secret

Custom TLS route certificate

TLS certificate for the created route is generated by default by Openshift, however it's possible to provide a own certificate stored in TLS secret and point to it in the CR: example:

oc create secret tls route-custom-cert --cert=tls.crt --key=tls.key

apiVersion: hawt.io/v1
kind: Hawtio
metadata:
  name: hawtio-online
spec:
...
  route:
    certSecret:
      name: route-custom-cert
...

Optionally it's possible to provide custom CA certificate in another secret:

oc create secret generic route-ca-cert --from-file=secretKey=tls.crt

...
route:
  certSecret:
    name: route-custom-cert
  caCert:
    name: route-ca-cert
    key: secretKey
...

If the 'key' isn't defined 'tls.crt' is automatically used.

Custom routes

To use custom routes, it is necessary to create the correct annotation in the service account. All the routes to annotate can be listed in the externalRoutes field in the custom resource:

  externalRoutes:
    - second-route
    - third-route

Deploy

To create the required resources by the operator (e.g. CRD, service account, roles, role binding, deployment, ...), run the following command:

make deploy

The above command must be executed on behalf of a privileged user, as the creation of the custom resource definition and the cluster role requires cluster-admin permission.

Note

To see the full list of available make commands and their optional environment variables, run:

make help

Test

To create and operate a Hawtio resource, you can run the following commands:

# Create Hawtio
$ kubectl apply -f deploy/crs/hawtio_v1_hawtio_cr.yaml
hawtio.hawt.io/hawtio-online created

# Get Hawtio info
$ kubectl get hawtio
NAME             AGE   URL                                           IMAGE
hawtio-online   16s   https://hawtio-online.192.168.64.38.nip.io   quay.io/hawtio/online:2.0.0

# Scale Hawtio
$ kubectl scale hawtio hawtio-online --replicas=3
hawtio.hawt.io/hawtio-online scaled

# Edit Hawtio resource
$ kubectl patch hawtio hawtio-online --type='merge' -p '{"spec":{"routeHostName":"hawtio.192.168.64.38.nip.io"}}'
hawtio.hawt.io/hawtio-online patched
# Check the status has updated accordingly
$ kubectl get hawtio
NAME             AGE   URL                                   IMAGE
hawtio-online   1m    https://hawtio.192.168.64.38.nip.io   quay.io/hawtio/online:latest

# Edit Hawtio config
$ kubectl edit configmap hawtio-online
configmap/hawtio-online edited
# Watch rollout deployment triggered by config change
$ kubectl rollout status deployment.v1.apps/hawtio-online
Waiting for deployment "hawtio-online" rollout to finish: 1 out of 3 new replicas have been updated...
Waiting for deployment "hawtio-online" rollout to finish: 2 out of 3 new replicas have been updated...
Waiting for deployment "hawtio-online" rollout to finish: 1 old replicas are pending termination...
deployment "hawtio-online" successfully rolled out

# Change the Hawtio version
$ kubectl patch hawtio hawtio-online --type='merge' -p '{"spec":{"version":"1.7.1"}}'
hawtio.hawt.io/hawtio-online patched
# Check the status has updated accordingly
$ kubectl get hawtio
NAME             AGE   URL                                   IMAGE
hawtio-online   1m    https://hawtio.192.168.64.38.nip.io   quay.io/hawtio/online:1.7.1
# Watch rollout deployment triggered by version change
$ kubectl rollout status deployment.v1.apps/hawtio-online
...
deployment "hawtio-online" successfully rolled out

# Delete Hawtio
$ kubectl delete hawtio hawtio-online
hawtio.hawt.io "hawtio-online" deleted

Develop

To build and test the operator locally, run the following command:

make build

Once you get hawtio-operator locally, you can run the operator as follows:

WATCH_NAMESPACE=<namespace> ./hawtio-operator

where WATCH_NAMESPACE is the mandatory environment variable. Setting WATCH_NAMESPACE= (empty) runs the operator as cluster type.

You can also specify the IMAGE_REPOSITORY environment variable to change the quay image repository for the hawtio-online instances from the default quay.io/hawtio/online to somewhere else. For example:

WATCH_NAMESPACE=hawtio IMAGE_REPOSITORY=quay.io/fuse/hawtio-online ./hawtio-operator

Likewise, you can specify the IMAGE_VERSION environment variable to change the version tag for the Hawtio-Online instances to a snapshot or self-compiled image. For example:

WATCH_NAMESPACE=hawtio IMAGE_REPOSITORY=quay.io/hawtio/online IMAGE_VERSION=2.0.0-202312061128 ./hawtio-operator