docs: Add documentation about LVM LogicalVolume volumes

Add some documentation about how to create LVM LogicalVolume volumes from the CLI and explanation about fields Refs: #1997
scality · Mar 29, 2021 · 2e66c69 · 2e66c69
1 parent d87e0eb
commit 2e66c69
Show file tree

Hide file tree

Showing 5 changed files with 199 additions and 73 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -74,10 +74,73 @@
 if not salt_defaults["metalk8s"]["downgrade"]["enabled"]:
     tags.add("downgrade_not_supported")
 
+# Read volume examples
+volume_common_fields = {
+    "name": "the name of your volume, must be unique",
+    "nodeName": "the name of the node where the volume will be located",
+    "storageClassName": "the StorageClass to use",
+    "mode": "describes how the volume is intented to be consumed, "
+    "either Block or Filesystem (default to Filesystem if not specificed)",
+}
+basic_block_device = """
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <volume_name>
+spec:
+  nodeName: <node_name>
+  storageClassName: <storageclass_name>
+  mode: "Filesystem"
+  rawBlockDevice:
+    devicePath: <device_path>
+"""
+basic_lvm_lv = """
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <volume_name>
+spec:
+  nodeName: <node_name>
+  storageClassName: <storageclass_name>
+  mode: "Filesystem"
+  lvmLogicalVolume:
+    vgName: <vg_name>
+    size: 10Gi
+"""
+volume_infos = {
+    "rawBlockDevice": {
+        "example_variables": {
+            "device_path": "with the ``/dev`` path for the partitions to use",
+        },
+        "fields": {"devicePath": "path to the block device (for example: `/dev/sda1`)"},
+        "basic": basic_block_device,
+    },
+    "lvmLogicalVolume": {
+        "example_variables": {
+            "vg_name": "with the existing LVM VolumeGroup name of this specific Node",
+        },
+        "fields": {
+            "vgName": "LVM VolumeGroup name to create the LogicalVolume "
+            "the VolumeGroup must exists on the Node",
+            "size": "Size of the LVM LogicalVolume to create",
+        },
+        "basic": basic_lvm_lv,
+    },
+}
+
+with open("../examples/block-device-volumes.yaml") as fd:
+    volume_infos["rawBlockDevice"]["examples"] = fd.read()
+with open("../examples/lvm-lv-volumes.yaml") as fd:
+    volume_infos["lvmLogicalVolume"]["examples"] = fd.read()
+
 jinja_contexts = {
     "salt_values": {
         "listening_processes": salt_defaults["networks"]["listening_process_per_role"]
-    }
+    },
+    "volume_values": {
+        "volume_infos": volume_infos,
+        "common_fields": volume_common_fields,
+    },
 }
 
 # -- General configuration ---------------------------------------------------

