[docs] Fix badge, improve docs and descriptions in CRDs (#15)

Signed-off-by: Aleksandr Zimin <[email protected]> Signed-off-by: Andrey Polovov <[email protected]> Signed-off-by: Artem Kladov <[email protected]> Signed-off-by: Kirill Kononovich <[email protected]> Co-authored-by: Andrey Polovov <[email protected]> Co-authored-by: Artem Kladov <[email protected]> Co-authored-by: Kirill Kononovich <[email protected]>
deckhouse · Jan 23, 2024 · c1c30ba · c1c30ba
1 parent 23842ef
commit c1c30ba
Show file tree

Hide file tree

Showing 16 changed files with 355 additions and 283 deletions.
diff --git a/.werf/bundle.yaml b/.werf/bundle.yaml
@@ -2,7 +2,7 @@
 ---
 image: bundle
 from: registry.deckhouse.io/base_images/scratch@sha256:b054705fcc9f2205777d80a558d920c0b4209efdc3163c22b5bfcb5dda1db5fc
-fromCacheVersion: "2023-11-27.1"
+fromCacheVersion: "2024-01-05.1"
 import:
 # Rendering .werf/images-digests.yaml is required!
 - image: images-digests
@@ -21,6 +21,7 @@ git:
   - .helmignore
   - charts
   - crds
+  - docs
   - enabled
   - hooks
   - monitoring

diff --git a/crds/blockdevices.yaml b/crds/blockdevices.yaml
@@ -24,20 +24,18 @@ spec:
         openAPIV3Schema:
           type: object
           description: |
-            BlockDevice is a Kubernetes Custom Resource that displays actual information about block devices, which might be used by the sds-node-configurator controller to create Volume Groups, extend Physical Volumes, and so on.
+            The resource displays up-to-date information about available block devices on nodes that can be used by the sds-node-configurator controller for LVM operations.
             
-            > The resource is created and managed by the controller only.
+            > The resource is created and managed by the controller only. Manual modification of the resource is prohibited.
           properties:
             status:
               type: object
-              description: |
-                Defines the current device state.
               required: [size,type,consumable,path,rota,hotPlug,nodeName,machineId]
               properties:
                 type:
                   type: string
                   description: |
-                    The device's type.
+                    The device's type (disk, part, RAID, and others).
                 fsType:
                   type: string
                   enum: [LVM2_member, ""]
@@ -50,45 +48,45 @@ spec:
                 consumable:
                   type: boolean
                   description: |
-                    The flag that defines whether this device can be used by the controller.
+                    The flag that defines whether this device can be used by the controller to create an LVM Physical Volume.
                 pvUUID:
                   type: string
                   description: |
-                    The Physical Volume UUID.
+                    The LVM Physical Volume UUID.
                     
-                    > Optional: exists only if the device is used as a Physical Volume.
+                    > Optional: exists only if the device is used as a LVM Physical Volume.
                 vgUUID:
                   type: string
                   description: | 
-                    The Volume Group UUID.
+                    The UUID of the LVM Volume Group to which this device belongs to as a Physical Volume.
 
                     > Optional: exists only if the device is used as a Physical Volume and is included in a Volume Group.
                 lvmVolumeGroupName:
                   type: string
                   description: | 
                     The LVMVolumeGroup resource name. 
                     
-                    > Optional: exists only if the device is used as a Physical Volume and is included in a Volume Group and LVMVolumeGroup resource.
+                    > Optional: exists only if the device is used as a Physical Volume, is included in a Volume Group, and is specified in an LVMVolumeGroup resource.
                 actualVGNameOnTheNode:
                   type: string
                   description: |
-                    The actual name of the Volume Group the device is included in.
+                    The actual name of the LVM Volume Group the device is included in.
                     
                     > Optional: exists if only the device is used as a Physical Volume and is included in a Volume Group.
                 wwn:
                   type: string
                   description: |
                     The device unique wwn (World Wide Name) identifier.
                     
-                    > Optional: might be empty if no WWN was set.
+                    > Optional: might be empty if WWN is not supported for this type of disk by the manufacturer.
                 serial:
                   type: string
                   description: |
                     The device unique serial number.
                 path:
                   type: string
                   description: |
-                    The device path (name).
+                    The device path on the node (/dev/sda).
                 size:
                   type: string
                   description: |
@@ -98,19 +96,19 @@ spec:
                   description: |
                     The device model.
                     
-                    > Optional: might be empty if no model was set.
+                    > Optional: might be empty if not supported by the manufacturer for this type of disk.
                 rota:
                   type: boolean
                   description: |
                     The device media type. Might be:
-                    - 'True' (for HHD)
-                    - 'False' (for SSD)
+                    - 'true' (for HHD)
+                    - 'false' (for SSD)
                 hotPlug:
                   type: boolean
                   description: |
                     The device connection type. Might be:
-                    - 'True' (if the device has been hotPlugged)
-                    - 'False' (otherwise)
+                    - 'true' (if the device has been hotPlugged)
+                    - 'false' (otherwise)
                 machineId:
                   type: string
                   description: |

diff --git a/crds/doc-ru-blockdevices.yaml b/crds/doc-ru-blockdevices.yaml
@@ -4,17 +4,15 @@ spec:
       schema:
         openAPIV3Schema:
           description: |
-            BlockDevice — это пользовательский ресурс Kubernetes, который отображает актуальную информацию о блочных устройствах, которые могут быть использованы контроллером sds-node-configurator для операций создания Volume Group, расширения Physical Volume и других.
+            Ресурс отображает актуальную информацию о доступных блочных устройствах на узлах, которые могут быть использованы контроллером sds-node-configurator для операций в LVM.
             
-            > Ресурс создается и обслуживается только контроллером.
+            > Ресурс создается и обслуживается только контроллером. Ручное изменение ресурса запрещено.
           properties:
             status:
-              description: |
-                Определяет текущее состояние девайса.
               properties:
                 type:
                   description: |
-                    Тип девайса.
+                    Тип девайса (диск, партиция, RAID и другие).
                 fsType:
                   description: |
                     Тип файловой системы.
@@ -23,56 +21,56 @@ spec:
                     Имя Kubernetes-узла, на котором находится девайс.
                 consumable:
                   description: |                    
-                    Флаг, определяющий, может ли данный девайс быть использован контроллером.
+                    Флаг, определяющий, может ли данный девайс быть использован контроллером для создания LVM Physical Volume.
                 pvUUID:
                   description: |                    
-                    UUID Physical Volume.
+                    LVM Physical Volume UUID.
                                         
-                    > Опциально: присутствует, только если девайс используется как Physical Volume.
+                    > Опциально: присутствует, только если девайс используется как LVM Physical Volume.
                 vgUUID:
                   description: |
-                    UUID Volume Group.
+                    LVM Volume Group UUID, которой принадлежит данный девайс в качестве Physical Volume.
 
                     > Опциально: присутствует, только если девайс используется как Physical Volume и включен в Volume Group.
                 lvmVolumeGroupName:
                   description: |
                     Имя ресурса LVMVolumeGroup.
                     
-                    > Опциально: присутствует, только если девайс используется как Physical Volume и включен в Volume Group и LVMVolumeGroup-ресурс.
+                    > Опциально: присутствует, только если девайс используется как Physical Volume, включен в Volume Group и указан в LVMVolumeGroup-ресурсе.
                 actualVGNameOnTheNode:
                   description: |
-                    Фактическое имя Volume Group на узле, в который включен девайс.
+                    Фактическое имя LVM Volume Group на узле, в которую включен девайс.
                     
                     > Опциально: присутствует, только если девайс используется как Physical Volume и включен в Volume Group.
                 wwn:
                   description: |
                     Уникальный идентификатор девайса WWN (World Wide Name).
                     
-                    > Опционально: может отсутствовать, если WWN не было задано.
+                    > Опционально: может отсутствовать, если WWN для данного типа дисков не поддерживается производителем.
                 serial:
                   description: |
                     Уникальный серийный номер девайса.
                 path:
                   description: |
-                    Путь (имя) девайса на узле.
+                    Путь девайса на узле (/dev/sda).
                 size:
                   description: |
                     Размер девайса.
                 model:
                   description: |
                     Модель девайса. 
                     
-                    > Опционально: может отсутствовать, если модель не была задана.
+                    > Опционально: может отсутствовать, если для данного типа дисков не поддерживается производителем.
                 rota:
                   description: |
                     Медиатип девайса. Может быть:
-                    - True (для HHD)
-                    - False (для SSD)
+                    - true (для HHD)
+                    - false (для SSD)
                 hotPlug:
                   description: |
                     Тип подключения девайса. Может быть:
-                    - True (если девайс был подключен как съемный)
-                    - False (в иных случаях)
+                    - true (если девайс был подключен как съемный)
+                    - false (в иных случаях)
                 machineId:
                   description: |
                     Уникальный идентификатор узла, на котором располагается девайс (обычно хранится в /etc/machine-id).
diff --git a/crds/doc-ru-lvmvolumegroup.yaml b/crds/doc-ru-lvmvolumegroup.yaml
@@ -4,17 +4,16 @@ spec:
       schema:
         openAPIV3Schema:
           description: |
-            LVMVolumeGroup — это ресурс для управления Volume Group'ами и Thin pool'ами на узлах.
+            Интерфейс управления Volume Group'ами и Thin pool'ами на узлах.
             
-            > Этот тип ресурсов может быть создан как самим пользователем, так и контроллером SDS-Node-Configurator.
-            Контроллер sds-node-configurator автоматически создаст ресурс LVMVolumeGroup в случае, если найдет на узле существующую Volume Group со специальным тегом 'storage.deckhouse.io/enabled=true', при этом контроллер самостоятельно заполнит как `spec`, так и `status` поля.
+            > Этот тип ресурсов может быть создан как самим пользователем, так и контроллером sds-node-configurator. Контроллер sds-node-configurator автоматически создаст ресурс LVMVolumeGroup в случае, если найдет на узле существующую Volume Group со специальным тегом 'storage.deckhouse.io/enabled=true', при этом контроллер самостоятельно заполнит как `spec`, так и `status` поля.
           properties:
             spec:
               properties:
                 type:
                   description: |
                     Тип Volume Group. Может быть: 
-                    - Local (то есть локальным, если используемые девайсы не являются распределенными)
+                    - Local, то есть локальным, если используемые девайсы не являются распределенными (не Shared LUN).
                 blockDeviceNames:
                   description: |
                     Список имен ресурсов BlockDevice для создания Volume Group.
@@ -39,10 +38,6 @@ spec:
                         description: |
                           Желаемый размер Thin-pool.
             status:
-              description: |
-                Отображает текущее состояние Volume Group.
-                
-                > Эти параметры обновляются контроллером.
               properties:
                 health:
                   description: |
@@ -57,10 +52,10 @@ spec:
                     Уникальный идентификатор Volume Group.
                 vgSize:
                   description: |
-                    Максимальный размер Volume Group.
+                    Ёмкость Volume Group.
                 allocatedSize:
                   description: |
-                    Текущий размер Volume Group.
+                    Текущее занятое место на Volume Group.
                 thinPools:
                   description: |
                     Текущее состояние Thin-pool'ов в Volume Group.
@@ -73,7 +68,7 @@ spec:
                           Имя Thin-pool.
                       actualSize:
                         description: |
-                          Общий текущий размер Thin-pool.
+                          Ёмкость Thin-pool.
                       usedSize:
                         description: |
                           Используемый размер Thin-pool.
@@ -92,7 +87,7 @@ spec:
                           properties:
                             path:
                               description: |
-                                Путь (имя) девайса на узле.
+                                Путь девайса на узле (/dev/sda, например).
                             pvSize:
                               description: |
                                 Размер Physical Volume.
@@ -101,7 +96,7 @@ spec:
                                 Размер девайса.
                             pvUUID:
                               description: |
-                                Уникальный идентификатор Physical Volume.
+                                Уникальный идентификатор LVM Physical Volume.
                             blockDevice:
                               description: |
                                 Имя связанного ресурса BlockDevice.