Update docs

Author: LEDfan

.github/screenshots/grafana_active_users.png

@@ -9,7 +9,7 @@ jobs:
       fail-fast: false
       matrix:
         java: [ 11 ]
-        kubernetes: [ '1.21.4', '1.20.10', 'v1.19.14', 'v1.18.20', 'v1.17.17', 'v1.16.15']
+        kubernetes: [ '1.21.3', '1.20.9', 'v1.19.14', 'v1.18.20', 'v1.17.17', 'v1.16.15']
 
     steps:
       - uses: actions/checkout@v2

.github/screenshots/message_app_page.png

@@ -4,6 +4,35 @@ Easily run ShinyProxy on a Kubernetes cluster
 
 **(c) Copyright Open Analytics NV, 2020-2021 - Apache License 2.0**
 
+## Why?
+
+Deploying and managing ShinyProxy can get complex when many apps are used,
+especially when the configuration of ShinyProxy is often updated. When
+restarting a running ShinyProxy instance (in order to update its configuration),
+users will face a disconnect from their running applications. The only solution
+to guarantee that users do not lose their connection to running apps, is to keep
+the current instance alive when updating ShinyProxy's configuration. However,
+manually keeping track of these instances would be too cumbersome and should
+therefore be automated.
+
+The ShinyProxy operator for Kubernetes is able to manage multiple ShinyProxy
+instances and their configuration. To give an example of the working of the
+operator, assume we have some ShinyProxy configuration `config1` which contains
+one app called `app1`. When the operator starts working, it checks whether a
+ShinyProxy instance exists with that configuration. If not, it starts a
+ShinyProxy instance and all other required configuration. Users can now start
+using `app1` on this instance. Some time later, the need for a second app
+arises. Therefore the administrator adapts the configuration of ShinyProxy to
+include a second app `app2`. However, some users are still using `app1` on the
+old instance. These apps may have some state, which should not be lost.
+Therefore, the operator starts a second ShinyProxy instance using configuration
+`config2`. The operator ensures that users which are currently using the first
+instance, stay on that instance. All other users, are forwarded to the new
+server and can use the new application. Nevertheless, users using an old
+instance can choose to use the new instance, by clicking a button in the user
+interface. The operator stops the old instance once it has no apps running.
+
+
 ## Building from source
 
 Clone this repository and run
@@ -41,13 +70,13 @@ now these options are specified using environment variables. All variables start
   used Kubernetes version does not support startup probes.
 - `SPO_STARTUP_PROBE_INITIAL_DELAY`: specifies the initial delay of the StartUp probe. By default this is 60 seconds.
 - `SPO_LOG_LEVEL`: configures the log level of the operator, may be one of the following:
-    - `OFF`: disables logging
-    - `ERROR`
-    - `WARN`
-    - `INFO`
-    - `DEBUG`: default (may change)
-    - `TRACE`
-    - `ALL`: enables all logging
+  - `OFF`: disables logging
+  - `ERROR`
+  - `WARN`
+  - `INFO`
+  - `DEBUG`: default (may change)
+  - `TRACE`
+  - `ALL`: enables all logging
 
 Note: in our deployments where startup probes aren't supported we have success with the following configuration:
 
@@ -57,20 +86,27 @@ Note: in our deployments where startup probes aren't supported we have success w
 
 ## Supported Versions
 
-| ShinyProxy Version  | Operator 0.0.1-20201215.112635 or older | Operator 0.0.1-SNAPSHOT-20210302.095930 or newer        |
-| ------------------- | --------------------------------------- | ------------------------------------------------------- |
-| 2.4.3 or older      | Compatible                              | Not Compatible                                          |
-| 2.5.0 or newer      | Not Compatible                          | Compatible                                              |
+The first stable release of the operator (0.1.0) is compatible with ShinyProxy
+2.6.0. Older ShinyProxy versions are supported by running development snapshots
+of the operator, however, we strongly advice to upgrade to the latest version of
+ShinyProxy and the operator for the best experience.
+
+| ShinyProxy Version | Minimum operator version         | Maximum operator version (inclusive) |
+|--------------------|----------------------------------|--------------------------------------|
+| 2.4.3              | `0.0.1-SNAPSHOT-20201215.112635` | `0.0.1-SNAPSHOT-20201215.112635`     |
+| 2.5.0              | `0.0.1-SNAPSHOT-20210302.095930` | `0.0.1-SNAPSHOT-20210607.070151`     |
+| 2.6.0              | 0.1.0                            | N/A                                  |
 
 ## Kubernetes versions
 
