Skip to content

Commit e861d8a

Browse files
LEDfanLEDfan
committed
Update README for v2
1 parent a31c1ec commit e861d8a

1 file changed

Lines changed: 66 additions & 56 deletions

File tree

‎README.md‎

Lines changed: 66 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -19,21 +19,29 @@ therefore be automated.
1919
The ShinyProxy operator for Kubernetes is able to manage multiple ShinyProxy
2020
instances and their configuration.
2121

22-
### example
23-
24-
Assume we have some ShinyProxy configuration `config1` which contains
25-
one app called `app1`. When the operator starts working, it checks whether a ShinyProxy instance exists with that configuration.
26-
If not, it starts a ShinyProxy instance and all other required configuration. Users can now start using `app1` on this instance.
27-
28-
Some time later, the need for a second app arises.
29-
Therefore the administrator adapts the configuration of ShinyProxy to
30-
include a second app `app2`.
31-
32-
However, some users are still using `app1` on the old instance.
33-
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.
34-
35-
All other users are forwarded to the new server and can use the new application. Nevertheless, users using an old
36-
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.
22+
### Example
23+
24+
Assume we have some ShinyProxy configuration `config1` which contains one app
25+
called `app1`. When the operator starts working, it checks whether a ShinyProxy
26+
instance exists with that configuration. If not, it starts a ShinyProxy instance
27+
and all other required configuration. Users can now start using `app1` on this
28+
instance.
29+
30+
Some time later, the need for a second app arises. Therefore, the administrator
31+
adapts the configuration of ShinyProxy to include a second app `app2`.
32+
33+
However, some users are still using `app1` on the old instance. These apps may
34+
have some state, which should not be lost. Therefore, the operator starts a
35+
second ShinyProxy instance using configuration `config2`. The operator does not
36+
modify the original ShinyProxy server, therefore the existing apps continue to
37+
work (even if they are using Websocket connections).
38+
39+
All new HTTP (and Websocket) connections are forwarded to the new server, i.e.
40+
any new connection is handled by the new server. Therefore, if users go to the
41+
main ShinyProxy page, they will see that a new app is available. Every user (
42+
also those still using the old application) can start the new app. The operator
43+
stops and removes the old server as soon as it has finished handling any
44+
existing (Websocket) connections.
3745

3846
## Building from source
3947

@@ -48,8 +56,9 @@ The build will result in a single `.jar` file:
4856

4957
## Running
5058

