1# VNC Gateway Service
2
3VNC Gateway is a server used to manage all Edge VNC connection requests. The service is expected to be run in a kube cluster. The libraries used to build up the source code can be found in `pkg/sds/vnc/gateway`.
4
5- [VNC Gateway Service](#vnc-gateway-service)
6 - [Nginx Auth Request](#nginx-auth-request)
7 - [Connect Mode](#connect-mode)
8 - [Endpoints](#endpoints)
9 - [Authorize](#authorize)
10 - [Validate](#validate)
11 - [Disconnect](#disconnect)
12 - [Integration Testing](#integration-testing)
13 - [Overview](#overview)
14 - [Daemonsetdns](#daemonsetdns)
15 - [Re-Installing the Daemonsetdns component](#re-installing-the-daemonsetdns-component)
16 - [Running the integration package:](#running-the-integration-package)
17
18## Nginx Auth Request
19
20VNC Gateway requests are made via an nginx `auth_request` module proxy pass. This means that the requests that VNC Gateway receives will not be the original request sent by the noVNC client. To preserve query parameters sent by noVNC, the original request URI is stored by nginx in the `X-Original-URI` header when needed. It is understood that any mention of "query parameters" in the documentation is in reference to the query parameters of the URI found in `X-Original-URI`, and not the URL of the incoming HTTP request.
21
22An example of a `X-Original-URI` header you would expect to see:
23
24```http
25X-Original-Uri: //write/ws?requestID=9c04e5c5-d8aa-4b7c-8cbf-828fa024a45d&token=s2-worker-1
26```
27
28### Connect Mode
29
30Each request ID is associated with a single connect mode, i.e. read or write.
31The connect mode is discovered from the original uri, in the first path segment.
32
33## Endpoints
34
35### Authorize
36
37Authorizes an incoming VNC connection request. Returns 200 when a valid request is accepted by the target node.
38This endpoint is idempotent, it may be called multiple times with the same request ID if the connection times out before the target node accepts/rejects the request.
39Additional http requests with the same request ID will wait for the existing interlock request to be accepted rather than make a new interlock request.
40Rejects new connections with an existing request ID if the connect mode has been updated.
41
42__URI__: `/authorize`
43
44__Method__ : `GET`
45
46__Header__:
47
48| Header | Type | Multi-Valued | Details |
49| ------ | ---- | ------------ | ------- |
50| `X-Vnc-Request-Id` | string | false | A UUID representing the VNC connection session. Generated and by authserver for all incoming authorize requests |
51| `X-Webauth-User` | string | false | The username of the user making the VNC request. Added by authserver for all incoming requests |
52| `X-Original-Uri` | string | false | The original request URI sent by the noVNC client |
53
54__Query_Parameters__:
55
56| Name | Type | Details |
57| ---- | ---- | ------- |
58| `token` | string | Hostname of the target node |
59
60__Error codes__:
61
62| Code | Description |
63| ---- | ----------- |
64| 200 | OK |
65| 400 | Bad Request |
66| 403 | Forbidden |
67| 500 | Internal Server Error |
68
69### Validate
70
71Validates an incoming VNC connection. This will increase the number of connections to the target node by 1 and notify interlock of a new connection. Returns 200 when a valid incoming request ID is confirmed to be associated with an authorized node connection.
72Verifies that the requested connect mode is equivalent to the connect mode supplied in the `/authorize` request for the same request ID.
73
74If gateway fails to notify interlock, a 500 status is returned. A user can reconnect using the same request ID in this case if they wish.
75
76__URI__: `/validate`
77
78__Method__ : `GET`
79
80__Header__:
81
82| Header | Type | Multi-Valued | Details |
83| ------ | ---- | ------------ | ------- |
84| `X-Webauth-User` | string | false | The username of the user making the VNC request. Added by authserver for all incoming requests |
85| `X-Original-Uri` | string | false | The original request URI sent by the noVNC client |
86
87__Query_Parameters__:
88
89| Name | Type | Details |
90| ---- | ---- | ------- |
91| `token` | string | Hostname of the target node |
92| `requestID` | string | A UUID representing the VNC connection session |
93
94__Error codes__:
95
96| Code | Description |
97| ---- | ----------- |
98| 200 | OK |
99| 400 | Bad Request |
100| 403 | Forbidden |
101| 500 | Internal Server Error |
102
103### Disconnect
104
105Disconnects an existing VNC connection.
106This will decrease the number of connections to the target node by 1 and notify interlock of the disconnection.
107Returns 200 when a valid request ID is confirmed to be associated with an active node connection.
108Status will switch to DROPPED if the total number of connections is zero.
109
110If gateway fails to notify interlock, or if the internal status does not match the given request ID, hostname or connect mode, a 500 is returned.
111
112__URI__: `/disconnect`
113
114__Method__ : `GET`
115
116__Header__:
117
118| Header | Type | Details |
119| ------------------ | ------ | ------- |
120| `X-Webauth-User` | string | The username of the user making the VNC request. Added by authserver for all incoming requests |
121| `X-Vnc-Request-Id` | string | A UUID representing the VNC connection session |
122| `X-Vnc-Token` | string | Hostname of the target node |
123| `X-Original-Uri` | string | The original request URI sent by the noVNC client |
124
125__Error codes__:
126
127| Code | Description |
128| ---- | ----------- |
129| 200 | OK |
130| 500 | Internal Server Error |
131
132
133## Integration Testing
134
135Integration testing for gateway follows a very similar pattern to novnc integration testing. The f2 setup tests are defined in their own package under `pkg/vnc/gateway/integration/gateway_test.go`. The tests for gateway are L2 tests and will therefore need a cluster to run locally.
136
137### Overview
138_note: all paths are relative to `path/to/edge-infra/`_
139
140The setup does the following:
1411. Creates a new test namespace
1422. Deploys dependencies for `vncgateway`:
143 - daemonsetdns
144 - interlock + role bindings to read `edge-info` config map
1453. Deploys novnc components. (defined under `config/pallets/sds/vnc/novnc/gateway-local`)
146
147### Daemonsetdns
148The integration tests will install the `daemonsetdns` component into the cluster if it does not already exist on the cluster, or it will use the existing component if it is present on the cluster.
149For the integration tests to successfully install the component they will need access to the container image, which can be done by building and pushing the image:
150
151```bash
152just push --bazel-configs=local cmd/sds/daemonsetdns/...
153```
154
155
156#### Re-Installing the Daemonsetdns component
157
158If changes have been made to the daemonsetdns component you may wish to test vncgateway with the new version of daemonsetdns.
159To do this you will need to remove the existing `daemonsetdns` component from the cluster for the tests to install the new version the next time they are run.
160This can be done using the following commands
161
162```bash
163kubectl delete clusterrole daemonsetdns
164kubectl delete clusterrolebindings daemonsetdns
165kubectl delete ns daemonsetdns
166```
167
168### Running the integration package:
169_note: check docker service and kind cluster are running correctly before running these steps (`docker-service`, `k get ns` on `k ctx kind-edge`)_
170
171To run the setup locally, first push all required containers:
172
173```bash
174just push --bazel-configs=local cmd/sds/vnc/...
175just push --bazel-configs=local cmd/sds/novnc/...
176just push --bazel-configs=local cmd/sds/interlock/...
177```
178
179Add `"kind-cluster": true` to your `test/config.json` file.
180
181When running the tests you may need to specify that the tests should use the local registry, which can be done using the `--workloads_repo=localhost:21700` argument. For example:
182
183```bash
184rosa int l2 //pkg/sds/vnc/gateway/integration:integration_test --workloads_repo=localhost:21700
185```
186The `-kind-cluster` flag should be added only if running tests on `kind-edge` to avoid subscription errors from the API informer.
View as plain text