feat: add LNet info to Lustre Explanation and deployment How-to

Author: dsloanm

.custom_wordlist.txt

@@ -139,6 +139,7 @@ nfs
 OSSes
 OSTs
 userinfo
+vdev
 vdevs
 zpool
 

explanation/lustre.md

@@ -35,15 +35,23 @@ The `lustre-server` charm is in an experimental state and is not yet ready for p
 
 ### Package installation
 
-TODO
+The Lustre server packages are installed from a PPA maintained by the Ubuntu HPC team located at [`ppa:ubuntu-hpc/lustre-2.17`](https://launchpad.net/~ubuntu-hpc/+archive/ubuntu/lustre-2.17) and containing the latest stable release supported by the charm. Setup of the PPA and package install are handled automatically by the charm during its `install` hook.
 
 ### LNet configuration
 
-TODO
+LNet is Lustre's network layer, responsible for communication between clients and server components. The `lustre-server` charm can automatically detect network interfaces and configure LNet or a custom configuration can be provided using the `lnet-networks` option.
+
+Both the `lustre-server` and `filesystem-client` charms perform network auto-detection by default, during the charm `install` hook. LNet is automatically configured with a network name of `tcp` using the default route Ethernet interface and, if RDMA hardware such as InfiniBand is detected, another network name of `o2ib` using every RDMA device, in a multi-rail setup if multiple devices are detected.
+
+Auto-detection can be overridden by setting the `lnet-networks` configuration value. The format for `lnet-networks` is `<name>=<iface>[,<iface>...]`, where `<name>` is the LNet network name and `<iface>` is the network interface. For example, to configure LNet with a net name of `tcp` using the `eth0` interface, and a net name of `o2ib0` using the `ib0` and `ib1` interfaces, the following flag would be used:
+
+```shell
+--config lnet-networks="tcp=eth0; o2ib0=ib0,ib1"
+```
 
 ### Service placement
 
-TODO
+The charm automatically places the MGS and MDS on the initial leader unit, with all subsequent units becoming OSSes. A minimum of two units is required in a deployment.
 
 ### Storage
 

howto/deploy/deploy-lustre.md

@@ -20,40 +20,47 @@ The `lustre-server` charm is in an experimental state and is not ready for produ
 
 ## Prerequisites
 
-- A [Slurm cluster](#howto-deploy-deploy-slurm).
 - The [Juju CLI client](https://documentation.ubuntu.com/juju/latest/user/howto/manage-juju/) installed on your machine.
 - Secure boot **disabled** on target machines, as the charm builds DKMS kernel modules.
 
+(howto-deploy-deploy-lustre-server)=
 ## Deploy the `lustre-server` charm
 
-To deploy the `lustre-server` charm:
+To deploy a default configuration, where the initial leader unit is a combined MGS+MDS and all remaining units are OSSes, run the following:
 
 :::{code-block} shell
 juju deploy lustre-server \
   --channel latest/edge \
-  -n 2
+  -n <number of units>
 :::
 
-At least two units are required; a single unit deployment is not supported.
+A minimum of two units is required; a single unit deployment is not supported.
 
-The Juju application leader at deployment time becomes a combined MGS+MDS unit. All additional units become OSSes, each providing one OST.
+## Deploy the `lustre-server` charm with custom LNet configuration
 
-Wait for all units in the deployment to become active:
+To override LNet auto-detection and deploy with a custom configuration, deploy as described in {ref}`howto-deploy-deploy-lustre-server` but include the `lnet-networks` configuration option following format: `<name>=<iface>[,<iface>...]`.
+
+For example, to configure LNet with a net name of `tcp` using the `eth0` interface, and a net name of `o2ib0` using the `ib0` and `ib1` interfaces, run the following:
 
 :::{code-block} shell
-juju status
+juju deploy lustre-server \
+  --channel latest/edge \
+  --config lnet-networks="tcp=eth0; o2ib0=ib0,ib1" \
+  -n <number of units>
 :::
 
 ## Deploy the `filesystem-client` charm
 
-To mount the Lustre filesystem on client nodes, deploy the `filesystem-client` subordinate charm
-charm with `mountpoint` configuration set to the path Lustre should be mounted at on each client.
-Then integrate with the `lustre-server` application on the `filesystem` endpoint:
+To mount the Lustre filesystem on client nodes, deploy the `filesystem-client` subordinate charm,
+with the `mountpoint` configuration set to the path Lustre should be mounted at on each client and
+the `enable-lustre` configuration set to `true`. Then integrate with the `lustre-server` application
+on the `filesystem` endpoint:
 
 :::{code-block} shell
 juju deploy filesystem-client \
   --channel latest/edge \
-  --config mountpoint="/mnt/lustre"
+  --config mountpoint="/mnt/lustre" \
+  --config enable-lustre=true
 
 juju integrate filesystem-client:filesystem lustre-server:filesystem
 :::

howto/deploy/index.md

@@ -1,8 +1,9 @@
 # Deploy
 
-Deploy and configure the core components of a Charmed HPC cluster, with support for high availability, NFS and CephFS filesystem serves, LXD-based deployments, and LDAP-backed identity management.
+Deploy and configure the core components of a Charmed HPC cluster, with support for high availability, filesystem serves (Lustre, NFS, and CephFS), LXD-based deployments, and LDAP-backed identity management.
 
 - {ref}`Deploy Slurm <howto-deploy-deploy-slurm>`
+- {ref}`Deploy Lustre <howto-deploy-deploy-lustre>`
 - {ref}`Deploy a shared filesystem <howto-deploy-deploy-shared-filesystem>`
 - {ref}`Deploy an identity provider <howto-deploy-deploy-identity-provider>`
 
@@ -12,6 +13,7 @@ Deploy and configure the core components of a Charmed HPC cluster, with support
 :hidden:
 
 Deploy Slurm <deploy-slurm>
+Deploy Lustre <deploy-lustre>
 Deploy a shared filesystem <deploy-shared-filesystem>
 Deploy identity provider <deploy-identity-provider>
 :::

howto/index.md

@@ -15,6 +15,7 @@ Install dependencies and initialize the backing cloud for your cluster.
 Deploy and configure the core components of your cluster.
 
 - {ref}`Deploy Slurm <howto-deploy-deploy-slurm>`
+- {ref}`Deploy Lustre <howto-deploy-deploy-lustre>`
 - {ref}`Deploy a shared filesystem <howto-deploy-deploy-shared-filesystem>`
 - {ref}`Deploy an identity provider <howto-deploy-deploy-identity-provider>`