Skip to content

Commit 7c37b04

Browse files
LEDfanLEDfan
committed
Update README
1 parent cff6a29 commit 7c37b04

1 file changed

Lines changed: 51 additions & 40 deletions

File tree

‎README.md‎

Lines changed: 51 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -6,32 +6,24 @@ Easily run ShinyProxy on a Kubernetes cluster
66

77
## Why?
88

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.
34-
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.
3527

3628
## Building from source
3729

@@ -56,7 +48,8 @@ See the [docs/deployment](docs/deployment) folder for more information.
5648

5749
We try to keep the configuration of the Operator itself as minimum as possible. Furthermore we want the operator to work
5850
without configuration in most cases. Nevertheless, for some specific cases some configuration options are available. For
59-
now these options are specified using environment variables. All variables start with the `SPO` prefix, meaning **S**hiny**P**roxy**O**perator.
51+
now these options are specified using environment variables. All variables start with the `SPO` prefix, meaning **S**
52+
hiny**P**roxy**O**perator.
6053

6154
- `SPO_MODE`: can either be `namespaced` or `clustered` (default). This specifies whether the operator should only look
6255
in its own namespace for ShinyProxy configurations or in all namespaces.
@@ -70,13 +63,13 @@ now these options are specified using environment variables. All variables start
7063
used Kubernetes version does not support startup probes.
7164
- `SPO_STARTUP_PROBE_INITIAL_DELAY`: specifies the initial delay of the StartUp probe. By default this is 60 seconds.
7265
- `SPO_LOG_LEVEL`: configures the log level of the operator, may be one of the following:
73-
- `OFF`: disables logging
74-
- `ERROR`
75-
- `WARN`
76-
- `INFO`
77-
- `DEBUG`: default (may change)
78-
- `TRACE`
79-
- `ALL`: enables all logging
66+
- `OFF`: disables logging
67+
- `ERROR`
68+
- `WARN`
69+
- `INFO`
70+
- `DEBUG`: default (may change)
71+
- `TRACE`
72+
- `ALL`: enables all logging
8073

8174
Note: in our deployments where startup probes aren't supported we have success with the following configuration:
8275

@@ -86,10 +79,9 @@ Note: in our deployments where startup probes aren't supported we have success w
8679

8780
## Supported Versions
8881

89-
The first stable release of the operator (0.1.0) is compatible with ShinyProxy
90-
2.6.0. Older ShinyProxy versions are supported by running development snapshots
91-
of the operator, however, we strongly advice to upgrade to the latest version of
92-
ShinyProxy and the operator for the best experience.
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.
9385

9486
| ShinyProxy Version | Minimum operator version | Maximum operator version (inclusive) |
9587
|--------------------|----------------------------------|--------------------------------------|
@@ -105,8 +97,27 @@ ShinyProxy and the operator for the best experience.
10597
| v1.17 | Any version | Requires the use of `SPO_PROBE_INITIAL_DELAY` and `SPO_PROBE_FAILURE_THRESHOL` due to lack of startup probes. |
10698
| v1.18 | Any version | Includes startup probes (as beta). |
10799
| v1.19 | Any version | |
108-
| 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. |
109-
| v1.21 | 0.1.0 | Idem as for v1.20 |
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. |
105+
106+
### Workaround for bug in Kubernetes
107+
108+
A [bug](https://github.com/kubernetes/kubernetes/issues/102464) affecting the
109+
operator was introduced in Kubernetes 1.20 and fixed in versions 1.20.10 and
110+
1.21.3. However, some deployments (e.g. using EKS) are not able to use this
111+
version. When using the affected versions, Kubernetes stops sending events for
112+
the `Service` resources after a certain amount of time. Therefore, the Operator
113+
is unaware of any events happening on services and is therefore unable to fully
114+
configure a ShinyProxy server. The bug only occurs after the operator has been
115+
running for a random time between 30 minutes and two hours. Unfortunately, the
116+
only reasonable work-around is to regularly restart the Operator. Since version
117+
`0.1.0-SNAPSHOT-20210831.075527`, it is possible to specify the
118+
`SPO_PROCESS_MAX_LIFETIME` environment variable. After the configured time (in
119+
minutes), the operator stops. The corresponding Docker container then
120+
automatically restarts the Java process.
110121

111122
## Java Version
112123

0 commit comments

Comments
 (0)