docs: xfs quota documentation (#503)

* docs: created 4 new docs for xfs quota Signed-off-by: Bala Harish <[email protected]> * docs: created 4 new docs for xfs quota Signed-off-by: Bala Harish <[email protected]> * docs: created 4 new docs for xfs quota Signed-off-by: Bala Harish <[email protected]> --------- Signed-off-by: Bala Harish <[email protected]>
openebs · Jan 9, 2025 · 797cfaf · 797cfaf
1 parent 45c9a27
commit 797cfaf
Show file tree

Hide file tree

Showing 6 changed files with 673 additions and 0 deletions.
diff --git a/docs/i18n/en/docusaurus-plugin-content-docs/version-4.1.x.json b/docs/i18n/en/docusaurus-plugin-content-docs/version-4.1.x.json
@@ -90,5 +90,9 @@
   "sidebar.docs.category.Support": {
     "message": "Support",
     "description": "The label for category Support in sidebar docs"
+  },
+  "sidebar.docs.category.Backup and Restore": {
+    "message": "Backup and Restore",
+    "description": "The label for category Backup and Restore in sidebar docs"
   }
 }
diff --git a/...-user-guide/local-pv-hostpath/advanced-operations/xfs-quota/enable-xfs-quota.md b/...-user-guide/local-pv-hostpath/advanced-operations/xfs-quota/enable-xfs-quota.md
@@ -0,0 +1,166 @@
+---
+id: enable-xfs-quota
+title: Enable XFS Quota on LocalPV Hostpath
+keywords:
+ - OpenEBS LocalPV Hostpath Enable XFS Quota
+ - XFS Quota
+ - Enable XFS Quota
+ - Advanced Operations
+description: This section describes about enabling XFS quotas for OpenEBS LocalPV Hostpath. 
+---
+
+# Enable XFS Quota on LocalPV Hostpath
+
+This document provides the necessary steps to enable and configure XFS Quota on OpenEBS LocalPV HostPath. By following these instructions, you will install the OpenEBS LocalPV provisioner, create a StorageClass with XFS Quota support, and set up a PersistentVolumeClaim (PVC) to apply project quotas on the local volumes. It also includes the process for mounting the volume to an application pod and verifying that the quota is successfully applied.
+
+## Install the OpenEBS Dynamic LocalPV Provisioner
+
+Refer to the [OpenEBS Installation documentation](../../../../../quickstart-guide/installation.md) to install the OpenEBS LocalPV Hostpath Provisioner.
+
+## Create StorageClass
+
+1. To create a hostpath StorageClass with the XFSQuota configuration option, use the following YAML definition. This configuration will enable the XFSQuota for the specified path and storage type.
+
+```
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: openebs-hostpath-xfs
+  annotations:
+    openebs.io/cas-type: local
+    cas.openebs.io/config: |
+      - name: StorageType
+        value: "hostpath"
+      - name: BasePath
+        value: "/var/openebs/local/"
+      - name: XFSQuota
+        enabled: "true"
+provisioner: openebs.io/local
+volumeBindingMode: WaitForFirstConsumer
+reclaimPolicy: Delete
+```
+
+2. For advanced configuration of XFSQuota, you may also set the `softLimitGrace` and `hardLimitGrace` parameters, which define the storage capacity limits beyond the Persistent Volume (PV) storage request. The updated YAML definition is as follows:
+
+```
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: openebs-hostpath-xfs
+  annotations:
+    openebs.io/cas-type: local
+    cas.openebs.io/config: |
+      - name: StorageType
+        value: "hostpath"
+      - name: BasePath
+        value: "/var/openebs/local/"
+      - name: XFSQuota
+        enabled: "true"
+        data:
+          softLimitGrace: "0%"
+          hardLimitGrace: "0%"
+provisioner: openebs.io/local
+volumeBindingMode: WaitForFirstConsumer
+reclaimPolicy: Delete
+```
+
+:::note
+- `softLimitGrace` and `hardLimitGrace` are used in conjunction with the PV storage request to determine the soft and hard limits of the quota.
+
+- The size of these limits is calculated as **"Size of PV storage request * (1 + LimitGrace%)"**
+
+- If no values are specified, the default is **softLimitGrace: "0%" / hardLimitGrace: "0%"**, meaning the storage capacity is limited to the PV storage request value.
+
+  For example, with a PV of 100Gi capacity and values **softLimitGrace: "90%" / hardLimitGrace: "100%"**, the soft limit will be set to 190Gi, and the hard limit will be set to 200Gi.
+  You can select to use either `softLimitGrace` or `hardLimitGrace` independently based on your requirements.
+
+  Refer to the relevant [xfs_quota documentation](https://man7.org/linux/man-pages/man8/xfs_quota.8.html#QUOTA_OVERVIEW) for more detailed instructions regarding the configuration of soft and hard limits.
+:::
+
+## Create a PVC
+
+1. To create a PVC using the StorageClass's name, use the following definition:
+
+```
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  name: local-hostpath-xfs
+spec:
+  storageClassName: openebs-hostpath-xfs
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 5Gi
+```
+
+At this stage, the PVC will remain in the 'Pending' state until the volume is successfully mounted.
+
+2. Verify the PVC status.
+
+```
+$ kubectl get pvc
+```
+
+**Example Output**
+
+```
+NAME                  STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS           AGE
+local-hostpath-xfs    Pending                                      openebs-hostpath-xfs   21s
+```
+
+## Mount the Volume
+
+1. Mount the volume to the application pod container. A sample BusyBox Pod template is as follows:
+
+```
+apiVersion: v1
+kind: Pod
+metadata:
+  name: busybox
+spec:
+  volumes:
+  - name: local-storage
+    persistentVolumeClaim:
+      claimName: local-hostpath-xfs
+  containers:
+  - name: busybox
+    image: busybox
+    command:
+       - sh
+       - -c
+       - 'while true; do echo "`date` [`hostname`] Hello from OpenEBS Local PV." >> /mnt/store/greet.txt; sleep $(($RANDOM % 5 + 300)); done'
+    volumeMounts:
+    - mountPath: /mnt/store
+      name: local-storage
+```
+
+The PVC status will change to 'Bound' once the volume is successfully mounted and the quota will be applied.
+
+2. Verify that the XFS project quota is applied.
+
+```
+$ sudo xfs_quota -x -c 'report -h' /var/openebs/local/
+```
+
+**Example Output**
+
+```
+Project quota on /var/openebs/local (/dev/loop16)
+                        Blocks
+Project ID   Used   Soft   Hard Warn/Grace
+---------- ---------------------------------
+#0              0      0      0  00 [------]
+#1              0   5.7G   6.7G  00 [------]
+```
+
+## Limitation
+
+Resizing of quota is not supported.
+
+## See Also
+
+- [XFS Quota Prerequisites](xfs-quota-pre.md)
+- [Modify XFS Quota on LocalPV Hostpath](modify-xfs-quota.md)
+- [XFS Quota with Loop Device](xfs-quota-pre.md)
diff --git a/...-guide/local-pv-hostpath/advanced-operations/xfs-quota/loop-device-xfs-quota.md b/...-guide/local-pv-hostpath/advanced-operations/xfs-quota/loop-device-xfs-quota.md
@@ -0,0 +1,76 @@
+---
+id: loop-device-xfs-quota
+title: XFS Quota with Loop Device
+keywords:
+ - OpenEBS LocalPV Hostpath Modify XFS Quota
+ - XFS Quota
+ - XFS Quota with Loop Device
+ - Advanced Operations
+description: This section talks about creating XFS filesystem at the basepath as loop device. 
+---
+
+# XFS Quota with Loop Device
+
+In scenarios where you do not have an existing device formatted with the XFS filesystem, you can create an XFS filesystem on a loop device. This process is particularly useful when the root filesystem is not XFS and it allows you to simulate an XFS-based storage environment.
+
+This document outlines the steps to create a sparse file, format it with the XFS filesystem, and mount it as a loop device at the specified directory, `/var/openebs/local`, with project quota enabled.
+
+## Create XFS filesystem at the Basepath as Loop Device (If filesystem is not XFS)
+
+If your environment does not have a XFS filesystem, you can use a loop device to create an XFS filesystem. The following steps will guide you through the process of creating a 32MiB sparse file, formatting it with XFS, and mounting it with project quota enabled.
+
+1. **Ensure XFS Utilities Are Installed**
+
+Before proceeding, ensure that the library for managing xfs-fs is installed on your system.
+
+**For Ubuntu/Debian-based Systems**
+
+```
+sudo apt update
+sudo apt-get install -y xfsprogs
+```
+
+**For RHEL/CentOS-based Systems**
+
+```
+sudo yum install -y xfsprogs
+```
+
+2. **Create the Mount Directory**
+
+Create the directory where the filesystem will be mounted.
+
+```
+sudo mkdir -p /var/openebs/local
+cd /var/openebs
+```
+
+3. **Create a 32MiB Sparse File**
+
+Create a sparse file of maximum size 32MiB.
+
+```
+sudo dd if=/dev/zero of=xfs.32M bs=1 count=0 seek=32M
+```
+
+4. **Format the Sparse File with XFS**
+
+Format the newly created sparse file with the XFS filesystem.
+
+```
+sudo mkfs -t xfs -q xfs.32M
+```
+
+5. **Mount the Sparse File**
+
+Finally, mount the sparse file as a loop device with project quota enabled. This will make the file accessible as a directory, `/var/openebs/local`.
+
+```
+sudo mount -o loop,rw xfs.32M -o pquota /var/openebs/local
+```
+
+## See Also
+
+- [XFS Quota Prerequisites](xfs-quota-pre.md)
+- [Enable XFS Quota on LocalPV Hostpath](enable-xfs-quota.md)
+- [Modify XFS Quota on LocalPV Hostpath](modify-xfs-quota.md)