docs: update docs for v0.15

Signed-off-by: Pavel Tishkov <[email protected]>
deckhouse · Jan 13, 2025 · b9dda4b · b9dda4b
1 parent 8e11086
commit b9dda4b
Show file tree

Hide file tree

Showing 11 changed files with 195 additions and 86 deletions.
diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md
@@ -200,10 +200,36 @@ d8 k get cvi some-image
 
 The `VirtualMachineClass` resource is designed for centralized configuration of preferred virtual machine settings. It allows you to define CPU instructions and configuration policies for CPU and memory resources for virtual machines, as well as define ratios of these resources. In addition, `VirtualMachineClass` provides management of virtual machine placement across platform nodes. This allows administrators to effectively manage virtualization platform resources and optimally place virtual machines on platform nodes.
 
+The structure of the `VirtualMachineClass` resource is as follows:
+
+```yaml
+apiVersion: virtualization.deckhouse.io/v1alpha2
+kind: VirtualMachineClass
+metadata:
+  name: <vmclass-name>
+spec:
+  # The block describes the virtual processor parameters for virtual machines.
+  # This block cannot be changed after the resource has been created.
+  cpu: ...
+  # Describes the rules for node placement of virtual machines.
+  # When changed, it is automatically applied to all virtual machines using this VirtualMachineClass.
+  nodeSelector: ...
+  # Describes the sizing policy for configuring virtual machine resources.
+  # When changed, it is automatically applied to all virtual machines using this VirtualMachineClass.
+  sizingPolicies: ...
+```
+
+{{< alert level="warning" >}}
+Warning. Since changing the `.spec.nodeSelector` parameter affects all virtual machines using this `VirtualMachineClass`, the following should be considered:
+
+For Enterprise-edition: this may cause virtual machines to be migrated to new destination nodes if the current nodes do not meet placement requirements.
+For Community edition: this may cause virtual machines to restart according to the automatic change application policy set in the `.spec.disruptions.restartApprovalMode` parameter.
+{{< /alert >}}
+
 The virtualization platform provides 3 predefined `VirtualMachineClass` resources:
 
 ```bash
-kubectl get virtualmachineclass
+d8 k get virtualmachineclass
 NAME               PHASE   AGE
 host               Ready   6d1h
 host-passthrough   Ready   6d1h
@@ -226,7 +252,7 @@ spec:
   ...
 ```
 
-{{< alert level="warning" >}}
+{{< alert level="info" >}}
 Warning. It is recommended to create at least one `VirtualMachineClass` resource in the cluster with the Discovery type immediately after all nodes are configured and added to the cluster. This will allow the virtual machines to utilize a generic CPU with the highest possible CPU performance given the CPUs on the cluster nodes, allowing the virtual machines to utilize the maximum CPU capabilities and migrate seamlessly between cluster nodes if necessary.
 {{< /alert >}}
 
@@ -398,7 +424,7 @@ spec:
 - to create a vCPU of a specific CPU with a pre-defined instruction set, we use `type: Model`. In advance, to get a list of supported CPU names for the cluster node, run the command:
 
 ```bash
-kubectl get nodes <node-name> -o json | jq '.metadata.labels | to_entries[] | select(.key | test(“cpu-model”)) | .key | split(“/”)[1]'' -r
+d8 k get nodes <node-name> -o json | jq '.metadata.labels | to_entries[] | select(.key | test(“cpu-model”)) | .key | split(“/”)[1]'' -r
 
 # Sample output:
 #
@@ -436,33 +462,33 @@ The following is an example of migrating a selected virtual machine:
 Before starting the migration, see the current status of the virtual machine:
 
 ```bash
-kubectl get vm
+d8 k get vm
 # NAME                                   PHASE     NODE           IPADDRESS     AGE
 # linux-vm                              Running   virtlab-pt-1   10.66.10.14   79m
 ```
 
 We can see that it is currently running on the `virtlab-pt-1` node.
 
-To migrate a virtual machine from one host to another, taking into account the virtual machine placement requirements, the `VirtualMachineOperations` (`vmop`) resource with the migrate type is used.
+To migrate a virtual machine from one host to another, taking into account the virtual machine placement requirements, the `VirtualMachineOperations` (`vmop`) resource with the `Evict` type is used.
 
 ```yaml
 d8 k apply -f - <<EOF
 apiVersion: virtualization.deckhouse.io/v1alpha2
 kind: VirtualMachineOperation
 metadata:
-  name: migrate-linux-vm-$(date +%s)
+  name: evict-linux-vm-$(date +%s)
 spec:
   # virtual machine name
   virtualMachineName: linux-vm
   # operation for migration
