From 42998a955d6c7e57204fb7bde45d0eea91548833 Mon Sep 17 00:00:00 2001 From: Vladislav Panfilov Date: Tue, 17 Feb 2026 18:28:40 +0400 Subject: [PATCH 1/6] docs: add instruction to restore cluster after license change Signed-off-by: Vladislav Panfilov --- docs/FAQ.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/FAQ.ru.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index 1743223093..6aaeb0e6d4 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -823,3 +823,67 @@ A golden image is a pre-configured virtual machine image that can be used to qui ``` After completing these steps, you will have a golden image that can be used to quickly create new virtual machines with pre-installed software and configurations. + +## 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. In that case, nodes still have the outdated config 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. + +To fix this, apply a NodeGroupConfiguration (NGC) manifest: it will remove the file on the nodes. After the `registry` module starts, remove the manifest, since this is a one-time fix. + +1. Save the manifest to a file (for example, `containerd-dvcr-remove-old-config.yaml`): + + ```yaml + apiVersion: deckhouse.io/v1alpha1 + kind: NodeGroupConfiguration + metadata: + name: containerd-dvcr-remove-old-config.sh + spec: + weight: 32 # Must be in range 32–90 + nodeGroups: ["*"] + bundles: ["*"] + content: | + # Copyright 2023 Flant JSC + # Licensed under the Apache License, Version 2.0 (the "License"); + # you may not use this file except in compliance with the License. + # You may obtain a copy of the License at + # http://www.apache.org/licenses/LICENSE-2.0 + # Unless required by applicable law or agreed to in writing, software + # distributed under the License is distributed on an "AS IS" BASIS, + # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + # See the License for the specific language governing permissions and + # limitations under the License. + + rm -f /etc/containerd/conf.d/dvcr.toml + ``` + +1. Apply the manifest: + + ```bash + d8 k apply -f containerd-dvcr-remove-old-config.yaml + ``` + +1. Verify that the `registry` module is running: + + ```bash + d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)' + ``` + + Example output when the `registry` module is running: + + ```yaml + conditions: + # ... + - lastTransitionTime: "..." + message: "" + reason: "" + status: "True" + type: Ready + ``` + +1. Delete the NGC manifest: + + ```bash + d8 k delete -f containerd-dvcr-remove-old-config.yaml + ``` + +For more information on migration, see [Migrating container runtime to containerd v2](/products/virtualization-platform/documentation/admin/platform-management/platform-scaling/node/migrating.html). diff --git a/docs/FAQ.ru.md b/docs/FAQ.ru.md index 047c3bccc4..eec7c3d402 100644 --- a/docs/FAQ.ru.md +++ b/docs/FAQ.ru.md @@ -822,3 +822,67 @@ Golden image — это предварительно настроенный об ``` После выполнения этих шагов у вас будет golden image, который можно использовать для быстрого создания новых виртуальных машин с предустановленным программным обеспечением и настройками. + +## Как восстановить кластер, если после смены лицензии образы из registry.deckhouse.io не загружаются? + +После смены лицензии на кластере с `containerd v1` и удаления устаревшей лицензии образы из `registry.deckhouse.io` могут перестать загружаться. При этом на узлах остаётся устаревший файл конфигурации `/etc/containerd/conf.d/dvcr.toml`, который не удаляется автоматически. Из-за него не запускается модуль `registry`, без которого не работает DVCR. + +Чтобы это исправить, примените манифест NodeGroupConfiguration (NGC): он удалит файл на узлах. После запуска модуля `registry` манифест нужно удалить, так как это разовое исправление. + +1. Сохраните манифест в файл (например, `containerd-dvcr-remove-old-config.yaml`): + + ```yaml + apiVersion: deckhouse.io/v1alpha1 + kind: NodeGroupConfiguration + metadata: + name: containerd-dvcr-remove-old-config.sh + spec: + weight: 32 # Должен быть в диапазоне 32–90 + nodeGroups: ["*"] + bundles: ["*"] + content: | + # Copyright 2023 Flant JSC + # Licensed under the Apache License, Version 2.0 (the "License"); + # you may not use this file except in compliance with the License. + # You may obtain a copy of the License at + # http://www.apache.org/licenses/LICENSE-2.0 + # Unless required by applicable law or agreed to in writing, software + # distributed under the License is distributed on an "AS IS" BASIS, + # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + # See the License for the specific language governing permissions and + # limitations under the License. + + rm -f /etc/containerd/conf.d/dvcr.toml + ``` + +1. Примените манифест: + + ```bash + d8 k apply -f containerd-dvcr-remove-old-config.yaml + ``` + +1. Проверьте, что модуль `registry` запущен: + + ```bash + d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)' + ``` + + Пример вывода при успешном запуске: + + ```yaml + conditions: + # ... + - lastTransitionTime: "..." + message: "" + reason: "" + status: "True" + type: Ready + ``` + +1. Удалите манифест NGC: + + ```bash + d8 k delete -f containerd-dvcr-remove-old-config.yaml + ``` + +Подробнее о миграции см. в статье [Миграция container runtime на containerd v2](/products/virtualization-platform/documentation/admin/platform-management/platform-scaling/node/migrating.html). From 478499aa786053f32187035955d5d06b473beb78 Mon Sep 17 00:00:00 2001 From: Pavel Tishkov Date: Wed, 18 Feb 2026 12:59:25 +0300 Subject: [PATCH 2/6] docs: add network naming info Signed-off-by: Pavel Tishkov --- docs/USER_GUIDE.md | 46 ++++++++++++++++++++++++++++++++++++++++++- docs/USER_GUIDE.ru.md | 46 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 90 insertions(+), 2 deletions(-) diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 49b6c6dd64..15ce807ab4 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -271,7 +271,7 @@ The image status shows two sizes: - `UNPACKEDSIZE` (unpacked size) — the image size after unpacking. It is used when creating a disk from the image and defines the minimum disk size that can be created. {{< alert level="info" >}} -When creating a disk from an image, set the disk size to `UNPACKEDSIZE` or larger . +When creating a disk from an image, set the disk size to `UNPACKEDSIZE` or larger. If the size is not specified, the disk will be created with a size equal to `UNPACKEDSIZE`. {{< /alert >}} @@ -2257,6 +2257,46 @@ Use stable identifiers instead of `/dev/sdX`: In configuration files and scripts, use partition UUIDs or symlinks from `/dev/disk/by-*` instead of `/dev/sdX` names. +#### Network interface naming in guest OS + +In systems without predictable network interface naming support, network interface names (`eth0`, `eth1`, `eth2`, etc.) are assigned by the Linux kernel in the order devices are discovered during boot. When adding new network interfaces or changing the order of networks in `.spec.networks`, the interface order may change, which leads to IP addresses "shifting" to other interfaces. + +Using `ethX` in configuration files (for example, `/etc/network/interfaces`, `netplan`, `systemd-networkd`) or scripts may cause incorrect network behavior or connection to the wrong network when adding new interfaces or changing the network order. + +Modern distributions with systemd (Ubuntu 16.04+, Debian 9+, CentOS 7+, RHEL 7+) use predictable interface names (`enpXsY`, `ensX`, `enoX`) by default, which are based on the physical characteristics of the device (PCI coordinates) and remain stable between reboots and when adding new interfaces. + +However, even when using predictable names, it is recommended to bind network configuration to interface MAC addresses for guaranteed stability, especially when changing the order of networks in `.spec.networks` or adding new interfaces. + +**Example for systems without predictable naming:** + +Initially, the VM has two interfaces: + +```console +$ ip link show +1: lo: mtu 65536 +2: eth0: mtu 1500 +3: eth1: mtu 1500 +``` + +After adding a new interface at the beginning of the `.spec.networks` list and rebooting the VM: + +```console +$ ip link show +1: lo: mtu 65536 +2: eth0: mtu 1500 # New interface +3: eth1: mtu 1500 # Old eth0 +4: eth2: mtu 1500 # Old eth1 +``` + +MAC addresses remain unchanged, but interface names (`eth0`, `eth1`) shift, which can lead to IP addresses being assigned to the wrong interfaces. + +Use stable identifiers instead of `ethX`: + +- **`enpXsY`** — predictable names based on physical location (systemd networkd naming scheme, enabled by default in modern systems) +- **MAC address binding** — in `netplan`, `systemd-networkd`, or `/etc/network/interfaces` configuration (preferred for guaranteed stability) + +In configuration files and scripts, use stable interface names (`enpXsY`) or MAC address binding instead of `ethX` names. + ### Organizing interaction with virtual machines Virtual machines can be accessed directly via their fixed IP addresses. However, this approach has limitations: direct use of IP addresses requires manual management, complicates scaling, and makes the infrastructure less flexible. An alternative is services—a mechanism that abstracts access to VMs by providing logical entry points instead of binding to physical addresses. @@ -2933,6 +2973,10 @@ 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). +{{< alert level="info" >}} +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 >}} + Example of connecting a VM to the main cluster network and the project network `user-net`: ```yaml diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md index 3e199f8479..37c5d78c6d 100644 --- a/docs/USER_GUIDE.ru.md +++ b/docs/USER_GUIDE.ru.md @@ -274,7 +274,7 @@ weight: 50 - UNPACKEDSIZE (распакованный размер) — размер образа после распаковки. Он используется при создании диска из образа и задаёт минимальный размер диска, который можно создать. {{< alert level="info" >}} -При создании диска из образа укажите размер диска не меньше значения `UNPACKEDSIZE`. +При создании диска из образа укажите размер диска не меньше значения `UNPACKEDSIZE`. Если размер не задан, диск будет создан с размером, соответствующим распакованному размеру образа. {{< /alert >}} @@ -2279,6 +2279,46 @@ SCSI-адреса (`0:0:0:1`, `0:0:0:2`) остаются неизменными В конфигурационных файлах и скриптах используйте UUID разделов или символические ссылки из `/dev/disk/by-*` вместо имён `/dev/sdX`. +#### Именование сетевых интерфейсов в гостевой ОС + +В системах без поддержки предсказуемого именования интерфейсов (predictable network interface naming) имена сетевых интерфейсов (`eth0`, `eth1`, `eth2` и т. д.) присваиваются ядром Linux в порядке обнаружения устройств при загрузке. При добавлении новых сетевых интерфейсов или изменении порядка сетей в `.spec.networks` порядок интерфейсов может измениться, что приводит к "съезжанию" IP-адресов на другие интерфейсы. + +Если использовать `ethX` в конфигурационных файлах (например, `/etc/network/interfaces`, `netplan`, `systemd-networkd`) или скриптах, при добавлении новых интерфейсов или изменении порядка сетей можно получить некорректную работу сети или подключение к неверной сети. + +В современных дистрибутивах с systemd (Ubuntu 16.04+, Debian 9+, CentOS 7+, RHEL 7+) по умолчанию используются предсказуемые имена интерфейсов (`enpXsY`, `ensX`, `enoX`), которые основаны на физических характеристиках устройства (PCI координаты) и остаются стабильными между перезагрузками и при добавлении новых интерфейсов. + +Однако даже при использовании предсказуемых имён рекомендуется привязывать конфигурацию сети к MAC-адресам интерфейсов для гарантированной стабильности, особенно при изменении порядка сетей в `.spec.networks` или добавлении новых интерфейсов. + +Пример для систем без предсказуемого именования: + +Изначально ВМ имеет два интерфейса: + +```console +$ ip link show +1: lo: mtu 65536 +2: eth0: mtu 1500 +3: eth1: mtu 1500 +``` + +После добавления нового интерфейса в начало списка `.spec.networks` и перезагрузки ВМ: + +```console +$ ip link show +1: lo: mtu 65536 +2: eth0: mtu 1500 # Новый интерфейс +3: eth1: mtu 1500 # Старый eth0 +4: eth2: mtu 1500 # Старый eth1 +``` + +MAC-адреса остаются неизменными, но имена интерфейсов (`eth0`, `eth1`) сдвигаются, что может привести к назначению IP-адресов не тем интерфейсам. + +Используйте стабильные идентификаторы вместо `ethX`: + +- `enpXsY` — предсказуемые имена на основе физического расположения (systemd networkd naming scheme, включены по умолчанию в современных системах); +- привязка по MAC-адресу — в конфигурации `netplan`, `systemd-networkd` или `/etc/network/interfaces` (предпочтительно для гарантированной стабильности). + +В конфигурационных файлах и скриптах используйте стабильные имена интерфейсов (`enpXsY`) или привязку по MAC-адресу вместо имён `ethX`. + ### Организация взаимодействия с ВМ К виртуальным машинам можно обращаться напрямую по их фиксированным IP-адресам. Однако такой подход имеет ограничения: прямое использование IP-адресов требует ручного управления, усложняет масштабирование и делает инфраструктуру менее гибкой. Альтернативой служат сервисы — механизм, который абстрагирует доступ к ВМ, предоставляя логические точки входа вместо привязки к физическим адресам. @@ -2967,6 +3007,10 @@ EOF - политики сетевой безопасности (NetworkPolicy) не применяются к дополнительным сетевым интерфейсам; - параметры сети (IP-адреса, шлюзы, DNS и т.д.) для дополнительных сетей настраиваются вручную изнутри гостевой ОС (например, с помощью Cloud-Init). +{{< alert level="info" >}} +При настройке сетевых интерфейсов в гостевой ОС используйте стабильные идентификаторы (предсказуемые имена `enpXsY` или привязку по MAC-адресу) вместо имён `ethX`. Подробнее см. раздел [Именование сетевых интерфейсов в гостевой ОС](#именование-сетевых-интерфейсов-в-гостевой-ос). +{{< /alert >}} + Пример подключения ВМ к основной сети кластера и проектной сети `user-net`: ```yaml From 80e2254c6699b2e5a089389edb6b989c24b0332c Mon Sep 17 00:00:00 2001 From: Vladislav Panfilov Date: Wed, 18 Feb 2026 15:00:00 +0400 Subject: [PATCH 3/6] docs: fix indentation Signed-off-by: Vladislav Panfilov --- docs/FAQ.md | 60 +++++++++++++++++++++++++------------------------- docs/FAQ.ru.md | 58 ++++++++++++++++++++++++------------------------ 2 files changed, 59 insertions(+), 59 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 6aaeb0e6d4..54fcee5d56 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -826,47 +826,47 @@ After completing these steps, you will have a golden image that can be used to q ## 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. In that case, nodes still have the outdated config 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. +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. In that case, nodes still have the outdated config 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. To fix this, apply a NodeGroupConfiguration (NGC) manifest: it will remove the file on the nodes. After the `registry` module starts, remove the manifest, since this is a one-time fix. 1. Save the manifest to a file (for example, `containerd-dvcr-remove-old-config.yaml`): - ```yaml - apiVersion: deckhouse.io/v1alpha1 - kind: NodeGroupConfiguration - metadata: - name: containerd-dvcr-remove-old-config.sh - spec: - weight: 32 # Must be in range 32–90 - nodeGroups: ["*"] - bundles: ["*"] - content: | - # Copyright 2023 Flant JSC - # Licensed under the Apache License, Version 2.0 (the "License"); - # you may not use this file except in compliance with the License. - # You may obtain a copy of the License at - # http://www.apache.org/licenses/LICENSE-2.0 - # Unless required by applicable law or agreed to in writing, software - # distributed under the License is distributed on an "AS IS" BASIS, - # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - # See the License for the specific language governing permissions and - # limitations under the License. - - rm -f /etc/containerd/conf.d/dvcr.toml - ``` + ```yaml + apiVersion: deckhouse.io/v1alpha1 + kind: NodeGroupConfiguration + metadata: + name: containerd-dvcr-remove-old-config.sh + spec: + weight: 32 # Must be in range 32–90 + nodeGroups: ["*"] + bundles: ["*"] + content: | + # Copyright 2023 Flant JSC + # Licensed under the Apache License, Version 2.0 (the "License"); + # you may not use this file except in compliance with the License. + # You may obtain a copy of the License at + # http://www.apache.org/licenses/LICENSE-2.0 + # Unless required by applicable law or agreed to in writing, software + # distributed under the License is distributed on an "AS IS" BASIS, + # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + # See the License for the specific language governing permissions and + # limitations under the License. + + rm -f /etc/containerd/conf.d/dvcr.toml + ``` 1. Apply the manifest: - ```bash - d8 k apply -f containerd-dvcr-remove-old-config.yaml - ``` + ```bash + d8 k apply -f containerd-dvcr-remove-old-config.yaml + ``` 1. Verify that the `registry` module is running: - ```bash - d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)' - ``` + ```bash + d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)' + ``` Example output when the `registry` module is running: diff --git a/docs/FAQ.ru.md b/docs/FAQ.ru.md index eec7c3d402..e6818217b4 100644 --- a/docs/FAQ.ru.md +++ b/docs/FAQ.ru.md @@ -831,41 +831,41 @@ Golden image — это предварительно настроенный об 1. Сохраните манифест в файл (например, `containerd-dvcr-remove-old-config.yaml`): - ```yaml - apiVersion: deckhouse.io/v1alpha1 - kind: NodeGroupConfiguration - metadata: - name: containerd-dvcr-remove-old-config.sh - spec: - weight: 32 # Должен быть в диапазоне 32–90 - nodeGroups: ["*"] - bundles: ["*"] - content: | - # Copyright 2023 Flant JSC - # Licensed under the Apache License, Version 2.0 (the "License"); - # you may not use this file except in compliance with the License. - # You may obtain a copy of the License at - # http://www.apache.org/licenses/LICENSE-2.0 - # Unless required by applicable law or agreed to in writing, software - # distributed under the License is distributed on an "AS IS" BASIS, - # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - # See the License for the specific language governing permissions and - # limitations under the License. - - rm -f /etc/containerd/conf.d/dvcr.toml - ``` + ```yaml + apiVersion: deckhouse.io/v1alpha1 + kind: NodeGroupConfiguration + metadata: + name: containerd-dvcr-remove-old-config.sh + spec: + weight: 32 # Должен быть в диапазоне 32–90 + nodeGroups: ["*"] + bundles: ["*"] + content: | + # Copyright 2023 Flant JSC + # Licensed under the Apache License, Version 2.0 (the "License"); + # you may not use this file except in compliance with the License. + # You may obtain a copy of the License at + # http://www.apache.org/licenses/LICENSE-2.0 + # Unless required by applicable law or agreed to in writing, software + # distributed under the License is distributed on an "AS IS" BASIS, + # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + # See the License for the specific language governing permissions and + # limitations under the License. + + rm -f /etc/containerd/conf.d/dvcr.toml + ``` 1. Примените манифест: - ```bash - d8 k apply -f containerd-dvcr-remove-old-config.yaml - ``` + ```bash + d8 k apply -f containerd-dvcr-remove-old-config.yaml + ``` 1. Проверьте, что модуль `registry` запущен: - ```bash - d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)' - ``` + ```bash + d8 k -n d8-system -o yaml get secret registry-state | yq -C -P '.data | del .state | map_values(@base64d) | .conditions = (.conditions | from_yaml)' + ``` Пример вывода при успешном запуске: From e9f1153598b017c977f949599ad7acb236e86b67 Mon Sep 17 00:00:00 2001 From: Pavel Tishkov Date: Wed, 18 Feb 2026 20:17:44 +0300 Subject: [PATCH 4/6] docs: add cloud init network configure examples Signed-off-by: Pavel Tishkov --- docs/FAQ.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/FAQ.ru.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 176 insertions(+), 2 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 54fcee5d56..d65061ffd8 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -439,6 +439,94 @@ mounts: - ["/dev/sdb1", "/mnt/data", "ext4", "defaults", "0", "2"] ``` +### Configuring network interfaces for additional networks + +{{< alert level="warning" >}} +The settings described in this section apply only to additional networks. The main network (Main) is configured automatically via cloud-init and does not require manual configuration. +{{< /alert >}} + +If additional networks are connected to a virtual machine, they must be configured manually via cloud-init. Use `write_files` to create configuration files and `runcmd` to apply the settings. + +#### For systemd-networkd + +```yaml +#cloud-config +write_files: + - path: /etc/systemd/network/10-eth1.network + content: | + [Match] + Name=eth1 + + [Network] + Address=192.168.1.10/24 + Gateway=192.168.1.1 + DNS=8.8.8.8 + +runcmd: + - systemctl restart systemd-networkd +``` + +#### For Netplan (Ubuntu) + +```yaml +#cloud-config +write_files: + - path: /etc/netplan/99-custom.yaml + content: | + network: + version: 2 + ethernets: + eth1: + addresses: + - 10.0.0.5/24 + gateway4: 10.0.0.1 + nameservers: + addresses: [8.8.8.8] + eth2: + dhcp4: true + +runcmd: + - netplan apply +``` + +#### For ifcfg (RHEL/CentOS) + +```yaml +#cloud-config +write_files: + - path: /etc/sysconfig/network-scripts/ifcfg-eth1 + content: | + DEVICE=eth1 + BOOTPROTO=none + ONBOOT=yes + IPADDR=192.168.1.10 + PREFIX=24 + GATEWAY=192.168.1.1 + DNS1=8.8.8.8 + +runcmd: + - nmcli connection reload + - nmcli connection up eth1 +``` + +#### For Alpine Linux + +```yaml +#cloud-config +write_files: + - path: /etc/network/interfaces + append: true + content: | + auto eth1 + iface eth1 inet static + address 192.168.1.10 + netmask 255.255.255.0 + gateway 192.168.1.1 + +runcmd: + - /etc/init.d/networking restart +``` + ## How to use Ansible to provision virtual machines? [Ansible](https://docs.ansible.com/ansible/latest/index.html) is an automation tool that helps you to run tasks on remote servers via SSH. In this example, we will show you how to use Ansible to manage virtual machines in a demo-app project. diff --git a/docs/FAQ.ru.md b/docs/FAQ.ru.md index e6818217b4..c905ad7bd4 100644 --- a/docs/FAQ.ru.md +++ b/docs/FAQ.ru.md @@ -436,6 +436,92 @@ mounts: - ["/dev/sdb1", "/mnt/data", "ext4", "defaults", "0", "2"] ``` +### Настройка сетевых интерфейсов для дополнительных сетей + +{{< alert level="warning" >}} +Настройки, описанные в этом разделе, применяются только для дополнительных сетей. Основная сеть (Main) настраивается автоматически через cloud-init и не требует ручной конфигурации. +{{< /alert >}} + +#### Для systemd-networkd + +```yaml +#cloud-config +write_files: + - path: /etc/systemd/network/10-eth1.network + content: | + [Match] + Name=eth1 + + [Network] + Address=192.168.1.10/24 + Gateway=192.168.1.1 + DNS=8.8.8.8 + +runcmd: + - systemctl restart systemd-networkd +``` + +#### Для Netplan (Ubuntu) + +```yaml +#cloud-config +write_files: + - path: /etc/netplan/99-custom.yaml + content: | + network: + version: 2 + ethernets: + eth1: + addresses: + - 10.0.0.5/24 + gateway4: 10.0.0.1 + nameservers: + addresses: [8.8.8.8] + eth2: + dhcp4: true + +runcmd: + - netplan apply +``` + +#### Для ifcfg (RHEL/CentOS) + +```yaml +#cloud-config +write_files: + - path: /etc/sysconfig/network-scripts/ifcfg-eth1 + content: | + DEVICE=eth1 + BOOTPROTO=none + ONBOOT=yes + IPADDR=192.168.1.10 + PREFIX=24 + GATEWAY=192.168.1.1 + DNS1=8.8.8.8 + +runcmd: + - nmcli connection reload + - nmcli connection up eth1 +``` + +#### Для Alpine Linux + +```yaml +#cloud-config +write_files: + - path: /etc/network/interfaces + append: true + content: | + auto eth1 + iface eth1 inet static + address 192.168.1.10 + netmask 255.255.255.0 + gateway 192.168.1.1 + +runcmd: + - /etc/init.d/networking restart +``` + ## Как использовать Ansible для конфигурирования виртуальных машин? [Ansible](https://docs.ansible.com/ansible/latest/index.html) — это инструмент автоматизации, который позволяет выполнять задачи на удаленных серверах с использованием протокола SSH. В данном примере мы рассмотрим, как использовать Ansible для управления виртуальными машинами расположенных в проекте demo-app. @@ -490,7 +576,7 @@ ansible -m shell -a "uptime" \ {{< /alert >}} {{< alert level="warning" >}} -Команда работает только для виртуальных машин, у которых подключена основная сеть кластера (Main). +Команда работает только для виртуальных машин, у которых подключена основная сеть кластера (Main). {{< /alert >}} Вместо ручного создания inventory-файла можно использовать команду `d8 v ansible-inventory`, которая автоматически генерирует инвентарь Ansible из виртуальных машин в указанном неймспейсе. Команда совместима с интерфейсом [ansible inventory script](https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html#inventory-scripts). @@ -500,7 +586,7 @@ ansible -m shell -a "uptime" \ При необходимости настройте переменные хоста через аннотации (например, пользователя для SSH): ```bash -d8 k -n demo-app annotate vm frontend provisioning.virtualization.deckhouse.io/ansible_user="cloud" +d8 k -n demo-app annotate vm frontend provisioning.virtualization.deckhouse.io/ansible_user="cloud" ``` Используйте команду напрямую: From 33510e313c035fd76078bf82542c4010deb9b00d Mon Sep 17 00:00:00 2001 From: Pavel Tishkov Date: Wed, 18 Feb 2026 20:50:31 +0300 Subject: [PATCH 5/6] docs: add cloud init specificities Signed-off-by: Pavel Tishkov --- docs/FAQ.md | 4 ++++ docs/FAQ.ru.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index d65061ffd8..f3c63acef5 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -356,6 +356,10 @@ spec: Cloud-Init is a tool for automatically configuring virtual machines on first boot. The configuration is written in YAML format and must start with the `#cloud-config` header. +{{< alert level="warning" >}} +When using cloud images (for example, official images from distributions), you must provide a cloud-init configuration. Without it, on some distributions, network connectivity is not configured, and the virtual machine becomes unavailable on the network, even if the main network (Main) is connected. In addition, cloud images do not allow login by default — you must either add SSH keys for the default user or create a new user with SSH access. Without this, it will be impossible to access the virtual machine. +{{< /alert >}} + ### Updating and installing packages Example configuration for updating the system and installing packages: diff --git a/docs/FAQ.ru.md b/docs/FAQ.ru.md index c905ad7bd4..ced36a6c92 100644 --- a/docs/FAQ.ru.md +++ b/docs/FAQ.ru.md @@ -353,6 +353,10 @@ spec: Cloud-Init — это инструмент для автоматической настройки виртуальных машин при первом запуске. Конфигурация записывается в формате YAML и должна начинаться с заголовка `#cloud-config`. +{{< alert level="warning" >}} +При использовании cloud-образов (например, официальных образов от дистрибутивов) необходимо обязательно предоставить конфигурацию cloud-init. Без неё на некоторых дистрибутивах не настраивается сетевое подключение, и виртуальная машина становится недоступна в сети, даже если подключена основная сеть (Main). Кроме того, в cloud-образах по умолчанию отсутствует возможность входа в систему — необходимо либо добавить SSH-ключи для пользователя по умолчанию, либо создать нового пользователя с SSH-доступом. Без этого войти в виртуальную машину будет невозможно. +{{< /alert >}} + ### Обновление и установка пакетов Пример конфигурации для обновления системы и установки пакетов: From 9b0a516421144a289af22fd0a8e29aa02fa07722 Mon Sep 17 00:00:00 2001 From: Pavel Tishkov Date: Wed, 18 Feb 2026 20:55:48 +0300 Subject: [PATCH 6/6] docs: add links Signed-off-by: Pavel Tishkov --- docs/FAQ.md | 2 ++ docs/FAQ.ru.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/FAQ.md b/docs/FAQ.md index f3c63acef5..6c03401b0b 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -445,6 +445,8 @@ mounts: ### Configuring network interfaces for additional networks +For more information on connecting additional networks to a virtual machine, see the [Additional network interfaces](./user_guide.html#additional-network-interfaces) section. + {{< alert level="warning" >}} The settings described in this section apply only to additional networks. The main network (Main) is configured automatically via cloud-init and does not require manual configuration. {{< /alert >}} diff --git a/docs/FAQ.ru.md b/docs/FAQ.ru.md index ced36a6c92..8f40230074 100644 --- a/docs/FAQ.ru.md +++ b/docs/FAQ.ru.md @@ -442,6 +442,8 @@ mounts: ### Настройка сетевых интерфейсов для дополнительных сетей +Подробнее о подключении дополнительных сетей к виртуальной машине см. в разделе [Дополнительные сетевые интерфейсы](./user_guide.html#дополнительные-сетевые-интерфейсы). + {{< alert level="warning" >}} Настройки, описанные в этом разделе, применяются только для дополнительных сетей. Основная сеть (Main) настраивается автоматически через cloud-init и не требует ручной конфигурации. {{< /alert >}}