Skip to content
Draft

upd #1456

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 91 additions & 2 deletions docs/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -2802,6 +2831,66 @@ d8 k get vmop <vmop-name> -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: <vmop-name>
spec:
type: Clone
virtualMachineName: <name of the VM to be cloned>
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: <resource type>
name: <old name>
- to:
name: <new name>
customisation:
namePrefix: <prefix>
nameSuffix: <suffix>
```

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 <vmop-name> -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).
Expand Down
94 changes: 93 additions & 1 deletion docs/USER_GUIDE.ru.md
Original file line number Diff line number Diff line change
Expand Up @@ -625,8 +625,9 @@ EOF

Режим доступа AccessMode:

- `ReadWriteOnce (RWO)` - доступ к диску предоставляется только одному экземпляру виртуальной машины.
- `ReadWriteMany (RWX)` - множественный доступ к диску. Живая миграция виртуальных машин с такими дисками возможна.
- `ReadWriteOnce (RWO)` - доступ к диску предоставляется только одному экземпляру виртуальной машины. Живая миграция виртуальных машин с такими дисками возможна только для платных редакций DVP. Живая миграция доступна только если все диски подключенны статически через (`.spec.blockDeviceRefs`). Диски подключенные динамически через `VirtualMachineBlockDeviceAttachments`, необходимо статически подключить их заново, указав их в `.spec.blockDeviceRefs`.


При создании диска контроллер самостоятельно определит наиболее оптимальные параметры поддерживаемые хранилищем.

Expand Down Expand Up @@ -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`. Его параметры позволяют сконфигурировать:
Expand Down Expand Up @@ -2837,6 +2867,68 @@ d8 k get vmop <vmop-name> -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: <vmop-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 <vmop-name> -o json | jq '.status.resources'
```

## Экспорт данных

DVP позволяет экспортировать диски и снимки дисков виртуальных машин с использованием утилиты `d8` (версия 1.17 и выше).
Expand Down
Loading