From bba8baf4a67cc86df3daa1bf2d7d77c8cc0555e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jos=C3=A9=20Juli=C3=A1n=20Espina?=
 <julian.espina@canonical.com>
Date: Tue, 14 Jan 2025 10:07:52 -0600
Subject: [PATCH] feat: add docs for how to deploy the filesystem client

---
 .custom_wordlist.txt                          |  9 ++
 custom_conf.py                                |  2 +
 .../deploy-shared-filesystem.md               | 84 +++++++++++++++++++
 howto/getting-started/index.md                |  2 +
 4 files changed, 97 insertions(+)
 create mode 100644 howto/getting-started/deploy-shared-filesystem.md

diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt
index 40061e1..4073028 100644
--- a/.custom_wordlist.txt
+++ b/.custom_wordlist.txt
@@ -14,3 +14,12 @@ PyPI
 GPUs
 integrations
 autonomizing
+filesystem
+filesystems
+Ceph
+cephx
+hostname
+hostnames
+fsid
+CephFS
+NFS
diff --git a/custom_conf.py b/custom_conf.py
index a2feb31..e832ecf 100644
--- a/custom_conf.py
+++ b/custom_conf.py
@@ -74,3 +74,5 @@
 .. role:: center
    :class: align-center
 """
+
+linkcheck_anchors_ignore = ['heading--subordinate', 'heading--proxy']
diff --git a/howto/getting-started/deploy-shared-filesystem.md b/howto/getting-started/deploy-shared-filesystem.md
new file mode 100644
index 0000000..43a6cec
--- /dev/null
+++ b/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
+```
diff --git a/howto/getting-started/index.md b/howto/getting-started/index.md
index 710f486..f9b7a78 100644
--- a/howto/getting-started/index.md
+++ b/howto/getting-started/index.md
@@ -5,6 +5,7 @@ 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:
@@ -12,4 +13,5 @@ See the how-to guides in this section for how to get started with Charmed HPC.
 :hidden:
 
 Deploy workload manager <deploy-workload-manager>
+Deploy a shared filesystem <deploy-shared-filesystem>
 ```