add documentation on clustering

docs/index.rst

@@ -31,6 +31,7 @@ Nuts documentation
     pages/deployment/configuration.rst
     pages/deployment/migration.rst
     pages/deployment/recommended-deployment.rst
+    pages/deployment/clustering.rst
     pages/deployment/certificates.rst
     pages/deployment/docker.rst
     pages/deployment/storage.rst

docs/pages/deployment/clustering.rst

@@ -0,0 +1,16 @@
+.. _clustering:
+
+Clustering
+##########
+
+With the introduction of a SQL database and separate session storage, clustering with HA is now possible.
+Clustering is currently limited to nodes that have the ``did:nuts`` method disabled.
+To enable clustering, you must support the following:
+
+- A clustered SQL database (SQLite is not supported)
+- A clustered session storage (Redis sentinel is recommended)
+- A clustered private key storage (Hashicorp Vault or Azure Keyvault)
+- Read only mounts for configuration, policy, discovery and JSON-LD context files.
+
+It's recommended to use a level 4 load balancer to distribute the load across the nodes.
+Each node should have a reverse proxy for TLS termination.

docs/pages/deployment/storage.rst

@@ -44,6 +44,68 @@ Refer to the documentation of the driver for the database you are using for the
     Usage of SQLite is not recommended for production environments.
     Connections to a SQLite DB are restricted to 1, which will lead to severe performance reduction.
 
+Session storage
+***************
+
+Session storage is used for storing access tokens, nonces and other volatile data.
+Data is stored in-memory only. There are 3 supported session storage types:
+
+- local
+- memcached
+- redis (standalone, cluster, sentinel)
+
+Local
+=====
+
+This is the default and will store data in-memory. Any restart will wipe all data.
+Data is also not shared if you run multiple nodes.
+
+Memcached
+=========
+
+Memcached can be enabled with the following config:
+
+.. code-block:: yaml
+
+    storage.session.memcached.address:
+      - localhost:11211
+
+You can add multiple memcached servers to the list.
+memcached is not capable of clustering. Each piece of data is stored on a single instance.
+If you want true HA, you'll need to use Redis.
+
+Redis
+=====
+
+Redis is the only option if you want to run multiple nodes and the cache as HA.
+Redis can be configured in standalone or sentinel mode.
+Standalone:
+
+.. code-block:: yaml
+
+    storage:
+      session:
+        redis:
+          address: localhost:6379
+          username: user
+          password: pass
+          db: 0
+
+Sentinel:
+
+.. code-block:: yaml
+
+    storage:
+      session:
+        redis:
+          sentinel:
+            master: mymaster
+            nodes:
+              - localhost:26379
+              - localhost:26380
+              - localhost:26381
+
+
 Private Keys
 ************