-  type: Migrate
+  type: Evict
 EOF
 ```
 
 Immediately after creating the `vmop` resource, run the command:
 
 ```bash
-kubectl get vm -w
+d8 k get vm -w
 # NAME                                   PHASE       NODE           IPADDRESS     AGE
 # linux-vm                              Running     virtlab-pt-1   10.66.10.14   79m
 # linux-vm                              Migrating   virtlab-pt-1   10.66.10.14   79m
@@ -477,21 +503,21 @@ When performing work on nodes with running virtual machines, there is a risk of
 To do this, run the following command:
 
 ```bash
-kubectl drain <nodename> --ignore-daemonsets --delete-emptydir-dat
+d8 k drain <nodename> --ignore-daemonsets --delete-emptydir-dat
 ```
 
 where `<nodename>` is the node on which the work is to be performed and which should be freed from all resources (including system resources).
 
 If there is a need to push only virtual machines off the node, run the following command:
 
 ```bash
-kubectl drain <nodename> --pod-selector vm.kubevirt.internal.virtualization.deckhouse.io/name --delete-emptydir-data
+d8 k drain <nodename> --pod-selector vm.kubevirt.internal.virtualization.deckhouse.io/name --delete-emptydir-data
 ```
 
-After running the `kubectl drain` conmade, the node will go into maintenance mode and no virtual machines will be able to start on it. To take it out of maintenance mode, run the following command:
+After running the `d8 k drain` command, the node will go into maintenance mode and no virtual machines will be able to start on it. To take it out of maintenance mode, run the following command:
 
 ```bash
-kubectl uncordon <nodename>
+d8 k uncordon <nodename>
 ```
 
 ![](./images/drain.png)
@@ -523,7 +549,7 @@ For storing disks (`VirtualDisk`) and images (`VirtualImage`) with the `Persiste
 The list of storage supported by the platform can be listed by executing the command to view storage classes (`StorageClass`)
 
 ```bash
-kubectl get storageclass
+d8 k get storageclass
 ```
 
 Example of command execution:

diff --git a/docs/ADMIN_GUIDE_RU.md b/docs/ADMIN_GUIDE_RU.md
@@ -203,10 +203,36 @@ d8 k get cvi some-image
 
 Ресурс `VirtualMachineClass` предназначен для централизованной конфигурации предпочтительных параметров виртуальных машин. Он позволяет определять инструкции CPU и политики конфигурации ресурсов CPU и памяти для виртуальных машин, а также определять соотношения этих ресурсов. Помимо этого, `VirtualMachineClass` обеспечивает управление размещением виртуальных машин по узлам платформы. Это позволяет администраторам эффективно управлять ресурсами платформы виртуализации и оптимально размещать виртуальные машины на узлах платформы.
 
+Структура ресурса `VirtualMachineClass` выглядит следующим образом:
+
+```yaml
+apiVersion: virtualization.deckhouse.io/v1alpha2
+kind: VirtualMachineClass
+metadata:
+  name: <vmclass-name>
+spec:
+  # Блок описывает параметры виртуального процессора для виртуальных машин.
+  # Изменять данны блок нельзя после создания ресурса.
+  cpu: ...
+  # Описывает правила размещения виртуальных машины по узлам.
+  # При изменении автоматически применяется ко всем виртуальных машинам, использующим данный VirtualMachineClass.
+  nodeSelector: ...
+  # Описывает политику настройки ресурсов виртуальных машин.
+  # При изменении автоматически применяется ко всем виртуальных машинам, использующим данный VirtualMachineClass.
+  sizingPolicies: ...
+```
+
+{{< alert level="warning" >}}
+Внимание! Поскольку изменение параметра `.spec.nodeSelector` влияет на все виртуальные машины, использующие данный `VirtualMachineClass`, следует учитывать следующее:
+
+Для Enterprise-редакции: это может привести к миграции виртуальных машин на новые узлы назначения, если текущие узлы не соответствуют требованиям размещения.
+Для Community-редакции: это может вызвать перезапуск виртуальных машин в соответствии с автоматической политикой применения изменений, установленной в параметре `.spec.disruptions.restartApprovalMode`.
+{{< /alert >}}
+
 Платформа виртуализации предоставляет 3 предустановленных ресурса `VirtualMachineClass`:
 
 ```bash
-kubectl get virtualmachineclass
+d8 k get virtualmachineclass
 NAME               PHASE   AGE
 host               Ready   6d1h
 host-passthrough   Ready   6d1h
