docs(module): add module components info and other small fixes (#308)

docs(module): add module components info

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>

crds/clustervirtualimage.yaml

@@ -58,7 +58,7 @@ spec:
 
                         * `HTTP` — create an image from a file published on http/https service at a given url
                         * `ContainerImage` — create the image from image stored in container registry.
-                        * `ObjectRef` — fill the cluster image from another existing `VirtualImage` or `ClusterVirtualImage`.
+                        * `ObjectRef` — fill the disk from another existing resource.
                         * `Upload` — fill the image with data, uploaded by user via the special interface.
                     http:
                       type: object

crds/doc-ru-clustervirtualimage.yaml

@@ -88,11 +88,10 @@ spec:
                       description: |
                         Доступные типы источников для создания образа:
 
-                        * `HTTP` — создать образ из файла, опубликованного на HTTP/HTTPS-сервере.
-                        * `ContainerImage` — создать образ из образа в container registry.
-                        * `VirtualImage` — создать новый образ из существующего `VirtualImage`.
-                        * `ClusterVirtualImage` — создать новый образ из существующего `ClusterVirtualImage`.
-                        * `Upload` — загрузить образ вручную, через веб-интерфейс.
+                        * `HTTP` — создать диск из файла, опубликованного на HTTP/HTTPS-сервере.
+                        * `ContainerImage` — создать диск из образа в container registry.
+                        * `ObjectRef` — создать диск из существующего ресурса.
+                        * `Upload` — загрузить образ диска вручную.
             status:
               properties:
                 conditions:

crds/doc-ru-virtualdisk.yaml

@@ -4,9 +4,10 @@ spec:
       schema:
         openAPIV3Schema:
           description: |
-            Описывает диск виртуальной машины, который может быть смонтирован в `VirtualMachines`. После создания ресурса изменить можно только размер диска `.spec.persistentVolumeClaim.size`, все остальные поля неизменяемы.
+            Ресурс `VirtualDisk` описывает желаемую конфигурацию диска виртуальной машины. `VirtualDisk` может быть смонтирован в виртуальной машине статически, указав его в списке дисков `.spec.blockDeviceRefs`, или смонтирован «на лету» с помощью ресурса `VirtualMachineBlockDeviceAttachments`.
+
+            После создания `VirtualDisk` можно изменить только размер диска `.spec.persistentVolumeClaim.size`, все остальные поля неизменяемы.
 
-            Под капотом ресурса создается PVC, в который заливаются данные из источника.
           properties:
             spec:
               properties:
@@ -83,19 +84,43 @@ spec:
 
                         * `HTTP` — создать диск из файла, опубликованного на HTTP/HTTPS-сервере.
                         * `ContainerImage` — создать диск из образа в container registry.
-                        * `VirtualImage` — создать диск из существующего `VirtualImage`.
-                        * `ClusterVirtualImage` — создать диск из существующего `ClusterVirtualImage`.
-                        * `Upload` — загрузить образ диска вручную, через веб-интерфейс.
+                        * `ObjectRef` — создать диск из существующего ресурса.
+                        * `Upload` — загрузить образ диска вручную.
                 persistentVolumeClaim:
                   description: |
                     Настройки для создания PVC для хранения диска.
                   properties:
                     size:
                       description: |
                         Желаемый размер PVC для хранения диска. Если диск создается из образа, то размер должен быть не меньше, чем исходный образ в распакованном состоянии.
+
+                        Данный параметр можно опустить, если задан блок `.spec.dataSource`, в этом случае контроллер определит размер диска автоматически, на основе размера распакованного образа из источника указанного в `.spec.dataSource`.
+
                     storageClassName:
                       description: |
-                        Имя класса StorageClass, требуемого для PersistentVolumeClaim. Дополнительная информация — https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1.
+                        Имя StorageClass, требуемого для PersistentVolumeClaim. Дополнительная информация — https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1.
+
+                        При создании дисков пользователь может указать требуемый StorageClass для создания диска, либо не указывать явно и в этом случае будет использован StorageClass доступный по умолчанию.
+
+                        Особенности диска и поведение виртуальной машины зависят от выбранного StorageClass.
+
+                        Параметр `VolumeBindingMode` в StorageClass влияет на процесс создания дисков:
+
+                        - `Immediate` - Диск будет создан и доступен для использования сразу после создания.
+                        - `WaitForFirstConsumer` - Диск создается только при его использовании в виртуальной машине. При этом диск будет создан на узле, где будет запущена виртуальная машина.
+
+                        StorageClass может поддерживать различные настройки хранения:
+
+                        - Создание блочного устройства (`Block`) или файловой системы (`FileSystem`).
+                        - Множественный доступ (`ReadWriteMany`) или единичный доступ (`ReadWriteOnce`). `ReadWriteMany`-диски поддерживают множественный доступ, что позволяет выполнять живую миграцию виртуальных машин. В отличие от них, `ReadWriteOnce`-диски, ограниченные доступом только с одного узла, не могут обеспечить такую возможность.
+
+                        Для известных типов хранилищ платформа самостоятельно определит наиболее эффективные настройки при создании дисков (в порядке убывания приоритетов):
+
+                        1. `Block` + `ReadWriteMany`
+                        2. `FileSystem` + `ReadWriteMany`
+                        3. `Block` + `ReadWriteOnce`
+                        4. `FileSystem` + `ReadWriteOnce`
+
             status:
               properties:
                 conditions:

crds/doc-ru-virtualimage.yaml

@@ -77,11 +77,10 @@ spec:
                       description: |
                         Тип источника, из которого будет создан образ:
 
-                        * `HTTP` — создать образ из файла, опубликованного на HTTP/HTTPS-сервере.
-                        * `ContainerImage` — создать образ из образа в container registry.
-                        * `VirtualImage` — создать образ из другого существующего `VirtualImage`.
-                        * `ClusterVirtualImage` — создать образ из другого существующего `ClusterVirtualImage`.
-                        * `Upload` — загрузить образ вручную, через веб-интерфейс.
+                        * `HTTP` — создать диск из файла, опубликованного на HTTP/HTTPS-сервере.
+                        * `ContainerImage` — создать диск из образа в container registry.
+                        * `ObjectRef` — создать диск из существующего ресурса.
+                        * `Upload` — загрузить образ диска вручную.
                 storage:
                   description: |
                     Тип хранилища для хранения образа:

crds/doc-ru-virtualmachine.yaml

@@ -4,7 +4,12 @@ spec:
       schema:
         openAPIV3Schema:
           description: |
-            Конфигурация виртуальной машины (ВМ).
+            Ресурс, описывающий конфигурацию и статус виртуальной машины (ВМ).
+            Для запущенной ВМ изменение параметров может быть применено только после перезагрузки ВМ, за исключением следующих параметров (они применяются на лету):
+            - `.metadata.labels`
+            - `.metadata.annotations`
+            - `.spec.disruptions.restartApprovalMode`
+            - `.spec.disruptions.runPolicy`
           properties:
             spec:
               properties:

crds/virtualdisk.yaml

@@ -27,16 +27,14 @@ spec:
         openAPIV3Schema:
           type: object
           description: |
-            Describes a virtual disk that can be mounted in `VirtualMachines`. Once the resource is created, only the disk size `.spec.persistentVolumeClaim.size` can be changed, all other fields are immutable.
+            The `VirtualDisk` resource describes the desired virtual machine disk configuration. A `VirtualDisk` can be mounted statically in the virtual machine by specifying it in the `.spec.blockDeviceRefs` disk list, or mounted on-the-fly using the `VirtualMachineBlockDeviceAttachments` resource.
 
-            A PVC is created under the hood of the resource, into which the data from the source is filled.
+            Once `VirtualDisk` is created, only the disk size `.spec.persistentVolumeClaim.size` can be changed, all other fields are immutable.
           required:
             - spec
           properties:
             spec:
               type: object
-              required:
-                - persistentVolumeClaim
               properties:
                 bindingMode:
                   type: string
@@ -57,11 +55,31 @@ spec:
                       type: string
                       description: |
                         Desired size for PVC to store the disk. If the disk is created from an image, the size must be at least as large as the original unpacked image.
+
+                        This parameter can be omitted if the `.spec.dataSource` block is specified, in which case the controller will determine the disk size automatically, based on the size of the extracted image from the source specified in `.spec.dataSource`.
                       pattern: "^([+-]?[0-9.]+)([eEinumkKMGTP]*[-+]?[0-9]*)$"
                     storageClassName:
                       type: string
                       description: |
                         The name of the StorageClass required by the claim. More info — https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1
+
+                        When creating disks, the user can specify the required StorageClass to create the disk, or not explicitly, in which case the default StorageClass will be used.
+
+                        The disk features and virtual machine behavior depend on the selected StorageClass.
+
+                        The `VolumeBindingMode` parameter in the StorageClass affects the disk creation process:
+                        - `Immediate` - The disk will be created and available for use immediately after creation.
+                        - `WaitForFirstConsumer` - The disk will be created only when it is used in a virtual machine. In this case, the disk will be created on the host where the virtual machine will be started.
+
+                        StorageClass can support different storage settings:
+                        - Creating a block device (`Block`) or file system (`FileSystem`).
+                        - Multiple Access (`ReadWriteMany`) or Single Access (`ReadWriteOnce`). `ReadWriteMany` disks support multiple access, which enables live migration of virtual machines. In contrast, `ReadWriteOnce` disks, which are limited to access from only one host, cannot provide this capability.
+
+                        For known storage types, the platform will independently determine the most effective settings when creating disks (in descending order of priority):
+                        1. `Block` + `ReadWriteMany`
+                        2. `FileSystem` + `ReadWriteMany`
+                        3. `Block` + `ReadWriteOnce`
+                        4. `FileSystem` + `ReadWriteOnce`
                 dataSource:
                   type: object
                   description: |
@@ -81,7 +99,7 @@ spec:
 
                         * `HTTP` — create an image from a file published on http/https service at a given url
                         * `ContainerImage` — create the image from image stored in container registry.
-                        * `ObjectRef` — fill the disk from another existing `VirtualImage` or `ClusterVirtualImage`.
+                        * `ObjectRef` — fill the disk from another existing resource.
                         * `Upload` — fill the disk with data, uploaded by user via the special interface.
                     http:
                       type: object
@@ -114,7 +132,7 @@ spec:
                           type: string
                           format: byte
                           description: |
-                            The CA chain in base64 format to verify the url.
+                            A certificate bundle in Base64 format to verify the TLS certificate of the server hosting the image.
                           example: |
                             YWFhCg==
                         checksum:

crds/virtualimage.yaml

@@ -68,7 +68,7 @@ spec:
 
                         * `HTTP` — fill the image with data from some external http/https url.
                         * `ContainerImage` — use an image, stored in container registry image.
-                        * `ObjectRef` — fill the disk from another existing `VirtualImage` or `ClusterVirtualImage`.
+                        * `ObjectRef` — fill the disk from another existing resource.
                         * `Upload` — fill the image with data, uploaded by user via the special interface.
                     http:
                       type: object

crds/virtualmachine.yaml

@@ -28,7 +28,12 @@ spec:
         openAPIV3Schema:
           type: object
           description: |
-            Virtual Machine (VM) Configuration.
+            This resource describes the configuration and status of a virtual machine (VM).
+            For a running VM, parameter changes can only be applied after the VM is rebooted, except for the following parameters (they are applied on the fly):
+            - `.metadata.labels`.
+            - `.metadata.annotations`.
+            - `.spec.disruptions.restartApprovalMode`.
+            - `.spec.disruptions.runPolicy`.
           required:
             - spec
           properties:
@@ -1156,6 +1161,10 @@ spec:
           type: string
           jsonPath: .status.conditions[?(@.type=="AgentReady")].status
           priority: 1
+        - name: Agent
+          type: string
+          jsonPath: .status.conditions[?(@.type=="Migratable")].status
+          priority: 1
         - name: Node
           type: string
           jsonPath: .status.nodeName

docs/ADMIN_GUIDE.ru.md → docs/ADMIN_GUIDE_RU.md

@@ -165,7 +165,7 @@ generic            Ready   6d1h
 - `host-passthrough` - используется физический CPU узла платформы напрямую без каких-либо изменений. При использовании данного класса, гостевая ВМ может быть мигрирована только на целевой узел, у которого CPU точно соответствует CPU исходного узла.
 - `generic` - универсальная модель CPU, использующая достаточно старую, но поддерживаемую большинством современных процессоров модель Nehalem. Это позволяет запускать ВМ на любых узлах кластера с возможностью живой миграции.
 
-`VirtualMachineClass` является обязательным для узказания в конфигурации виртуальной машины, пример того как указывать класс в спецификаии ВМ:
+`VirtualMachineClass` является обязательным для узказания в конфигурации виртуальной машины, пример того как указывать класс в спецификации ВМ:
 
 ```yaml
 apiVersion: virtualization.deckhouse.io/v1alpha2
@@ -342,7 +342,7 @@ spec:
       type: Discovery
   ```
 
-- чтобы создать vCPU конкретного процессора с предварительно определенным набором интрукций, используем тип `type: Model`. Предварительно, чтобы получить перечень названий поддерживаемых CPU для узла кластера, выполните команду:
+- чтобы создать vCPU конкретного процессора с предварительно определенным набором инструкций, используем тип `type: Model`. Предварительно, чтобы получить перечень названий поддерживаемых CPU для узла кластера, выполните команду:
 
   ```bash
   kubectl get nodes <node-name> -o json | jq '.metadata.labels | to_entries[] | select(.key | test("cpu-model")) | .key | split("/")[1]' -r