Skip to content

Commit cadf4aa

Browse files
slashburyginslashburygin
committed
docs: add virt-manager realm setup guide
1 parent 059c96c commit cadf4aa

3 files changed

Lines changed: 230 additions & 0 deletions

File tree

‎docs/realms/realm-virt-manager.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Running Exordos Realm with virt-manager
2+
3+
> **Console-access note:** The production realm-node artifact is intended to
4+
> be configured by a parent realm and does **not** provide console access. To
5+
> operate a standalone developer stand, use image exordos-realm-dev.raw.zst.
6+
7+
## Create and run the VM
8+
9+
These commands download the dev image, expand it, and create an
10+
importable disk. Run them on an Ubuntu/Debian KVM host:
11+
12+
```bash
13+
sudo apt update
14+
sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients virt-manager zstd
15+
sudo usermod -aG libvirt,kvm "$USER"
16+
# Log out and back in once for the new group membership to take effect.
17+
18+
cd /var/lib/libvirt/images/
19+
sudo wget -O exordos-realm-dev.raw.zst \
20+
https://repo.exordos.com/exordos-elements/exordos-realm/latest/images/exordos-realm-dev.raw.zst
21+
sudo zstd --decompress --keep exordos-realm-dev.raw.zst
22+
sudo chown libvirt-qemu:kvm exordos-realm-dev.raw
23+
sudo qemu-img info exordos-realm-dev.raw
24+
```
25+
26+
The host must expose nested KVM to the guest because the realm node runs a
27+
nested core VM. Check the relevant value before creating the VM:
28+
29+
```bash
30+
# Intel hosts
31+
cat /sys/module/kvm_intel/parameters/nested
32+
# AMD hosts
33+
cat /sys/module/kvm_amd/parameters/nested
34+
```
35+
36+
It must print `Y` (or `1`). Enable nested virtualization on the host before
37+
continuing if it does not.
38+
39+
Start virt-manager and select the system libvirt connection:
40+
41+
```bash
42+
virt-manager --connect qemu:///system
43+
```
44+
45+
In the GUI, select **File → New Virtual Machine**, then configure:
46+
47+
1. Select **Import existing disk image**.
48+
2. Select `/var/lib/libvirt/images/exordos-realm-dev.raw`; choose a recent Ubuntu OS
49+
type (for example, Ubuntu 24.04) if virt-manager asks.
50+
3. Allocate at least **4 vCPUs** and **8192 MiB RAM**; use more resources if the nested core workload requires it.
51+
4. Keep the default NAT network or choose a bridged network appropriate for
52+
the host.
53+
5. Tick **Customize configuration before install**. In **CPUs**, select
54+
**Copy host CPU configuration** / host-passthrough so KVM virtualization
55+
extensions are visible to the guest. Ensure the disk uses the `raw` format
56+
and virtio bus, then click **Begin Installation**.
57+
58+
The following fully command-line import is equivalent and registers the VM so
59+
it can be opened and managed with virt-manager:
60+
61+
```bash
62+
virt-install --connect qemu:///system \
63+
--name exordos-realm \
64+
--memory 8192 \
65+
--vcpus 4 \
66+
--cpu host-passthrough \
67+
--disk path=/var/lib/libvirt/images/exordos-realm-dev.raw,format=raw,bus=virtio \
68+
--network network=default,model=virtio \
69+
--os-variant ubuntu24.04 \
70+
--graphics spice \
71+
--video virtio \
72+
--import --noautoconsole
73+
74+
# Open the VM's graphical console in virt-manager.
75+
virt-manager --connect qemu:///system --show-domain-console exordos-realm
76+
```
77+
78+
## Test the VM
79+
80+
After starting it, confirm that libvirt reports it as running and that KVM is
81+
available inside the realm node:
82+
83+
```bash
84+
virsh --connect qemu:///system list --all
85+
virsh --connect qemu:///system dominfo exordos-realm
86+
87+
# Run this in the guest console (a DEV_ACCESS image is required to log in).
88+
kvm-ok
89+
```
90+
91+
`virsh` should show `exordos-realm` as `running`; `kvm-ok` should report that
92+
KVM acceleration can be used. For a DEV_ACCESS image, log in as
93+
`ubuntu:ubuntu`.
94+
The production image will wait for `/etc/exordos/realm_spec.json` from its
95+
parent realm rather than offering standalone console access.
96+
97+
## Developer stand
98+
99+
Simulate the managed flow by writing `/etc/exordos/realm_spec.json`
100+
yourself (see the contract in exordos_ecosystem `docs/realm-manager.md`, or you can copy example spec
101+
by `cp /etc/exordos/realm_spec.json.example /etc/exordos/realm_spec.json`) —
102+
the first-boot unit picks it up.
103+
104+
Key names deliberately match the `spec.json` keys consumed by
105+
`exordos_core/cmd/bootstrap.py` / `exordos_core/bootstrap/defaults.py`
106+
(`realm_uuid`, `realm_secret`, `realm_tokens`, `ecosystem_endpoint`,
107+
`admin_password`, `disable_telemetry`), so the image's first-boot script can
108+
merge this file into its baked spec template with minimal mapping.
109+
110+
Next you can see logs of bootstrap service by `sudo journalctl -u exordos-realm-bootstrap`.
111+
112+
And after some time you can see work stand by `exordos e e l.`

