repo init

2026-08-21 07:34:45 +03:00
commit 7e44db87b2
@@ -0,0 +1,275 @@
+# Подготовка стенда и первичная инициализация
+
+Документ описывает, как собрать компоненты, подготовить конфигурацию и
+запустить стенд с нуля — от чистой машины до работающего control-api,
+валидаторов и проберов. Если нужно просто быстро посмотреть систему в
+работе без реального OpenStack — сразу переходите к разделу
+[«Быстрая проверка без OpenStack»](#быстрая-проверка-без-openstack-offline-режим).
+
+## Содержание
+
+- [Компоненты и роли машин](#компоненты-и-роли-машин)
+- [Требования](#требования)
+- [Сборка бинарников](#сборка-бинарников)
+- [Быстрая проверка без OpenStack (offline-режим)](#быстрая-проверка-без-openstack-offline-режим)
+- [Подготовка конфигурации для реального стенда](#подготовка-конфигурации-для-реального-стенда)
+- [Развёртывание control-api](#развёртывание-control-api)
+- [Развёртывание validator-agent на ВМ-валидаторах](#развёртывание-validator-agent-на-вм-валидаторах)
+- [Развёртывание prober на внешних площадках](#развёртывание-prober-на-внешних-площадках)
+- [Проверка после запуска](#проверка-после-запуска)
+- [Сетевые доступы](#сетевые-доступы)
+
+## Компоненты и роли машин
+
+| Компонент | Где запускается | Кол-во |
+|---|---|---|
+| `control-api` | Отдельная управляющая машина/ВМ с доступом к OpenStack API | 1 (без HA) |
+| `validator-agent` | Каждая ВМ-валидатор в сервисном проекте облака | по числу валидаторов |
+| `prober` | По одному на каждой из внешних тестовых площадок | 3 (по числу площадок) |
+
+`control-api` — единственный компонент с состоянием (SQLite). Валидаторы и
+проберы не хранят локального состояния и полностью управляются через опрос
+control-api (см. [API.md](API.md)).
+
+## Требования
+
+- **Go 1.22+** для сборки (проверено на Go 1.26). Собранные бинарники —
+  статические, дополнительных зависимостей на целевых машинах не требуют
+  (используется чистый Go-драйвер SQLite, без cgo).
+- Для `control-api` в боевом режиме (`openstack.mode: real`) — учётная
+  запись OpenStack с правами на чтение/изменение floating IP (Neutron)
+  в сервисном проекте, и заранее выделенные (allocated) floating IP —
+  инструмент их **не создаёт**, только привязывает/отвязывает
+  существующие.
+- Для `validator-agent` и `prober` — возможность отправлять ICMP echo
+  (нужен root либо capability `CAP_NET_RAW`, см. юниты systemd).
+- `curl`, `sqlite3` (опционально, для ручной инспекции БД) на машине с
+  control-api пригодятся для диагностики.
+
+## Сборка бинарников
+
+Из корня репозитория:
+
+```bash
+export PATH=$PATH:/usr/local/go/bin   # если go не в PATH
+go build -o bin/control-api     ./cmd/control-api
+go build -o bin/validator-agent ./cmd/validator-agent
+go build -o bin/prober          ./cmd/prober
+```
+
+Каждый бинарник самодостаточен — скопируйте нужный файл на
+соответствующую машину (control-api → управляющая машина, validator-agent
+→ каждый валидатор, prober → каждая площадка).
+
+Убедиться, что всё собирается и юнит-тесты проходят:
+
+```bash
+go build ./... && go test ./...
+```
+
+## Быстрая проверка без OpenStack (offline-режим)
+
+Прежде чем разворачивать реальный стенд, рекомендуется убедиться, что всё
+собирается и работает корректно на локальной машине — без облака и
+внешних площадок:
+
+```bash
+scripts/run-local-e2e.sh
+```
+
+Скрипт сам поднимает control-api (в режиме `openstack.mode: mock`),
+одного validator-agent и трёх проберов как локальные процессы, прогоняет
+один тестовый адрес через полный цикл проверки и печатает итоговый
+результат. Подробности — в [docs/LOCAL_E2E.md](LOCAL_E2E.md). Это же
+хороший способ разобраться в поведении системы перед первым боевым
+запуском.
+
+## Подготовка конфигурации для реального стенда
+
+Все три компонента конфигурируются YAML-файлами. Шаблоны лежат в
+`configs/*.example.yaml` — скопируйте их и заполните под ваш стенд.
+
+### 1. `control-api.yaml`
+
+```bash
+cp configs/control-api.example.yaml /etc/cloud-ip-validator/control-api.yaml
+```
+
+Что обязательно нужно заполнить:
+
+- **`validators`** — список валидаторов, у каждого `validator_id`
+  (произвольное имя, должно совпадать с `validator_id` в конфиге
+  соответствующего `validator-agent`) и `os_port_id` — **ID Neutron-порта**
+  основного сетевого интерфейса ВМ-валидатора (узнать: `openstack port
+  list --server <имя-ВМ>` или в веб-консоли облака).
+- **`sites`** — три внешние площадки, `site_id` + `index` (1, 2 или 3).
+  `site_id` должен совпадать с `site_id` в конфиге соответствующего
+  `prober`.
+- **`ip_addresses`** — список публичных IPv4-адресов на проверку, **в
+  порядке обработки**. Адреса должны существовать в сервисном проекте как
+  уже выделенные (allocated) floating IP — инструмент их не создаёт.
+- **`openstack.mode: "real"`** и `*_env` поля — имена переменных
+  окружения, из которых будут прочитаны реальные учётные данные (сами
+  значения в этот файл **не пишутся**, см. следующий пункт).
+- **`targets`** и **`check_types`** — при необходимости смените набор
+  целей для egress-проверок (по умолчанию — hub.docker.com, github.com,
+  packages.ubuntu.com) или включите `ssh` (по умолчанию выключен).
+
+### 2. Переменные окружения для OpenStack
+
+Учётные данные передаются **только** через переменные окружения — никогда
+через YAML. Создайте файл (доступный на чтение только сервисному
+пользователю):
+
+```bash
+install -m 0600 -o cloud-ip-validator -g cloud-ip-validator /dev/null /etc/cloud-ip-validator/control-api.env
+cat >> /etc/cloud-ip-validator/control-api.env <<'EOF'
+OS_AUTH_URL=https://keystone.example.com:5000/v3
+OS_TOKEN=<токен администратора с правами на управление floating IP>
+OS_PROJECT_ID=<id сервисного проекта>
+OS_REGION_NAME=<регион>
+EOF
+```
+
+Имена переменных должны совпадать с тем, что указано в
+`control-api.yaml` в секции `openstack` (`auth_url_env`, `token_env` и
+т.д.) — в шаблоне это ровно `OS_AUTH_URL`, `OS_TOKEN`, `OS_PROJECT_ID`,
+`OS_PROJECT_NAME`, `OS_PROJECT_DOMAIN_NAME`, `OS_REGION_NAME`.
+
+### 3. `validator-agent.yaml` (свой на каждом валидаторе)
+
+```bash
+cp configs/validator-agent.example.yaml /etc/cloud-ip-validator/validator-agent.yaml
+```
+
+Обязательно поменять:
+- `validator_id` — должен совпадать с одним из `validators[].validator_id`
+  в конфиге control-api.
+- `control_api_url` — адрес, по которому эта ВМ достучится до control-api.
+
+### 4. `prober.yaml` (свой на каждой площадке)
+
+```bash
+cp configs/prober.example.yaml /etc/cloud-ip-validator/prober.yaml
+```
+
+Обязательно поменять:
+- `site_id` — должен совпадать с одним из `sites[].site_id` в конфиге
+  control-api (для трёх площадок — три разных файла с `site-1`,
+  `site-2`, `site-3` или как вы их назвали).
+- `control_api_url` — адрес control-api, доступный с площадки (обычно
+  через интернет — площадки внешние).
+
+## Развёртывание control-api
+
+```bash
+useradd --system --no-create-home --shell /usr/sbin/nologin cloud-ip-validator
+mkdir -p /var/lib/cloud-ip-validator /etc/cloud-ip-validator
+chown cloud-ip-validator:cloud-ip-validator /var/lib/cloud-ip-validator
+
+cp bin/control-api /usr/local/bin/control-api
+cp deploy/systemd/control-api.service /etc/systemd/system/
+
+systemctl daemon-reload
+systemctl enable --now control-api
+```
+
+**Первичная инициализация базы данных происходит автоматически** — при
+первом старте `control-api` создаёт файл SQLite по пути `database.path`
+из конфига (миграция схемы применяется один раз, повторные запуски —
+no-op). Отдельной команды "init db" не требуется.
+
+При каждом старте control-api также:
+1. Регистрирует в БД всех валидаторов из `validators` конфига (если их
+   там ещё нет).
+2. Добавляет в очередь все адреса из `ip_addresses`, которых там ещё нет
+   (уже обработанные ранее адреса повторно не добавляются и не
+   сбрасываются — см. [USAGE.md](USAGE.md#добавление-новых-ip-в-очередь)).
+
+Проверить, что процесс поднялся:
+
+```bash
+curl -s http://localhost:8080/healthz
+# {"ok":true}
+journalctl -u control-api -f
+```
+
+## Развёртывание validator-agent на ВМ-валидаторах
+
+Повторить на каждой ВМ-валидаторе:
+
+```bash
+cp bin/validator-agent /usr/local/bin/validator-agent
+cp deploy/systemd/validator-agent.service /etc/systemd/system/
+mkdir -p /etc/cloud-ip-validator
+# скопировать сюда заполненный validator-agent.yaml с уникальным validator_id
+
+systemctl daemon-reload
+systemctl enable --now validator-agent
+journalctl -u validator-agent -f
+```
+
+Юнит выдаёт процессу capability `CAP_NET_RAW` (без root) — она нужна для
+отправки ICMP echo в рамках проверок.
+
+## Развёртывание prober на внешних площадках
+
+Аналогично, на каждой из трёх площадок:
+
+```bash
+cp bin/prober /usr/local/bin/prober
+cp deploy/systemd/prober.service /etc/systemd/system/
+mkdir -p /etc/cloud-ip-validator
+# скопировать сюда prober.yaml с уникальным site_id для этой площадки
+
+systemctl daemon-reload
+systemctl enable --now prober
+journalctl -u prober -f
+```
+
+## Проверка после запуска
+
+После того как control-api, все валидаторы и все три пробера запущены:
+
+```bash
+curl -s http://<control-api>:8080/api/v1/admin/status | python3 -m json.tool
+```
+
+Ожидаемая картина сразу после старта: часть адресов в состоянии `queued`,
+часть уже переходит в `assigning_fip`/`awaiting_self_check`/`checking` по
+мере того, как освобождаются валидаторы. Через некоторое время появляются
+записи в `done`/`failed`. Подробнее о том, как читать этот вывод и что
+делать дальше — в [USAGE.md](USAGE.md).
+
+Также стоит убедиться, что все валидаторы видны и не «зависли»:
+
+```bash
+curl -s http://<control-api>:8080/api/v1/admin/validators | python3 -m json.tool
+```
+
+Все зарегистрированные валидаторы должны рано или поздно оказываться в
+состоянии `idle` (между заданиями) — если валидатор надолго застрял в
+`unreachable`, проверьте сетевую связность до control-api и логи агента
+(`journalctl -u validator-agent`).
+
+## Сетевые доступы
+
+Минимально необходимая связность:
+
+- `validator-agent` → `control-api`: TCP, порт из `server.listen_addr`
+  (обычно 8080).
+- `prober` (на каждой из 3 площадок) → `control-api`: тот же порт, обычно
+  через интернет.
+- `prober` → адрес, который в данный момент проверяется (динамический,
+  меняется по ходу работы очереди): TCP 22/80/443/8080 + ICMP —
+  собственно и есть проверяемый трафик, его нельзя заранее ограничить
+  одним IP.
+- `validator-agent` → интернет: HTTPS/ICMP до целей из `targets` конфига
+  (по умолчанию hub.docker.com, github.com, packages.ubuntu.com) — именно
+  через floating IP, который в данный момент привязан к валидатору.
+- `control-api` → OpenStack Keystone/Neutron API (`OS_AUTH_URL` и далее по
+  каталогу сервисов).
+
+API control-api сейчас не аутентифицирован (см. предупреждение в начале
+[API.md](API.md)) — ограничивайте доступ к порту control-api на уровне
+сети/firewall теми хостами, где реально работают валидаторы и проберы.