From 2e66c6933320fc8ee90a1ac3d7c3f7d4d1d7c277 Mon Sep 17 00:00:00 2001 From: Teddy Andrieux Date: Fri, 26 Mar 2021 18:20:48 +0100 Subject: [PATCH] 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 --- docs/conf.py | 65 +++++++++++++++- docs/installation/post-install.rst | 74 +++++++------------ .../volume_creation_deletion_cli.rst | 46 ++++++------ examples/block-device-volumes.yaml | 42 +++++++++++ examples/lvm-lv-volumes.yaml | 45 +++++++++++ 5 files changed, 199 insertions(+), 73 deletions(-) create mode 100644 examples/block-device-volumes.yaml create mode 100644 examples/lvm-lv-volumes.yaml diff --git a/docs/conf.py b/docs/conf.py index 41fe341290..76bf39ffe4 100644 --- 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: +spec: + nodeName: + storageClassName: + mode: "Filesystem" + rawBlockDevice: + devicePath: +""" +basic_lvm_lv = """ +apiVersion: storage.metalk8s.scality.com/v1alpha1 +kind: Volume +metadata: + name: +spec: + nodeName: + storageClassName: + mode: "Filesystem" + lvmLogicalVolume: + vgName: + 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 index 9a30b168f5..166cdc0403 100644 --- 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 ` from :ref:`Infra services `. -To create the required *Volume* objects, write a YAML file with the following -contents, replacing ```` with the name of the :term:`Node` on which -to run Prometheus, AlertManager and Loki, and ```` with the -``/dev`` path for the partitions to use: - -.. code-block:: yaml - - --- - apiVersion: storage.metalk8s.scality.com/v1alpha1 - kind: Volume - metadata: - name: -prometheus - spec: - nodeName: - storageClassName: metalk8s - rawBlockDevice: # Choose a device with at least 10GiB capacity - devicePath: - template: - metadata: - labels: - app.kubernetes.io/name: 'prometheus-operator-prometheus' - --- - apiVersion: storage.metalk8s.scality.com/v1alpha1 - kind: Volume - metadata: - name: -alertmanager - spec: - nodeName: - storageClassName: metalk8s - rawBlockDevice: # Choose a device with at least 1GiB capacity - devicePath: - template: - metadata: - labels: - app.kubernetes.io/name: 'prometheus-operator-alertmanager' - --- - apiVersion: storage.metalk8s.scality.com/v1alpha1 - kind: Volume - metadata: - name: -loki - spec: - nodeName: - storageClassName: metalk8s - rawBlockDevice: # Choose a device with at least 10GiB capacity - devicePath: - 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: + + - ```` 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 ```` 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 index 45ee49693a..5220b47d9a 100644 --- 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: - spec: - nodeName: - storageClassName: - mode: "Filesystem" - rawBlockDevice: - devicePath: - - 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 new file mode 100644 index 0000000000..7cc6a19dff --- /dev/null +++ b/examples/block-device-volumes.yaml @@ -0,0 +1,42 @@ +--- +apiVersion: storage.metalk8s.scality.com/v1alpha1 +kind: Volume +metadata: + name: -prometheus +spec: + nodeName: + storageClassName: metalk8s + rawBlockDevice: # Choose a device with at least 10GiB capacity + devicePath: + template: + metadata: + labels: + app.kubernetes.io/name: 'prometheus-operator-prometheus' +--- +apiVersion: storage.metalk8s.scality.com/v1alpha1 +kind: Volume +metadata: + name: -alertmanager +spec: + nodeName: + storageClassName: metalk8s + rawBlockDevice: # Choose a device with at least 1GiB capacity + devicePath: + template: + metadata: + labels: + app.kubernetes.io/name: 'prometheus-operator-alertmanager' +--- +apiVersion: storage.metalk8s.scality.com/v1alpha1 +kind: Volume +metadata: + name: -loki +spec: + nodeName: + storageClassName: metalk8s + rawBlockDevice: # Choose a device with at least 10GiB capacity + devicePath: + template: + metadata: + labels: + app.kubernetes.io/name: 'loki' diff --git a/examples/lvm-lv-volumes.yaml b/examples/lvm-lv-volumes.yaml new file mode 100644 index 0000000000..185a3b1689 --- /dev/null +++ b/examples/lvm-lv-volumes.yaml @@ -0,0 +1,45 @@ +--- +apiVersion: storage.metalk8s.scality.com/v1alpha1 +kind: Volume +metadata: + name: -prometheus +spec: + nodeName: + storageClassName: metalk8s + lvmLogicalVolume: + vgName: # 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: -alertmanager +spec: + nodeName: + storageClassName: metalk8s + lvmLogicalVolume: + vgName: # 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: -loki +spec: + nodeName: + storageClassName: metalk8s + lvmLogicalVolume: + vgName: # Choose an existing LVM VolumeGroup + size: 10Gi # Loki LogicalVolume should have at least 10GiB capacity + template: + metadata: + labels: + app.kubernetes.io/name: 'loki'