-| Kubernetes Version | Minimal required operator version      | Notes                                                                                                          |
-| ------------------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| v1.16              | Any version                            | Requires the use of `SPO_PROBE_INITIAL_DELAY` and `SPO_PROBE_FAILURE_THRESHOL` due to lack of startup probes.  |
-| v1.17              | Any version                            | Requires the use of `SPO_PROBE_INITIAL_DELAY` and `SPO_PROBE_FAILURE_THRESHOL` due to lack of startup probes.  |
-| v1.18              | Any version                            | Includes startup probes (as beta).                                                                             |
-| v1.19              | Any version                            |                                                                                                                |
-| v1.20              | 0.0.1-SNAPSHOT-20210113.083121         |                                                                                                                |
+| Kubernetes Version | Minimal required operator version | Notes                                                                                                                                                                                                                       |
+|--------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| v1.16              | Any version                       | Requires the use of `SPO_PROBE_INITIAL_DELAY` and `SPO_PROBE_FAILURE_THRESHOL` due to lack of startup probes.                                                                                                               |
+| v1.17              | Any version                       | Requires the use of `SPO_PROBE_INITIAL_DELAY` and `SPO_PROBE_FAILURE_THRESHOL` due to lack of startup probes.                                                                                                               |
+| v1.18              | Any version                       | Includes startup probes (as beta).                                                                                                                                                                                          |
+| v1.19              | Any version                       |                                                                                                                                                                                                                             |
+| v1.20              | 0.0.1-SNAPSHOT-20210113.083121    | This version is not officially supported by the Kubernetes API Client we use, however, integration and manual tests are performed against this version. Version 0.2.0 of the operator will officially support this version. |
+| v1.21              | 0.1.0                             | Idem as for v1.20                                                                                                                                                                                                           |
 
 ## Java Version
 

.github/screenshots/message_main_page.png

@@ -6,13 +6,15 @@ directory.
 
 ## Component and dependencies
 
-Before showing how to deploy the operator, this section describes the components and dependencies of the operator.
+Before showing how to deploy the operator, this section describes the components
+and dependencies of the operator.
 
-- **Operator**: the operator itself which manages the different ShinyProxy servers.
+- **Operator**: the operator itself which manages the different ShinyProxy
+  servers.
 - **ShinyProxy**: the ShinyProxy servers, these host the Shiny apps. You do not
-  need to create these servers manually, since these are created by the operator.
-  Instead you define which servers to create and the operator creates all
-  necessary Kubernetes resources, without affecting any existing server or
+  need to create these servers manually, since these are created by the
+  operator. Instead you define which servers to create and the operator creates
+  all necessary Kubernetes resources, without affecting any existing server or
   causing downtime.
 - **Redis**: Redis is used by ShinyProxy (not by the operator) to implement
   session persistence. This ensures that when a ShinyProxy server is replaced,
@@ -34,9 +36,9 @@ ShinyProxy operator on minikube.
 
 1. This tutorial requires that you install some tools:
 
