forcad-local

Автоматизированный локальный оркестратор для запуска ForcAD + игровых сервисов + чекеров в контейнерах.

Инструмент делает:

auto-discovery сервисов в переданной папке;
preflight-проверки структуры сервисов и чекеров;
containerized сборку checker-артефактов (например make для archive) без хостовых dev-пакетов;
auto-cleanup хвостов прошлых запусков перед новым up;
prewarm k3d/k3s образов перед деплоем k3d-сервисов;
retry для k3d-деплоя и rollback при ошибке (настраивается);
генерацию runtime-конфига ForcAD без правок исходников борды/сервисов;
запуск light smoke-check check для каждого сервиса без полного ForcAD стека;
опциональный full режим с полным ForcAD стеком;
команды up, down, status, validate.

Требования

docker + docker compose
Python 3.10+
Для Helm/k3d-профилей сервисов: helm, kubectl, k3d (если требуется конкретному сервису)

Базовый запуск

python3 infra/forcad-local/forcad_local.py validate \
  --services-root /path/to/services \
  --checkers-root /path/to/checkers

python3 infra/forcad-local/forcad_local.py up \
  --services-root /path/to/services \
  --checkers-root /path/to/checkers \
  --mode light

python3 infra/forcad-local/forcad_local.py status

python3 infra/forcad-local/forcad_local.py down

После up борда доступна по http://127.0.0.1:8080/ (или через --board-port). Это относится только к --mode full. В --mode light борда не запускается.

Какие структуры поддерживаются

Для сервиса в services-root/<service_name>/:

Compose-профиль
- должен быть docker-compose.yml
Script/Helm-профиль
- deploy.sh, либо
- redeploy.sh, либо
- deploy/chart/values.yaml (с возможным build-docker.sh)

Для чекера в checkers-root/<service_name>/:

должен быть checker.py или *.checker.py
если есть requirements.txt (или requirments.txt) — зависимости автоматически объединяются
если есть Makefile — сборка выполняется внутри builder-контейнера (cpp-make профиль по умолчанию)

Автопроверки (preflight)

Команда validate проверяет:

обнаружены ли сервисы;
есть ли deploy-профиль;
есть ли checker entrypoint;
определён ли host-порт для сервиса;
нет ли конфликтов портов между сервисами и портом борды;
наличие системных команд (docker, а для helm/k3d-профиля — предупреждения про helm, kubectl, k3d).
валидность конфигурации containerized checker-build профиля.

Поведение `up` по умолчанию

сервисы сортируются в детерминированном порядке (k3d-сервисы сначала);
перед запуском выполняется auto-cleanup по обнаруженным сервисам;
для k3d-сервисов заранее выполняется pull базовых образов;
если k3d-деплой падает, делается retry (--k3d-retries);
в strict режиме падение одного сервиса прерывает запуск и откатывает уже поднятые;
в best-effort режимe проблемные сервисы пропускаются.

Runtime-файлы

Все временные файлы создаются в:

infra/forcad-local/.runtime/

Кэш сборки checker-артефактов:

infra/forcad-local/.cache/checker-builds/

Там же сохраняется state.json, который используется командами status и down.

Переопределения через manifest

Если auto-discovery не хватает, в services-root можно положить файл forcad-local.json:

{
  "services": {
    "warehouse": {
      "checker_dir": "warehouse",
      "port": 31443,
      "checker_timeout": 40,
      "checker_type": "pfr",
      "places": 2,
      "profile": "helm_chart",
      "start_cmd": "bash redeploy.sh",
      "stop_cmd": "helm uninstall warehouse -n warehouse",
      "checker_build": {
        "enabled": false
      }
    },
    "archive": {
      "checker_build": {
        "enabled": true,
        "profile": "cpp-make",
        "command": "make",
        "artifacts": ["libgen"]
      }
    }
  }
}

Поля опциональны. Используй их, если сервис нестандартный или порт не удаётся вывести автоматически.

Полезные параметры

--service <name> — выбрать конкретные сервисы (можно повторять)
--board-port 8080 — порт борды
--mode light|full — режим работы (light по умолчанию)
--failure-policy strict|best-effort — остановиться при первой ошибке или пропускать упавшие сервисы
--rollback-on-failure / --no-rollback-on-failure — откат уже поднятых сервисов при ошибке в strict режиме
--auto-cleanup / --no-auto-cleanup — очистка прошлых запусков перед новым up
--prewarm-k3d / --no-prewarm-k3d — предварительный pull k3d/k3s образов
--k3d-retries — число повторов деплоя для k3d-сервисов
--k3d-retry-delay — задержка между retry для k3d
--image-pull-retries — число дополнительных retry на pull docker-образов
--image-pull-retry-delay — задержка между retry pull
--team-count 2 — число команд в runtime-конфиге
--workers 2 — число celery worker'ов
--cache-dir — путь к кэшу сборки checker-артефактов
--no-fast — не использовать docker-compose-fast.yml

6.8 KiB Raw Permalink Blame History Unescape Escape