Skip to content

docs: update docs due 1.8.0 #2205

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
prismagod wants to merge 8 commits into
base: main
Choose a base branch
from
Draft

docs: update docs due 1.8.0 #2205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7d1f99c
docs: ARP flux note for multi-subnet Linux guests
prismagod Apr 11, 2026
e4e7b3c
docs: fix arp flux doc
fl64 Apr 12, 2026
161cd85
docs: add requirements for USB device passthrough
prismagod Apr 15, 2026
1a8150e
docs: update instruction for changing DVCR StorageClass
prismagod Apr 16, 2026
782adc0
docs: fix
prismagod Apr 16, 2026
15dd9b1
Apply suggestions from code review
prismagod Apr 17, 2026
5699174
Update docs/USER_GUIDE.ru.md
prismagod Apr 17, 2026
b33dcde
Update docs/USER_GUIDE.ru.md
prismagod Apr 17, 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
26 changes: 0 additions & 26 deletions docs/ADMIN_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,32 +62,6 @@ The `.spec.settings.dvcr.storage` block configures a persistent volume for stori
- `.spec.settings.dvcr.storage.persistentVolumeClaim.size`: Volume size (for example, `50G`). To expand the storage, increase the value of the parameter.
- `.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName`: StorageClass name (for example, `rv-thin-r1`).

{{< alert level="warning" >}}
Migrating images when changing the `.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName` parameter value is not supported.

When you change the DVCR StorageClass, all images stored in DVCR will be lost.
{{< /alert >}}

To change the DVCR StorageClass, perform the following steps:

1. Change the value of the [`.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName`](/modules/virtualization/configuration.html#parameters-dvcr-storage-persistentvolumeclaim-storageclassname) parameter.

1. Delete the old PVC for DVCR using the following command:

```shell
d8 k -n d8-virtualization delete pvc -l app=dvcr
```

1. Restart DVCR by running the following command:

```shell
d8 k -n d8-virtualization rollout restart deployment dvcr
```

{{< alert level="warning" >}}
The storage that serves the `.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName` StorageClass must be accessible from the nodes where DVCR runs (system nodes, or worker nodes if there are no system nodes).
{{< /alert >}}

**Ingress settings**

The `.spec.settings.ingressClass` parameter defines the Ingress controller class that will be used to upload virtual machine images via the web interface or CLI.
Expand Down
26 changes: 0 additions & 26 deletions docs/ADMIN_GUIDE.ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,32 +62,6 @@ spec:
- `.spec.settings.dvcr.storage.persistentVolumeClaim.size` — размер тома (например, `50G`). Для расширения хранилища увеличьте значение параметра;
- `.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName` — класс хранения (например, `rv-thin-r1`).

{{< alert level="warning" >}}
Перенос образов при изменении значения параметра `.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName` не поддерживается.

При смене StorageClass DVCR все образы, хранящиеся в DVCR, будут утеряны.
{{< /alert >}}

Для изменения StorageClass DVCR выполните следующие действия:

1. Измените значение [параметра `.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName`](/modules/virtualization/configuration.html#parameters-dvcr-storage-persistentvolumeclaim-storageclassname).

1. Удалите старый PVC для DVCR с помощью следующей команды:

```shell
d8 k -n d8-virtualization delete pvc -l app=dvcr
```

1. Перезапустите DVCR, выполнив следующую команду:

```shell
d8 k -n d8-virtualization rollout restart deployment dvcr
```

{{< alert level="warning" >}}
Хранилище, обслуживающее данный класс хранения `.spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName`, должно быть доступно на узлах, где запускается DVCR (system-узлы, либо worker-узлы, при отсутствии system-узлов).
{{< /alert >}}

**Настройки Ingress**

Параметр `.spec.settings.ingressClass` определяет класс Ingress-контроллера, который будет использоваться для загрузки образов виртуальных машин через веб-интерфейс или CLI.
Expand Down
60 changes: 60 additions & 0 deletions docs/FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -934,6 +934,66 @@ The DVCR volume size is set in the `virtualization` module ModuleConfig (`spec.s
dvcr Bound pvc-6a6cedb8-1292-4440-b789-5cc9d15bbc6b 57617188Ki RWO linstor-thick-data-r1 7d
```

### How do I change the DVCR StorageClass when a PVC already exists?

{{< alert level="warning" >}}
You can change the DVCR storage StorageClass only by recreating the PVC. All images previously loaded into DVCR are lost, along with data for existing [ClusterVirtualImage](/modules/virtualization/cr.html#clustervirtualimage) and [VirtualImage](/modules/virtualization/cr.html#virtualimage) resources.
{{< /alert >}}

The [`spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName`](configuration.html#parameters-dvcr-storage-persistentvolumeclaim-storageclassname) field in the `virtualization` module ModuleConfig sets the StorageClass for the virtual machine image storage volume (DVCR). While a PVC for that volume exists in the `d8-virtualization` namespace, you cannot change the field via the API.

You cannot change `storageClassName` on an existing PVC in place, and DVCR data is not migrated between storage classes.

To change the DVCR StorageClass, perform the following steps:

1. Stop DVCR:

```shell
d8 k -n d8-virtualization scale deployment dvcr --replicas=0
```

1. List PVCs in the `d8-virtualization` namespace, find the PVC for the DVCR volume, and delete it. Replace `<pvc-name>` with the resource name:

```shell
d8 k get pvc -n d8-virtualization
d8 k -n d8-virtualization delete pvc/<pvc-name>
```

1. Set the new StorageClass in ModuleConfig. Replace `<storage-class-name>` with the class name you need.

```shell
d8 k patch mc virtualization --type merge -p '{"spec":{"settings":{"dvcr":{"storage":{"persistentVolumeClaim":{"storageClassName":"<storage-class-name>"}}}}}}'
```

Example output:

```console
moduleconfig.deckhouse.io/virtualization patched
```

1. Start DVCR:

```shell
d8 k -n d8-virtualization scale deployment dvcr --replicas=1
```

1. Verify the PVC:

```shell
d8 k get pvc -n d8-virtualization
```

Example output:

```console
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE
dvcr Bound pvc-b43f2e33-32cc-435a-aa1d-b53df35b030a 100Gi RWO linstor-thin-r1-hdd <unset> 34s
```

{{< alert level="warning" >}}
The storage for the chosen StorageClass must be reachable from the nodes where DVCR runs: system nodes, or worker nodes if the cluster has no system nodes.
{{< /alert >}}

### How to restore the cluster if images from registry.deckhouse.io cannot be pulled after a license change?

After a license change on a cluster with `containerd v1` and removal of the outdated license, images from `registry.deckhouse.io` may stop being pulled. Nodes then retain the outdated configuration file `/etc/containerd/conf.d/dvcr.toml`, which is not removed automatically. Because of it, the `registry` module does not start, and without it DVCR does not work.
Expand Down
60 changes: 60 additions & 0 deletions docs/FAQ.ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -932,6 +932,66 @@ ansible -m shell -a "uptime" \
dvcr Bound pvc-6a6cedb8-1292-4440-b789-5cc9d15bbc6b 57617188Ki RWO linstor-thick-data-r1 7d
```

### Как сменить StorageClass у DVCR, если PVC уже создан?

{{< alert level="warning" >}}
StorageClass хранилища DVCR можно сменить только пересозданием PVC. При этом теряются все ранее загруженные в DVCR образы, то есть существующие ресурсы [ClusterVirtualImage](/modules/virtualization/cr.html#clustervirtualimage) и [VirtualImage](/modules/virtualization/cr.html#virtualimage) фактически перестают соответствовать данным в хранилище.
{{< /alert >}}

Поле [`spec.settings.dvcr.storage.persistentVolumeClaim.storageClassName`](configuration.html#parameters-dvcr-storage-persistentvolumeclaim-storageclassname) в ModuleConfig модуля `virtualization` задаёт класс хранения тома хранилища образов виртуальных машин (DVCR). Пока в пространстве имён `d8-virtualization` существует PVC этого тома, изменить поле через API нельзя.

У уже созданного PVC в Kubernetes нельзя сменить `storageClassName`, штатного переноса данных DVCR между классами хранения нет.

Для того чтобы изменить StorageClass у DVCR, выполните следующие действия:

1. Остановите DVCR:

```shell
d8 k -n d8-virtualization scale deployment dvcr --replicas=0
```

1. Выведите список PVC в неймспейсе `d8-virtualization`, найдите PVC тома DVCR и удалите его, подставив имя ресурса вместо `<pvc-name>`:

```shell
d8 k get pvc -n d8-virtualization
d8 k -n d8-virtualization delete pvc/<pvc-name>
```

1. Задайте новый StorageClass в ModuleConfig. Вместо `<storage-class-name>` укажите нужный класс.

```shell
d8 k patch mc virtualization --type merge -p '{"spec":{"settings":{"dvcr":{"storage":{"persistentVolumeClaim":{"storageClassName":"<storage-class-name>"}}}}}}'
```

Пример вывода:

```console
moduleconfig.deckhouse.io/virtualization patched
```

1. Запустите DVCR:

```shell
d8 k -n d8-virtualization scale deployment dvcr --replicas=1
```

1. Проверьте PVC:

```shell
d8 k get pvc -n d8-virtualization
```

Пример вывода:

```console
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS VOLUMEATTRIBUTESCLASS AGE
dvcr Bound pvc-b43f2e33-32cc-435a-aa1d-b53df35b030a 100Gi RWO linstor-thin-r1-hdd <unset> 34s
```

{{< alert level="warning" >}}
Хранилище выбранного StorageClass должно быть доступно на узлах, где запускается DVCR: на system-узлах или на worker-узлах, если в кластере нет system-узлов.
{{< /alert >}}

### Как восстановить кластер, если после смены лицензии образы из registry.deckhouse.io не загружаются?

После смены лицензии на кластере с `containerd v1` и удаления устаревшей лицензии образы из `registry.deckhouse.io` могут перестать загружаться. При этом на узлах остаётся устаревший файл конфигурации `/etc/containerd/conf.d/dvcr.toml`, который не удаляется автоматически. Из-за него не запускается модуль `registry`, без которого не работает DVCR.
Expand Down
34 changes: 31 additions & 3 deletions docs/USER_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3000,6 +3000,29 @@ Important considerations when working with additional network interfaces:
When configuring network interfaces in the guest OS, use stable identifiers (predictable names `enpXsY` or MAC address binding) instead of `ethX` names. For more details, see the [Network interface naming in guest OS](#network-interface-naming-in-guest-os) section.
{{< /alert >}}

{{< alert level="info" >}}
On a Linux guest system with multiple interfaces in the same subnet, the ARP Flux issue may occur, where the kernel responds to ARP requests via any arbitrary interface rather than the one the request was received on, leading to unstable connections and packet loss due to an incorrect MAC address in the router's ARP cache.

To resolve this, set the following parameters to force the system to respond to requests strictly via the interface holding the target IP and to use the correct source address:

```bash
sysctl -w net.ipv4.conf.all.arp_ignore=1
sysctl -w net.ipv4.conf.all.arp_announce=2
```

Cloud-init example:

```yaml
write_files:
- path: /etc/sysctl.d/90-arp-strict.conf
content: |
net.ipv4.conf.all.arp_ignore=1
net.ipv4.conf.all.arp_announce=2
```

For more details, see the [IP sysctl](https://docs.kernel.org/networking/ip-sysctl.html) documentation.
{{< /alert >}}

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

```yaml
Expand Down Expand Up @@ -3602,6 +3625,12 @@ USB device passthrough is available only in the **Enterprise Edition (EE)** of t

The virtualization module supports USB device passthrough to virtual machines using DRA (Dynamic Resource Allocation). This section describes how to use USB devices with virtual machines.

USB device passthrough requires:

- `containerd v2`: Detailed requirements for cluster nodes are described in the [`defaultCRI`](/products/kubernetes-platform/documentation/v1/reference/api/cr.html#clusterconfiguration-defaultcri) parameter.
- [Kubernetes](/products/kubernetes-platform/documentation/v1/reference/supported_versions.html#kubernetes) version 1.34 or higher.
- [Deckhouse Kubernetes Platform (DKP)](https://releases.deckhouse.io/) version 1.75 or higher.

### Overview

The module provides two custom resources for managing USB devices:
Expand All @@ -3625,7 +3654,7 @@ USB device passthrough follows a defined lifecycle — from device discovery on

The following steps describe the minimal workflow for attaching a USB device to a virtual machine:

1. Connect the USB device to a cluster node.
1. Connect the USB device to a cluster node.
1. Verify that a NodeUSBDevice resource has been created:

```bash
Expand Down Expand Up @@ -3833,7 +3862,7 @@ Status:
```

{{< alert level="info" >}}
If a USB device is physically disconnected from the node, the `Attached` condition becomes `False`.
If a USB device is physically disconnected from the node, the `Attached` condition becomes `False`.
Both `USBDevice` and `NodeUSBDevice` resources update their status conditions to indicate that the device is no longer present on the host.
{{< /alert >}}

Expand Down Expand Up @@ -3873,4 +3902,3 @@ If you are exporting data from a machine other than a cluster node (for example,
{{< alert level="info" >}}
To import a downloaded disk back into the cluster, upload it as an [image](#load-an-image-from-the-command-line) or as a [disk](#upload-a-disk-from-the-command-line).
{{< /alert >}}

32 changes: 30 additions & 2 deletions docs/USER_GUIDE.ru.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3034,6 +3034,29 @@ EOF
При настройке сетевых интерфейсов в гостевой ОС используйте стабильные идентификаторы (предсказуемые имена `enpXsY` или привязку по MAC-адресу) вместо имён `ethX`. Подробнее см. раздел [Именование сетевых интерфейсов в гостевой ОС](#именование-сетевых-интерфейсов-в-гостевой-ос).
{{< /alert >}}

{{< alert level="info" >}}
На гостевой системе Linux с несколькими интерфейсами в одной подсети может возникать проблема ARP Flux, при которой ядро отвечает на ARP-запросы через произвольный интерфейс, а не через тот, на который пришёл запрос, что приводит к нестабильному соединению и потере пакетов из-за некорректного MAC-адреса в кеше маршрутизаторов.

Чтобы это исправить, установите параметры, которые заставляют систему отвечать на запросы строго через интерфейс с целевым IP и использовать корректный исходный адрес:

```bash
sysctl -w net.ipv4.conf.all.arp_ignore=1
sysctl -w net.ipv4.conf.all.arp_announce=2
```

Пример для cloud-init:

```yaml
write_files:
- path: /etc/sysctl.d/90-arp-strict.conf
content: |
net.ipv4.conf.all.arp_ignore=1
net.ipv4.conf.all.arp_announce=2
```

Подробнее см. документацию [IP sysctl](https://docs.kernel.org/networking/ip-sysctl.html).
{{< /alert >}}

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

```yaml
Expand Down Expand Up @@ -3638,6 +3661,12 @@ spec:

Модуль виртуализации поддерживает проброс USB-устройств в виртуальные машины с использованием DRA (Dynamic Resource Allocation). В этом разделе описано, как использовать USB-устройства с виртуальными машинами.

Для проброса USB требуются:

- `containerd v2` — подробные требования к узлам кластера описаны в параметре [`defaultCRI`](/products/kubernetes-platform/documentation/v1/reference/api/cr.html#clusterconfiguration-defaultcri);
- [Kubernetes](/products/kubernetes-platform/documentation/v1/reference/supported_versions.html#kubernetes) версии не ниже 1.34;
- [Deckhouse Kubernetes Platform (DKP)](https://releases.deckhouse.ru/) версии не ниже 1.75.

### Обзор

Модуль предоставляет два пользовательских ресурса для управления USB-устройствами:
Expand Down Expand Up @@ -3869,7 +3898,7 @@ Status:
```

{{< alert level="info" >}}
Если USB-устройство физически отключено от узла, условие `Attached` принимает значение `False`.
Если USB-устройство физически отключено от узла, условие `Attached` принимает значение `False`.
Статусы ресурсов `USBDevice` и `NodeUSBDevice` обновляются и указывают на отсутствие устройства на хосте.
{{< /alert >}}

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

Loading