fix usage

Signed-off-by: Aleksandr Zimin <[email protected]>
deckhouse · Jan 21, 2024 · 9c5edbc · 9c5edbc
1 parent 55170d5
commit 9c5edbc
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 34 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -14,12 +14,12 @@ The module manages `LVM` on cluster nodes through [Kubernetes custom resources](
 
   - Detecting block devices and creating/updating/deleting the corresponding [BlockDevice resources](./cr.html#blockdevice).
 
-   > **Attention!** Manual creation and modification of the `BlockDevice` resource is prohibited.
+   > **Caution!** Manual creation and modification of the `BlockDevice` resource is prohibited.
 
   - Detecting `LVM Volume Groups` with the `storage.deckhouse.io/enabled=true` LVM tag and `Thin-pools` on them on the nodes, as well as managing the corresponding [LVMVolumeGroup resources](./cr.html#lvmvolumegroup). The module automatically creates an `LVMVolumeGroup` resource if it does not yet exist for the discovered `LVM Volume Group`.
 
   - Scanning `LVM Physical Volumes` on the nodes that are part of managed `LVM Volume Groups`. In case of expansion of underlying block device sizes, the corresponding `LVM Physical Volumes` will be automatically expanded (`pvresize` will occur).
 
-  > **Attention!** Reduction in the size of block devices is not supported.
+  > **Caution!** Reduction in the size of block devices is not supported.
 
   - Creating/expanding/deleting `LVM Volume Groups` on the node in accordance with user changes in `LVMVolumeGroup` resources. [Usage examples](./usage.html#lvmvolumegroup-resources)
diff --git a/docs/USAGE.md b/docs/USAGE.md
@@ -9,7 +9,6 @@ The module is guaranteed to work only with stock kernels that are shipped with t
 The functionality of the module with other kernels or distributions is possible but not guaranteed.
 {{< /alert >}}
 
-
 The controller supports two types of resources:
 * `BlockDevice`;
 * `LVMVolumeGroup`.
@@ -27,7 +26,7 @@ It contains all the information about the device in question.
 * The device is not a drbd device.
 * The device is not a pseudo-device (i.e. not a loop device).
 * The device is not a `Logical Volume`.
-* File system is missing or matches LVM2_MEMBER.
+* File system is missing or matches `LVM2_MEMBER`.
 * The block device has no partitions.
 * The size of the block device is greater than 1 Gi.
 * If the device is a virtual disk, it must have a serial number.
@@ -36,52 +35,84 @@ The controller will use the information from the custom resource to handle `LVMV
 
 ### Updating a `BlockDevice` resource
 
-The controller updates the information in the custom resource independently if the state of the block device it refers to has changed.
+The controller independently updates the information in the custom resource if the state of the block device, to which it refers, has changed on the node.
 
 ### Deleting a `BlockDevice` resource
 
 The following are the cases in which the controller will automatically delete a resource if the block device it refers to has become unavailable:
 * if the resource had a Consumable status;
-* if the block device belongs to a `Volume Group` that does not have the tag `storage.deckhouse.io/enabled=true` attached to it (this `Volume Group` is not managed by our controller).
-
+* if the block device belongs to a `Volume Group` that does not have the LVM tag `storage.deckhouse.io/enabled=true` attached to it (this `Volume Group` is not managed by our controller).
 
 > The controller performs the above activities automatically and requires no user intervention.
 
-## `LVMVolumeGroup` resources
+> In case of manual deletion of the resource, it will be recreated by the controller.
 
-The `BlockDevice` resources are required to create and update `LVMVolumeGroup` resources.
+## `LVMVolumeGroup` resources
 
-The `LVMVolumeGroup` resources are designed to communicate with the `Volume Group` and display up-to-date information about their state.
+`BlockDevice` resources are required to create and update `LVMVolumeGroup` resources.
+Currently, only local `Volume Groups` are supported.
+`LVMVolumeGroup` resources are designed to communicate with the `LVM Volume Groups` on nodes and display up-to-date information about their state.
 
-### Creating a `LVMVolumeGroup` resource and a `Volume Group`
+### Creating a `LVMVolumeGroup` resource
 
 There are two ways to create a `LVMVolumeGroup` resource:
 * Automatically:
-  * The controller automatically scans for information about the existing `Volume Groups` on nodes and creates a resource 
-  if a `Volume Group` is tagged with `storage.deckhouse.io/enabled=true` and there is no matching resource for it.
+  * The controller automatically scans for information about the existing `LVM Volume Groups` on nodes and creates a resource if a `LVM Volume Group` is tagged with LVM tag `storage.deckhouse.io/enabled=true` and there is no matching Kubernetes resource for it.
   * In this case, the controller populates all fields of the resource on its own.
 * By the user:
-  * The user manually creates the resource by filling in only the `Spec` field. In it, they specify the desired state of the new `Volume Group`.
-  * This information is then validated to ensure that the configuration provided is correct and can be implemented.
-  * After successful validation, the controller uses the provided information to create the specified `Volume Group` and update the user resource with the actual information about the state of the created `Volume Group`.  
+  * The user manually creates the resource by filling in only the `metadata.name` and `spec` fields. In it, they specify the desired state of the new `Volume Group`.
+  * This configuration is then validated to ensure its correctness.
+  * After successful validation, the controller uses the provided configuration to create the specified `LVM Volume Group` on the node and update the user resource with the actual information about the state of the created `LVM Volume Group`.
+  * An example of a resource for creating a local `LVM Volume Group` from multiple `BlockDevices`:
+
+    ```yaml
+    apiVersion: storage.deckhouse.io/v1alpha1
+    kind: LvmVolumeGroup
+    metadata:
+      name: "vg-0-on-node-0"
+    spec:
+      type: Local
+      blockDeviceNames:
+        - dev-c1de9f9b534bf5c0b44e8b1cd39da80d5cda7c3f
+        - dev-f3269d92a99e1f668255a47d5d3500add1462711
+      actualVGNameOnTheNode: "vg-0"
+    ```
+  
+  * An example of a resource for creating a local `LVM Volume Group` and a `Thin-pool` on it from multiple `BlockDevices`:
+
+    ```yaml
+    apiVersion: storage.deckhouse.io/v1alpha1
+    kind: LvmVolumeGroup
+    metadata:
+      name: "vg-thin-on-node-0"
+    spec:
+      type: Local
+      blockDeviceNames:
+        - dev-0428672e39334e545eb96c85f8760fd59dcf15f1
+        - dev-456977ded72ef804dd7cec90eec94b10acdf99b7
+      actualVGNameOnTheNode: "vg-thin"
+      thinPools:
+      - name: thin-1
+        size: 250Gi
+    ```
+
+  > Please note that the resource does not specify the node on which the `Volume Group` will be created. The node is determined from the `BlockDevice` resources whose names are specified in `spec.blockDeviceNames`.
+
+  > **Caution!** All selected block devices must belong to the same node for an 'Local' `LVMVolumeGroup`.
 
 ### Updating a `LVMVolumeGroup` resource and a `Volume Group`
 
-The controller automatically updates the `Status` field of the `LVMVolumeGroup` with the current data about the `Volume Group` in question.
-We do **not recommend** making manual changes to the `Status` field.
+The controller automatically updates the `status` field of the `LVMVolumeGroup` resource to display up-to-date data about the corresponding `LVM Volume Group` on the node.
+We do **not recommend** making manual changes to the `status` field.
 
-> The controller does not update the `Spec` field since it represents the desired state of the `Volume Group`. The user can make changes to the `Spec` field to change the state of the `Volume Group`.
+> The controller does not update the `spec` field since it represents the desired state of the `LVM Volume Group`. The user can make changes to the `spec` field to change the state of the `LVM Volume Group` on the node.
 
 ### Deleting a `LVMVolumeGroup` resource and a `Volume Group`
 
-The controller will automatically delete a resource if the `Volume Group` it references has become unavailable.
-
-> The user may delete a resource manually. However, if the corresponding `Volume Group` still exists at the moment the resource is deleted, 
-> the controller will create a resource *automatically* based on the existing `Volume Group` 
-> and assign it a new generated name.
+The controller will automatically delete a resource if the `Volume Group` it references has become unavailable (e.g. all block devices forming the `Volume Group` have been unplugged).
 
-To delete a `Volume Group` and its associated `Physical Volume`, append the `storage.deckhouse.io/sds-delete-vg: ""` annotation to the corresponding `LVMVolumeGroup` resource.
+> The user may delete a resource manually. However, if the corresponding `LVM Volume Group` still exists at the moment the resource is deleted, the controller will create a resource *automatically* based on the existing `Volume Group` and assign it a new generated name.
 
-The controller will detect that the annotation has been added and initiate the process of deleting the `Volume Group` and its parts.
+To delete a `LVM Volume Group` and its associated `LVM Physical Volume`, append the `storage.deckhouse.io/sds-delete-vg: ""` annotation to the corresponding `LVMVolumeGroup` resource. The controller will detect that the annotation has been added and initiate the process of deleting the `Volume Group` and its parts from the node.
 
-This will result in the `Volume Group` being deleted, as well as its associated `Physical Volume`, and the `LVMVolumeGroup` resource (**if there is no `Logical Volume`** on the `Volume Group`**). If there is a `Logical Volume` on the `Volume Group`, the user must first manually delete the `Logical Volume` on the node.
+> **Caution!** It is forbidden to delete a `LVM Volume Group` using the above method if it contains a `Logical Volume`, even if it is only a `Thin-pool` that is specified in `spec`. The user must delete all `Logical Volumes` that the `Volume Group` to be deleted contains.
diff --git a/docs/USAGE_RU.md b/docs/USAGE_RU.md
@@ -49,23 +49,22 @@ description: Использование и примеры работы SDS-Node-
 
 ## Работа с ресурсами `LVMVolumeGroup`
 
-Ресурсы `BlockDevice` необходимы для создания и обновления ресурсов `LVMVolumeGroup`. На данный момент поддерживаются только локальные `Volume Group`.
-
+Ресурсы `BlockDevice` необходимы для создания и обновления ресурсов `LVMVolumeGroup`. 
+На данный момент поддерживаются только локальные `Volume Group`.
 `LVMVolumeGroup`-ресурсы предназначены для взаимодействия с `LVM Volume Group` на узлах и отображения актуальной информации об их состоянии.
 
 ### Создание ресурса `LVMVolumeGroup`
 
 Ресурс `LVMVolumeGroup` может быть создан 2 способами:
 * Автоматическое создание:
-  * Контроллер автоматически сканирует информацию о существующих `LVM Volume Group` на узлах и создает ресурс в случае,
-  если у `LVM Volume Group` имеется LVM-тег `storage.deckhouse.io/enabled=true` и соответствующий ей Kubernetes-ресурс отсутствует.
+  * Контроллер автоматически сканирует информацию о существующих `LVM Volume Group` на узлах и создает ресурс в случае, если у `LVM Volume Group` имеется LVM-тег `storage.deckhouse.io/enabled=true` и соответствующий ей Kubernetes-ресурс отсутствует.
   * В этом случае контроллер самостоятельно заполняет все поля ресурса.
 * Пользовательское создание:
   * Пользователь вручную создает ресурс, заполняя только поля `metadata.name` и `spec`, в котором указывает желаемое состояние новой `Volume Group`.
-  * Конфигурации, указанная пользователем, пройдет специальную валидацию на корректность.
+  * Конфигурация, указанная пользователем, пройдет специальную валидацию на корректность.
   * После успешного прохождения валидации контроллер использует указанную конфигурацию, чтобы по ней создать указанную `LVM Volume Group` на узле и обновить пользовательский ресурс актуальной информацией о состоянии созданной `LVM Volume Group`.
   * Пример ресурса для создания локальной `LVM Volume Group` из нескольких `BlockDevice`:
-    
+
     ```yaml
     apiVersion: storage.deckhouse.io/v1alpha1
     kind: LvmVolumeGroup
@@ -80,7 +79,7 @@ description: Использование и примеры работы SDS-Node-
     ```
 
   * Пример ресурса для создания локальной `LVM Volume Group` и `Thin-pool` на ней из нескольких `BlockDevice`:
-    
+
     ```yaml
     apiVersion: storage.deckhouse.io/v1alpha1
     kind: LvmVolumeGroup
@@ -96,6 +95,7 @@ description: Использование и примеры работы SDS-Node-
       - name: thin-1
         size: 250Gi
     ```
+
   > Обратите внимание, что в ресурсе не указывается узел, на котором будет создана `Volume Group`. Узел берется из ресурсов `BlockDevice`, имена которых указаны в `spec.blockDeviceNames`.
 
   > **Внимание!** Все выбранные блок-девайсы должны принадлежать одному узлу для `LVMVolumeGroup` с типом 'Local'.