diff --git a/README.md b/README.md index 78a52c91ef..ded4e0ec51 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,10 @@ See [Upgrading Guide](docs/upgrading.md) when you are upgrading your hawtio-oper ## Resources -The `Hawtio` CRD defines the resource the operator uses to configure a Hawtio Online operand, e.g.: +The `Hawtio` Custom Resource Definition (CRD) defines the Custom Resource (CR) that the operator uses to configure a `Hawtio-Online` operand, e.g.: ```yaml -apiVersion: hawt.io/v1alpha1 +apiVersion: hawt.io/v1 kind: Hawtio metadata: name: hawtio-online @@ -34,8 +34,6 @@ spec: # 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 version (default 'latest') - version: latest # The compute resources required by the deployment resources: limits: @@ -45,6 +43,14 @@ spec: 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.0.0-20231208`; +- IMAGE_REPOSITORY: Adding this environment variable will override the image name / repository of the `Hawtio-Online` container image, eg. `quay.io/hawtio/online`. ## Features @@ -56,7 +62,7 @@ The operator covers the following cases: * 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 from the `version` field + * 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 @@ -72,7 +78,7 @@ The operator covers the following cases: ### Custom TLS route certificate -TLS certificate for the created route is generated by default by Openshift, however it's possible to provide +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: @@ -81,7 +87,7 @@ oc create secret tls route-custom-cert --cert=tls.crt --key=tls.key ``` ```yaml -apiVersion: hawt.io/v1alpha1 +apiVersion: hawt.io/v1 kind: Hawtio metadata: name: hawtio-online @@ -90,7 +96,7 @@ spec: route: certSecret: name: route-custom-cert -... +... ``` Optionally it's possible to provide custom CA certificate in another secret: @@ -113,7 +119,7 @@ route: 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. +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: ```yaml @@ -131,19 +137,25 @@ 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: +> ```console +> make help +> ``` + ## Test To create and operate a Hawtio resource, you can run the following commands: ```console # Create Hawtio -$ kubectl apply -f deploy/crs/hawtio_v1alpha1_hawtio_cr.yaml +$ 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 docker.io/hawtio/online:latest +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 @@ -155,7 +167,7 @@ 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 docker.io/hawtio/online:latest +hawtio-online 1m https://hawtio.192.168.64.38.nip.io quay.io/hawtio/online:latest # Edit Hawtio config $ kubectl edit configmap hawtio-online @@ -173,7 +185,7 @@ 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 docker.io/hawtio/online:1.7.1 +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 ... @@ -200,8 +212,14 @@ WATCH_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 `IMAGE_REPOSITORY` environment variable to change the docker image repository for the hawtio-online instances from the default `docker.io/hawtio/online` to somewhere else. For example: +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: + +```console +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: ```console -WATCH_NAMESPACE=hawtio IMAGE_REPOSITORY=docker.io/fuse/hawtio-online ./hawtio-operator +WATCH_NAMESPACE=hawtio IMAGE_REPOSITORY=quay.io/hawtio/online IMAGE_VERSION=2.0.0-202312061128 ./hawtio-operator ```