@@ -229,7 +255,7 @@ spec:
   ...
 ```
 
-{{< alert level="warning" >}}
+{{< alert level="info" >}}
 Внимание! Рекомендуется создать как минимум один ресурс `VirtualMachineClass` в кластере с типом Discovery сразу после того как все узлы будут настроены и добавлены в кластер. Это позволит использовать в виртуальных машинах универсальный процессор с максимально возможными характеристиками с учетом ЦП на узлах кластера, что позволит виртуальным машинам использовать максимум возможностей ЦП и при необходимости беспрепятственно осуществлять миграцию между узлами кластера.
 {{< /alert >}}
 
@@ -401,7 +427,7 @@ spec:
 - чтобы создать vCPU конкретного процессора с предварительно определенным набором инструкций, используем тип `type: Model`. Предварительно, чтобы получить перечень названий поддерживаемых CPU для узла кластера, выполните команду:
 
   ```bash
-  kubectl get nodes <node-name> -o json | jq '.metadata.labels | to_entries[] | select(.key | test("cpu-model")) | .key | split("/")[1]' -r
+  d8 k get nodes <node-name> -o json | jq '.metadata.labels | to_entries[] | select(.key | test("cpu-model")) | .key | split("/")[1]' -r
 
   # Примерный вывод:
   #
@@ -439,33 +465,33 @@ spec:
 Перед запуском миграции посмотрите текущий статус виртуальной машины:
 
 ```bash
-kubectl get vm
+d8 k get vm
 # NAME                                   PHASE     NODE           IPADDRESS     AGE
 # linux-vm                              Running   virtlab-pt-1   10.66.10.14   79m
 ```
 
 Мы видим что на данный момент она запущена на узле `virtlab-pt-1`.
 
-Для осуществления миграции виртуальной машины с одного узла на другой, с учетом требований к размещению виртуальной машины используется ресурс `VirtualMachineOperations` (`vmop`) с типом migrate.
+Для осуществления миграции виртуальной машины с одного узла на другой, с учетом требований к размещению виртуальной машины используется ресурс `VirtualMachineOperations` (`vmop`) с типом `Evict`.
 
 ```yaml
 d8 k apply -f - <<EOF
 apiVersion: virtualization.deckhouse.io/v1alpha2
 kind: VirtualMachineOperation
 metadata:
-  name: migrate-linux-vm-$(date +%s)
+  name: evict-linux-vm-$(date +%s)
 spec:
   # имя виртуальной машины
   virtualMachineName: linux-vm
   # операция для миграции
-  type: Migrate
+  type: Evict
 EOF
 ```
 
 Сразу после создания ресурса `vmop`, выполните команду:
 
 ```bash
-kubectl get vm -w
+d8 k get vm -w
 # NAME                                   PHASE       NODE           IPADDRESS     AGE
 # linux-vm                              Running     virtlab-pt-1   10.66.10.14   79m
 # linux-vm                              Migrating   virtlab-pt-1   10.66.10.14   79m
@@ -480,21 +506,21 @@ kubectl get vm -w
 Для этого необходимо выполнить следующую команду:
 
 ```bash
-kubectl drain <nodename> --ignore-daemonsets --delete-emptydir-dat
+d8 k drain <nodename> --ignore-daemonsets --delete-emptydir-dat
 ```
 
 где `<nodename>` - узел, на котором предполагается выполнить работы и который должен быть освобожден от всех ресурсов (в том числе и от системных).
 
 Если есть необходимость вытеснить с узла только виртуальные машины, выполните следующую команду:
 
 ```bash
-kubectl drain <nodename> --pod-selector vm.kubevirt.internal.virtualization.deckhouse.io/name --delete-emptydir-data
+d8 k drain <nodename> --pod-selector vm.kubevirt.internal.virtualization.deckhouse.io/name --delete-emptydir-data
 ```
 
-После выполнения конмад `kubectl drain` - узле перейдет в режим обслуживания и виртуальные машины на нем запускаться не смогут. Чтобы вывести его из режима обслуживания выполните следующую команду:
+После выполнения конмад `d8 k drain` - узле перейдет в режим обслуживания и виртуальные машины на нем запускаться не смогут. Чтобы вывести его из режима обслуживания выполните следующую команду:
 
 ```bash
-kubectl uncordon <nodename>
+d8 k uncordon <nodename>
 ```
 
 ![](./images/drain.ru.png)
@@ -526,7 +552,7 @@ ColdStandby обеспечивает механизм восстановлени
 Перечень поддерживаемых платформой хранилищ можно посмотреть, выполнив команду, для просмотра классов хранилищ (`StorageClass`)
 
 ```bash
