Skip to content

docs: update due 1.4.0 #1865

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
fl64 wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

docs: update due 1.4.0 #1865

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e340185
docs: update due 1.4.0
fl64 Jan 3, 2026
9325138
docs: update ru user guide
fl64 Jan 15, 2026
e375530
docs: update en user guide
fl64 Jan 15, 2026
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
48 changes: 33 additions & 15 deletions docs/USER_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -620,11 +620,6 @@ VolumeBindingMode property:

![vd-wffc](images/vd-wffc.png)

AccessMode:

- `ReadWriteMany (RWX)`: Multiple disk access. Live migration of virtual machines with such disks is possible.
- `ReadWriteOnce (RWO)`: The disk can be accessed by only a single virtual machine instance. Live migration of virtual machines that use such disks is supported only in commercial editions.

When creating a disk, the controller will independently determine the most optimal parameters supported by the storage.

Attention: It is impossible to create disks from iso-images!
Expand Down Expand Up @@ -928,6 +923,8 @@ Method #2:

In commercial editions, you can migrate (move) a virtual machine disk to another storage by changing its StorageClass.

Migration is supported for both statically attached disks and dynamically attached (hotplug) disks.

{{< alert level="warning">}}
Limitations of disk migration between storage:

Expand Down Expand Up @@ -2679,6 +2676,12 @@ Virtual machines can be connected to additional networks: project networks (`Net

To do this, specify the desired networks in the configuration section `.spec.networks`. If this block is not specified (which is the default behavior), the VM will use only the main cluster network.

{{< alert level="info" >}}
Specifying the main cluster network (`type: Main`) in `.spec.networks` is optional. If you do not need a connection to the main cluster network, you can use only additional networks (`Network` or `ClusterNetwork`).

However, if the main network is specified, it must always be first in the `.spec.networks` list.
{{< /alert >}}

Important considerations when working with additional network interfaces:

- The order of listing networks in `.spec.networks` determines the order in which interfaces are connected inside the virtual machine.
Expand All @@ -2687,28 +2690,39 @@ Important considerations when working with additional network interfaces:
- Network security policies (NetworkPolicy) do not apply to additional network interfaces.
- Network parameters (IP addresses, gateways, DNS, etc.) for additional networks are configured manually from within the guest OS (for example, using Cloud-Init).

Example of connecting a VM to the project network `user-net`:
Example of connecting a VM to the main cluster network and the project network `user-net`:

```yaml
spec:
networks:
- type: Main # Must always be specified first
- type: Main # If specified, must be first
- type: Network # Network type (Network \ ClusterNetwork)
name: user-net # Network name
```

Example of connecting to the cluster network `corp-net`:
Example of connecting to multiple networks, including the cluster network `corp-net`:

```yaml
spec:
networks:
- type: Main # Must always be specified first
- type: Main # If specified, must be first
- type: Network
name: user-net
- type: ClusterNetwork
name: corp-net # Network name
```

Example of connecting a VM only to additional networks (without the main cluster network):

```yaml
spec:
networks:
- type: Network
name: isolated-net
- type: ClusterNetwork
name: corp-net
```

You can view information about connected networks and their MAC addresses in the VM status:

```yaml
Expand Down Expand Up @@ -2779,12 +2793,13 @@ Snapshots allow you to capture the current state of a resource for later recover

Snapshots can be consistent or inconsistent; this is controlled by the `requiredConsistency` parameter. By default, `requiredConsistency` is set to `true`, which means a consistent snapshot is required.

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:
A consistent snapshot guarantees a consistent and complete state of disk data. Such a snapshot can be created when one of the following conditions is met:

- The disk is not attached to any virtual machine — the snapshot will always be consistent.
- The virtual machine is turned off.
- [`qemu-guest-agent`](#guest-os-agent) is installed in the guest system, which temporarily suspends the file system at the time the snapshot is created to ensure its consistency.
- [`qemu-guest-agent`](#guest-os-agent) is installed and running in the guest system, which temporarily suspends ("freezes") the file system at the time the snapshot is created to ensure its consistency.

An inconsistent snapshot may not reflect a consistent state of the virtual machine's disks and its components. Such a snapshot is created if the VM is running and `qemu-guest-agent` is not installed or not running in the guest OS.
An inconsistent snapshot may not reflect a consistent state of the virtual machine's disks and its components. Such a snapshot is created if the VM is running and `qemu-guest-agent` is not installed or not running in the guest OS.
If the snapshot manifest explicitly specifies the `requiredConsistency: false` parameter, but `qemu-guest-agent` is running, an attempt will be made to freeze the file system to ensure that the snapshot is consistent.

QEMU Guest Agent supports hook scripts that allow you to prepare applications for snapshot creation without stopping services, ensuring application-level consistency. For more information on configuring hooks scripts, see the [Guest OS agent](#guest-os-agent) section.
Expand Down Expand Up @@ -2840,9 +2855,11 @@ Example output:

```txt
NAME PHASE CONSISTENT AGE
linux-vm-root-1728027905 Ready 3m2s
linux-vm-root-1728027905 Ready true 3m2s
```

The `CONSISTENT` field shows whether the snapshot was created consistently (`true`) or not (`false`). This value is determined automatically based on the snapshot creation conditions and cannot be changed after creation.

After creation, `VirtualDiskSnapshot` can be in the following states (phases):

- `Pending` - waiting for all dependent resources required for snapshot creation to be ready.
Expand Down Expand Up @@ -3090,8 +3107,9 @@ d8 k get vmsop <vmsop-name> -o json | jq '.status.resources'

VM cloning is performed using the VirtualMachineOperation resource with the `Clone` operation type.

{{< alert level="warning" >}}
Before cloning, the source VM must be [powered off](#vm-start-and-state-management-policy).
Cloning is supported for both powered-off and running virtual machines. When cloning a running VM, a consistent snapshot is automatically created, from which the clone is then formed.

{{< alert level="info" >}}
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 >}}

Expand Down
48 changes: 33 additions & 15 deletions docs/USER_GUIDE.ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -628,11 +628,6 @@ EOF

![](images/vd-wffc.ru.png)

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

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

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

> Внимание: Создать диски из iso-образов - нельзя!
Expand Down Expand Up @@ -936,6 +931,8 @@ linux-vm-root Ready 11Gi 12m

В платных редакциях вы можете мигрировать (перенести) диск виртуальной машины на другое хранилище, изменив для него класс хранилища (StorageClass).

Миграция поддерживается как для статически подключённых дисков, так и для динамически подключённых (hotplug) дисков.

{{< alert level="warning">}}
Ограничения миграции дисков между хранилищами:

Expand Down Expand Up @@ -2710,6 +2707,12 @@ EOF

Для этого необходимо указать желаемые сети в конфигурационном разделе `.spec.networks`. Если данный блок не задан (что является значением по умолчанию), ВМ будет использовать только основную сеть кластера.

{{< alert level="info" >}}
Указание основной сети кластера (`type: Main`) в `.spec.networks` является опциональным. Если вам не требуется подключение к основной сети кластера, можно использовать только дополнительные сети (`Network` или `ClusterNetwork`).

Однако если основная сеть указана, она обязательно должна быть первой в списке `.spec.networks`.
{{< /alert >}}

Особенности и важные моменты работы с дополнительными сетевыми интерфейсами:

- порядок перечисления сетей в `.spec.networks` определяет порядок подключения интерфейсов внутри виртуальной машины;
Expand All @@ -2718,28 +2721,39 @@ EOF
- политики сетевой безопасности (NetworkPolicy) не применяются к дополнительным сетевым интерфейсам;
- параметры сети (IP-адреса, шлюзы, DNS и т.д.) для дополнительных сетей настраиваются вручную изнутри гостевой ОС (например, с помощью Cloud-Init).

Пример подключения ВМ к проектной сети `user-net`:
Пример подключения ВМ к основной сети кластера и проектной сети `user-net`:

```yaml
spec:
networks:
- type: Main # Обязательно указывать первым
- type: Main # Если указана, должна быть первой
- type: Network # Тип сети (Network \ ClusterNetwork)
name: user-net # Название сети
```

Пример подключения кластерной сети `corp-net`:
Пример подключения к нескольким сетям, включая кластерную сеть `corp-net`:

```yaml
spec:
networks:
- type: Main # Обязательно указывать первым
- type: Main # Если указана, должна быть первой
- type: Network
name: user-net
- type: ClusterNetwork
name: corp-net # Название сети
```

Пример подключения ВМ только к дополнительным сетям (без основной сети кластера):

```yaml
spec:
networks:
- type: Network
name: isolated-net
- type: ClusterNetwork
name: corp-net
```

Информацию о подключённых сетях и их MAC-адресах можно посмотреть в статусе ВМ:

```yaml
Expand Down Expand Up @@ -2810,13 +2824,14 @@ vm-01-fz9cr 5e:e6:19:22:0f:d8 Attached vm-01 5m42s

Снимки могут быть консистентными и неконсистентными. За это отвечает параметр `requiredConsistency`, по умолчанию его значение равно `true`, что означает требование консистентного снимка.

Консистентный снимок гарантирует согласованное и целостное состояние дисков виртуальной машины. Такой снимок можно создать при выполнении одного из следующих условий:
Консистентный снимок гарантирует согласованное и целостное состояние данных диска. Такой снимок можно создать при выполнении одного из следующих условий:

- диск не подключён ни к одной виртуальной машине — снимок всегда будет консистентным;
- виртуальная машина выключена;
- в гостевой системе установлен [`qemu-guest-agent`](#агент-гостевой-ос), который на момент создания снимка временно приостанавливает работу файловой системы для обеспечения её согласованности.
- в гостевой системе установлен и запущен [`qemu-guest-agent`](#агент-гостевой-ос), который на момент создания снимка временно приостанавливает («замораживает») работу файловой системы для обеспечения её согласованности.

Неконсистентный снимок может не отражать согласованное состояние дисков виртуальной машины и её компонентов. Такой снимок создаётся, если ВМ запущена, и в гостевой ОС не установлен или не запущен `qemu-guest-agent`.
Если в манифесте снимка явно указан параметр `requiredConsistency: false`, но `qemu-guest-agent` при этом запущен, будет акже предпринята попытка заморозки файловой системы, чтобы снимок получился консистентным.
Неконсистентный снимок может не отражать согласованное состояние дисков виртуальной машины и её компонентов. Такой снимок создаётся, если ВМ запущена, и в гостевой ОС не установлен или не запущен `qemu-guest-agent`.
Если в манифесте снимка явно указан параметр `requiredConsistency: false`, но `qemu-guest-agent` при этом запущен, будет также предпринята попытка заморозки файловой системы, чтобы снимок получился консистентным.

QEMU Guest Agent поддерживает скрипты hooks, которые позволяют подготовить приложения к созданию снимка без остановки сервисов, обеспечивая согласованное состояние на уровне приложений. Подробнее о настройке скриптов hooks см. в разделе [«Агент гостевой ОС»](#агент-гостевой-ос).

Expand Down Expand Up @@ -2874,6 +2889,8 @@ NAME PHASE CONSISTENT AGE
linux-vm-root-snapshot Ready true 3m2s
```

Поле `CONSISTENT` показывает, был ли снимок создан консистентным (`true`) или нет (`false`). Это значение определяется автоматически на основе условий создания снимка и не может быть изменено после создания.

После создания `VirtualDiskSnapshot` может находиться в следующих состояниях (фазах):

- `Pending` - ожидание готовности всех зависимых ресурсов, требующихся для создания снимка.
Expand Down Expand Up @@ -3123,9 +3140,9 @@ d8 k get vmsop <vmsop-name> -o json | jq '.status.resources'

Клонирование ВМ выполняется с использованием ресурса VirtualMachineOperation с типом операции `Clone`.

{{< alert level="warning" >}}
Перед клонированием ВМ должна быть [выключена](#политика-запуска-и-управление-состоянием-вм).
Клонирование поддерживается как для выключенных, так и для работающих виртуальных машин. При клонировании работающей ВМ автоматически создаётся консистентный снимок, из которого затем формируется клон.

{{< alert level="info" >}}
Рекомендуется задавать параметр `.spec.runPolicy: AlwaysOff` в конфигурации клонируемой ВМ, чтобы предотвратить автоматический запуск клона ВМ. Это связано с тем, что клон наследует поведение родительской ВМ.
{{< /alert >}}

Expand Down Expand Up @@ -3317,3 +3334,4 @@ d8 data download -n <namespace> vds/<virtual-disksnapshot-name> -o file.img
{{< alert level="info" >}}
Чтобы импортировать скачанный диск обратно в кластер, загрузите его как [образ](#загрузка-образа-из-командной-строки) или как [диск](#загрузка-диска-из-командной-строки).
{{< /alert >}}

Loading