From 839b4b6b21fbf96632999cc2962921c279ab8a36 Mon Sep 17 00:00:00 2001 From: Aleksandr Zimin Date: Sun, 21 Jan 2024 23:32:35 +0300 Subject: [PATCH] fix faq Signed-off-by: Aleksandr Zimin --- docs/FAQ.md | 56 ++++++++++++++++++++++++++++---------------------- docs/FAQ_RU.md | 15 ++++++++++++-- 2 files changed, 44 insertions(+), 27 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index a7f5a01f..72adad8d 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -11,59 +11,65 @@ The functionality of the module with other kernels or distributions is possible ## Why does creating `BlockDevice` and `LVMVolumeGroup` resources in a cluster fail? -* In most cases, the creation of `BlockDevice` resources fails because the existing devices fail filtering by the controller. Please make sure that your devices meet the [requirements](link to requirements). +* In most cases, the creation of `BlockDevice` resources fails because the existing devices fail filtering by the controller. Please make sure that your devices meet the [requirements](./usage.html#the-conditions-the-controller-imposes-on-the-device). -* Creating `LVMVolumeGroup` resources may fail due to the missing `BlockDevice` resources, as they use them as the data source. +* Creating LVMVolumeGroup resources may fail due to the absence of BlockDevice resources in the cluster, as their names are used in the LVMVolumeGroup specification. -* If the `BlockDevice` resources are present and the `LVMVolumeGroup` resources are not present, please make sure the existing `Volume Group` has a special tag `storage.deckhouse.io/enabled=true` attached. +* If the `BlockDevice` resources are present and the `LVMVolumeGroup` resources are not present, please make sure the existing `LVM Volume Group` on the node has a special tag `storage.deckhouse.io/enabled=true` attached. ## 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 -`Volume Group` and its associated resource. +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. -> Note thatSimply deleting the `LVMVolumeGroup` resource will result in the creation of a new resource with a generated name based on the existing `Volume Group`. +> 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. ## 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 there are `Logical Volumes` for the `Volume Group` the resource references. The controller does not delete `Logical Volumes` because these `volumes` may contain data and the user must purge them manually. +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. Once the `Logical Volume` has been deleted, the controller will proceed to delete the `Volume Group` and its corresponding resource. -> The time it takes to delete may be longer if the controller's reconcile queue is crowded with other events. To delete the `Volume Group` and its linked resource immediately, update the delete annotation, e. g., by adding any number to its value: `storage.deckhouse.io/sds-delete-vg: ""` -> `storage.deckhouse.io/sds-delete-vg: "1"`. -> In this case, it will be deleted immediately. - ## 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. -The exact cause of the failure can be found in the `Status.Message` field of the resource itself, +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. > The problem usually stems from incorrectly defined `BlockDevice` resources. Please make sure that 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 type `Shared`, the specified `BlockDevice` is the only resource. -> - The selected `BlockDevice` does not share other `LVMVolumeGroup` resources (other `Volume Groups`). + > - The current names of the `BlockDevice` resources are specified. -> The full list of expected values can be found in the [CR reference](link to the reference) of the `LVMVolumeGroup` resource. +> +> The full list of expected values can be found in the [CR reference](./cr.html) of the `LVMVolumeGroup` resource. ## What happens if I unplug one of the devices in a `Volume Group`? Will the linked `LVMVolumeGroup` resource be deleted? 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`. +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. + +## How to transfer control of an existing `LVM Volume Group` on the node to the controller? + +Simply add the LVM tag `storage.deckhouse.io/enabled=true` to the LVM Volume Group on the node: + +```shell +vgchange myvg-0 --addtag storage.deckhouse.io/enabled=true +``` -When the unplugged device is reactivated, the `Volume Group` will recover while the linked `LVMVolumeGroup` resource be brought to its current state as well. +## How do I get the controller to stop monitoring the `LVM Volume Group` on the node? -## How do I get the controller to stop monitoring the `Volume Group`? +Delete the `storage.deckhouse.io/enabled=true` LVM tag for the target `Volume Group` on the node: -Delete the `storage.deckhouse.io/enabled=true` tag for the target `Volume Group`. The controller will then stop tracking the selected `Volume Group` and delete the associated `LVMVolumeGroup` resource automatically. +```shell +vgchange myvg-0 --addtag storage.deckhouse.io/enabled=true +``` -## I haven't added the `storage.deckhouse.io/enabled=true` tag to the `Volume Group`, but it is there. How is this possible? +The controller will then stop tracking the selected `Volume Group` and delete the associated `LVMVolumeGroup` resource automatically. -This is possible if you have created the `Volume group` using the `LVMVolumeGroup` resource (in this case, the controller will automatically add this tag to the created `Volume Group`) or if this `Volume Group` had the `Linstor` module tag (`linstor-*`). +## I haven't added the `storage.deckhouse.io/enabled=true` LVM tag to the `Volume Group`, but it is there. How is this possible? -The `sds-node-configurator` module replaces some of the functionality of the `linstor-pools-importer` controller of the built-in `Linstor` module. -So when you switch from the `Linstor` module to the `sds-node-configurator` and `sds-drbd` modules, the `linstor-*` tags are automatically replaced with the `storage.deckhouse.io/enabled=true` tag in the `Volume Group`. This way, the `sds-node-configurator` gets control of these `Volume Groups`. +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-*`).å -> The controller performs a one-time re-tagging operation on all existing `Volume Groups` when it starts up. +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`. diff --git a/docs/FAQ_RU.md b/docs/FAQ_RU.md index dffe1693..d8219414 100644 --- a/docs/FAQ_RU.md +++ b/docs/FAQ_RU.md @@ -55,13 +55,24 @@ description: "Распространенные вопросы и ответы н ## Как передать контроллеру управление существующей на узле `LVM Volume Group`? -Достаточно добавить LVM-тег `storage.deckhouse.io/enabled=true` на `LVM Volume Group` (`vgchange myvg-0 --addtag storage.deckhouse.io/enabled=true`). +Достаточно добавить LVM-тег `storage.deckhouse.io/enabled=true` на `LVM Volume Group` на узле: + +```shell +vgchange myvg-0 --addtag storage.deckhouse.io/enabled=true +``` ## Я хочу, чтобы контроллер перестал следить за `LVM Volume Group` на узле. Как мне это сделать? -Достаточно удалить LVM-тег `storage.deckhouse.io/enabled=true` у нужной `LVM Volume Group` на узле (`vgchange myvg-0 --deltag storage.deckhouse.io/enabled=true`). После этого контроллер перестанет отслеживать выбранную `Volume Group` и самостоятельно удалит связанный с ней ресурс `LVMVolumeGroup`. +Достаточно удалить LVM-тег `storage.deckhouse.io/enabled=true` у нужной `LVM Volume Group` на узле: + +```shell +vgchange myvg-0 --addtag storage.deckhouse.io/enabled=true +``` + +После этого контроллер перестанет отслеживать выбранную `Volume Group` и самостоятельно удалит связанный с ней ресурс `LVMVolumeGroup`. ## Я не вешал LVM-тег `storage.deckhouse.io/enabled=true` на `Volume Group`, но он появился. Как это возможно? Это возможно в случае, если вы создавали `LVM Volume Group` через ресурс `LVMVolumeGroup` (в таком случае контроллер автоматически вешает данный LVM-тег на созданную `LVM Volume Group`). Либо на данной `Volume Group` или ее `Thin-pool` был LVM-тег модуля `Linstor` — `linstor-*`. + При миграции с встроенного модуля `Linstor` на модули `sds-node-configurator` и `sds-drbd` автоматически происходит изменение LVM-тегов `linstor-*` на LVM-тег `storage.deckhouse.io/enabled=true` в `Volume Group`. Таким образом, управление этими `Volume Group` передается модулю `sds-node-configurator`.