From d5f5c05e6836f0a6d8af60e3f19cd034872fd979 Mon Sep 17 00:00:00 2001 From: Viktor Kramarenko Date: Mon, 6 May 2024 12:04:28 +0300 Subject: [PATCH] [controller] Add docs for local-csi-node-watcher controller Signed-off-by: Viktor Kramarenko --- docs/FAQ.ru.md | 160 ++++++++++++++++++++++++++++++++++++++++++-- docs/README.ru.md | 167 ++-------------------------------------------- 2 files changed, 159 insertions(+), 168 deletions(-) diff --git a/docs/FAQ.ru.md b/docs/FAQ.ru.md index fccb9162..a4b996bf 100644 --- a/docs/FAQ.ru.md +++ b/docs/FAQ.ru.md @@ -16,7 +16,66 @@ Overprovisioning в LVMThin нужно использовать с осторо ## Как назначить StorageClass по умолчанию? -В соответствующем пользовательском ресурсе [LocalStorageClass](./cr.html#localstorageclass) в поле `spec.isDefault` указать `true`. +В соответствующем пользовательском ресурсе [LocalStorageClass](./cr.html#localstorageclass) в поле `spec.isDefault` указать `true`. + +## Я не хочу, чтобы модуль использовался на всех узлах кластера. Как мне выбрать желаемые узлы? +Узлы, которые будут задействованы модулем, определяются специальными метками, указанными в поле `nodeSelector` в настройках модуля. + +Для отображения и редактирования настроек модуля, можно выполнить команду: +```shell +kubectl edit mc sds-local-volume +``` + +Примерный вывод команды: +```yaml +apiVersion: deckhouse.io/v1alpha1 +kind: ModuleConfig +metadata: + name: sds-local-volume +spec: + enabled: true + settings: + dataNodes: + nodeSelector: + my-custom-label-key: my-custom-label-value +status: + message: "" + version: "1" +``` + +Для отображения существующих меток, указанных в поле `nodeSelector`, можно выполнить команду: +```shell +kubectl get mc sds-local-volume -o=jsonpath={.spec.settings.dataNodes.nodeSelector} +``` +Примерный вывод команды: +```yaml +nodeSelector: + my-custom-label-key: my-custom-label-value +``` + +Также Вы можете дополнительно проверить селекторы, которые используются модулем в конфиге секрета `d8-sds-local-volume-controller-config` в пространстве имен `d8-sds-local-volume`. + +```shell +kubectl -n d8-sds-local-volume get secret d8-sds-local-volume-controller-config -o jsonpath='{.data.config}' | base64 --decode +``` + +Примерный вывод команды: +```yaml +nodeSelector: + kubernetes.io/os: linux + my-custom-label-key: my-custom-label-value +``` + +> В выводе данной команды должны быть указаны все метки из настроек модуля `data.nodeSelector`, а также `kubernetes.io/os: linux`. + +Узлы, метки которых включают в себя набор, указанный в настройках, выбираются модулем как целевые для использования. Соответственно, изменяя поле `nodeSelector` Вы можете влиять на список узлов, которые будут использованы модулем. + +> Обратите внимание, что в поле `nodeSelector` может быть указано любое количество меток, но важно, чтобы каждая из указанных меток присутствовала на узле, который Вы собираетесь использовать для работы с модулем. Именно при наличии всех указанных меток на выбранном узле, произойдет запуск pod-а `sds-local-volume-csi-node`. + +После добавление меток на узлах должны быть запущены pod-ы `sds-local-volume-csi-node`. Проверить их наличие можно командой: +```shell + kubectl -n d8-sds-local-volume get pod -owide + ``` ## Почему не удается создать PVC на выбранном узле с помощью модуля? @@ -27,21 +86,108 @@ kubectl -n d8-sds-local-volume get po -owide ``` Если pod отсутствует, значит данный узел не удовлетворяет `nodeSelector`, указанному в настройках `ModuleConfig` `sds-local-volume`. -Настройка модуля и `nodeSelector` описаны [здесь](README.ru.md#добавление-узла-в-nodeselector-модуля). +Настройка модуля и `nodeSelector` описаны [здесь](#я-не-хочу-чтобы-модуль-использовался-на-всех-узлах-кластера-как-мне-выбрать-желаемые-узлы-). -Если лейблы присутствуют, необходимо проверить наличие лейбла `storage.deckhouse.io/sds-local-volume-node=` на узле. Если лейбл отсутствует, следует проверить работает ли `sds-local-volume-controller`, и в случае его работоспособности, проверить логи: +Если метки присутствуют, необходимо проверить наличие метки `storage.deckhouse.io/sds-local-volume-node=` на узле. Если метка отсутствует, следует проверить работает ли `sds-local-volume-controller`, и в случае его работоспособности, проверить логи: ```shell kubectl -n d8-sds-local-volume get po -l app=sds-local-volume-controller kubectl -n d8-sds-local-volume logs -l app=sds-local-volume-controller ``` -## Я хочу вывести узел из-под управления модуля, что делать? -Шаги по выводу узла из-под управления модуля подробно описаны [здесь](README.ru.md#вывод-узла-из-под-управления-модуля). +## Я хочу вывести узел из-под управления модуля, что делать? +Для вывода узла из-под управления модуля необходимо убрать метки, указанные в поле `nodeSelector` в настройках модуля `sds-local-volume`. + +Проверить наличие существующих меток в `nodeSelector` можно командой: +```shell +kubectl get mc sds-local-volume -o=jsonpath={.spec.settings.dataNodes.nodeSelector} +``` + +Примерный вывод команды: +```yaml +nodeSelector: + my-custom-label-key: my-custom-label-value +``` + +Снимите указанные в `nodeSelector` метки с желаемых узлов. +```shell +kubectl label node %node-name% %label-from-selector%- +``` +> Обратите внимание, что для снятия метки необходимо после его ключа вместо значения сразу же поставить знак минуса. + +В результате pod `sds-local-volume-csi-node` должен быть удален с желаемого узла. Для проверки состояния можно выполнить команду: +```shell +kubectl -n d8-sds-local-volume get po -owide +``` + +Если pod `sds-local-volume-csi-node` после удаления метки `nodeSelector` все же остался на узле, пожалуйста, убедитесь, что указанные в конфиге `d8-sds-local-volume-controller-config` в `nodeSelector` метки действительно успешно снялись с выбранного узла. +Проверить это можно командой: +> ```shell +> kubectl get node %node-name% --show-labels=true +> ``` +Если метки из `nodeSelector` не присутствуют на узле, то убедитесь, что данному узлу не принадлежат `LVMVolumeGroup` ресурсы, использующиеся `LocalStorageClass` ресурсами. Подробнее об этой проверке можно [здесь](#как-проверить-имеются-ли-зависимые-ресурсы-lvmvolumegroup-на-узле-). + + +> Обратите внимание, что на ресурсах `LVMVolumeGroup` и `LocalStorageClass`, из-за которых не удается вывести узел из-под управления модуля будет отображена метка `storage.deckhouse.io/sds-local-volume-candidate-for-eviction`. +> +> На самом узле будет присутствовать метка `storage.deckhouse.io/sds-local-volume-need-manual-eviction`. + +## Как проверить, имеются ли зависимые ресурсы `LVMVolumeGroup` на узле? +Для проверки таковых ресурсов необходимо выполнить следующие шаги: +1. Отобразить имеющиеся `LocalStorageClass` ресурсы +```shell +kubectl get lsc +``` +2. Проверить у каждого из них список используемых `LVMVolumeGroup` ресурсов +```shell +kubectl get lsc %lsc-name% -oyaml +``` + +Примерный вид `LocalStorageClass` +```yaml +apiVersion: v1 +items: +- apiVersion: storage.deckhouse.io/v1alpha1 + kind: LocalStorageClass + metadata: + finalizers: + - localstorageclass.storage.deckhouse.io + name: test-sc + spec: + lvm: + lvmVolumeGroups: + - name: test-vg + type: Thick + reclaimPolicy: Delete + volumeBindingMode: WaitForFirstConsumer + status: + phase: Created +kind: List +``` +> Обратите внимание на поле spec.lvm.lvmVolumeGroups - именно в нем указаны используемые `LVMVolumeGroup` ресурсы. + +3. Отобразите список существующих `LVMVolumeGroup` ресурсов +```shell +kubectl get lvg +``` +Примерный вывод `LVMVolumeGroup` ресурсов +```text +NAME HEALTH NODE SIZE ALLOCATED SIZE VG AGE +lvg-on-worker-0 Operational node-worker-0 40956Mi 0 test-vg 15d +lvg-on-worker-1 Operational node-worker-1 61436Mi 0 test-vg 15d +lvg-on-worker-2 Operational node-worker-2 122876Mi 0 test-vg 15d +lvg-on-worker-3 Operational node-worker-3 307196Mi 0 test-vg 15d +lvg-on-worker-4 Operational node-worker-4 307196Mi 0 test-vg 15d +lvg-on-worker-5 Operational node-worker-5 204796Mi 0 test-vg 15d +``` + +4. Проверьте, что на узле, который вы собираетесь вывести из-под управления модуля, не присутствует какой-либо `LVMVolumeGroup` ресурс, используемый в `LocalStorageClass` ресурсах. + +> Во избежание непредвиденной потери контроля за уже созданными с помощью модуля томами пользователю необходимо вручную удалить зависимые ресурсы, совершив необходимые операции над томом. -## Я убрал лейблы с узла, но pod `sds-local-volume-csi-node` остался. Почему так произошло? +## Я убрал метки с узла, но pod `sds-local-volume-csi-node` остался. Почему так произошло? Вероятнее всего, на узле присутствуют `LVMVolumeGroup` ресурсы, которые используются в одном из `LocalStorageClass` ресурсов. Во избежание непредвиденной потери контроля за уже созданными с помощью модуля томами пользователю необходимо вручную удалить зависимые ресурсы, совершив необходимые операции над томом. -Процесс проверки на наличие вышеуказанных ресурсов описан [здесь](README.ru.md#проверка-используемых-lvmvolumegroup-в-localstorageclass). \ No newline at end of file +Процесс проверки на наличие вышеуказанных ресурсов описан [здесь](#как-проверить-имеются-ли-зависимые-ресурсы-lvmvolumegroup-на-узле-). \ No newline at end of file diff --git a/docs/README.ru.md b/docs/README.ru.md index e56abe14..0bc4b585 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -69,78 +69,16 @@ moduleStatus: experimental ``` ### Подготовка узлов к созданию хранилищ на них - Для создания хранилищ на узлах необходимо, чтобы на выбранных узлах были запущены pod-ы `sds-local-volume-csi-node`. -Расположение данных pod-ов определяется специальными лейблами (nodeSelector), которые указываются в поле `spec.settings.dataNodes.nodeSelector` в настройках модуля. - -```yaml -apiVersion: deckhouse.io/v1alpha1 -kind: ModuleConfig -metadata: - name: sds-local-volume -spec: - enabled: true - settings: - dataNodes: - nodeSelector: - my-custom-label-key: my-custom-label-value -status: - message: "" - version: "1" -``` - -> Обратите внимание, что в поле `nodeSelector` может быть указано любое количество лейблов, но важно, что каждый из указанных лейблов присутствовал на узле, который Вы собираетесь использовать для работы с модулем. Именно при наличии всех указанных лейблов на выбранном узле, произойдет запуск pod-а `sds-local-volume-csi-node`. - -Проверить наличие существующих лейблов можно командой: -```shell -kubectl get mc sds-local-volume -o=jsonpath={.spec.settings.dataNodes.nodeSelector} -``` - -Вы можете дополнительно проверить селекторы, которые используются модулем в конфиге секрета `d8-sds-local-volume-controller-config` в пространстве имен `d8-sds-local-volume`. - -```shell -kubectl -n d8-sds-local-volume get secret d8-sds-local-volume-controller-config -o jsonpath='{.data.config}' | base64 --decode -``` - -Примерный вывод команды: -```yaml -nodeSelector: - kubernetes.io/os: linux - my-custom-label-key: my-custom-label-value -``` - -> В выводе данной команды должны быть указаны все лейблы из настроек модуля `data.nodeSelector`, а также `kubernetes.io/os: linux`. - -### Добавление узла в `nodeSelector` модуля. -- Добавьте желаемые лейблы (nodeSelector) в поле `spec.settings.dataNodes.nodeSelector` в настройках модуля. - -```yaml -apiVersion: deckhouse.io/v1alpha1 -kind: ModuleConfig -metadata: - annotations: - name: sds-local-volume -spec: - enabled: true - settings: - dataNodes: - nodeSelector: - my-custom-label-key: my-custom-label-value -status: - message: "" - version: "1" -``` -- Сохраните изменения -- Добавьте лейблы, указанные в `nodeSelector`, на узлы, которые вы желаете отдать под управление модулю, используя шаблоны в `NodeGroup`. - -После добавление лейблов на узлах должны быть запущены pod-ы `sds-local-volume-csi-node`. Проверить их наличие можно командой: +По умолчанию pod-ы выедут на всех узлах кластера, проверить их наличие можно командой: ```shell kubectl -n d8-sds-local-volume get pod -owide ``` -### Настройка хранилища на узлах +> Расположение данных pod-ов определяется специальными метками (nodeSelector), которые указываются в поле `spec.settings.dataNodes.nodeSelector` в настройках модуля. Для получения более подробной информации о настройке, пожалуйста, перейдите по [ссылке](FAQ.ru.md#я-не-хочу-чтобы-модуль-использовался-на-всех-узлах-кластера-как-мне-выбрать-желаемые-узлы-) +### Настройка хранилища на узлах Необходимо на этих узлах создать группы томов `LVM` с помощью пользовательских ресурсов `LVMVolumeGroup`. В быстром старте будем создавать обычное `Thick` хранилище. > Пожалуйста, перед созданием `LVMVolumeGroup` убедитесь, что на данном узле запущен pod `sds-local-volume-csi-node`. Это можно сделать командой: @@ -275,104 +213,11 @@ status: ## Вывод узла из-под управления модуля -Если в процессе работы появилась необходимость вывести узел из-под управления модуля, необходимо убрать лейблы, указанные в `nodeSelector` в настройках `ModuleConfig` `sds-local-volume`. - -> Обратите внимание, что для успешного вывода узла из-под управления модуля, необходимо, чтобы на узле не было создано ресурсов `LVMVolumeGroup`, которые использовались бы в ресурсах `LocalStorageClass`, то есть, которые использовались бы `Storage Class` с `provisioner` `local.csi.storage.deckhouse.io`. - -### Проверка используемых `LVMVolumeGroup` в `LocalStorageClass` -Для проверки таковых ресурсов необходимо выполнить следующие шаги: - 1. Отобразить имеющиеся `LocalStorageClass` ресурсы -```shell -kubectl get lsc -``` -2. Проверить у каждого из них список используемых `LVMVolumeGroup` ресурсов -```shell -kubectl get lsc %lsc-name% -oyaml -``` - -Примерный вид `LocalStorageClass` -```yaml -apiVersion: v1 -items: -- apiVersion: storage.deckhouse.io/v1alpha1 - kind: LocalStorageClass - metadata: - finalizers: - - localstorageclass.storage.deckhouse.io - generation: 2 - name: test-sc - resourceVersion: "26243988" - uid: 05e32b0c-0bb1-4754-a305-7646d483175e - spec: - lvm: - lvmVolumeGroups: - - name: test-vg - type: Thick - reclaimPolicy: Delete - volumeBindingMode: WaitForFirstConsumer - status: - phase: Created -kind: List -metadata: - resourceVersion: "" -``` -> Обратите внимание на поле spec.lvm.lvmVolumeGroups - именно в нем указаны используемые `LVMVolumeGroup` ресурсы. - -3. Отобразите список существующих `LVMVolumeGroup` ресурсов -```shell -kubectl get lvg -``` -Примерный вывод `LVMVolumeGroup` ресурсов -```text -NAME HEALTH NODE SIZE ALLOCATED SIZE VG AGE -lvg-on-worker-0 Operational node-worker-0 40956Mi 0 test-vg 15d -lvg-on-worker-1 Operational node-worker-1 61436Mi 0 test-vg 15d -lvg-on-worker-2 Operational node-worker-2 122876Mi 0 test-vg 15d -lvg-on-worker-3 Operational node-worker-3 307196Mi 0 test-vg 15d -lvg-on-worker-4 Operational node-worker-4 307196Mi 0 test-vg 15d -lvg-on-worker-5 Operational node-worker-5 204796Mi 0 test-vg 15d -``` - -4. Проверьте, что на узле, который вы собираетесь вывести из-под управления модуля, не присутствует какой-либо `LVMVolumeGroup` ресурс, используемый в `LocalStorageClass` ресурсах. - -> Во избежание непредвиденной потери контроля за уже созданными с помощью модуля томами пользователю необходимо вручную удалить зависимые ресурсы, совершив необходимые операции над томом. - -### Вывод узла из-под управления модуля - -Проверить наличие существующих лейблов в `nodeSelector` можно командой: -```shell -kubectl get mc sds-local-volume -o=jsonpath={.spec.settings.dataNodes.nodeSelector} -``` - -Примерный вывод команды: -```yaml -nodeSelector: - my-custom-label-key: my-custom-label-value -``` - -- Снимите указанные в `nodeSelector` лейблы с желаемых узлов -```shell -kubectl label node %node-name% %label-from-selector%- -``` -> Обратите внимание, что для снятия лейбла необходимо после его ключа вместо значения сразу же поставить знак минуса. - -В результате pod `sds-local-volume-csi-node` должен быть удален с желаемого узла. Для проверки состояния можно выполнить команду -```shell -kubectl -n d8-sds-local-volume get po -owide -``` - -> Если pod `sds-local-volume-csi-node` после удаления лейблов `nodeSelector` все же остался на узле, пожалуйста, убедитесь, указанные в конфиге `d8-sds-local-volume-controller-config` в `nodeSelector` лейблы действительно успешно снялись с выбранного узла. -> Проверить это можно командой: -> ```shell -> kubectl get node %node-name% --show-labels=true -> ``` -> Если лейблы из `nodeSelector` не присутствуют на узле, то убедитесь, что данному узлу не принадлежат `LVMVolumeGroup` ресурсы, использующиеся `LocalStorageClass` ресурсами. Для этого необходимо выполнить следующую [проверку](#проверка-используемых-lvmvolumegroup-в-localstorageclass). - -> Обратите внимание, что на ресурсах `LVMVolumeGroup` и `LocalStorageClass`, из-за которых не удается вывести узел из-под управления модуля будут отображен лейбл `storage.deckhouse.io/sds-local-volume-candidate-for-eviction`. -> -> На самом узле будет присутствовать лейбл `storage.deckhouse.io/sds-local-volume-need-manual-eviction`. +Если в процессе работы появилась необходимость вывести узел из-под управления модуля, необходимо убрать с узла метки, указанные в `nodeSelector` в настройках `ModuleConfig` `sds-local-volume`. +Подробнее про процедуру вывода узла из-под управления модуля можно прочитать [здесь](FAQ.ru.md#я-хочу-вывести-узел-из-под-управления-модуля-что-делать). +> Обратите внимание, что для успешного вывода узла из-под управления модуля, необходимо, чтобы на узле не было создано ресурсов `LVMVolumeGroup`, которые использовались бы в ресурсах `LocalStorageClass`, то есть, которые использовались бы `Storage Class` с `provisioner` `local.csi.storage.deckhouse.io`. Подробнее про процедуру проверки описано [здесь](FAQ.ru.md#как-проверить-имеются-ли-зависимые-ресурсы-lvmvolumegroup-на-узле-). ## Системные требования и рекомендации