‎docs/realms/realm-virt-manager.ru.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Запуск Realm Exordos с virt-manager
2+
3+
> **Примечание о консольном доступе:** Артефакт production realm-node
4+
> предназначен для настройки родительским realm и **не** предоставляет
5+
> консольного доступа. Для работы автономного стенда разработчика
6+
> используйте образ exordos-realm-dev.raw.zst.
7+
8+
## Создание и запуск ВМ
9+
10+
Эти команды загружают dev-образ, распаковывают его и создают диск для
11+
импорта. Выполняйте их на KVM-хосте с Ubuntu/Debian:
12+
13+
```bash
14+
sudo apt update
15+
sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients virt-manager zstd
16+
sudo usermod -aG libvirt,kvm "$USER"
17+
# Выйдите из системы и зайдите снова, чтобы применить новую группу.
18+
19+
cd /var/lib/libvirt/images/
20+
sudo wget -O exordos-realm-dev.raw.zst \
21+
https://repo.exordos.com/exordos-elements/exordos-realm/latest/images/exordos-realm-dev.raw.zst
22+
sudo zstd --decompress --keep exordos-realm-dev.raw.zst
23+
sudo chown libvirt-qemu:kvm exordos-realm-dev.raw
24+
sudo qemu-img info exordos-realm-dev.raw
25+
```
26+
27+
Хост должен предоставлять вложенный KVM (nested KVM) гостевой системе,
28+
поскольку realm node запускает вложенную core VM. Проверьте соответствующее
29+
значение перед созданием ВМ:
30+
31+
```bash
32+
# Хосты Intel
33+
cat /sys/module/kvm_intel/parameters/nested
34+
# Хосты AMD
35+
cat /sys/module/kvm_amd/parameters/nested
36+
```
37+
38+
Значение должно быть `Y` (или `1`). Если это не так, включите вложенную
39+
виртуализацию на хосте прежде чем продолжать.
40+
41+
Запустите virt-manager и выберите системное подключение libvirt:
42+
43+
```bash
44+
virt-manager --connect qemu:///system
45+
```
46+
47+
В графическом интерфейсе выберите **Файл → Новая виртуальная машина**, затем
48+
настройте:
49+
50+
1. Выберите **Импортировать существующий образ диска**.
51+
2. Укажите `/var/lib/libvirt/images/exordos-realm-dev.raw`; выберите
52+
подходящий тип ОС Ubuntu (например, Ubuntu 24.04), если virt-manager
53+
запросит.
54+
3. Выделите не менее **4 vCPU** и **8192 MiB ОЗУ**; увеличьте ресурсы, если
55+
этого требует вложенная core-нагрузка.
56+
4. Оставьте сеть NAT по умолчанию или выберите мостовую сеть, подходящую
57+
для хоста.
58+
5. Отметьте **Настроить конфигурацию перед установкой**. В разделе **CPU**
59+
выберите **Копировать конфигурацию CPU хоста** / host-passthrough, чтобы
60+
расширения виртуализации KVM были доступны гостю. Убедитесь, что диск
61+
использует формат `raw` и шину virtio, затем нажмите **Начать установку**.
62+
63+
Полностью командная строка ниже эквивалентна и регистрирует ВМ так, чтобы её
64+
можно было открыть и управлять ей через virt-manager:
65+
66+
```bash
67+
virt-install --connect qemu:///system \
68+
--name exordos-realm \
69+
--memory 8192 \
70+
--vcpus 4 \
71+
--cpu host-passthrough \
72+
--disk path=/var/lib/libvirt/images/exordos-realm-dev.raw,format=raw,bus=virtio \
73+
--network network=default,model=virtio \
74+
--os-variant ubuntu24.04 \
75+
--graphics spice \
76+
--video virtio \
77+
--import --noautoconsole
78+
79+
# Откройте графическую консоль ВМ в virt-manager.
80+
virt-manager --connect qemu:///system --show-domain-console exordos-realm
81+
```
82+
83+
## Проверка ВМ
84+
85+
После запуска убедитесь, что libvirt сообщает о работе ВМ и что KVM доступен
86+
внутри realm node:
87+
88+
```bash
89+
virsh --connect qemu:///system list --all
90+
virsh --connect qemu:///system dominfo exordos-realm
91+
92+
# Выполните в гостевой консоли (для входа требуется образ DEV_ACCESS).
93+
kvm-ok
94+
```
95+
96+
`virsh` должен показать `exordos-realm` в статусе `running`; `kvm-ok` должен
97+
сообщить, что ускорение KVM может быть использовано. Для образа DEV_ACCESS
98+
войдите как `ubuntu:ubuntu`.
99+
Production-образ будет ожидать `/etc/exordos/realm_spec.json` от своего
100+
родительского realm.
101+
102+
## Стенд разработчика
103+
104+
Смоделируйте создание стенда, написав `/etc/exordos/realm_spec.json`
105+
самостоятельно (смотрите контракт в exordos_ecosystem `docs/realm-manager.md`, или вы можете скопировать пример спецификации
106+
с помощью `cp /etc/exordos/realm_spec.json.example /etc/exordos/realm_spec.json`) —
107+
модуль первой загрузки распознает его.
108+
109+
Имена ключей намеренно совпадают с ключами `spec.json`, используемыми
110+
`exordos_core/cmd/bootstrap.py` / `exordos_core/bootstrap/defaults.py`
111+
(`realm_uuid`, `realm_secret`, `realm_tokens`, `ecosystem_endpoint`,
112+
`admin_password`, `disable_telemetry`), чтобы скрипт первой загрузки образа мог
113+
объедините этот файл с его готовым шаблоном спецификации с минимальным сопоставлением.
114+
115+
Далее вы можете просмотреть логи службы bootstrap с помощью `sudo journalctl -u exordos-realm-bootstrap`.
116+
117+
И через некоторое время вы можете увидеть рабочий стенд, выполнив команду "exordos e e l`.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,3 +165,4 @@ nav:
165165
- Secrets:
166166
- Certificates: secret/certificates.md
167167
- Passwords: secret/passwords.md
168+
- Realms: realms/realm-virt-manager.md

0 commit comments

Comments
 (0)