@@ -6,24 +6,31 @@ Easily run ShinyProxy on a Kubernetes cluster
66
77## Why?
88
9- Deploying and managing ShinyProxy can get complex when many apps are used, especially when the configuration of
10- ShinyProxy is often updated. When restarting a running ShinyProxy instance (in order to update its configuration), users
11- will face a disconnect from their running applications. The only solution to guarantee that users do not lose their
12- connection to running apps, is to keep the current instance alive when updating ShinyProxy's configuration. However,
13- manually keeping track of these instances would be too cumbersome and should therefore be automated.
14-
15- The ShinyProxy operator for Kubernetes is able to manage multiple ShinyProxy instances and their configuration. To give
16- an example of the working of the operator, assume we have some ShinyProxy configuration ` config1 ` which contains one app
17- called ` app1 ` . When the operator starts working, it checks whether a ShinyProxy instance exists with that configuration.
18- If not, it starts a ShinyProxy instance and all other required configuration. Users can now start using ` app1 ` on this
19- instance. Some time later, the need for a second app arises. Therefore the administrator adapts the configuration of
20- ShinyProxy to include a second app ` app2 ` . However, some users are still using ` app1 ` on the old instance. These apps
21- may have some state, which should not be lost. Therefore, the operator starts a second ShinyProxy instance using
22- configuration
23- ` config2 ` . The operator ensures that users which are currently using the first instance, stay on that instance. All
24- other users, are forwarded to the new server and can use the new application. Nevertheless, users using an old instance
25- can choose to use the new instance, by clicking a button in the user interface. The operator stops the old instance once
26- it has no apps running.
9+ Deploying and managing ShinyProxy can get complex when many apps are used,
10+ especially when the configuration of ShinyProxy is often updated. When
11+ restarting a running ShinyProxy instance (in order to update its configuration),
12+ users will face a disconnect from their running applications. The only solution
13+ to guarantee that users do not lose their connection to running apps, is to keep
14+ the current instance alive when updating ShinyProxy's configuration. However,
15+ manually keeping track of these instances would be too cumbersome and should
16+ therefore be automated.
17+
18+ The ShinyProxy operator for Kubernetes is able to manage multiple ShinyProxy
19+ instances and their configuration. To give an example of the working of the
20+ operator, assume we have some ShinyProxy configuration ` config1 ` which contains
21+ one app called ` app1 ` . When the operator starts working, it checks whether a
22+ ShinyProxy instance exists with that configuration. If not, it starts a
23+ ShinyProxy instance and all other required configuration. Users can now start
24+ using ` app1 ` on this instance. Some time later, the need for a second app
25+ arises. Therefore, the administrator adapts the configuration of ShinyProxy to
26+ include a second app ` app2 ` . However, some users are still using ` app1 ` on the
27+ old instance. These apps may have some state, which should not be lost.
28+ Therefore, the operator starts a second ShinyProxy instance using configuration
29+ ` config2 ` . The operator ensures that users which are currently using the first
30+ instance, stay on that instance. All other users, are forwarded to the new
31+ server and can use the new application. Nevertheless, users using an old
32+ instance can choose to use the new instance, by clicking a button in the user
33+ interface. The operator stops the old instance once it has no apps running.
2734
2835## Building from source
2936
@@ -33,75 +40,85 @@ Clone this repository and run
3340mvn -U clean install
3441```
3542
36- The build will result in a single ` .jar ` file: ` target/target/shinyproxy-operator-jar-with-dependencies.jar ` .
43+ The build will result in a single ` .jar ` file:
44+ ` target/target/shinyproxy-operator-jar-with-dependencies.jar ` .
3745
3846## Running
3947
40- The operator should be run in Kubernetes using
41- the [ docker image ] ( https://hub.docker.com/r/openanalytics/shinyproxy-operator-snapshot ) . It can run in
42- either ` clustered ` scope or ` namespaced ` mode. In the former the operator looks for ShinyProxy instances in all
43- namespaces while in the latter it only manages ShinyProxy instances in its own namespace.
48+ The operator should be run in Kubernetes using the [ docker image ] ( https://hub.docker.com/r/openanalytics/shinyproxy-operator-snapshot ) .
49+ It can run in either ` clustered ` scope or ` namespaced ` mode. In the former the
50+ operator looks for ShinyProxy instances in all namespaces while in the latter it
51+ only manages ShinyProxy instances in its own namespace.
4452
4553See the [ docs/deployment] ( docs/deployment ) folder for more information.
4654
4755## Configuration
4856
49- We try to keep the configuration of the Operator itself as minimum as possible. Furthermore we want the operator to work
50- without configuration in most cases. Nevertheless, for some specific cases some configuration options are available. For
51- now these options are specified using environment variables. All variables start with the ` SPO ` prefix, meaning ** S**
52- hiny** P** roxy** O** perator.
53-
54- - ` SPO_MODE ` : can either be ` namespaced ` or ` clustered ` (default). This specifies whether the operator should only look
55- in its own namespace for ShinyProxy configurations or in all namespaces.
56- - ` SPO_DISABLE_SECURE_COOKIES ` : when set to any value, this disables the ` secure ` flag on all cookies used by the
57- Operator.
58- - ` SPO_PROBE_INITIAL_DELAY ` : specifies the initial delay of the Readiness and Liveness probes. This is useful when the
59- used Kubernetes version does not support startup probes.
60- - ` SPO_PROBE_FAILURE_THRESHOLD ` : specifies the failure threshold of the Readiness and Liveness probes. This is useful
61- when the used Kubernetes version does not support startup probes.
62- - ` SPO_PROBE_TIMEOUT ` : specifies the timeout in seconds of the Readiness and Liveness probes. This is useful when the
63- used Kubernetes version does not support startup probes.
64- - ` SPO_STARTUP_PROBE_INITIAL_DELAY ` : specifies the initial delay of the StartUp probe. By default this is 60 seconds.
65- - ` SPO_LOG_LEVEL ` : configures the log level of the operator, may be one of the following:
66- - ` OFF ` : disables logging
67- - ` ERROR `
68- - ` WARN `
69- - ` INFO `
70- - ` DEBUG ` : default (may change)
71- - ` TRACE `
72- - ` ALL ` : enables all logging
73-
74- Note: in our deployments where startup probes aren't supported we have success with the following configuration:
75-
76- - ` SPO_PROBE_INITIAL_DELAY ` to something between 40 and 140 depending on the performance of the cluster.
57+ We try to keep the configuration of the Operator itself as minimum as possible.
58+ Furthermore, we want the operator to work without configuration in most cases.
59+ Nevertheless, for some specific cases some configuration options are available.
60+ For now these options are specified using environment variables. All variables
61+ start with the ` SPO ` prefix, meaning ** S** hiny** P** roxy** O** perator.
62+
63+ - ` SPO_MODE ` : can either be ` namespaced ` or ` clustered ` (default). This
64+ specifies whether the operator should only look in its own namespace for
65+ ShinyProxy configurations or in all namespaces.
66+ - ` SPO_DISABLE_SECURE_COOKIES ` : when set to any value, this disables the
67+ ` secure ` flag on all cookies used by the Operator.
68+ - ` SPO_PROBE_INITIAL_DELAY ` : specifies the initial delay of the Readiness and
69+ Liveness probes. This is useful when the used Kubernetes version does not
70+ support startup probes.
71+ - ` SPO_PROBE_FAILURE_THRESHOLD ` : specifies the failure threshold of the
72+ Readiness and Liveness probes. This is useful when the used Kubernetes version
73+ does not support startup probes.
74+ - ` SPO_PROBE_TIMEOUT ` : specifies the timeout in seconds of the Readiness and
75+ Liveness probes. This is useful when the used Kubernetes version does not
76+ support startup probes.
77+ - ` SPO_STARTUP_PROBE_INITIAL_DELAY ` : specifies the initial delay of the StartUp probe. By default, this is 60 seconds.
78+ - ` SPO_LOG_LEVEL ` : configures the log level of the operator, may be one of the
79+ following:
80+ - ` OFF ` : disables logging
81+ - ` ERROR `
82+ - ` WARN `
83+ - ` INFO `
84+ - ` DEBUG ` : default (may change)
85+ - ` TRACE `
86+ - ` ALL ` : enables all logging
87+
88+ Note: in our deployments where startup probes aren't supported we have success
89+ with the following configuration:
90+
91+ - ` SPO_PROBE_INITIAL_DELAY ` to something between 40 and 140 depending on the
92+ performance of the cluster.
7793- ` SPO_PROBE_FAILURE_THRESHOLD ` to ` 2 `
7894- ` SPO_PROBE_TIMEOUT ` to ` 3 `
7995
8096## Supported Versions
8197
82- The first stable release of the operator (0.1.0) is compatible with ShinyProxy 2.6.0. Older ShinyProxy versions are
83- supported by running development snapshots of the operator, however, we strongly advice to upgrade to the latest version
84- of ShinyProxy and the operator for the best experience.
98+ The first stable release of the operator (1.0.0) is compatible with ShinyProxy
99+ 2.6.0. Older ShinyProxy versions are supported by running development snapshots
100+ of the operator, however, we strongly advice to upgrade to the latest version of
101+ ShinyProxy and the operator for the best experience.
85102
86103| ShinyProxy Version | Minimum operator version | Maximum operator version (inclusive) |
87104| --------------------| ----------------------------------| --------------------------------------|
88105| 2.4.3 | ` 0.0.1-SNAPSHOT-20201215.112635 ` | ` 0.0.1-SNAPSHOT-20201215.112635 ` |
89106| 2.5.0 | ` 0.0.1-SNAPSHOT-20210302.095930 ` | ` 0.0.1-SNAPSHOT-20210607.070151 ` |
90- | 2.6.0 | 0. 1.0 | N/A |
107+ | 2.6.0 | 1.0.0 | TBD |
91108
92109## Kubernetes versions
93110
94- | Kubernetes Version | Minimal required operator version | Notes |
95- | -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -------|
96- | v1.16 | Any version | Requires the use of ` SPO_PROBE_INITIAL_DELAY ` and ` SPO_PROBE_FAILURE_THRESHOL ` due to lack of startup probes. |
97- | v1.17 | Any version | Requires the use of ` SPO_PROBE_INITIAL_DELAY ` and ` SPO_PROBE_FAILURE_THRESHOL ` due to lack of startup probes. |
98- | v1.18 | Any version | Includes startup probes (as beta). |
99- | v1.19 | Any version | |
100- | v1.20.9 or older | 0.1.0-SNAPSHOT-20210831.075527 | Requires workaround - see below. |
101- | v1.20.10 or newer | 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. |
102- | v1.21.2 or older | 0.1.0-SNAPSHOT-20210831.075527 | Requires workaround - see below. |
103- | v1.21.3 or newer | 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. |
104- | v1.22 | N/A | This version has not yet been tested with the operator. Version 0.2.0 of the operator will officially support this version. |
111+ | | k8s 1.22.x | k8s >= v1.21.3 | k8s <= v1.21.2 | k8s >= 1.20.10 | k8s <= v1.20.9 | v1.19 | v1.18 | v1.17 | v1.16 |
112+ | ----------------| ------------| ----------------| ----------------| ----------------| ----------------| -------| -------| -------| -------|
113+ | 1.1.0³ | ✓ | ✓ | ✓² | ✓ | ✓² | ✓ | - | - | - |
114+ | 1.0.0 | - | ✓ | ✓² | ✓ | ✓² | ✓ | ✓ | ✓¹ | ✓¹ |
115+ | 0.0.1-SNAPSHOT | - | ✓ | ✓² | ✓ | ✓² | ✓ | ✓ | ✓¹ | ✓¹ |
116+
117+ ** Note: **
118+
119+ - ¹ requires the use of ` SPO_PROBE_INITIAL_DELAY ` and ` SPO_PROBE_FAILURE_THRESHOL ` due to lack of startup probes
120+ - ² requires a workaround, see below.
121+ - ³ not yet released; this version will use the ` extensions/v1beta1 ` version of ` Ingress ` which is removed in k8s v1.22, but only available from v1.19
105122
106123### Workaround for bug in Kubernetes
107124
0 commit comments