feat: add docs for how to deploy the filesystem client

.custom_wordlist.txt

@@ -14,3 +14,12 @@ PyPI
 GPUs
 integrations
 autonomizing
+filesystem
+filesystems
+Ceph
+cephx
+hostname
+hostnames
+fsid
+CephFS
+NFS

custom_conf.py

@@ -74,3 +74,5 @@
 .. role:: center
    :class: align-center
 """
+
+linkcheck_anchors_ignore = ['heading--subordinate', 'heading--proxy']

howto/getting-started/deploy-shared-filesystem.md

@@ -0,0 +1,84 @@
+(deploy-shared-filesystem)=
+# How to deploy a shared filesystem
+
+This how-to guide shows you how to deploy a shared filesystem in a Charmed-HPC cluster.
+
+## Prerequisites
+
+- {ref}`deploy-workload-manager`.
+
+## Deploy a shared filesystem provider
+
+A Charmed-HPC cluster allows deploying external filesystems not handled by Juju using a
+[proxy charm](https://juju.is/docs/sdk/charm-taxonomy#heading--proxy):
+
+```````{tabs}
+
+``````{group-tab} NFS
+
+To deploy an NFS server, you will require:
+- The server's hostname.
+- The exported path.
+- (optional) the port.
+
+```shell
+juju deploy nfs-server-proxy --config \
+    hostname=<server hostname> \
+    path=<exported path> \
+    port=<server port>
+
+```
+
+``````
+
+``````{group-tab} CephFS
+
+To deploy a CephFS server, you will require:
+ - The unique identifier of the cluster (commonly known as fsid).
+ - The name of the filesystem within the Ceph cluster.
+ - The exported path of the filesystem.
+ - The list of hostnames for MON nodes of the Ceph cluster.
+ - The username with permissions to access the filesystem.
+ - The cephx key for the username.
+
+```shell
+juju deploy cephfs-server-proxy --config \
+    --config fsid=<unique identifier of the cluster> \
+    --config sharepoint=<name of the filesystem>:/<exported path> \
+    --config monitor-hosts="<MON hostname 1> <MON hostname 2> <MON hostname 3>" \
+    --config auth-info=<username>:<cephx key for the username>
+```
+
+``````
+
+```````
+
+
+## Deploy the filesystem-client
+
+To add the charm that takes care of mounting a shared filesystem to the cluster nodes,
+deploy the `filesystem-client` charm:
+
+```shell
+juju deploy filesystem-client --channel latest/edge \
+    --config mountpoint='/scratch' \
+    --config noexec=true
+```
+
+The `mountpoint` configuration represents the path that the filesystem will be mounted onto.
+
+The `filesystem-client` is a [subordinate charm](https://juju.is/docs/juju/relation#heading--subordinate)
+that can be related to another charm using the `juju-info` endpoint:
+
+```shell
+juju integrate slurmd:juju-info filesystem-client:juju-info
+```
+
+## Relate the filesystem client with the filesystem provider
+
+Every filesystem provider can be integrated with the filesystem client using the
+`filesystem` endpoint:
+
+```shell
+juju integrate filesystem-client:filesystem <filesystem-provider>:filesystem
+```

howto/getting-started/index.md

@@ -5,11 +5,13 @@ See the how-to guides in this section for how to get started with Charmed HPC.
 ## How to deploy Charmed HPC
 
 - {ref}`deploy-workload-manager`
+- {ref}`deploy-shared-filesystem`
 
 ```{toctree}
 :titlesonly:
 :maxdepth: 1
 :hidden:
 
 Deploy workload manager <deploy-workload-manager>
+Deploy a shared filesystem <deploy-shared-filesystem>
 ```