-kubectl get storageclass
+d8 k get storageclass
 ```
 
 Пример выполнения команды:

diff --git a/docs/FAQ_RU.md b/docs/FAQ_RU.md
@@ -229,15 +229,15 @@ metadata:
 1. Проверьте текущий размер dvcr:
 
 ```shell
-kubectl get mc virtualization -o jsonpath='{.spec.settings.dvcr.storage.persistentVolumeClaim}'
+d8 k get mc virtualization -o jsonpath='{.spec.settings.dvcr.storage.persistentVolumeClaim}'
 #Output
 {"size":"58G","storageClass":"linstor-thick-data-r1"}
 ```
 
 1. Задайте размер:
 
 ```shell
-kubectl patch mc virtualization \
+d8 k patch mc virtualization \
   --type merge -p '{"spec": {"settings": {"dvcr": {"storage": {"persistentVolumeClaim": {"size":"59G"}}}}}}'
 
 #Output
@@ -247,11 +247,11 @@ moduleconfig.deckhouse.io/virtualization patched
 1. Проверьте изменение размера:
 
 ```shell
-kubectl get mc virtualization -o jsonpath='{.spec.settings.dvcr.storage.persistentVolumeClaim}'
+d8 k get mc virtualization -o jsonpath='{.spec.settings.dvcr.storage.persistentVolumeClaim}'
 #Output
 {"size":"59G","storageClass":"linstor-thick-data-r1"}
 
-kubectl get pvc dvcr -n d8-virtualization
+d8 k get pvc dvcr -n d8-virtualization
 #Output
 NAME   STATUS   VOLUME                                     CAPACITY     ACCESS MODES   STORAGECLASS            AGE
 dvcr   Bound    pvc-6a6cedb8-1292-4440-b789-5cc9d15bbc6b   57617188Ki   RWO            linstor-thick-data-r1   7d

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
@@ -98,6 +98,10 @@ Deckhouse Virtualization Platform uses five update channels designed for use in
 | Stable         | Stable update channel for clusters where active work is finished and mostly operational. Functionality updates to this update channel do not reach this update channel until two weeks after they appear in the release.                                           |
 | Rock Solid     | The most stable update channel. Suitable for clusters that need a higher level of stability. Feature updates do not reach this channel until one month after they are released.                                                                                    |
 
+{{< alert level="warning" >}}
+Attention: Changing the virtual machine “firmware” during a platform version upgrade may result in virtual machines migrating to the new “firmware”.
+{{< /alert >}}
+
 Deckhouse Virtualization Platform components can be updated automatically, or with manual confirmation as updates are released in the update channels.
 
 For information on the versions available on the update channels, visit this site at https://releases.deckhouse.io/.
diff --git a/docs/INSTALL_RU.md b/docs/INSTALL_RU.md
@@ -104,4 +104,9 @@ Deckhouse Virtualization Platform использует пять каналов
 
 Компоненты Deckhouse Virtualization Platform могут обновляться автоматически, либо с ручным подтверждением по мере выхода обновлений в каналах обновления.
 
+{{< alert level="warning" >}}
+Внимание! Изменение "прошивки" виртуальной машины в процессе обновления версии платформы может привести к миграции виртуальных машин для перехода на новую "прошивку".
+{{< /alert >}}
+
+
 Информацию по версиям, доступных на каналах обновления, можно получить на данном сайте https://releases.deckhouse.ru/
diff --git a/docs/README.md b/docs/README.md
@@ -19,7 +19,7 @@ Scenarios of using the module:
 
 ![](./images/cases-pods-and-vms.png)
 
-{{< alert level="warning" >}}
+{{< alert level="info" >}}
 If you plan to use Deckhouse Virtualization Platform in a production environment, it is recommended to deploy it on physical servers. Deploying Deckhouse Virtualization Platform on virtual machines is also possible, but in this case you must enable nested virtualization.
 {{< /alert >}}
 
@@ -98,7 +98,7 @@ Commands available for operations with the d8 command line utility:
 | d8 v start                    | N    | Y              | Y      | Y     | Y             | Y            |
 | d8 v stop                     | N    | Y              | Y      | Y     | Y             | Y            |
 | d8 v restart                  | N    | Y              | Y      | Y     | Y             | Y            |
-| d8 v migrate                  | N    | Y              | Y      | Y     | Y             | Y            |
+| d8 v evict                    | N    | Y              | Y      | Y     | Y             | Y            |
 
 Abbreviations: