Incorporate existing kernel persistence docs

Author: kevin-bates

docs/source/operators/config-availability.md

@@ -76,19 +76,49 @@ fi
 
 ## Kernel Session Persistence
 
+Enabling kernel session persistence allows Jupyter Notebooks to reconnect to kernels when Enterprise Gateway is restarted and forms the basis for the _availability modes_ described above. Enterprise Gateway provides two ways of persisting kernel sessions: _File Kernel Session Persistence_ and _Webhook Kernel Session Persistence_, although others can be provided by subclassing `KernelSessionManager` (see below).
+
 ```{attention}
 Due to its experimental nature, kernel session persistence is disabled by default. To enable this functionality, you must configure `KernelSessionManger.enable_persistence=True` or configure `EnterpriseGatewayApp.availability_mode` to either `single-instance` or `multi-instance`.
 ```
 
 As noted above, the availability modes rely on the persisted information relative to the kernel. This information consists of the arguments and options used to launch the kernel, along with its connection information. In essence, it consists of any information necessary to re-establish communication with the kernel.
 
-Kernel session persistence is unique to Enterprise Gateway and consists of a _bring-your-own_ model whereby subclasses of `KernelSessionManager` can be configured that manage their own persistent storage of kernel sessions. By default, Enterprise Gateway provides a `FileKernelSessionManager` that reads and writes kernel session information to a pre-configured directory. For use with `availability_mode` it is presumed that directory resides in a location accessible by all applicable nodes running Enterprise Gateway.
+### File Kernel Session Persistence
+
+File Kernel Session Persistence stores kernel sessions as files in a specified directory. To enable this form of persistence, set the environment variable `EG_KERNEL_SESSION_PERSISTENCE=True` or configure `FileKernelSessionManager.enable_persistence=True`. To change the directory in which the kernel session file is being saved, either set the environment variable `EG_PERSISTENCE_ROOT` or configure `FileKernelSessionManager.persistence_root` to the directory. By default, the directory used to store a given kernel's session information is the `JUPYTER_DATA_DIR`.
 
 ```{note}
-This option can be also be set on subclasses of `KernelSessionManager` (e.g., `FileKernelSessionManager.enable_persistence=True`).
+Because `FileKernelSessionManager` is the default class for kernel session persistence, configuring `EnterpriseGatewayApp.kernel_session_manager_class` to `enterprise_gateway.services.sessions.kernelsessionmanager.FileKernelSessionManager` is not necessary.
+```
+
+### Webhook Kernel Session Persistence
+
+Webhook Kernel Session Persistence stores all kernel sessions to any database. In order for this to work, an API must be created. The API must include four endpoints:
+
+- A `GET` that will retrieve a list of all kernel sessions from a database
+- A `GET` that will take the kernel id as a path variable and retrieve that information from a database
+- A `DELETE` that will delete all kernel sessions, where the body of the request is a list of kernel ids
+- A `POST` that will take kernel id as a path variable and kernel session in the body of the request and save it to a database where the object being saved is:
+
+```
+    {
+      kernel_id: UUID string,
+      kernel_session: JSON
+    }
 ```
 
-By default, the directory used to store a given kernel's session information is the `JUPYTER_DATA_DIR`. This location can be configured using `FileKernelSessionManager.persistence_root` with a value of a fully-qualified path to an existing directory.
+To enable the webhook kernel session persistence, set the environment variable `EG_KERNEL_SESSION_PERSISTENCE=True` or configure `WebhookKernelSessionManager.enable_persistence=True`. To connect the API, set the environment variable `EG_WEBHOOK_URL` or configure `WebhookKernelSessionManager.webhook_url` to the API endpoint.
+
+Because `WebhookKernelSessionManager` is not the default kernel session persistence class, an additional configuration step must be taken to instruct EG to use this class: `EnterpriseGatewayApp.kernel_session_manager_class = enterprise_gateway.services.sessions.kernelsessionmanager.WebhookKernelSessionManager`.
+
+#### Enabling Authentication
+
+Enabling authentication is an option if the API requires it for requests. Set the environment variable `EG_AUTH_TYPE` or configure `WebhookKernelSessionManager.auth_type` to be either `Basic` or `Digest`. If it is set to an empty string authentication won't be enabled.
+
+Then set the environment variables `EG_WEBHOOK_USERNAME` and `EG_WEBHOOK_PASSWORD` or configure `WebhookKernelSessionManager.webhook_username` and `WebhookKernelSessionManager.webhook_password` to provide the username and password for authentication.
+
+### Bring Your Own Kernel Session Persistence
 
 To introduce a different implementation, you must configure the kernel session manager class. Here's an example for starting Enterprise Gateway using a custom `KernelSessionManager` and 'single-instance' availability. Note that setting `--MyCustomKernelSessionManager.enable_persistence=True` is not necessary because an availability mode is specified, but displayed here for completeness:
 
@@ -111,3 +141,9 @@ fi
 ```
 
 Alternative persistence implementations using SQL and NoSQL databases would be ideal and, as always, contributions are welcome!
+
+### Testing Kernel Session Persistence
+
+Once kernel session persistence has been enabled and configured, create a kernel by opening up a Jupyter Notebook. Save some variable in that notebook and shutdown Enterprise Gateway using `kill -9 PID`, where `PID` is the PID of gateway. Restart Enterprise Gateway and refresh you notebook tab. If all worked correctly, the variable should be loaded without the need to rerun the cell.
+
+If you are using docker, ensure the container isn't tied to the PID of Enterprise Gateway. The container should still run after killing that PID.