-   - [minikube](https://github.com/kubernetes/minikube)
-   - [kubectl](https://github.com/kubernetes/kubectl)
-   - [kustomize](https://github.com/kubernetes-sigs/kustomize)
+    - [minikube](https://github.com/kubernetes/minikube)
+    - [kubectl](https://github.com/kubernetes/kubectl)
+    - [kustomize](https://github.com/kubernetes-sigs/kustomize)
 
 2. Start minikube:
 
@@ -58,8 +60,8 @@ ShinyProxy operator on minikube.
    ```
 
 5. Wait for all the resources to startup. At this point the operator should
-   start. It is now time to configure web access to the cluster.
-   First get the IP of minikube using:
+   start. It is now time to configure web access to the cluster. First get the
+   IP of minikube using:
 
    ```bash
    minikube ip
@@ -105,8 +107,7 @@ ShinyProxy operator on minikube.
 
 ## Overview of examples
 
-The Operator is designed to be flexible and fit many type of deployments. This
-repository includes examples for many kind of deployments:
+The Operator is designed to be flexible and fit many type of deployments. This repository includes examples for many kind of deployments:
 
 - *1-namespaced-hpa*:
   - Operator-mode: `namespaced`
@@ -117,8 +118,7 @@ repository includes examples for many kind of deployments:
   - ShinyProxy-namespace: `shinyproxy`
   - URLs: `https://shinyproxy-demo.local`
 
-  This is a very simple deployment of the operator, were everything runs in the same
-  namespace.
+  This is a very simple deployment of the operator, were everything runs in the same namespace.
 
 - *2-namespaced-ds*:
   - Operator-mode: `namespaced`
@@ -129,14 +129,8 @@ repository includes examples for many kind of deployments:
   - ShinyProxy-namespace: `shinyproxy`
   - URLs: `https://shinyproxy-demo.local`
 
-  This deployment is very similar to the previous one, except that it runs
-  Skipper using a `DaemonSet` instead of an automatically scaling `Deployment`.
-  Using the `DaemonSet` ensures that every Kubernetes nodes contains a Skipper
-  pod. This is useful when you want an predictable amount of Skipper pods. In
-  the previous example, the cluster automatically scales the amount of Skipper
-  pods according to the load of these pods. When properly configured, this
-  ensures that Skipper has enough resources to do its work, while not waisting
-  resources.
+  This deployment is very similar to the previous one, except that it runs Skipper using a `DaemonSet` instead of an automatically scaling `Deployment`. Using the `DaemonSet` ensures that every Kubernetes nodes contains a Skipper pod. This is useful when you want an predictable amount of Skipper pods. In the previous example, the cluster automatically scales the amount of Skipper pods according to the load of these pods. When properly configured, this ensures that Skipper has enough resources to
+  do its work, while not waisting resources.
 
 - *3-clustered-hpa*:
   - Operator-mode: `clustered`
@@ -149,14 +143,8 @@ repository includes examples for many kind of deployments:
     - `https://shinyproxy-demo.local`
     - `https://shinyproxy-demo2.local`
 
-  In this example, the operator runs in `clustered` mode. Therefore the operator
-  will look into all namespaces for `ShinyProxy` resources and deploy these
-  resources in their respective namespace. This also requires Skipper to be run
-  in clustered mode (in the previous examples it would only look at `Ingress`
-  definitions in the `shinyproxy` namespace.) This example also demonstrates how
-  the Operator can be used in a multi-tenancy or multi-realm way. Each
-  ShinyProxy server runs in its own namespace, isolated from the other servers.
-  However, they are managed by a single operator.
+  In this example, the operator runs in `clustered` mode. Therefore the operator will look into all namespaces for `ShinyProxy` resources and deploy these resources in their respective namespace. This also requires Skipper to be run in clustered mode (in the previous examples it would only look at `Ingress`
+  definitions in the `shinyproxy` namespace.) This example also demonstrates how the Operator can be used in a multi-tenancy or multi-realm way. Each ShinyProxy server runs in its own namespace, isolated from the other servers. However, they are managed by a single operator.
 
 - *4-clustered-ds*:
   - Operator-mode: `clustered`
@@ -181,9 +169,7 @@ repository includes examples for many kind of deployments:
   - URLs: `https://shinyproxy-demo.local`
 
   Similar to example example 1, however, the `01_hello` app will now run in the
-  `my-namespace` namespace instead of the `shinyproxy` namespace. In addition to
-  the change in the `shinyproxy.yaml`, this configuration requires the
-  definition of the extra namespace and the modification of the `ServiceAccount`
+  `my-namespace` namespace instead of the `shinyproxy` namespace. In addition to the change in the `shinyproxy.yaml`, this configuration requires the definition of the extra namespace and the modification of the `ServiceAccount`
   of the ShinyProxy server.
 
 - *6-namespaced-ds-multi*:
@@ -200,17 +186,23 @@ repository includes examples for many kind of deployments:
 
   Based on example 2, this example shows how multi-tenancy can be achieved using
   sub-paths instead of multiple domainnames. Each ShinyProxy server is made
-  available at the same domainname but at a different path under that domainname.
+  available at the same domainname but at a different path under that
+  domainname.
 
 ## ShinyProxy CRD
 
 The `CustomResourceDefinition` of the operator can be found in the
 `bases/namespaced/operator/crd.yaml` directory (the CRD is equal for `clustered`
-and `namespaced` deployments). The following sections of this file are important:
+and `namespaced` deployments). The following sections of this file are
+important:
 
 - `spring` config related to Spring, such as the redis connection information
-- `proxy` the configuration of ShinyProxy, this is the same configuration as if you were manually deploying ShinyProxy
+- `proxy` the configuration of ShinyProxy, this is the same configuration as if
+  you were manually deploying ShinyProxy
 - `kubernetesPodTemplateSpecPatches` allows to patch the PodTemplate
 - `image` the docker image to use for the ShinyProxy instances
 - `fqdn` the FQDN at which the service should be available
-- `appNamespaces` a list of namespaces in which apps will be deployed. This is only needed when you change the namespace of an app using the `kubernetes-pod-patches` feature. The namespace of the operator and ShinyProxy instance are automatically included
+- `appNamespaces` a list of namespaces in which apps will be deployed. This is
+  only needed when you change the namespace of an app using the
+  `kubernetes-pod-patches` feature. The namespace of the operator and ShinyProxy
+  instance are automatically included

.github/screenshots/prometheus.png

@@ -0,0 +1,69 @@
+# Prometheus Usage Statistics
+
+This page describes how the usage statistics feature of ShinyProxy works in
+combination with the operator.
+
+**Note:** this page is only applicable to ShinyProxy 2.6.0.
+
+Before diving into the details, have a look at the setup of Prometheus
+monitoring with ShinyProxy in a [regular deployment](https://shinyproxy.io/documentation/usage-statistics/#micrometer).
+
+Because the operator is meant to dynamically create ShinyProxy servers, it does
+not suffice to configure static list of ShinyProxy servers in Prometheus.
+Fortunately, Prometheus has the concept of [Service Discover](https://prometheus.io/docs/prometheus/latest/configuration/configuration/),
+which allows Prometheus to automatically *discover* ShinyProxy servers. We
+assume here that Prometheus is running in the same Kubernetes cluster as the
+ShinyProxy operator.
+
+What follows is an example configuration of Prometheus:
+
+```yaml
+scrape_configs:
+  - job_name: 'k8pods'
+    kubernetes_sd_configs:
+    - role: pod
+    relabel_configs:
+    - source_labels: [__meta_kubernetes_pod_container_port_name]
+      regex: metrics
+      action: keep
+    - source_labels: [__meta_kubernetes_pod_container_name]
+      target_label: job
+  - job_name: 'shinyproxy'
+    metrics_path: '/actuator/prometheus'
+    kubernetes_sd_configs:
+    - role: pod
+    relabel_configs:
+    # instruct Prometheus to only look for ShinyProxy servers
+    - source_labels: [__meta_kubernetes_pod_label_app]
+      regex: shinyproxy
+      action: keep
+    # instruct Prometheus to use the special actuator port (9090)
+    - source_labels: [__meta_kubernetes_pod_container_port_name]
+      regex: actuator
+      action: keep
+    # provide a value for the job label
+    - source_labels: [__meta_kubernetes_pod_container_name]
+      target_label: job
+```
+
+This configuration automatically discovers all ShinyProxy servers.
+
+![Prometheus UI](../.github/screenshots/prometheus.png)
+
+The above screenshot shows the `absolute_users_active` metric int the Prometheus
+UI. The `shinyproxy_realm` label is automatically added by ShinyProxy to every
+metric. The tag contains the resource name of the ShinyProxy server. Therefore
+this tag is not added to the metrics when ShinyProxy is not being run using the
+Operator. In the screenshot there are three ShinyProxy servers being managed by
+the ShinyProxy server and two servers using a traditional deployment. The
+`shinyproxy` realm has has two severs (instances) running (see the
+`shinyproxy_instance` label). The dashboard provided on the [ShinyProxy website](https://shinyproxy.io/documentation/usage-statistics/#micrometer) 
+is designed to work with multiple realms and multiple servers inside each realm.
+For example, when displaying the Active Users, the dashboard differentiates
+between the different realms:
+
+![Grafana UI](../.github/screenshots/grafana_active_users.png)
+
+The dashboard contains two variables which allow you to filter the panels by
+realm or app name. By default these are hidden, check the [ShinyProxy website](https://shinyproxy.io/documentation/usage-statistics/#variable-filters)
+to makes these visible.