Usage

Installation

To use WebsocketProxyLib, first install it using pip:

(.venv) $ pip3 install lab-orchestrator-ws-proxy-lib

Creating a Proxy

To create a Proxy you need to create a lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy object:

class lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy(remote_url, api_path, local_dev_mode, secret_key, host_path_prefix=None)

Add JWT authentication to KubeVirts VNC Websockets.

This WebsocketProxy is made to be run inside of Kubernetes. It creates a proxy to access KubeVirts VNC Websockets and adds authentication to this.

Methods

__init__(remote_url, api_path, local_dev_mode, secret_key, host_path_prefix=None)

Initializes a WebsocketProxy object.

Parameters

remote_url (str) – Base URL to the Kubernetes api.
api_path (str) – The path in the api that points to a VMI.
local_dev_mode (bool) – Indicates if the proxy runs in development mode or in Kubernetes.
secret_key (str) – Key that is used to decrypt the tokens.
host_path_prefix (Optional[str]) – Prefix that is removed from the path.

run(host, port)

Starts the websocket proxy server.

Parameters

host – Host that the server should use.
port – Port that the server should use.

run_in_thread(host, port)

Starts the websocket proxy server in a thread.

To stop this thread use the method stop_thread.

Parameters

host – Host that the server should use.
port – Port that the server should use.

stop_thread(): Stops the thread where the websocket proxy server was started.

lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy.__init__(self, remote_url, api_path, local_dev_mode, secret_key, host_path_prefix=None)

Initializes a WebsocketProxy object.

Parameters

remote_url (str) – Base URL to the Kubernetes api.
api_path (str) – The path in the api that points to a VMI.
local_dev_mode (bool) – Indicates if the proxy runs in development mode or in Kubernetes.
secret_key (str) – Key that is used to decrypt the tokens.
host_path_prefix (Optional[str]) – Prefix that is removed from the path.

The remote_url parameter is the base URL to the Kubernetes api (for example “ws://localhost:8001”).
The api_path parameter is the path in the api that points to a VMI. This needs to contain the variables {namespace} and {vmi_name} (for example “/apis/subresources.kubevirt.io/v1alpha3/namespaces/{namespace}/virtualmachineinstances/{vmi_name}/vnc”). The variables will be replaced when a new connection is made with the correct namespace name and the VMI-name.
The local_dev_mode parameter is a boolean that indicated if you are running the lib locally in a development mode or running it in a Kubernetes cluster. Running it locally disables ssl. Running it in Kubernetes will automatically include the TLS client certificate from /var/run/secrets/kubernetes.io/serviceaccount/ca.crt and use the token from /var/run/secrets/kubernetes.io/serviceaccount/token.
The secret_key parameter is the key that is used to decrypt the token.
The host_path_prefix when the server is started behind a reverse proxy it is possible that the path contains a prefix. For example /ws_proxy/token/vm.

Run Websocket Proxy

After creating a proxy you need to run it. For this case you have the lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy.run method:

lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy.run(self, host, port)

Starts the websocket proxy server.

Parameters

host – Host that the server should use.
port – Port that the server should use.

The run method starts the websocket server in foreground and every new connection is added to an event loop.

Run Websocket Proxy in Thread

Another way to start the proxy is the lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy.run_in_thread method:

lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy.run_in_thread(self, host, port)

Starts the websocket proxy server in a thread.

To stop this thread use the method stop_thread.

Parameters

host – Host that the server should use.
port – Port that the server should use.

This method runs the websocket server in background.

Stop Websocket Proxy Thread

To stop the thread you can use the lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy.stop_thread method:

lab_orchestrator_ws_proxy_lib.ws_proxy_lib.WebsocketProxy.stop_thread(self): Stops the thread where the websocket proxy server was started.

Connect

The proxy works as follows:

It creates a websocket at the given host and port. Then when you want to access a VM you need to call the websocket with a path that contains the token and the VM-name divided by a slash. Example: localhost:5001/ABCTOKENDEF/ubuntu. The example contains the token ABCTOKENDEF and tries to access the VM with the name ubuntu. The token contains a list of allowed VM-names and if the given VM-name is part of the token you will be able to access the VM.

Example CURL call:

$ curl \
 --header "Connection: Upgrade" \
 --header "Upgrade: websocket" \
 --header "Sec-WebSocket-Version: 13" \
 --header "Sec-WebSocket-Key: wPu8b8WOqAJZCYo95uVRDA==" \
 --include --no-buffer \
 localhost:5001/ABCTOKENDEF/ubuntu

Example

An example can be found here.