diff --git a/docs/installation/post-install.rst b/docs/installation/post-install.rst
@@ -16,55 +16,31 @@ node`, or later on other nodes joining the cluster. It is even recommended to
 separate :ref:`Bootstrap services <node-role-bootstrap>` from :ref:`Infra
 services <node-role-infra>`.
 
-To create the required *Volume* objects, write a YAML file with the following
-contents, replacing ``<node_name>`` with the name of the :term:`Node` on which
-to run Prometheus, AlertManager and Loki, and ``<device_path[3]>`` with the
-``/dev`` path for the partitions to use:
-
-.. code-block:: yaml
-
-   ---
-   apiVersion: storage.metalk8s.scality.com/v1alpha1
-   kind: Volume
-   metadata:
-     name: <node_name>-prometheus
-   spec:
-     nodeName: <node_name>
-     storageClassName: metalk8s
-     rawBlockDevice:  # Choose a device with at least 10GiB capacity
-       devicePath: <device_path>
-     template:
-       metadata:
-         labels:
-           app.kubernetes.io/name: 'prometheus-operator-prometheus'
-   ---
-   apiVersion: storage.metalk8s.scality.com/v1alpha1
-   kind: Volume
-   metadata:
-     name: <node_name>-alertmanager
-   spec:
-     nodeName: <node_name>
-     storageClassName: metalk8s
-     rawBlockDevice:  # Choose a device with at least 1GiB capacity
-       devicePath: <device_path2>
-     template:
-       metadata:
-         labels:
-           app.kubernetes.io/name: 'prometheus-operator-alertmanager'
-   ---
-   apiVersion: storage.metalk8s.scality.com/v1alpha1
-   kind: Volume
-   metadata:
-     name: <node_name>-loki
-   spec:
-     nodeName: <node_name>
-     storageClassName: metalk8s
-     rawBlockDevice:  # Choose a device with at least 10GiB capacity
-       devicePath: <device_path3>
-     template:
-       metadata:
-         labels:
-           app.kubernetes.io/name: 'loki'
+To create the required *Volume* objects, use one of the following volume
+type depending on the platform.
+
+.. jinja:: volume_values
+
+   {%- for volume_type, volume_info in volume_infos.items() %}
+
+   {{ volume_type }} Volumes
+   """""""""""""""""""""""""
+
+   Write a YAML file with the following contents, replacing:
+
+   - ``<node_name>`` with the name of the :term:`Node` on which
+   {% for variable, info in volume_info["example_variables"].items() %}
+   - ``<{{ variable }}>`` {{ info }}
+   {% endfor %}
+
+   .. code-block:: yaml
+
+      {{ volume_info["examples"] | indent(6) }}
+
+   {% endfor %}
+
+Create Volumes objects
+""""""""""""""""""""""
 
 Once this file is created with the right values filled in, run the following
 command to create the *Volume* objects (replacing ``<file_path>`` with the path

diff --git a/docs/operation/volume_management/volume_creation_deletion_cli.rst b/docs/operation/volume_management/volume_creation_deletion_cli.rst
@@ -16,29 +16,29 @@ Requirements
 Creating a Volume
 -----------------
 
-#. Create a Volume manifest using the following template:
-
-   .. code-block:: yaml
-
-       apiVersion: storage.metalk8s.scality.com/v1alpha1
-       kind: Volume
-       metadata:
-         name: <volume_name>
-       spec:
-         nodeName: <node_name>
-         storageClassName: <storageclass_name>
-         mode: "Filesystem"
-         rawBlockDevice:
-           devicePath: <device_path>
-
-   Set the following fields:
-
-   - **name**: the name of your volume, must be unique.
-   - **nodeName**: the name of the node where the volume will be located.
-   - **storageClassName**: the StorageClass to use.
-   - **mode**: describes how the volume is intended to be consumed, either
-     Block or Filesystem (default to Filesystem if not specified).
-   - **devicePath**: path to the block device (for example: `/dev/sda1`).
+#. Create a Volume manifest using one of the following templates:
+
+   .. jinja:: volume_values
+
+       {%- for volume_type, volume_info in volume_infos.items() %}
+
+       {{ volume_type }} Volumes
+       ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+       .. code-block:: yaml
+
+          {{ volume_info["basic"] | indent(8) }}
+
+
+       Set the following fields:
+
+       {% for key, info in common_fields.items() %}
+       - **{{ key }}**: {{ info }}.
+       {% endfor %}
+       {% for key, info in volume_info["fields"].items() %}
+       - **{{ key }}**: {{ info }}.
+       {% endfor %}
+       {% endfor %}
 
 #. Create the Volume.
 

diff --git a/examples/block-device-volumes.yaml b/examples/block-device-volumes.yaml
@@ -0,0 +1,42 @@
+---
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <node_name>-prometheus
+spec:
+  nodeName: <node_name>
+  storageClassName: metalk8s
+  rawBlockDevice:  # Choose a device with at least 10GiB capacity
+    devicePath: <device_path>
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: 'prometheus-operator-prometheus'
+---
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <node_name>-alertmanager
+spec:
+  nodeName: <node_name>
+  storageClassName: metalk8s
+  rawBlockDevice:  # Choose a device with at least 1GiB capacity
+    devicePath: <device_path2>
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: 'prometheus-operator-alertmanager'
+---
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <node_name>-loki
+spec:
+  nodeName: <node_name>
+  storageClassName: metalk8s
+  rawBlockDevice:  # Choose a device with at least 10GiB capacity
+    devicePath: <device_path3>
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: 'loki'
diff --git a/examples/lvm-lv-volumes.yaml b/examples/lvm-lv-volumes.yaml
@@ -0,0 +1,45 @@
+---
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <node_name>-prometheus
+spec:
+  nodeName: <node_name>
+  storageClassName: metalk8s
+  lvmLogicalVolume:
+    vgName: <vg_name>  # Choose an existing LVM VolumeGroup
+    size: 10Gi  # Prometheus LogicalVolume should have at least 10GiB capacity
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: 'prometheus-operator-prometheus'
+---
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <node_name>-alertmanager
+spec:
+  nodeName: <node_name>
+  storageClassName: metalk8s
+  lvmLogicalVolume:
+    vgName: <vg_name>  # Choose an existing LVM VolumeGroup
+    size: 10Gi  # Alertmanager LogicalVolume should have at least 1GiB capacity
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: 'prometheus-operator-alertmanager'
+---
+apiVersion: storage.metalk8s.scality.com/v1alpha1
+kind: Volume
+metadata:
+  name: <node_name>-loki
+spec:
+  nodeName: <node_name>
+  storageClassName: metalk8s
+  lvmLogicalVolume:
+    vgName: <vg_name>  # Choose an existing LVM VolumeGroup
+    size: 10Gi  # Loki LogicalVolume should have at least 10GiB capacity
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: 'loki'