Backport: docs: update docs due v0.21.0 (#1200)

docs: update docs due v0.21.0 (#1153)

Signed-off-by: Pavel Tishkov <pavel.tishkov@flant.com>
Signed-off-by: Dmitry Lopatin <dmitry.lopatin@flant.com>
Signed-off-by: Vladislav Panfilov <vladislav.panfilov@flant.com>
Co-authored-by: Pavel Tishkov <pavel.tishkov@flant.com>
Co-authored-by: goganat <georgy.dauman@flant.com>
Co-authored-by: Dmitry Lopatin <dmitry.lopatin@flant.com>
Co-authored-by: Vladislav Panfilov <vladislav.panfilov@flant.com>

Author: 5 people

docs/ADMIN_GUIDE.md

@@ -733,13 +733,22 @@ spec:
 
 ## Reliability mechanisms
 
+### VM Rebalancing
+
+The platform provides the ability to automate the management of already running virtual machines in the cluster. To activate this feature, you need to enable the `descheduler` module.
+
+When you enable the module, it automatically monitors the optimal operation of virtual machines in the cluster. The main features it provides are:
+
+- Load balancing: The system analyses CPU reservation on cluster nodes. When CPU reservations exceed 80% on a node, the system automatically transfers part of the VMs to less loaded nodes. This prevents overload and ensures stable VM operation.
+- Appropriate placement: The system checks whether the current node meets the requirements of each VM and whether the placement rules are followed in relation to the node or other VMs in the cluster. For example, if a VM should not be on the same node as another VM, the module transfers it to a more suitable node.
+
 ### Migration and maintenance mode
 
 Virtual machine migration is an important feature in virtualized infrastructure management. It allows you to move running virtual machines from one physical node to another without shutting them down. Virtual machine migration is required for a number of tasks and scenarios:
 
-- **Load balancing**. Moving virtual machines between nodes allows you to evenly distribute the load on servers, ensuring that resources are utilized in the best possible way.
-- **Node maintenance**. Virtual machines can be moved from nodes that need to be taken out of service to perform routine maintenance or software upgrade.
-- **Upgrading a virtual machine firmware**. The migration allows you to upgrade the firmware of virtual machines without interrupting their operation.
+- Load balancing: Moving virtual machines between nodes allows you to evenly distribute the load on servers, ensuring that resources are utilized in the best possible way.
+- Node maintenance: Virtual machines can be moved from nodes that need to be taken out of service to perform routine maintenance or software upgrade.
+- Upgrading a virtual machine firmware: The migration allows you to upgrade the firmware of virtual machines without interrupting their operation.
 
 #### Start migration of an arbitrary machine
 

docs/ADMIN_GUIDE.ru.md

@@ -747,13 +747,22 @@ spec:
 
 ## Механизмы обеспечения надежности
 
+### Перебалансировка ВМ
+
+Платформа предоставляет возможность автоматизировать управление размещением уже запущенных виртуальных машин в кластере. Для активации этой функции необходимо включить модуль `descheduler`.
+
+После включения модуля система самостоятельно следит за оптимальной работой виртуальных машин в кластере. Основные возможности модуля:
+
+- Балансировка нагрузки — система анализирует резервирование процессора на узлах кластера. Если на узле зарезервировано более 80% процессора, система автоматически переносит часть ВМ на менее загруженные узлы. Это предотвращает перегрузку и обеспечивает стабильную работу ВМ.
+- Подходящее размещение — система проверяет, соответствует ли текущий узел требованиям каждой ВМ, соблюдены ли правила размещения по отношению к узлу или другим ВМ кластера. Например, если ВМ не должна находиться на одном узле с другой ВМ, модуль переносит её на более подходящий узел.
+
 ### Миграция и режим обслуживания
 
 Миграция виртуальных машин является важной функцией в управлении виртуализированной инфраструктурой. Она позволяет перемещать работающие виртуальные машины с одного физического узла на другой без их отключения. Миграция виртуальных машин необходима для ряда задач и сценариев:
 
-- **Балансировка нагрузки**. Перемещение виртуальных машин между узлами позволяет равномерно распределять нагрузку на серверы, обеспечивая использование ресурсов наилучшим образом.
-- **Перевод узла в режим обслуживания**. Виртуальные машины могут быть перемещены с узлов, которые нужно вывести из эксплуатации для выполнения планового обслуживания или обновления программного обеспечения.
-- **Обновление «прошивки» виртуальных машин**. Миграция позволяет обновить «прошивку» виртуальных машины, не прерывая их работу.
+- Балансировка нагрузки — перемещение виртуальных машин между узлами позволяет равномерно распределять нагрузку на серверы, обеспечивая использование ресурсов наилучшим образом.
+- Перевод узла в режим обслуживания — виртуальные машины могут быть перемещены с узлов, которые нужно вывести из эксплуатации для выполнения планового обслуживания или обновления программного обеспечения.
+- Обновление «прошивки» виртуальных машин — миграция позволяет обновить «прошивку» виртуальных машин, не прерывая их работу.
 
 #### Запуск миграции произвольной машины
 

docs/USER_GUIDE.md

@@ -2189,7 +2189,12 @@ EOF
 
 A virtual machine snapshot is a saved state of a virtual machine at a specific point in time. The `VirtualMachineSnapshot` resource is used to create virtual machine snapshots.
 
+{{< alert level="warning" >}}
+It is recommended to disconnect all images (VirtualImage/ClusterVirtualImage) from the virtual machine before creating its snapshot. Disk images are not saved together with the VM snapshot, and their absence in the cluster during recovery may cause the virtual machine to fail to start and remain in a Pending state while waiting for the images to become available.
+{{< /alert >}}
+
 #### Types of snapshots
+
 Snapshots can be consistent or inconsistent, which is determined by the `requiredConsistency` parameter. By default, the `requiredConsistency` parameter is set to `true`, which requires a consistent snapshot.
 
 A consistent snapshot guarantees a consistent and complete state of the virtual machine's disks. Such a snapshot can be created when one of the following conditions is met:
@@ -2224,6 +2229,12 @@ If you plan to use the snapshot as a template, perform the following steps in th
 - Resetting initialization configurations (`cloud-init clean`).
 - Create a snapshot with a clear indication not to save the IP address: `keepIPAddress: Never`
 
+When creating an image, follow these recommendations:
+
+- Disconnect all images if they were connected to the virtual machine.
+- Do not use a static IP address for VirtualMachineIPAddress. If a static address has been used, change it to automatic.
+- Create a snapshot with an explicit indication not to save the IP address: `keepIPAddress: Never`.
+
 #### Creating snapshots
 
 When creating a snapshot, you must specify the names of the `VolumeSnapshotClasses` volume snapshot classes that will be used to create snapshots of the disks attached to the virtual machine.
@@ -2275,6 +2286,25 @@ spec:
 EOF
 ```
 
+After successfully creating a snapshot, its status will show the list of resources saved in the snapshot.
+
+Output example:
+
+```yaml
+status:
+  ...
+  resources:
+  - apiVersion: virtualization.deckhouse.io/v1alpha2
+    kind: VirtualMachine
+    name: linux-vm
+  - apiVersion: v1
+    kind: Secret
+    name: cloud-init
+  - apiVersion: virtualization.deckhouse.io/v1alpha2
+    kind: VirtualDisk
+    name: linux-vm-root
+```
+
 ### Restore from snapshots
 
 The `VirtualMachineRestore` resource is used to restore a virtual machine from a snapshot. During the restore process, the following objects are automatically created in the cluster:
@@ -2311,6 +2341,8 @@ A snapshot of a virtual machine can be used both to create its exact copy (clone
 
 This requires creating a `VirtualMachineRestore` resource and setting the renaming parameters in the `.spec.nameReplacements` block to avoid name conflicts.
 
+The list of resources and their names are available in the VM snapshot status in the `status.resources` block.
+
 Example manifest for restoring a VM from a snapshot:
 
 ```yaml
@@ -2347,4 +2379,15 @@ When restoring a virtual machine from a snapshot, it is important to consider th
 2. For static IP addresses (`type: Static`) the value must be exactly the same as what was captured in the snapshot.
 3. Automation-related secrets (such as cloud-init or sysprep configuration) must exactly match the configuration being restored.
 
-Failure to do so will result in a restore error . This is because the system checks the integrity of the configuration and the uniqueness of the resources to prevent conflicts in the cluster.
+Failure to do so will result in a restore error, and the VirtualMachineRestore resource will enter the `Failed` state. This is because the system checks the integrity of the configuration and the uniqueness of the resources to prevent conflicts in the cluster.
+
+When restoring or cloning a virtual machine, the operation may be successful, but the VM will remain in `Pending` state.
+This occurs if the VM depends on resources (such as disk images or virtual machine classes) or their configurations that have been changed or deleted at the time of restoration.
+
+Check the VM's conditions block using the command:
+
+```bash
+d8 k vm get <vmname> -o json | jq ‘.status.conditions’
+```
+
+Check the output for errors related to missing or changed resources. Manually update the VM configuration to remove dependencies that are no longer available in the cluster.

docs/USER_GUIDE.ru.md

@@ -2209,6 +2209,10 @@ EOF
 
 Снимок виртуальной машины — это сохранённое состояние виртуальной машины в определённый момент времени. Для создания снимков виртуальных машин используется ресурс `VirtualMachineSnapshot`.
 
+{{< alert level="warning" >}}
+Рекомендуется отключить все образы (VirtualImage/ClusterVirtualImage) от виртуальной машины перед созданием её снимка. Образы дисков не сохраняются вместе со снимком ВМ, и их отсутствие в кластере при восстановлении может привести к тому, что виртуальная машина не сможет запуститься и будет находиться в состоянии Pending, ожидая доступности образа.
+{{< /alert >}}
+
 #### Типы снимков
 
 Снимки могут быть консистентными и неконсистентными, за это отвечает параметр `requiredConsistency`, по умолчанию его значение равно `true`, что означает требование консистентного снимка.
@@ -2244,6 +2248,12 @@ EOF
 - Сброс конфигураций инициализации (`cloud-init clean`).
 - Создавайте снимок с явным указанием не сохранять IP-адрес: `keepIPAddress: Never`
 
+При создании снимка следуйте следующим рекомендациям:
+
+- Отключите все образы, если они были подключены к виртуальной машине.
+- Не используйте статический IP-адрес в VirtualMachineIPAddress. Если использовался статический адрес, сконвертируйте его в автоматический.
+- Создавайте снимок с явным указанием не сохранять IP-адрес: `keepIPAddress: Never`.
+
 #### Создание снимков
 
 При создании снимка необходимо указать названия классов снимков томов `VolumeSnapshotClass`, которые будут использованы для создания снимков дисков, подключенных к виртуальной машине.
@@ -2295,6 +2305,25 @@ spec:
 EOF
 ```
 
+После успешного создания снимка, в его статусе будет отражен перечень ресурсов, которые были сохранены в снимке .
+
+Пример вывода:
+
+```yaml
+status:
+  ...
+  resources:
+  - apiVersion: virtualization.deckhouse.io/v1alpha2
+    kind: VirtualMachine
+    name: linux-vm
+  - apiVersion: v1
+    kind: Secret
+    name: cloud-init
+  - apiVersion: virtualization.deckhouse.io/v1alpha2
+    kind: VirtualDisk
+    name: linux-vm-root
+```
+
 ### Восстановление из снимков
 
 Для восстановления виртуальной машины из снимка используется ресурс `VirtualMachineRestore` . В процессе восстановления в кластере автоматически создаются следующие объекты:
@@ -2331,6 +2360,8 @@ EOF
 
 Для этого требуется создать ресурс `VirtualMachineRestore` и задать параметры переименования в блоке `.spec.nameReplacements`, чтобы избежать конфликтов имён.
 
+Перечень ресурсов и их имена доступны в статусе снимка ВМ в блоке `status.resources`.
+
 Пример манифеста для восстановления ВМ из снимка:
 
 ```yaml
@@ -2367,4 +2398,15 @@ EOF
 2. Для статических IP-адресов (`type: Static`) значение должно полностью совпадать с тем, что было зафиксировано в снимке.
 3. Секреты, связанные с автоматизацией (например, конфигурация cloud-init или sysprep), должны точно соответствовать восстанавливаемой конфигурации.
 
-Несоблюдение этих требований приведёт к ошибке восстановления . Это связано с тем, что система проверяет целостность конфигурации и уникальность ресурсов для предотвращения конфликтов в кластере.
+Несоблюдение этих требований приведёт к ошибке восстановления, и ресурс VirtualMachineRestore перейдет в состояние `Failed`. Это связано с тем, что система проверяет целостность конфигурации и уникальность ресурсов для предотвращения конфликтов в кластере.
+
+При восстановлении или клонировании виртуальной машины операция может быть выполнена успешно, но ВМ останется в статусе `Pending`.
+Это происходит, если ВМ зависит от ресурсов (например, образов дисков или классов виртуальных машин) или их конфигураций, которые были изменены или удалены на момент восстановления.
+
+Проверьте блок условий ВМ с помощью команды:
+
+```bash
+d8 k vm get <vmname> -o json | jq '.status.conditions'
+```
+
+Проверьте вывод на наличие ошибок, связанных с отсутствующими или изменёнными ресурсами. Вручную обновите конфигурацию ВМ, чтобы устранить зависимости, которые больше не доступны в кластере.