Files
mtusi2026lab3/openspec/changes/replicas-lb/specs/container-run/spec.md
T
ricoromaandClaude Opus 5.5 8e15e02898 docs: propose replicas-lb change
HAProxy as the single entry point, API replicas without published
ports, resource limits and per-service secrets, restart and stop-one
hooks, replica tests in student-tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 17:40:04 +03:00

150 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Spec Delta
## MODIFIED Requirements
### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать стенд через
`docker compose`: PostgreSQL, Valkey, одноразовый сервис миграций,
`API_REPLICAS` реплик API (capability `load-balancing`) и балансировщик
(LB). Реплики API SHALL стартовать после готовности PostgreSQL и Valkey
и успешных миграций. Миграции SHALL выполняться один раз за запуск
отдельным сервисом, а не репликами. Перед этим цель SHALL создавать
недостающие `.env` и `config.toml` из шаблонов (`make env_setup`) и
MUST NOT перезаписывать существующие. `make stop` SHALL останавливать
сервисы, `make down` — удалять контейнеры, сохраняя volume, `make logs`
— показывать журнал всех реплик API.
#### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает через LB на
`http://localhost:8080/health/ready`, работают две реплики API, и
`make student_test` проходит
#### Scenario: Миграции один раз
- **WHEN** выполнен `make run_docker` с двумя репликами
- **THEN** журнал сервиса миграций содержит один прогон, а в журналах
реплик API нет запуска миграций
### Requirement: Порты из .env
Порты стенда и консольного запуска SHALL браться из одного `.env`:
- внутренний порт API — `APP__PORT`: параметр приложения `[app] port` в
формате настроек. Его слушает каждая реплика, на нём работают
healthcheck и проверки LB, на нём же LB принимает запросы внутри
своего контейнера;
- внешний порт стенда — `APP_OUT_PORT`: порт LB на `127.0.0.1` хоста,
приложение его не читает;
- порт PostgreSQL внутри сети compose — `POSTGRES_PORT`, его слушает
сам сервер и использует API в docker;
- внешний порт PostgreSQL — `POSTGRES_OUT_PORT`: порт на `127.0.0.1`
хоста для запуска в консоли;
- порт Valkey внутри сети compose — `VALKEY_PORT`, внешний —
`VALKEY_OUT_PORT` на `127.0.0.1` для запуска в консоли.
Если переменная порта API не задана, SHALL действовать 8080. Параметры
приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает. Адреса и порты PostgreSQL и Valkey MUST
NOT быть записаны в compose литералами.
#### Scenario: Другой внешний порт
- **WHEN** в `.env` задано `APP_OUT_PORT=8090`, и выполнен
`make run_docker`
- **THEN** API доступно через LB на `localhost:8090`, а внутри
контейнеров реплики слушают `APP__PORT`
#### Scenario: Другой внутренний порт
- **WHEN** в `.env` задано `APP__PORT=9090`
- **THEN** реплики внутри контейнеров слушают 9090 и становятся
`healthy`, LB проверяет их на 9090, а API доступно на
`localhost:$APP_OUT_PORT`
#### Scenario: Другой порт Postgres
- **WHEN** в `.env` заданы `POSTGRES_PORT=5544` и
`POSTGRES_OUT_PORT=5545`, а compose не правился
- **THEN** `make run_docker` поднимает стенд, `/health/ready` отвечает
200, а `make run_dev` подключается к Postgres на `127.0.0.1:5545`
#### Scenario: Другой порт Valkey
- **WHEN** в `.env` заданы другие `VALKEY_PORT` и `VALKEY_OUT_PORT`, а
compose не правился
- **THEN** `make run_docker` и `make run_dev` подключаются к Valkey на
новых портах, и кэш работает
### Requirement: Публикация только на localhost
Порты LB, PostgreSQL и Valkey SHALL публиковаться в compose только на
`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
переменной. Реплики API MUST NOT публиковать порты на хосте: к ним
ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть
доступен с других машин сети.
#### Scenario: Адрес публикации
- **WHEN** для запущенных контейнеров LB, API, Postgres и Valkey
выполняется `docker port`
- **THEN** порты LB, Postgres и Valkey опубликованы на `127.0.0.1`, а
не на `0.0.0.0`, а у контейнеров API опубликованных портов нет
### Requirement: Данные переживают рестарт стенда
Данные PostgreSQL SHALL храниться в именованном volume. Скрипт
`scripts/restart.sh` SHALL перезапускать LB, все реплики API и все
используемые хранилища — PostgreSQL и Valkey. Volume, схема и данные
SHALL сохраняться: без удаления volume, очистки и повторного
наполнения. Число реплик после рестарта SHALL оставаться прежним.
Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после
перезапуска, укладываться в 90 с и MUST NOT печатать секреты.
Публичная проверка `make test-persistence
ACTION_SCRIPT=scripts/restart.sh` SHALL проходить через LB.
#### Scenario: Рестарт hook-ом
- **WHEN** пользователь вошёл, отправил сообщение, затем выполнен
`scripts/restart.sh`
- **THEN** контейнеры LB, всех реплик API, Postgres и Valkey
перезапущены: те же ID и новое время старта в `docker inspect`. После
готовности запрос с прежним токеном через LB получает 200 и видит
своё сообщение
#### Scenario: Публичная проверка сохранности
- **WHEN** на запущенном стенде выполняется `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`
- **THEN** команда завершается с кодом 0 и печатает `PASS`
## ADDED Requirements
### Requirement: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API,
сервис миграций, PostgreSQL и Valkey. Сумма лимитов и расчёт
соединений PostgreSQL для заявленного числа реплик SHALL быть описаны
в `REPORT.md`. Секреты SHALL передаваться только тем сервисам, которым
они нужны:
- пароль PostgreSQL — PostgreSQL, репликам API и сервису миграций;
- пароль Valkey — Valkey и репликам API;
- LB MUST NOT получать ни одного секрета.
#### Scenario: Лимиты у всех контейнеров
- **WHEN** для каждого контейнера запущенного стенда выполняется
`docker inspect` (`HostConfig.NanoCpus`, `HostConfig.Memory`)
- **THEN** у LB, каждой реплики API, сервиса миграций, PostgreSQL и
Valkey оба значения больше нуля
#### Scenario: Секреты по сервисам
- **WHEN** проверяющий смотрит окружение сервисов в
`docker compose config`
- **THEN** у LB нет ни одного пароля, у сервиса миграций нет пароля
Valkey, а пароль Valkey есть только у Valkey и реплик API