From 53d5f49453053692522c037d22a703d22f6a414a Mon Sep 17 00:00:00 2001 From: Kirill Kononovich <41591254+kirkonru@users.noreply.github.com> Date: Mon, 22 Jan 2024 12:37:16 +0300 Subject: [PATCH 1/3] Translate/review README.md Signed-off-by: Kirill Kononovich <41591254+kirkonru@users.noreply.github.com> --- docs/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 8e3cea71..3fde7ed7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,19 +7,19 @@ moduleStatus: experimental {{< alert level="warning" >}} The module is guaranteed to work only with stock kernels that are shipped with the [supported distributions](https://deckhouse.io/documentation/v1/supported_versions.html#linux). -The functionality of the module with other kernels or distributions is possible but not guaranteed. +The module may work with other kernels or distributions, but its stable operation and availability of all features is not guaranteed. {{< /alert >}} -The module manages `LVM` on cluster nodes through [Kubernetes custom resources](./cr.html), performing the following operations: +The module manages `LVM` on cluster nodes through [Kubernetes custom resources](./cr.html) by performing the following operations: - - Detecting block devices and creating/updating/deleting the corresponding [BlockDevice resources](./cr.html#blockdevice). + - Discovering block devices and creating/updating/deleting their corresponding [BlockDevice resources](./cr.html#blockdevice). > **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`. + - Discovering `LVM Volume Groups` on the nodes with the `storage.deckhouse.io/enabled=true` LVM tag attached and `Thin-pools` running on them 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 a 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). + - Scanning `LVM Physical Volumes` on the nodes that are part of managed `LVM Volume Groups`. In case the size of underlying block device expands, the corresponding `LVM Physical Volumes` will be automatically expanded as well (`pvresize` will occur). - > **Caution!** Reduction in the size of block devices is not supported. + > **Caution!** Downsizing a block device 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) + - Creating/expanding/deleting `LVM Volume Groups` on the node according to the changes the user has made to the `LVMVolumeGroup` resources. [Usage examples](./usage.html#lvmvolumegroup-resources) From c22af1586b5d3930582c0cde96beaf09dbae1cca Mon Sep 17 00:00:00 2001 From: Kirill Kononovich <41591254+kirkonru@users.noreply.github.com> Date: Mon, 22 Jan 2024 16:34:10 +0300 Subject: [PATCH 2/3] Translate/review USAGE.md Signed-off-by: Kirill Kononovich <41591254+kirkonru@users.noreply.github.com> --- docs/USAGE.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index 9f43a9a9..1d8d133e 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -6,7 +6,7 @@ description: Usage and examples of the sds-node-configurator controller operatio {{< alert level="warning" >}} The module is guaranteed to work only with stock kernels that are shipped with the [supported distributions](https://deckhouse.io/documentation/v1/supported_versions.html#linux). -The functionality of the module with other kernels or distributions is possible but not guaranteed. +The module may work with other kernels or distributions, but its stable operation and availability of all features is not guaranteed. {{< /alert >}} The controller supports two types of resources: @@ -35,7 +35,7 @@ The controller will use the information from the custom resource to handle `LVMV ### Updating a `BlockDevice` resource -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. +The controller independently updates the information in the custom resource if the state of the block device to which it refers to has changed on the node. ### Deleting a `BlockDevice` resource @@ -45,7 +45,7 @@ The following are the cases in which the controller will automatically delete a > The controller performs the above activities automatically and requires no user intervention. -> In case of manual deletion of the resource, it will be recreated by the controller. +> If the resource is manually deleted, it will be recreated by the controller. ## `LVMVolumeGroup` resources @@ -53,11 +53,11 @@ The following are the cases in which the controller will automatically delete a 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 +### Creating an `LVMVolumeGroup` resource -There are two ways to create a `LVMVolumeGroup` resource: +There are two ways to create an `LVMVolumeGroup` resource: * Automatically: - * 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. + * The controller automatically scans for information about the existing `LVM Volume Groups` on nodes and creates a resource if an `LVM Volume Group` is tagged with the `storage.deckhouse.io/enabled=true` LVM tag 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 `metadata.name` and `spec` fields. In it, they specify the desired state of the new `Volume Group`. @@ -96,23 +96,23 @@ There are two ways to create a `LVMVolumeGroup` resource: 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`. + > Please note that the resource does not specify the node on which the `Volume Group` will be created. The node is picked from the `BlockDevice` resources whose names are listed in `spec.blockDeviceNames`. - > **Caution!** All selected block devices must belong to the same node for an 'Local' `LVMVolumeGroup`. + > **Caution!** All the selected block devices must belong to the same node for a 'Local' `LVMVolumeGroup`. -### Updating a `LVMVolumeGroup` resource and a `Volume Group` +### Updating an `LVMVolumeGroup` resource and a `Volume Group` 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 `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` +### Deleting an `LVMVolumeGroup` resource and a `Volume Group` -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). +The controller will automatically delete a resource if the `Volume Group` it references has become unavailable (e.g., all block devices that made up the `Volume Group` have been unplugged). -> 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 user may delete a resource manually. However, if the corresponding `LVM Volume Group` still exists on the node at the moment the resource is deleted, the controller will create a resource *automatically* based on the existing `Volume Group` and assign a newly generated name to it. -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. +To delete an `LVM Volume Group` and its associated `LVM Physical Volume`, add 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 components from 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. +> **Caution!** It is forbidden to delete an `LVM Volume Group` using the above method if it contains a `Logical Volume`, even if it is only the `Thin-pool` that is specified in `spec`. The user must delete all `Logical Volumes` that the `Volume Group` to be deleted contains. From edc4be1cbbaaa2b8d85b255eafbac65ea229514f Mon Sep 17 00:00:00 2001 From: Kirill Kononovich <41591254+kirkonru@users.noreply.github.com> Date: Mon, 22 Jan 2024 18:15:47 +0300 Subject: [PATCH 3/3] Translate/review FAQ.md Signed-off-by: Kirill Kononovich <41591254+kirkonru@users.noreply.github.com> --- docs/FAQ.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 4b6a2984..6c382652 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -6,7 +6,7 @@ description: "Deckhouse Kubernetes Platform. The sds-node-configurator module. C {{< alert level="warning" >}} The module is guaranteed to work only with stock kernels that are shipped with the [supported distributions](https://deckhouse.io/documentation/v1/supported_versions.html#linux). -The functionality of the module with other kernels or distributions is possible but not guaranteed. +The module may work with other kernels or distributions, but its stable operation and availability of all features is not guaranteed. {{< /alert >}} ## Why does creating `BlockDevice` and `LVMVolumeGroup` resources in a cluster fail? @@ -19,25 +19,25 @@ The functionality of the module with other kernels or distributions is possible ## I have deleted the `LVMVolumeGroup` resource, but the `Volume Group` is still there. What do I do? -Deleting a `LVMVolumeGroup` resource does not delete the `Volume Group` it references. To delete it, add a special `storage.deckhouse.io/sds-delete-vg: ""` annotation to trigger the deletion process. The controller will then automatically delete the `LVM Volume Group` from the node and its associated resource. +Deleting an `LVMVolumeGroup` resource does not delete the `Volume Group` it references. To delete it, add a special `storage.deckhouse.io/sds-delete-vg: ""` annotation to trigger the deletion process. The controller will then automatically delete the `LVM Volume Group` from the node as well as its associated resource. -> Note that simply deleting the `LVMVolumeGroup` resource will result in the creation of a new resource with a generated name based on the existing `LVM Volume Group` on the node. +> Note that merely deleting the `LVMVolumeGroup` resource will result in a new resource with a generated name being created based on the existing `LVM Volume Group` on the node. ## I have attached the delete annotation, but the `LVMVolumeGroup` resource is still there as well as the `Volume Group` on the node. Why? -The usual case is that the corresponding `LVM Volume Group` on the node has `Logical Volumes`. The controller does not delete `Logical Volumes` because these `volumes` may contain important data and the user must purge them manually. +Typically, the `LVM Volume Group` on the node has the corresponding `Logical Volumes`. The controller does not delete `Logical Volumes` because these `volumes` may contain important data. Thus, the user must purge them manually. Once the `Logical Volume` has been deleted, the controller will proceed to delete the `Volume Group` and its corresponding resource. ## I'm trying to create a `Volume Group` using the `LVMVolumeGroup` resource, but I'm not getting anywhere. Why? -Most likely, your resource fails controller validation, although it has passed the Kubernetes validation successfully. -The exact cause of the failure can be found in the `status.message` field of the resource itself, -or you can refer to the controller's logs. +Most likely, your resource fails controller validation even if it has passed the Kubernetes validation successfully. +The exact cause of the failure can be found in the `status.message` field of the resource itself. +You can also refer to the controller's logs. -The problem usually stems from incorrectly defined `BlockDevice` resources. Please make sure that these resources meet the following requirements: +The problem usually stems from incorrectly defined `BlockDevice` resources. Please make sure these resources meet the following requirements: - The `Consumable` field is set to `true`. -- For a `Volume Group` of type `Local`, the specified `BlockDevice` belong to the same node. +- For a `Volume Group` of the `Local` type, the specified `BlockDevice` belong to the same node. - The current names of the `BlockDevice` resources are specified. The full list of expected values can be found in the [CR reference](./cr.html) of the `LVMVolumeGroup` resource. @@ -47,7 +47,7 @@ The full list of expected values can be found in the [CR reference](./cr.html) o The `LVMVolumeGroup` resource will persist as long as the corresponding `Volume Group` exists. As long as at least one device exists, the `Volume Group` will be there, albeit in an unhealthy state. Note that these issues will be reflected in the resource's `status`. -When the unplugged device is reactivated, the `LVM Volume Group` will recover while the linked `LVMVolumeGroup` resource be brought to its current state as well. +Once the unplugged device is plugged back in and reactivated, the `LVM Volume Group` will regain its functionality while the corresponding `LVMVolumeGroup` resource will also be updated to reflect the current state. ## How to transfer control of an existing `LVM Volume Group` on the node to the controller? @@ -69,6 +69,6 @@ The controller will then stop tracking the selected `Volume Group` and delete th ## I haven't added the `storage.deckhouse.io/enabled=true` LVM tag to the `Volume Group`, but it is there. How is this possible? -This is possible if you have created the `LVM Volume Group` using the `LVMVolumeGroup` resource, in which case the controller will automatically add this LVM tag to the created `LVM Volume Group`. Alternatively, this applies if the `Volume Group` or its `Thin-pool` already had the `linstor` module LVM tag `linstor-*`. +This can happen if you created the `LVM Volume Group` using the `LVMVolumeGroup` resource, in which case the controller will automatically add this LVM tag to the created `LVM Volume Group`. This is also possible if the `Volume Group` or its `Thin-pool` already had the `linstor-*` LVM tag of the `linstor` module. -When you switch from the `linstor` module to the `sds-node-configurator` and `sds-drbd` modules, the `linstor-*` LVM tags are automatically replaced with the `storage.deckhouse.io/enabled=true` LVM tag in the `Volume Group`. This way, the `sds-node-configurator` gets control of these `Volume Groups`. +When you switch from the `linstor` module to the `sds-node-configurator` and `sds-drbd` modules, the `linstor-*` LVM tags are automatically replaced with the `storage.deckhouse.io/enabled=true` LVM tag in the `Volume Group`. This way, the `sds-node-configurator` gains control over these `Volume Groups`.