51-
The operator should be run in Kubernetes using the [docker image](https://hub.docker.com/r/openanalytics/shinyproxy-operator).
52-
It can run in either `clustered` scope or `namespaced` mode. In the former the
59+
The operator should be run in Kubernetes using
60+
the [docker image](https://hub.docker.com/r/openanalytics/shinyproxy-operator).
61+
It can run in either `clustered` or `namespaced` mode. In the former the
5362
operator looks for ShinyProxy instances in all namespaces while in the latter it
5463
only manages ShinyProxy instances in its own namespace.
5564

@@ -66,8 +75,6 @@ start with the `SPO` prefix, meaning **S**hiny**P**roxy**O**perator.
6675
- `SPO_MODE`: can either be `namespaced` or `clustered` (default). This
6776
specifies whether the operator should only look in its own namespace for
6877
ShinyProxy configurations or in all namespaces.
69-
- `SPO_DISABLE_SECURE_COOKIES`: when set to any value, this disables the
70-
`secure` flag on all cookies used by the Operator.
7178
- `SPO_PROBE_INITIAL_DELAY`: specifies the initial delay of the Readiness and
7279
Liveness probes. This is useful when the used Kubernetes version does not
7380
support startup probes.
@@ -77,7 +84,8 @@ start with the `SPO` prefix, meaning **S**hiny**P**roxy**O**perator.
7784
- `SPO_PROBE_TIMEOUT`: specifies the timeout in seconds of the Readiness and
7885
Liveness probes. This is useful when the used Kubernetes version does not
7986
support startup probes.
80-
- `SPO_STARTUP_PROBE_INITIAL_DELAY`: specifies the initial delay of the StartUp probe. By default, this is 60 seconds.
87+
- `SPO_STARTUP_PROBE_INITIAL_DELAY`: specifies the initial delay of the StartUp
88+
probe. By default, this is 60 seconds.
8189
- `SPO_LOG_LEVEL`: configures the log level of the operator, may be one of the
8290
following:
8391
- `OFF`: disables logging
@@ -105,22 +113,20 @@ ShinyProxy and the operator for the best experience.
105113

106114
| ShinyProxy Version | Minimum operator version | Maximum operator version (inclusive) |
107115
|--------------------|----------------------------------|--------------------------------------|
108-
| 2.4.3 | `0.0.1-SNAPSHOT-20201215.112635` | `0.0.1-SNAPSHOT-20201215.112635` |
116+
| 3.0.0 | 2.0.0 | TBD |
117+
| 2.6.0 | 1.0.0 | 1.1.0 |
109118
| 2.5.0 | `0.0.1-SNAPSHOT-20210302.095930` | `0.0.1-SNAPSHOT-20210607.070151` |
110-
| 2.6.0 | 1.0.0 | TBD |
119+
| 2.4.3 | `0.0.1-SNAPSHOT-20201215.112635` | `0.0.1-SNAPSHOT-20201215.112635` |
111120

112121
## Kubernetes versions
113122

114-
| | k8s 1.23.x | 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 | v1.15 | v1.14 |
115-
|----------------|------------|------------|----------------|----------------|----------------|----------------|-------|-------|-------|-------| ----- | ----- |
116-
| 1.1.0 | ✓ | ✓ | ✓ | ✓² | ✓ | ✓² | ✓ | - | - | - | - | - |
117-
| 1.0.0 | - | - | ✓ | ✓² | ✓ | ✓² | ✓ | ✓ | ✓¹ | ✓¹ | - | - |
118-
| 0.0.1-SNAPSHOT | - | - | ✓ | ✓² | ✓ | ✓² | ✓ | ✓ | ✓¹ | ✓¹ | ✓¹ | ✓¹ |
123+
| | k8s 1.25.x | k8s 1.24.x | k8s 1.23.x | k8s 1.22.x | k8s >= v1.21.3 | k8s <= v1.21.2 | k8s >= 1.20.10 | k8s <= v1.20.9 | v1.19 | <= v1.18 |
124+
|-------|------------|------------|-------------|------------|----------------|----------------|----------------|----------------|-------|----------|
125+
| 2.0.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓¹ | ✓ | ✓¹ | ✓ | - |
119126

120127
**Note:**
121128

122-
- ¹ requires the use of `SPO_PROBE_INITIAL_DELAY` and `SPO_PROBE_FAILURE_THRESHOL` due to lack of startup probes
123-
- ² requires a workaround, see below.
129+
- ¹ requires a workaround, see below.
124130

125131
### Workaround for bug in Kubernetes
126132

@@ -138,33 +144,37 @@ only reasonable work-around is to regularly restart the Operator. Since version
138144
minutes), the operator stops. The corresponding Docker container then
139145
automatically restarts the Java process.
140146

141-
### Update to 1.0.0
142-
143-
Be aware of these changes when updating to version 1.0.0:
144-
145-
- the ShinyProxy CRD now uses version `apiextensions.k8s.io/v1` of the
146-
`CustomResourceDefinition` resource instead of version
147-
`apiextensions.k8s.io/v1beta`. In our tests this update when smooth, but
148-
please take into account that you may be required to re-create the CRD and
149-
that therefore your ShinyProxy servers may have to be re-created (causing
150-
downtime).
151-
- because of this change, the operator requires at least version Kubernetes
152-
v1.16.
153-
- the ShinyProxy CRD now specifies version `openanalytics.eu/v1` instead of
154-
`openanalytics.eu/v1alpha1`. Nevertheless, the operator is still able to
155-
handle ShinyProxy resources using the `openanalytics.eu/v1alpha1` version.
156-
When creating resources with version `openanalytics.eu/v1alpha1`, Kubernetes
157-
will automatically convert these to use version `openanalytics.eu/v1`.
158-
159-
### Update to 1.1.0
160-
161-
Be aware of these changes when updating to version 1.0.0:
162-
163-
- starting with this version, the operator uses the `networking.k8s.io/v1`
164-
version of the Ingress resource. Therefore, this version is compatible with
165-
Kubernetes 1.22 or later and requires at least Kubernetes v1.19. In order to
166-
make this possible, the Skipper component was updated and the Skipper
167-
configuration was changed. Make sure to re-import the manifests.
147+
### Update to 2.0.0
148+
149+
Be aware of these changes when updating to version 2.0.0:
150+
151+
- the old mechanism where cookies were used to assign users to specific
152+
ShinyProxy servers is no longer used. Instead, as soon as a new server is
153+
started, all new requests will be handled by the new server, including
154+
requests for existing apps. Only existing websocket connections will stay open
155+
on the old servers. This has multiple benefits:
156+
- when a new server is started, users will immediately use and see the
157+
configuration of that new server. In other words, if a new configuration
158+
includes a new app, this app is immediately available to all users (even if
159+
they are using apps started on older servers)
160+
- there is no longer a process of transferring users to new servers. Both the
161+
forced method and the manual method (where users have to click a button) are
162+
removed. Users will immediately use the new configuration.
163+
- apps can be run for a (very) long time, even if frequently updating the
164+
configuration and without having many old servers. Old servers are removed
165+
as soon as no websocket connections are running on that server.
166+
- Skipper is no longer a dependency of the operator. There is no benefit in
167+
using with version two of the operator.
168+
- the operator now requires ShinyProxy to store the active proxies in Redis.
169+
Therefore, since this release Redis takes a more critical role. When running
170+
Redis inside Kubernetes, it is therefore best practice to use Redis Sentinel.
171+
This way Redis runs in a High Available mode, using three replicas. Compared
172+
to running a single Redis server, this prevents a single point of failure on
173+
Redis and the node it is running on. This repository contains all manifests
174+
required to set up Redis Sentinel (based on the bitnamai Redis helm chart).
175+
176+
The best way to update to ShinyProxy 2.0.0 is by creating a fresh deployment of
177+
the operator and migrating users to this new deployment.
168178

169179
## Java Version
170180

0 commit comments

Comments
 (0)