# Экспериментальные VM

Создание локальных кластеров VM на вашей рабочей станции для разработки и тестирования, без внешних облачных провайдеров.

## Требования

`rdc ops` требует **локального адаптера**. Недоступен с облачным адаптером.

```bash
rdc ops check
```

## Обзор

Команды `rdc ops` позволяют создавать и управлять экспериментальными кластерами VM локально. Это та же инфраструктура, которая используется в конвейере CI для интеграционных тестов, и теперь она доступна для практических экспериментов.

Сценарии использования:
- Тестирование развёртываний Rediacc без внешних провайдеров VM (Linode, Vultr и т.д.)
- Разработка и отладка конфигураций репозиториев локально
- Изучение платформы в полностью изолированной среде
- Запуск интеграционных тестов на рабочей станции

## Поддержка платформ

| Платформа | Архитектура | Бэкенд | Статус |
|-----------|-------------|---------|--------|
| Linux | x86_64 | KVM (libvirt) | Протестировано в CI |
| macOS | Intel | QEMU + HVF | Протестировано в CI |
| Linux | ARM64 | KVM (libvirt) | Поддерживается (не тестировалось в CI) |
| macOS | ARM (Apple Silicon) | QEMU + HVF | Поддерживается (не тестировалось в CI) |
| Windows | x86_64 / ARM64 | Hyper-V | Планируется |

**Linux (KVM)** использует libvirt для нативной аппаратной виртуализации с мостовой сетью.

**macOS (QEMU)** использует QEMU с Apple Hypervisor Framework (HVF) для производительности, близкой к нативной, с пользовательской сетью и проброской портов SSH.

**Windows (Hyper-V)**, поддержка планируется. Подробности см. в [issue #380](https://github.com/rediacc/console/issues/380). Требуется Windows Pro/Enterprise.

## Предварительные требования и настройка

### Linux

```bash
# Install prerequisites automatically
rdc ops setup

# Or manually:
sudo apt install libvirt-daemon-system virtinst qemu-utils cloud-image-utils docker.io
sudo systemctl enable --now libvirtd
```

### macOS

```bash
# Install prerequisites automatically
rdc ops setup

# Or manually:
brew install qemu cdrtools
```

### Проверка настройки

```bash
rdc ops check
```

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

## Быстрый старт

```bash
# 1. Check prerequisites
rdc ops check

# 2. Provision a minimal cluster (bridge + 1 worker)
rdc ops up --basic

# 3. Check VM status
rdc ops status

# 4. SSH into the bridge VM
rdc ops ssh --vm-id 1

# 4b. Or run a command directly
rdc ops ssh --vm-id 1 -c hostname

# 5. Tear down
rdc ops down
```

## Состав кластера

По умолчанию `rdc ops up` создаёт:

| VM | ID | Роль |
|----|-----|------|
| Bridge | 1 | Основной узел, запускает службу моста Rediacc |
| Worker 1 | 11 | Рабочий узел для развёртывания репозиториев |
| Worker 2 | 12 | Рабочий узел для развёртывания репозиториев |

Используйте флаг `--basic` для создания только моста и первого рабочего узла (ID 1 и 11).

Используйте `--skip-orchestration` для создания VM без запуска служб Rediacc, полезно для тестирования уровня VM в изоляции.

## Конфигурация

Мост VM использует меньшие значения по умолчанию, чем рабочие VM:

| Роль VM | CPU | RAM | Диск |
|---------|------|-----|------|
| Bridge | 1 | 1024 МБ | 8 ГБ |
| Worker | 2 | 4096 МБ | 16 ГБ |

Переменные окружения переопределяют ресурсы рабочих VM:

| Переменная | По умолчанию | Описание |
|------------|--------------|----------|
| `VM_CPU` | 2 | Количество ядер CPU на VM |
| `VM_RAM` | 4096 | Объём RAM в МБ на VM |
| `VM_DSK` | 16 | Размер диска в ГБ |
| `VM_NET_BASE` | 192.168.111 | Базовый адрес сети (только KVM) |
| `RENET_DATA_DIR` | ~/.renet | Каталог данных для дисков и конфигурации VM |

## Справочник по командам

| Команда | Описание |
|---------|----------|
| `rdc ops setup` | Установка предварительных требований платформы (KVM или QEMU) |
| `rdc ops check` | Проверка установки и работоспособности требований |
| `rdc ops up [options]` | Создание кластера VM |
| `rdc ops down` | Уничтожение всех VM и очистка |
| `rdc ops status` | Отображение статуса всех VM |
| `rdc ops ssh <vm-id> [command...]` | SSH-подключение к VM или выполнение команды на ней |

### Параметры `rdc ops up`

| Параметр | Описание |
|----------|----------|
| `--basic` | Минимальный кластер (мост + 1 рабочий узел) |
| `--lite` | Пропустить создание VM (только SSH-ключи) |
| `--force` | Принудительное пересоздание существующих VM |
| `--parallel` | Параллельное создание VM |
| `--skip-orchestration` | Только VM, без служб Rediacc |
| `--backend <kvm\|qemu>` | Принудительный выбор бэкенда вместо автоопределения |
| `--os <name>` | Образ ОС (по умолчанию: ubuntu-24.04) |
| `--debug` | Подробный вывод |

## Различия между платформами

### Linux (KVM)
- Использует libvirt для управления жизненным циклом VM
- Мостовая сеть, VM получают IP-адреса в виртуальной сети (192.168.111.x)
- Прямое SSH-подключение к IP-адресам VM
- Требуется `/dev/kvm` и служба libvirtd

### macOS (QEMU + HVF)
- Использует процессы QEMU, управляемые через PID-файлы
- Пользовательская сеть с проброской портов SSH (localhost:222XX)
- SSH через проброшенные порты, а не напрямую по IP
- ISO-образы cloud-init создаются через `mkisofs`

## Устранение неполадок

### Режим отладки

Добавьте `--debug` к любой команде для подробного вывода:

```bash
rdc ops up --basic --debug
```

### Распространённые проблемы

**KVM недоступен (Linux)**
- Проверьте наличие `/dev/kvm`: `ls -la /dev/kvm`
- Включите виртуализацию в BIOS/UEFI
- Загрузите модуль ядра: `sudo modprobe kvm_intel` или `sudo modprobe kvm_amd`

**libvirtd не запущен (Linux)**
```bash
sudo systemctl enable --now libvirtd
```

**QEMU не найден (macOS)**
```bash
brew install qemu cdrtools
```

**VM не запускаются**
- Проверьте свободное место в `~/.renet/disks/`
- Запустите `rdc ops check` для проверки всех требований
- Попробуйте `rdc ops down`, затем `rdc ops up --force`