From 3c20accaf7cba01a0b3e4217e5ec88cf6c56846b Mon Sep 17 00:00:00 2001 From: Pavel Tishkov Date: Thu, 11 Sep 2025 14:48:07 +0300 Subject: [PATCH 1/2] upd Signed-off-by: Pavel Tishkov --- docs/USER_GUIDE.md | 60 +++++++++++++++++++++++++++++++++++++++++ docs/USER_GUIDE.ru.md | 62 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+) diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 9237ccf099..fed3396923 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -2802,6 +2802,66 @@ d8 k get vmop -o json | jq “.status.resources” It is not recommended to cancel the restore operation (delete the `VirtualMachineOperation` resource in the `InProgress` phase) from a snapshot, which can result in an inconsistent state of the restored virtual machine. {{< /alert >}} + +## Creating a VM clone + +VM cloning is performed using the `VirtualMachineOperation` resource with the `clone` operation type. + +{{< alert level="warning">}} +To perform a VM cloning operation, the VM being cloned must be [powered off](#vm-start-and-state-management-policy). +It is recommended to set the `.spec.runPolicy: AlwaysOff` parameter in the configuration of the VM being cloned if you want to prevent the VM clone from starting automatically. This is because the clone inherits the behaviour of the parent VM. +{{< /alert >}} + +```yaml +apiVersion: virtualization.deckhouse.io/v1alpha2 +kind: VirtualMachineOperation +metadata: + name: +spec: + type: Clone + virtualMachineName: + clone: + mode: DryRun | Strict | BestEffort + nameReplacements: [] + customisation: {} +``` + +{{< alert level="warning">}} +The cloned VM will be assigned a new IP address for the cluster network and MAC addresses for additional network interfaces (if any), so you will need to reconfigure the network settings of the guest OS after cloning. +{{< /alert >}} + +Cloning creates a copy of an existing VM, so the resources of the new VM must have unique names. To do this, use the `.spec.clone.nameReplacements` and/or `.spec.clone.customisation` parameters. + +- `.spec.clone.nameReplacements` — allows you to replace the names of existing resources with new ones to avoid conflicts. +- `.spec.clone.customisation` — sets a prefix or suffix for the names of all cloned VM resources (disks, IP addresses, etc.). + +Configuration example: + +```yaml +spec: + clone: + nameReplacements: + - from: + kind: + name: + - to: + name: + customisation: + namePrefix: + nameSuffix: +``` + +One of three modes can be used for the cloning operation: +- `DryRun` — a test run to check for possible conflicts. The results are displayed in the `status.resources` field of the VirtualMachineOperation resource. +- `Strict` — strict mode, requiring all resources with new names and their dependencies (e.g., images) to be present in the cloned VM. +- `BestEffort` — mode in which missing external dependencies (e.g., ClusterVirtualImage, VirtualImage) are automatically removed from the configuration of the cloned VM. + +Information about conflicts that arose during cloning can be viewed in the resource status: + +```bash +d8 k get vmop -o json | jq “.status.resources” +``` + ## Data export DVP allows you to export virtual machine disks and disk images using the `d8` utility (version 1.17 and above). diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md index 263bdf5d20..499a41b873 100644 --- a/docs/USER_GUIDE.ru.md +++ b/docs/USER_GUIDE.ru.md @@ -2837,6 +2837,68 @@ d8 k get vmop -o json | jq '.status.resources' Не рекомендуется отменять операцию восстановления (удалять ресурс `VirtualMachineOperation` в фазе `InProgress`) из снимка, так как это может привести к неконсистентному состоянию восстанавливаемой виртуальной машины. {{< /alert >}} + +## Создание клона ВМ + +Клонирование ВМ выполняется с использованием ресурса `VirtualMachineOperation` с типом операции `clone`. + +{{< alert level="warning">}} +Для выолнения операции ВМ по клонированию, клонируемая ВМ должна быть [выключена](#политика-запуска-и-управление-состоянием-вм). + +Рекомендуется задавать параметр `.spec.runPolicy: AlwaysOff` в конфигурации клонируемой ВМ, если вы хотите предотвратить автоматический запуск клона ВМ. Это связано с тем, что клон наследует поведение родительской ВМ. +{{< /alert >}} + +```yaml +apiVersion: virtualization.deckhouse.io/v1alpha2 +kind: VirtualMachineOperation +metadata: + name: +spec: + type: Clone + virtualMachineName: <название ВМ, которую требуюется клонировать> + clone: + mode: DryRun | Strict | BestEffort + nameReplacements: [] + customization: {} +``` + +{{< alert level="warning">}} +Клонируемой ВМ будут назначены новый IP-адрес для кластерной сети и MAC-адреса для дополнительных сетевых интерфейсов (если они есть), поэтому после клонирования потребуется перенастроить сетевые параметры гостевой ОС. +{{< /alert >}} + +Клонирование создает копию существующей ВМ, поэтому ресурсы новой ВМ должны иметь уникальные имена. Для этого используются параметры `.spec.clone.nameReplacements` и/или `.spec.clone.customization`. + +- `.spec.clone.nameReplacements` — позволяет заменить имена существующих ресурсов на новые, чтобы избежать конфликтов. +- `.spec.clone.customization` — задает префикс или суффикс для имен всех клонируемых ресурсов ВМ (дисков, IP-адресов и т. д.). + +Пример конфигурации: + +```yaml +spec: + clone: + nameReplacements: + - from: + kind: <тип ресурса> + name: <старое имя> + - to: + name: <новое имя> + customization: + namePrefix: <префикс- > + nameSuffix: < -суффикс> +``` + +Для операции клонирования возможно использовать один из трех режимов: + +- `DryRun` — тестовый запуск для проверки возможных конфликтов. Результаты отображаются в поле `status.resources` ресурса VirtualMachineOperation. +- `Strict` — строгий режим, требующий наличия всех ресурсов с новыми именами и их зависимостей (например, образов) в клонируемой ВМ. +- `BestEffort` — режим, при котором отсутствующие внешние зависимости (например, ClusterVirtualImage, VirtualImage) автоматически удаляются из конфигурации клонируемой ВМ. + +Информацию о конфликтах, возникших при клонировании, можно просмотреть в статусе ресурса: + +```bash +d8 k get vmop -o json | jq '.status.resources' +``` + ## Экспорт данных DVP позволяет экспортировать диски и снимки дисков виртуальных машин с использованием утилиты `d8` (версия 1.17 и выше). From 6861e2edc4c52b9af1b98882422a1709bba60495 Mon Sep 17 00:00:00 2001 From: Pavel Tishkov Date: Thu, 11 Sep 2025 14:52:40 +0300 Subject: [PATCH 2/2] upd Signed-off-by: Pavel Tishkov --- docs/USER_GUIDE.md | 33 +++++++++++++++++++++++++++++++-- docs/USER_GUIDE.ru.md | 32 +++++++++++++++++++++++++++++++- 2 files changed, 62 insertions(+), 3 deletions(-) diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index fed3396923..f9a57a4ead 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -617,8 +617,8 @@ VolumeBindingMode property: AccessMode: -- `ReadWriteOnce (RWO)` - only one instance of the virtual machine is granted access to the disk. - `ReadWriteMany (RWX)` - multiple disk access. Live migration of virtual machines with such disks is possible. +- `ReadWriteOnce (RWO)` - only one instance of the virtual machine is granted access to the disk. Live migration of virtual machines with such disks is possible only in the DVP commercial editions. Live migration is only available if all disks are connected statically via (`.spec.blockDeviceRefs`). Disks connected dynamically via `VirtualMachineBlockDeviceAttachments` must be reconnected statically by specifying them in `.spec.blockDeviceRefs`. When creating a disk, the controller will independently determine the most optimal parameters supported by the storage. @@ -649,7 +649,7 @@ How to find out the available storage options in the DVP web interface: - Go to the "System" tab, then to the "Storage" section → "Storage Classes". -## Create an empty disk +### Create an empty disk Empty disks are usually used to install an OS on them, or to store some data. @@ -862,6 +862,35 @@ Method #2: - Click on the "Save" button that appears. - The disk status is displayed at the top left, under its name. +### Changing the disk StorageClass + +In the DVP commercial editions, it is possible to change the StorageClass for existing disks. At the moment, this is only supported for running VMs (`Phase` should be `Running`). + +{{< alert level="warning">}} +Storage class migration is only available for disks connected statically via (`.spec.blockDeviceRefs`). + +To migrate the storage class of disks attached via `VirtualMachineBlockDeviceAttachments`, you must statically reattach them by specifying them in `.spec.blockDeviceRefs`. +{{< /alert >}} + +Example: + +```bash +d8 k patch vd disk --type=merge --patch '{"spec":{"persistentVolumeClaim":{"storageClassName":"new-storage-class-name"}}}' +``` + +After the disk configuration is updated, a live migration of the VM will be initiated, during which the VM’s disk will be migrated to the new storage. + +If a VM has multiple disks attached and you need to change the storage class for several of them, this operation must be performed sequentially: + +```bash +d8 k patch vd disk1 --type=merge --patch '{"spec":{"persistentVolumeClaim":{"storageClassName":"new-storage-class-name"}}}' +d8 k patch vd disk2 --type=merge --patch '{"spec":{"persistentVolumeClaim":{"storageClassName":"new-storage-class-name"}}}' +``` + +If migration fails, repeated attempts are made with increasing delays (exponential backoff algorithm). The maximum delay is 300 seconds (5 minutes). Delays: 5 seconds (1st attempt), 10 seconds (2nd), then each delay doubles, reaching 300 seconds (7th and subsequent attempts). The first attempt is performed without delay. + +To cancel migration, the user must return the storage class in the specification to the original one. + ## Virtual machines The `VirtualMachine` resource is used to create a virtual machine, its parameters allow you to configure: diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md index 499a41b873..fec267e44e 100644 --- a/docs/USER_GUIDE.ru.md +++ b/docs/USER_GUIDE.ru.md @@ -625,8 +625,9 @@ EOF Режим доступа AccessMode: -- `ReadWriteOnce (RWO)` - доступ к диску предоставляется только одному экземпляру виртуальной машины. - `ReadWriteMany (RWX)` - множественный доступ к диску. Живая миграция виртуальных машин с такими дисками возможна. +- `ReadWriteOnce (RWO)` - доступ к диску предоставляется только одному экземпляру виртуальной машины. Живая миграция виртуальных машин с такими дисками возможна только для платных редакций DVP. Живая миграция доступна только если все диски подключенны статически через (`.spec.blockDeviceRefs`). Диски подключенные динамически через `VirtualMachineBlockDeviceAttachments`, необходимо статически подключить их заново, указав их в `.spec.blockDeviceRefs`. + При создании диска контроллер самостоятельно определит наиболее оптимальные параметры поддерживаемые хранилищем. @@ -870,6 +871,35 @@ linux-vm-root Ready 11Gi 12m - Нажмите на появившуюся кнопку «Сохранить». - Статус диска отображается слева вверху, под его именем. +### Изменение класса хранения диска + +Для платных редакций DVP существует возможность изменения класса хранения для созданных дисков. На данный момент это возможно только для работающих ВМ (`Phase` должна быть `Running`). + +{{< alert level="warning">}} +Миграция класса хранения поддерживается только для дисков, статически подключенных через параметр `.spec.blockDeviceRefs` в конфигурации виртуальной машины. + +Для миграции класса хранения дисков, подключенных через `VirtualMachineBlockDeviceAttachments`, необходимо переподключить их статически, указав в `.spec.blockDeviceRefs`. +{{< /alert >}} + +Пример: + +```bash +d8 k patch vd disk --type=merge --patch '{"spec":{"persistentVolumeClaim":{"storageClassName":"new-storage-class-name"}}}' +``` + +После изменения конфигурации диска запустится живая миграция ВМ, в процессе которой диск ВМ будет смигрирован на новое хранилище. + +Если к виртуальной машине подключены несколько дисков и требуется изменить класс хранения для нескольких дисков, эту операцию необходимо выполнить последовательно: + +```bash +d8 k patch vd disk1 --type=merge --patch '{"spec":{"persistentVolumeClaim":{"storageClassName":"new-storage-class-name"}}}' +d8 k patch vd disk2 --type=merge --patch '{"spec":{"persistentVolumeClaim":{"storageClassName":"new-storage-class-name"}}}' +``` + +При неуспешной миграции повторные попытки выполняются с увеличивающимися задержками (алгоритм экспоненциального backoff). Максимальная задержка — 300 секунд (5 минут). Задержки: 5 секунд (1-я попытка), 10 секунд (2-я), далее каждая задержка удваивается, достигая 300 секунд (7-я и последующие попытки). Первая попытка выполняется без задержки. + +Для отмены миграции пользователь должен вернуть класс хранения в спецификации на исходный. + ## Виртуальные машины Для создания виртуальной машины используется ресурс `VirtualMachine`. Его параметры позволяют сконфигурировать: