Merge pull request #288 from ByteInternet/update_cluster_docs

docs/hypernode-platform/cluster.md

@@ -36,15 +36,10 @@ the rest of the cluster stays up.
 ## Connecting between cluster Hypernodes
 
 All Hypernodes within the same cluster are connected to each other. You can see how the Hypernodes relate to each other in the
-map:
+cluster information table by running `hypernode-cluster-info`:
 
-![](cluster/_res/hypernode-cluster-map.png)
-
-You can generate this map on the fly using the CLI command `hypernode-cluster-map`. You can also get a detailed overview of the
-state of the cluster using the CLI command `hypernode-cluster-info`:
-
-```bash
-app@1fosk3-hnclusterweb1-magweb-hetz:~$ hypernode-cluster-info
+```console
+app@abcdef-hnclusterweb1-magweb-tbbm:~$ hypernode-cluster-info
 +---------------+--------------------------+-------------+----------------+------------+
 | Hypernode     | Roles                    | Private_IP  | Private_subnet | Cluster_IP |
 +---------------+--------------------------+-------------+----------------+------------+
@@ -61,13 +56,13 @@ All nodes within the cluster can communicate with each other over their cluster
 that are only accessible within the cluster, as they are [Wireguard](https://www.wireguard.com/) tunnels between each Hypernode
 in the cluster.
 
-```bash
-app@1fosk3-hnclusterweb1-magweb-hetz:~$ ssh hnclusterdb1.hypernode.io hostname
-cj8jv7-hnclusterdb1-magweb-hetz.nodes.hypernode.io
+```console
+app@abcdef-hnclusterweb1-magweb-tbbm:~$ ssh hnclusterdb1.hypernode.io hostname
+abcdef-hnclusterdb1-magweb-tbbm.nodes.hypernode.io
 
-# For convenience, you can also use the short hostname
-app@1fosk3-hnclusterweb1-magweb-hetz:~$ ssh hnclusterdb1.h hostname
-cj8jv7-hnclusterdb1-magweb-hetz.nodes.hypernode.io
+For convenience, you can also use the short hostname
+app@abcdef-hnclusterweb1-magweb-tbbm:~$ ssh hnclusterdb1.h hostname
+abcdef-hnclusterdb1-magweb-tbbm.nodes.hypernode.io
 ```
 
 ### Private network switch
@@ -80,3 +75,41 @@ For this we provide a subnet where every Hypernode has its own private network I
 in the same cluster and in the same datacenter/regions. Just like with Wireguard connections you can connect between Hypernodes
 over the same private network. When available, we automatically configure the use of the private network over Wireguard
 connections because of the larger bandwidth.
+
+## Loadbalancer setup
+
+In essence, loadbalancer servers accept HTTP(S) traffic (also known as web traffic) and forward the requests to application servers.
+It balances the load by taking the amount of open connections for an application servers into account, selecting the server with the
+least connections.
+
+Web traffic is terminated by NGINX, which (optionally) forwards the request to varnish, which can return a cached page or send the
+request to [HAProxy](https://www.haproxy.org/), which sends the request to the application servers.
+
+### Managing NGINX
+
+To add custom NGINX rules for handling specific things on the loadbalancer (like serving assets), the `loadbalancer.` prefix can be
+used in `/data/web/nginx` and `/data/web/nginx/<vhost>`. This can be very crucial for your performance, accelerating asset delivery
+and lowering pressure on varnish.
+
+When running `hypernode-manage-vhosts` ([docs](nginx/hypernode-managed-vhosts.md)) on a loadbalancer server for a specific vhost, a
+preconfigured loadbalancer configuration file will be created for you (for example `/data/web/nginx/example.com/loadbalancer.magento2.conf`).
+These preconfigured files act as a good starting point for your loadbalancer setup, but can be customized to your needs.
+
+On application servers, `/data/web/nginx` is an NFS mount to the `/data/web/nginx` directory of the loadbalancer server. Because of
+this, changes to this directory from the application server will not trigger the nginx-config-reloader across the cluster. We advise
+to do most nginx changes (either configuration files or hypernode-manage-vhosts) on the loadbalancer server.
+
+For consistency, nginx reload events are propagated throughout the cluster, so that an nginx reload on one server also means a reload
+on the other servers.
+
+### Filesystem persistence
+
+Application servers behind a loadbalancer will be configured with an NFS mount to the loadbalancer. The NFS share is mounted at
+`/data/shared` on the application servers, which points to `/data` on the loadbalancer. For consistency, the loadbalancer itself
+has a symlink `/data/shared`, which points to `/data`.
+
+### Background jobs
+
+While the loadbalancer server does not run PHP-FPM, it does have the PHP CLI installed, meaning that you could utilize the loadbalancer
+server to run background jobs like crons and queue workers. Typically, background jobs are only ran on a single server, often done on
+either the loadbalancer server or one of the application servers.