docs: propose rolling-update change
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-11
|
||||
@@ -0,0 +1,472 @@
|
||||
# Design
|
||||
|
||||
## Context
|
||||
|
||||
Мотивация — `proposal.md`, «Why». Требования — дельты в `specs/`.
|
||||
Стенд, LB и цепочка таймаутов — `.claude/rules/balancer.md`, миграции —
|
||||
`migrations.md`, стенд `bench/` — `bench.md`.
|
||||
|
||||
Текущее состояние (commit `c50b721`, change `graceful-failover` в
|
||||
архиве):
|
||||
|
||||
- **Стенд.** Сервис `api` × `API_REPLICAS` без имени контейнера. HAProxy
|
||||
находит реплики через DNS Docker: 8 слотов `server-template`,
|
||||
`init-state down`, `rise 2`, `inter 1s`, `fastinter 500ms`, `http-reuse
|
||||
never`, `timeout server 10s`. Сервис `migrate` — одноразовый контейнер
|
||||
на образе API, реплики ждут его завершения.
|
||||
- **Миграции.** Три ревизии, все только добавляют. Ревизия ключей
|
||||
идемпотентности `7652184b7016` уже писалась как expand.
|
||||
- **Остановка реплики** (`stop-one.sh`, профиль `failover`) — `docker
|
||||
stop` без вывода из LB. Под нагрузкой это даёт одиночный 502 в части
|
||||
фаз `stop`: гонка keep-alive при SIGTERM (`graceful-failover`,
|
||||
решения 3 и 10).
|
||||
- **Обновление кода.** Сейчас — только `make down` + `make run_docker`.
|
||||
`KNOWN_ISSUES.md` говорит, что `make run_docker` после пересборки не
|
||||
пересоздаёт работающие `api`.
|
||||
- **Хранилище образов Docker Desktop 29.8 — containerd** (`docker info`:
|
||||
`io.containerd.snapshotter.v1`). У тега три разных digest: индекс
|
||||
(`docker image inspect`), манифест платформы (метка
|
||||
`com.docker.compose.image` контейнера) и конфигурация (поле
|
||||
`.Image` контейнера; его показывает `docker ps` вместо имени тега).
|
||||
Разведка 2026-10-11: реплики рабочего стенда работают на текущем
|
||||
теге `mtusi-messenger:lab3`. Метка контейнера совпадает с манифестом
|
||||
платформы тега, хотя `docker ps` показывает `04f700d0d939`, а не
|
||||
имя.
|
||||
|
||||
Разведка runtime API HAProxy (2026-10-11). Временный HAProxy того же
|
||||
образа и с копией `haproxy.cfg` плюс `stats socket ipv4@127.0.0.1:9999
|
||||
level admin` стоял перед репликами рабочего стенда, команды шли через
|
||||
`bash` `/dev/tcp` изнутри контейнера:
|
||||
|
||||
- `show stat` по CLI отдаёт адрес слота (`172.30.0.5:8080`);
|
||||
- `set server api/api-1 state drain` — слот `DRAIN`, 6 из 6 новых
|
||||
запросов ушли на вторую реплику;
|
||||
- `state maint` — `MAINT`, запросов на неё тоже нет;
|
||||
- `state ready` при живом адресе — слот сначала `DOWN 1/2`, затем `UP`
|
||||
через проверки. Возврат из ручного состояния проходит обычный `rise`,
|
||||
а не мгновенный `UP`.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- Замена реплик на новый образ одной командой, без ошибок клиента под
|
||||
нагрузкой и без потери записей. Плановая остановка — с дренажём,
|
||||
поэтому без 502 гонки keep-alive.
|
||||
- Миграция при замене: одна, до новых реплик, совместима со старым
|
||||
кодом. Это проверено старым образом на новой схеме.
|
||||
- Предсказуемое поведение при сбое: `API_REPLICAS` готовых реплик и
|
||||
чистые слоты LB в любом исходе.
|
||||
- Профиль `rollout` воспроизводим одной командой и использует тот же
|
||||
скрипт, что рабочий стенд.
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- Автоматический откат при сбое. Скрипт останавливается, а смешанные
|
||||
версии допустимы: миграция только расширяет схему. Откат — тот же
|
||||
скрипт с образом прежнего commit (решение 6).
|
||||
- Дренаж в `stop-one.sh` и в профиле `failover`. Hook имитирует отказ,
|
||||
а его срок возврата (< 10 с) не вмещает дренаж и graceful.
|
||||
- Contract-миграция (удаление, переименование). В этой поставке её нет,
|
||||
правило и порядок описаны.
|
||||
- Swarm и сторонние плагины (`docker rollout`). Выбор Compose + HAProxy
|
||||
подтверждён 2026-10-07 (`PLAN.md`); незакреплённых зависимостей не
|
||||
прибавляется (`balancer.md`).
|
||||
- Изменение HTTP API и контракта.
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Порядок `scripts/rolling-update.sh`
|
||||
|
||||
`#!/bin/sh`, `set -eu`, как `stop-one.sh`. Скрипт вызывает `docker
|
||||
compose` без `-p` и `-f`. Проект, файлы и файл подстановок берутся из
|
||||
окружения (`COMPOSE_PROJECT_NAME`, `COMPOSE_FILE`, `COMPOSE_ENV_FILES`)
|
||||
или из каталога репозитория. Поэтому один и тот же скрипт работает с
|
||||
рабочим стендом и со стендом `bench/` (решение 8). Разведка
|
||||
подтвердила: Compose 5.5.1 берёт `COMPOSE_ENV_FILES`, а
|
||||
`COMPOSE_PROJECT_NAME` перекрывает `name:` файла.
|
||||
|
||||
0. **Предусловия** (ничего не меняют):
|
||||
- работает ровно `API_REPLICAS` реплик (по умолчанию 2);
|
||||
- остановленных реплик сервиса нет. Иначе `up --scale` запустил бы
|
||||
остановленную старую вместо новой;
|
||||
- все реплики `UP` в LB;
|
||||
- `API_REPLICAS` + 1 ≤ числа слотов LB.
|
||||
|
||||
Нарушение — код 2 и подсказка `make replicas`.
|
||||
1. **Сборка.** По умолчанию `docker compose build api` из рабочего
|
||||
дерева. С `ROLLOUT_COMMIT=<commit>` образ собирается из файлов
|
||||
commit (решение 6) под тем же тегом сервиса (`docker compose config
|
||||
--images api`).
|
||||
2. **Миграции один раз:** `docker compose run --rm --no-deps migrate` на
|
||||
только что собранном образе. Ошибка — код 1 до замены. Скрипт
|
||||
миграций не запускает при `ROLLOUT_MIGRATE=0` (откат, решение 6).
|
||||
Порядок «сборка → миграции», а не наоборот, как в `balancer.md`:
|
||||
новые ревизии лежат в новом образе. Правило исправляется.
|
||||
3. **Новая реплика:** `docker compose up -d --no-deps --no-recreate
|
||||
--no-build --scale api=N+1 api`. Новая — та, ID которой не было до
|
||||
команды.
|
||||
4. **Ожидание готовности** (решение 4).
|
||||
5. **Вывод и удаление старой** (решение 3).
|
||||
6. Шаги 3–5 — для каждой реплики, которая работала до шага 1.
|
||||
|
||||
В конце — те же проверки, что в шаге 0: `N` работающих реплик, все
|
||||
`UP`, ни одной из прежнего списка. Каждый шаг пишет строку `HH:MM:SS
|
||||
rolling-update: …` с контейнером, слотом и адресом. Эти строки
|
||||
разбирает профиль `rollout`. Вывод сборки и миграции идёт следом, в нём
|
||||
нет секретов.
|
||||
|
||||
### 2. Дренаж — runtime API HAProxy на loopback
|
||||
|
||||
В `global` `haproxy.cfg`: `stats socket ipv4@127.0.0.1:9999 level
|
||||
admin`. Скрипт отправляет команды так: `docker compose exec -T haproxy
|
||||
bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 …'`, как `make lb_stats` читает
|
||||
статистику. Слот реплики находится по её адресу в `show stat`: имя
|
||||
слота с именем контейнера не связано (`balancer.md`).
|
||||
|
||||
Почему так:
|
||||
|
||||
- Снаружи контейнера LB канал не виден: loopback другого контейнера
|
||||
недоступен, на хост порт не публикуется. Кто может выполнить `docker
|
||||
exec`, и так управляет всем стендом.
|
||||
- Приложение и цепочка таймаутов не меняются, поведение по SIGTERM
|
||||
(спек `graceful-shutdown`) остаётся прежним. Решение принимает
|
||||
оркестратор замены — он знает, что остановка плановая.
|
||||
- Действует мгновенно, а не через 1,5 с проверок.
|
||||
|
||||
Альтернативы:
|
||||
|
||||
- **Readiness 503 по SIGTERM.** Реплика после сигнала отвечает на
|
||||
`/health/ready` 503 и ещё ≥ 1,5 с принимает запросы, пока LB её не
|
||||
исключит. Минусы:
|
||||
- меняется спек `graceful-shutdown` («после SIGTERM новые соединения
|
||||
не принимаются»);
|
||||
- нужен свой обработчик сигнала поверх uvicorn;
|
||||
- остановка удлиняется до 1,5 + 8 с — впритык к `stop_grace_period`
|
||||
10 с;
|
||||
- срок `stop-one.sh` (< 10 с) перестаёт выполняться.
|
||||
|
||||
Отвергнуто.
|
||||
- **`stats admin` на странице `:8404`.** Порт открыт всей сети compose:
|
||||
любой контейнер стенда, включая реплику, мог бы вывести реплики из
|
||||
LB. Отвергнуто.
|
||||
- **Unix-сокет.** Нужен `socat` или `nc -U`, а в образе HAProxy их нет;
|
||||
bash с unix-сокетом не работает. Добавлять инструмент в закреплённый
|
||||
образ — свой образ LB. Отвергнуто.
|
||||
- **`set weight 0`** — то же, что `drain`, но состояние не видно в
|
||||
статистике явно. `drain` нагляднее (`make lb_stats` показывает
|
||||
`DRAIN`).
|
||||
|
||||
### 3. Состояния слота старой реплики
|
||||
|
||||
1. `set server api/<слот> state drain`. Новых запросов нет, начатые
|
||||
дорабатывают (разведка).
|
||||
2. Ожидание `scur` = 0 (запросов в полёте) не дольше
|
||||
`ROLLOUT_DRAIN_TIMEOUT` = 12 с. Это больше `timeout server` 10 с:
|
||||
дольше запрос через LB не живёт. По сроку — предупреждение и
|
||||
остановка: оставшееся доработает graceful uvicorn (8 с).
|
||||
3. `state maint` — проверки слота остановлены. Гибель процесса не
|
||||
пишет в журнал `DOWN` с ошибкой соединения, и слот не может
|
||||
вернуться в распределение по проверкам, пока процесс ещё отвечает.
|
||||
4. `docker stop --timeout 10` (= `stop_grace_period`), `docker rm`.
|
||||
Простаивающие соединения LB с репликой uvicorn закрывает при
|
||||
SIGTERM. LB их больше не выбирает: слот выведен. Поэтому гонки
|
||||
keep-alive нет.
|
||||
5. Ожидание, пока адрес уйдёт из слота: DNS `hold` 1 с, не дольше
|
||||
10 с. Затем `state ready`.
|
||||
|
||||
Почему `ready` нужен и почему после ухода адреса. Ручное состояние —
|
||||
свойство слота, а не реплики. Если слот останется в `drain` или
|
||||
`maint`, следующая реплика, которой DNS отдаст этот слот, не получит ни
|
||||
одного запроса. А `ready` при ещё живом адресе вернул бы проверки к
|
||||
мёртвому адресу: слот был бы `DOWN`, запросов бы не получил (разведка:
|
||||
`ready` → `DOWN 1/2` → проверки), но журнал LB шумел бы.
|
||||
|
||||
Почему `drain`, а потом `maint`, а не сразу `maint`. Исход для новых
|
||||
запросов одинаков. Но `drain` — штатное «не давать новых, доработать
|
||||
текущие», а ожидание `scur` = 0 видно в статистике и журнале LB как
|
||||
отдельный шаг. `maint` нужен только на время гибели процесса.
|
||||
|
||||
### 4. Новая реплика готова — `UP` в статистике LB
|
||||
|
||||
Ожидание, срок `ROLLOUT_READY_TIMEOUT` = 60 с:
|
||||
|
||||
1. Контейнер `healthy`, если у него есть healthcheck (рабочий стенд:
|
||||
healthcheck образа, `start_interval` 1 с), иначе `running`. На
|
||||
стенде `bench/` healthcheck выключен.
|
||||
2. Слот с адресом новой реплики в состоянии `UP`.
|
||||
|
||||
Только `healthy` мало. Слот получает адрес из DNS и начинает в `DOWN`
|
||||
(`init-state down`). В распределение он попадает после двух успешных
|
||||
проверок, то есть до 1,5 с после готовности (`downinter` + `fastinter`,
|
||||
`graceful-failover`). Вывести старую раньше — на время до 1,5 с
|
||||
остаться с N − 1 репликами.
|
||||
|
||||
### 5. Сбой на середине
|
||||
|
||||
Автоматического отката нет (Non-Goals). Скрипт держит инвариант
|
||||
«`API_REPLICAS` готовых реплик и чистые слоты». Состояние текущей
|
||||
замены — в переменных, `trap` на `EXIT`, `INT`, `TERM`:
|
||||
|
||||
| Где оборвалось | Что делает скрипт | Итог |
|
||||
|---|---|---|
|
||||
| предусловия, сборка, миграция | ничего не трогал | N старых, код 2 / 1 |
|
||||
| новая реплика не `UP` за срок, или прерывание до `UP` | `docker rm -f` новой; её слот уходит по DNS, ручного состояния у него не было | N реплик (k − 1 новых, остальные старые), код 1 |
|
||||
| новая `UP`, старая в дренаже или останавливается | довести шаг 3 решения 3: `maint`, `stop`, `rm`, `ready`. Повторный Ctrl+C на время уборки игнорируется | N реплик, код 1 или 130 |
|
||||
| уборка сама не удалась | печатает команды для ручного завершения (`docker rm …`, `set server … state ready`) | код 1 |
|
||||
|
||||
Почему «довести», а не «вернуть» старую. Новая реплика уже готова и
|
||||
получает запросы. Вернуть старую — значит N + 1 реплик или ещё один
|
||||
вывод из LB. Довести шаг — не больше ~25 с: 12 с дренажа, 10 с
|
||||
остановки, 2 с DNS.
|
||||
|
||||
- Смешанные версии после сбоя безопасны: схема совместима с обеими
|
||||
(решение 7, спек `db-migrations`).
|
||||
- Повторный запуск заменяет все работающие реплики. Уже новые
|
||||
заменяются на тот же образ: это лишняя, но безопасная работа. Образы
|
||||
скрипт не сравнивает, решение 9.
|
||||
- Слоты не переполняются: одновременно не больше N + 1 реплик, а N + 1
|
||||
≤ 8 проверяется в предусловиях.
|
||||
|
||||
Проверка сбоя — `ROLLOUT_READY_TIMEOUT=1`: реплика стартует ~3 с и за
|
||||
1 с готовой не станет. Плюс Ctrl+C во время дренажа и остановленная
|
||||
реплика перед запуском (`evidence/rollout/script-failures.md`).
|
||||
|
||||
### 6. Образ другого commit без изменения рабочего дерева
|
||||
|
||||
`git archive --format=tar <commit> | docker build -t <тег> -`.
|
||||
Контекст — ровно файлы commit, `.dockerignore` commit применяется к
|
||||
tar-контексту. Рабочее дерево, индекс и HEAD не меняются, лишних
|
||||
каталогов нет.
|
||||
|
||||
Где используется:
|
||||
|
||||
- **Профиль `rollout`.** Старт на образе `Profile.rollout_from` (решение
|
||||
8).
|
||||
- **Демонстрация на рабочем стенде.** Реплики на образе прежнего
|
||||
commit: `git archive c50b721 | docker build -t mtusi-messenger:lab3 -`
|
||||
и `docker compose up -d --no-build`.
|
||||
- **Откат кода скриптом.** `make rolling_update COMMIT=<commit>
|
||||
MIGRATE=0`. Миграции прежнего образа не знают новой ревизии, и
|
||||
`alembic upgrade head` упал бы на «Can't locate revision». Поэтому
|
||||
при откате миграции пропускаются явно. Схема остаётся новой,
|
||||
прежний код на ней работает (решение 7). Автоопределения нет: явный
|
||||
флаг надёжнее разбора текста ошибки alembic.
|
||||
|
||||
Альтернативы:
|
||||
|
||||
- `git worktree add` в scratchpad — тоже не трогает рабочее дерево, но
|
||||
оставляет метаданные в `.git/worktrees` и требует уборки;
|
||||
- `checkout` и `stash` запрещены (бриф) и сломали бы незакоммиченную
|
||||
работу;
|
||||
- `docker build` с git-URL контекста — нужен доступ к удалённому
|
||||
репозиторию и push.
|
||||
|
||||
### 7. Новая версия для демонстрации — `messages.instance_id`
|
||||
|
||||
Колонка `instance_id text NULL` в `messages`: `X-Instance-Id` реплики,
|
||||
которая записала сообщение. Новый код пишет `settings.app.instance_id`
|
||||
при вставке (параметр `insert_message`, DTO не меняется). Старый код
|
||||
колонку не знает:
|
||||
|
||||
- вставка перечисляет колонки, и в новой колонке остаётся NULL;
|
||||
- чтение выбирает `MESSAGE_COLUMNS`, то есть те же колонки.
|
||||
|
||||
Контракт и ответы API не меняются: колонка наружу не отдаётся.
|
||||
|
||||
Почему так:
|
||||
|
||||
- Новый код **зависит** от новой схемы: без миграции его вставка упала
|
||||
бы. Значит, порядок «миграция до новых реплик» проверяется по-настоящему.
|
||||
Старый код **терпит** новую схему. Это и есть expand/contract в
|
||||
миниатюре.
|
||||
- По данным видно, какая версия записала сообщение (NULL — прежняя).
|
||||
Это доказательство замены в БД, а не только по заголовкам.
|
||||
- Ревизия — `op.add_column(..., nullable=True)`. В PostgreSQL ≥ 11
|
||||
колонка без значения по умолчанию добавляется изменением каталога,
|
||||
без перезаписи таблицы. Блокировка `ACCESS EXCLUSIVE` берётся на
|
||||
миллисекунды, но в очереди за ней ждут все новые запросы к
|
||||
`messages`. Поэтому первой строкой ревизии идёт `SET LOCAL
|
||||
lock_timeout = '5s'`:
|
||||
- чужая долгая транзакция не заставит миграцию держать очередь;
|
||||
- по сроку миграция падает, схема не меняется, и замена не
|
||||
начинается (спек `db-migrations`);
|
||||
- повторный запуск проходит.
|
||||
- `downgrade` удаляет колонку. Это шаг contract, допустимый только
|
||||
после того, как не осталось нового кода.
|
||||
|
||||
Альтернативы:
|
||||
|
||||
- **Индекс `CONCURRENTLY`.** Код от схемы не зависит, демонстрация
|
||||
совместимости пустая. Кроме того, `CONCURRENTLY` не выполняется
|
||||
внутри транзакции alembic.
|
||||
- **Переименование колонки.** Это не expand: старый код ломается.
|
||||
Годится только как пример того, чего нельзя.
|
||||
- **Только правка кода без схемы.** Совместимость миграций не
|
||||
проверяется вовсе.
|
||||
|
||||
Цена: +~13 байт на строку `messages` (12 символов ID и заголовок
|
||||
varlena). Трек 1 снимает базовый замер после change, поэтому меток для
|
||||
сравнения «до» нет.
|
||||
|
||||
### 8. Профиль `rollout` стенда `bench/`
|
||||
|
||||
| Поле | `rollout` | `rollout_quick` |
|
||||
|---|---|---|
|
||||
| реплик, лимиты | 2; как рабочий стенд (как `failover`) | те же |
|
||||
| интенсивность | 100 записей с ключом + 100 чтений в секунду | та же |
|
||||
| `rollout_from` | `c50b721` — последний commit до change | тот же |
|
||||
| окна: до замены / бюджет замены / после | 15 / 90 / 15 с | 5 / 60 / 8 с |
|
||||
| порог доли успешных | 99 % | 99 % |
|
||||
| читаемый чат | 1 000 сообщений | тот же |
|
||||
|
||||
- **Старт.** `run.py` собирает образ текущего checkout (паспорт, как
|
||||
всегда) и образ `rollout_from` через `git archive` под тегом
|
||||
`mtusi-messenger:bench-from`. Затем `docker tag` на
|
||||
`mtusi-messenger:bench`, `Stand.start()`. Миграции прежнего образа
|
||||
дают его последнюю ревизию, реплики стартуют прежнего образа.
|
||||
Подготовка — как у `failover`: фикстура, читаемый чат, курсоры
|
||||
(общий хелпер).
|
||||
- **Нагрузка** — тот же `k6/failover.js`, `DURATION` = до + бюджет +
|
||||
после, `PHASE` 1. Через «до» секунд `run.py` запускает
|
||||
`scripts/rolling-update.sh`. Окружение — `Stand.env` (пароли,
|
||||
`BENCH_*`), плюс `COMPOSE_PROJECT_NAME=mtusi-bench`, `COMPOSE_FILE`
|
||||
(оба файла), `COMPOSE_ENV_FILES=bench/bench.env`, `API_REPLICAS`.
|
||||
`docker compose build api` пересобирает текущий checkout под тег
|
||||
`mtusi-messenger:bench`, слои из кэша. Правило `bench.md` «`-p`,
|
||||
оба `-f`, `--env-file`» выполняется переменными окружения.
|
||||
- **Время — часы ВМ.** Начало замены `t0` — событие `create` контейнера
|
||||
миграции (`docker events` с меткой проекта). Шаги каждой реплики
|
||||
берутся из трёх источников:
|
||||
- события Docker: `create`/`start` новой, `kill` с сигналом 15,
|
||||
`die`, `destroy` старой;
|
||||
- журнал LB: `UP` слота новой, `drain`/`maint` слота старой;
|
||||
- строки скрипта: какие слот и адрес у какой реплики.
|
||||
|
||||
Сборка до `t0` измеряется по строкам скрипта (секунды).
|
||||
- **Окна ошибок.** «До» — запросы, завершённые до `t0`. «Замена» —
|
||||
отправленные от `t0` до `destroy` последней старой. «После» — всё
|
||||
остальное.
|
||||
- **Шкала.** Посекундно от `t0`, по образцу `failover`. Добавлены
|
||||
`old_ok` и `new_ok`: успешные ответы с `X-Instance-Id` прежних и
|
||||
новых контейнеров. Новые столбцы — в конце (`bench.md`).
|
||||
- **Повтор и сверка** — `k6/retry.js` и `psql` стенда, как в `failover`.
|
||||
Плюс:
|
||||
- ревизия `alembic_version` до и после — измерение, а не изменение
|
||||
схемы;
|
||||
- контейнеры и `.Image` до и после;
|
||||
- тег образа после замены.
|
||||
- **Результаты** — `evidence/rollout/<метка>/`:
|
||||
- `meta.json` (паспорт и раздел `rollout`);
|
||||
- `rollout.csv` (строка прогона);
|
||||
- `replicas.csv` (строка на заменённую реплику);
|
||||
- `timeline.csv`, `summary.md`;
|
||||
- `raw/rollout-k6.json`, `raw/rollout-lb.log`, `raw/rollout-script.log`
|
||||
(только строки `rolling-update:`).
|
||||
|
||||
Пробные `quick-rollout-*` — в `.gitignore`.
|
||||
- **Отказ команды** — по списку спека `load-benchmark`. Ошибки клиента
|
||||
— пометка (`errors`), а не отказ.
|
||||
- **Код:**
|
||||
- `bench/rollout.py` — чистые функции разбора и сводки на stdlib
|
||||
поверх парсеров `failover.py`;
|
||||
- `run.py` — профили, `--from <commit>` для отладки (в
|
||||
`overrides`), оркестрация.
|
||||
|
||||
Тег `bench-from` снимается при уборке.
|
||||
|
||||
### 9. `make run_docker` и пересборка
|
||||
|
||||
Гипотеза: пункт `KNOWN_ISSUES.md` — ошибка диагностики. В хранилище
|
||||
containerd `docker ps` показывает у реплик digest конфигурации, а не
|
||||
имя тега, и это выглядит как «старый образ» (Context). Compose
|
||||
сравнивает метку `com.docker.compose.image` с манифестом платформы
|
||||
тега и должен пересоздавать реплики после пересборки.
|
||||
|
||||
Проверка в apply. Реплики работают на образе прежнего commit, затем:
|
||||
|
||||
1. `docker compose build api` (новый образ);
|
||||
2. `docker compose --dry-run up -d`;
|
||||
3. метки контейнеров против `docker image inspect --platform`.
|
||||
|
||||
Исход:
|
||||
|
||||
- **Compose пересоздаёт** (`Recreate`). Пункт закрывается в
|
||||
`KNOWN_ISSUES.md` с объяснением. В комментарии `run_docker` и в
|
||||
`REPORT.md`: `run_docker` пересоздаёт все реплики разом, с простоем;
|
||||
без простоя — `make rolling_update`.
|
||||
- **Не пересоздаёт.** `run_docker` получает явное пересоздание `api`
|
||||
после сборки, пункт закрывается исправлением.
|
||||
|
||||
Скрипт замены от этого не зависит: он определяет новую реплику по ID,
|
||||
а не по образу.
|
||||
|
||||
### 10. Evidence и отчёт
|
||||
|
||||
| Файл | Что показывает |
|
||||
|---|---|
|
||||
| `evidence/rollout/<метка>/` | полный профиль `rollout` с commit change: шкала, шаги по репликам, контейнеры и образы до и после, сверка; хост по брифу |
|
||||
| `evidence/rollout/compatibility.md` | рабочий стенд: реплики прежнего образа → новая миграция → `make test` и `make student_test` на прежнем образе и новой схеме → `make rolling_update` под `tests/load.py` → откат `COMMIT=c50b721 MIGRATE=0` под нагрузкой → снова вперёд; `docker compose ps` и образы до и после, `instance_id` сообщений по версиям, ревизия схемы; проверка `--dry-run` из решения 9 |
|
||||
| `evidence/rollout/script-failures.md` | предусловия (остановленная реплика, не то число реплик), новая реплика не готова (`ROLLOUT_READY_TIMEOUT=1`), Ctrl+C во время дренажа, миграция не получила блокировку (`lock_timeout`), канал управления LB недоступен из сети |
|
||||
| `evidence/tests/rolling-update-checks.md` | регрессия на commit кода: `make lint`, `check`, `test`, `student_test`, `test_isolated`, `failure_checks`, `test-persistence`, `test-failover` (`stop` и `kill`), `bench_quick`, `bench_failover_quick`, `bench_rollout_quick` |
|
||||
|
||||
`REPORT.md`:
|
||||
|
||||
- строки таблицы доказательств уровня «4» — замена под нагрузкой,
|
||||
миграции однократно и совместимы, вместо строки TODO;
|
||||
- процедура замены и состояния слота;
|
||||
- раздел профиля `rollout` в «Эксперименты и отказы»;
|
||||
- ограничения: нет автоотката, contract отдельной поставкой, одиночный
|
||||
502 остаётся только у незапланированного `docker stop`;
|
||||
- ответ на вопрос защиты о `depends_on` и healthcheck дополняется
|
||||
ожиданием `UP` в LB при замене;
|
||||
- раздел «Обновление без простоя и миграции» в ответах на вопросы
|
||||
защиты.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[Канал управления LB — admin-уровень]** → слушает только
|
||||
`127.0.0.1` внутри контейнера LB. Проверка — попытка подключиться к
|
||||
порту 9999 LB из другого контейнера сети (`script-failures.md`).
|
||||
Доступ через `docker exec` равен доступу к Docker, то есть ко всему
|
||||
стенду.
|
||||
- **[`lock_timeout` 5 с может не хватить под тяжёлой записью]** →
|
||||
миграция падает без изменений, замена не начинается, повтор проходит.
|
||||
Это лучше, чем очередь всех записей за миграцией. Без нагрузки
|
||||
блокировка берётся за миллисекунды.
|
||||
- **[Новый код на старой схеме падает]** → только если миграцию
|
||||
пропустить при движении вперёд. Скрипт пропускает её лишь по явному
|
||||
`MIGRATE=0` (откат). Порядок «миграция → новые реплики» закреплён в
|
||||
скрипте и спеке.
|
||||
- **[`git archive` берёт только закоммиченное]** → это и нужно:
|
||||
«прежняя версия» — commit, а не рабочее дерево. Commit записывается в
|
||||
паспорт.
|
||||
- **[Профиль `rollout` собирает образ под нагрузкой]** → сборка из кэша
|
||||
слоёв — секунды CPU ВМ, видны в шкале до `t0`. Так и при реальной
|
||||
замене на том же хосте; длительность — в результатах.
|
||||
- **[`docker compose exec` на каждую команду LB]** → ~0,1–0,2 с на вызов,
|
||||
опрос каждые 0,25–0,5 с. Замена двух реплик — десятки вызовов,
|
||||
секунды.
|
||||
- **[Повторный запуск после сбоя заменяет и уже новые реплики]** → это
|
||||
лишняя работа, но безопасная и проще, чем сравнивать digest в
|
||||
хранилище containerd (Context).
|
||||
- **[DNS отдал адрес удалённой реплики новой раньше, чем слот вернулся
|
||||
в `ready`]** → IPAM Docker не переиспользует адрес сразу, а `ready`
|
||||
выставляется до следующего `--scale`. Слот новой реплики проверяется
|
||||
в шаге ожидания по её адресу: если он застрял в ручном состоянии,
|
||||
замена падает по сроку с понятной причиной, а не тихо.
|
||||
- **[Один хост]** → профиль показывает поведение замены и порядок
|
||||
величин, а не распределение. Генератор, LB, реплики, сборка и
|
||||
PostgreSQL делят ВМ Docker.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Код, ревизия, скрипт и конфиг LB коммитятся. Рабочий стенд получает
|
||||
их одной командой `make rolling_update`: новая ревизия применяется,
|
||||
реплики заменяются. `haproxy.cfg` с runtime API подхватывается
|
||||
пересозданием LB (`docker compose up -d haproxy`). Это короткий
|
||||
перерыв точки входа, а не реплик. Делается один раз, до первой
|
||||
замены: без канала управления скрипт останавливается в предусловиях.
|
||||
2. Откат кода — `make rolling_update COMMIT=<прежний> MIGRATE=0`. Схема
|
||||
остаётся новой, прежний код на ней работает. Колонку удаляет только
|
||||
отдельная contract-миграция, когда прежнего кода точно нет.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Proposal
|
||||
|
||||
## Why
|
||||
|
||||
Последний пункт рубрики «4» лабы 3 (`README.md`) ещё не закрыт:
|
||||
|
||||
- rolling update или эквивалентная поочерёдная замена, проверенная под
|
||||
нагрузкой;
|
||||
- миграции запускаются однократно и совместимы с работающей версией,
|
||||
либо ограничение честно описано.
|
||||
|
||||
Сейчас новый код доходит до реплик только через `make down` и `make
|
||||
run_docker`. Это простой всего API (`KNOWN_ISSUES.md`, `PLAN.md`,
|
||||
раздел change `rolling-update`). Миграции действительно выполняются
|
||||
один раз: сервис `migrate` стартует до реплик. Но совместимость новой
|
||||
схемы с работающей версией нигде не проверялась.
|
||||
|
||||
Change `graceful-failover` передал сюда ещё три пункта:
|
||||
|
||||
- **дренаж до SIGTERM.** При `docker stop` под нагрузкой остаётся
|
||||
одиночный 502. Это гонка keep-alive: uvicorn закрывает простаивающие
|
||||
соединения, а LB в тот же миг шлёт в одно из них запрос. Так было в
|
||||
1 из 4 фаз `stop`. При плановой замене реплику нужно сначала вывести
|
||||
из LB;
|
||||
- **ожидание `UP` в LB**, а не только `healthy` контейнера: новая
|
||||
реплика попадает в распределение через ≤ 1,5 с после готовности;
|
||||
- **`make run_docker` не пересоздаёт работающие `api`** после пересборки
|
||||
образа. Пункт записан в `KNOWN_ISSUES.md`, но отдельно не
|
||||
воспроизводился.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **`scripts/rolling-update.sh` и `make rolling_update`.** Скрипт по
|
||||
одной заменяет реплики на новый образ без простоя:
|
||||
1. сборка образа;
|
||||
2. миграции, один раз;
|
||||
3. рядом со старыми поднимается одна новая реплика;
|
||||
4. скрипт ждёт её готовности и `UP` в LB;
|
||||
5. старая реплика выводится из LB и дорабатывает запросы, затем
|
||||
останавливается и удаляется;
|
||||
6. шаги 3–5 повторяются для каждой старой реплики.
|
||||
|
||||
Перед запуском скрипт проверяет состояние стенда. При сбое на
|
||||
середине останавливается и оставляет `API_REPLICAS` готовых реплик.
|
||||
- **Дренаж через runtime API HAProxy.** Канал управления LB слушает
|
||||
только loopback внутри контейнера LB, наружу и в сеть compose не
|
||||
открыт. Через него скрипт переводит слот старой реплики в `drain` и
|
||||
`maint` и потом возвращает его в `ready`. Поведение остановки по
|
||||
SIGTERM и hook `stop-one.sh` не меняются: hook имитирует отказ, а не
|
||||
плановую остановку.
|
||||
- **Новая версия для демонстрации — expand-миграция.** В таблицу
|
||||
`messages` добавляется колонка `instance_id`, допускающая NULL:
|
||||
реплика, которая записала сообщение. Новый код её заполняет, старый
|
||||
не знает о ней и пишет NULL. Контракт и поведение API не меняются.
|
||||
Миграция ограничивает ожидание блокировки (`lock_timeout`): долгая
|
||||
чужая транзакция не остановит все записи за ней.
|
||||
- **Совместимость доказывается на рабочем стенде** по шагам:
|
||||
1. реплики на образе прежнего commit;
|
||||
2. новая миграция, а реплики остаются прежними;
|
||||
3. `make test` и `make student_test` на старом образе и новой схеме;
|
||||
4. `make rolling_update` под нагрузкой `tests/load.py`;
|
||||
5. проверки на новом образе.
|
||||
- **Профиль `rollout` стенда `bench/`** (`make bench_rollout`, `make
|
||||
bench_rollout_quick`) построен по образцу `failover`:
|
||||
- стенд стартует на образе заданного commit;
|
||||
- k6 даёт постоянную интенсивность записи с ключом и чтения;
|
||||
- посреди нагрузки работает тот же `scripts/rolling-update.sh`;
|
||||
- сохраняются посекундная шкала, доли ответов старой и новой версии
|
||||
и время каждого шага замены;
|
||||
- фиксируются контейнеры, образы и ревизия схемы до и после;
|
||||
- неуспешные записи повторяются с тем же ключом, затем идёт сверка.
|
||||
|
||||
Результаты — в `evidence/rollout/<метка>/`.
|
||||
- **`make run_docker`.** Пункт `KNOWN_ISSUES.md` проверяется
|
||||
воспроизведением: собранный новый образ, `docker compose --dry-run up
|
||||
-d`. Если дефект подтвердится, он исправляется. Если нет, пункт
|
||||
закрывается с объяснением. В обоих случаях в документации:
|
||||
`run_docker` пересоздаёт все реплики разом, обновление без простоя
|
||||
делает `rolling_update`.
|
||||
- **Документы:**
|
||||
- правила `balancer.md`, `migrations.md`, `bench.md`, `run-modes.md`,
|
||||
`docker.md`;
|
||||
- `AGENTS.md`: команды, карта кода, «Переходное состояние»;
|
||||
- `REPORT.md`: строки доказательств уровня «4», процедура замены,
|
||||
ограничения, вопросы защиты.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
Нет.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `load-balancing`:
|
||||
- поочерёдная замена реплик на новый образ под нагрузкой без ошибок
|
||||
и без потери записей;
|
||||
- вывод реплики из LB перед плановой остановкой;
|
||||
- поведение замены при сбое на середине.
|
||||
- `db-migrations`:
|
||||
- миграция совместима с работающей версией (только расширение);
|
||||
- при замене миграции запускаются один раз и до новых реплик;
|
||||
- ожидание блокировки ограничено.
|
||||
- `graceful-shutdown`: плановая остановка реплики после дренажа не
|
||||
даёт клиенту ни одной ошибки, в том числе 502 гонки keep-alive.
|
||||
- `load-benchmark`:
|
||||
- профиль `rollout` стартует на образе заданного commit, а не
|
||||
текущего checkout;
|
||||
- новый профиль поочерёдной замены под нагрузкой.
|
||||
|
||||
## Impact
|
||||
|
||||
- **Новое:**
|
||||
- `scripts/rolling-update.sh`;
|
||||
- ревизия alembic `added message instance id`;
|
||||
- `bench/rollout.py` — разбор и сводка профиля;
|
||||
- `evidence/rollout/`.
|
||||
- **Код приложения:**
|
||||
- модель `Message`;
|
||||
- `src/core/repos/message.py` — `instance_id` при вставке;
|
||||
- `MessageService.send_message` передаёт `settings.app.instance_id`.
|
||||
|
||||
HTTP API и контракт не меняются.
|
||||
- **Стенд:**
|
||||
- `infra/haproxy/haproxy.cfg` — runtime API на loopback;
|
||||
- `Makefile` — цели `rolling_update`, `bench_rollout`,
|
||||
`bench_rollout_quick`, при необходимости `run_docker`;
|
||||
- `.gitignore` — `evidence/rollout/quick-*/`.
|
||||
- **Стенд `bench/`:**
|
||||
- `run.py` — профили `rollout` и `rollout_quick`, сборка образа
|
||||
прежнего commit через `git archive`;
|
||||
- `k6/failover.js` и `k6/retry.js` — без изменений, повторно
|
||||
используются.
|
||||
- **Документы:** `.claude/rules/`, `AGENTS.md`, `REPORT.md`,
|
||||
`KNOWN_ISSUES.md`, скилл `run-mtusi-messenger` (новая цель).
|
||||
- **Зависимости** не прибавляются: те же образы HAProxy и k6, shell и
|
||||
stdlib Python.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Совместимость миграции с работающей версией
|
||||
|
||||
Миграция SHALL только расширять схему:
|
||||
- новая таблица;
|
||||
- новая колонка, допускающая NULL или со значением по умолчанию;
|
||||
- новый индекс.
|
||||
|
||||
Удаление и переименование таблицы, колонки или ограничения, а также
|
||||
новое ограничение, которое нарушит запись прежней версии, MUST NOT
|
||||
входить в ту же поставку, что и код, которому они нужны. Такое
|
||||
изменение выполняется отдельной миграцией после того, как реплик
|
||||
прежней версии не осталось (expand/contract). Если так сделать нельзя,
|
||||
ограничение SHALL описываться в `REPORT.md`.
|
||||
|
||||
Реплики прежнего образа SHALL обслуживать обязательные запросы на
|
||||
схеме после новой миграции. Откат кода к прежнему образу MUST NOT
|
||||
требовать отката схемы.
|
||||
|
||||
Ожидание блокировки таблицы миграцией SHALL быть ограничено сроком.
|
||||
Долгая транзакция приложения не должна заставить миграцию держать
|
||||
очередь за собой и остановить запись остальных реплик. По истечении
|
||||
срока миграция SHALL завершаться ошибкой без изменения схемы, а её
|
||||
повторный запуск SHALL проходить.
|
||||
|
||||
#### Scenario: Старый образ на новой схеме
|
||||
|
||||
- **WHEN** стенд работает на образе прежнего commit, и миграции нового
|
||||
образа применены, а реплики не заменены
|
||||
- **THEN** `make test` и `make student_test` через LB проходят на
|
||||
прежних репликах
|
||||
|
||||
#### Scenario: Запись прежней версии
|
||||
|
||||
- **WHEN** после новой миграции сообщение отправлено через реплику
|
||||
прежнего образа
|
||||
- **THEN** ответ 201, а сообщение видно в истории через реплику любого
|
||||
образа
|
||||
|
||||
#### Scenario: Блокировка не получена
|
||||
|
||||
- **WHEN** таблицу, которую меняет миграция, держит открытая
|
||||
транзакция дольше срока ожидания блокировки
|
||||
- **THEN** миграция завершается ошибкой, схема не меняется, запись
|
||||
других клиентов продолжается, а после окончания транзакции повторный
|
||||
запуск применяет миграцию
|
||||
|
||||
### Requirement: Однократные миграции при замене реплик
|
||||
|
||||
Поочерёдная замена реплик (`load-balancing`) SHALL применять миграции
|
||||
один раз за запуск: отдельным одноразовым контейнером на новом образе,
|
||||
после сборки образа и до запуска первой новой реплики. Реплики MUST
|
||||
NOT запускать миграции сами. Если миграция завершилась ошибкой, замена
|
||||
MUST NOT начинаться: работающие реплики не трогаются, скрипт
|
||||
завершается с ненулевым кодом.
|
||||
|
||||
#### Scenario: Одна миграция на замену
|
||||
|
||||
- **WHEN** выполнен `make rolling_update` для двух реплик
|
||||
- **THEN** в журнале замены одна миграция до первой новой реплики, в
|
||||
журналах реплик записей alembic нет, а ревизия схемы после замены —
|
||||
последняя
|
||||
|
||||
#### Scenario: Миграция упала
|
||||
|
||||
- **WHEN** миграция при замене завершается ошибкой
|
||||
- **THEN** скрипт завершается с ненулевым кодом до запуска новых
|
||||
реплик, а прежние реплики работают и обслуживают запросы
|
||||
@@ -0,0 +1,31 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Плановая остановка реплики без ошибок
|
||||
|
||||
При плановой остановке реплики за балансировщиком (поочерёдная замена,
|
||||
`load-balancing`) реплика SHALL сначала выводиться из LB. Только когда
|
||||
у неё не осталось запросов в полёте, она получает SIGTERM. Поэтому
|
||||
плановая остановка под постоянной нагрузкой MUST NOT давать клиенту ни
|
||||
одной ошибки, включая 502 гонки keep-alive из требования «Остановка
|
||||
реплики за балансировщиком».
|
||||
|
||||
Поведение процесса по SIGTERM не меняется: требования выше действуют. Не
|
||||
меняется и остановка без дренажа (`scripts/stop-one.sh`, `docker
|
||||
stop`): она имитирует отказ, и исключение для 502 гонки keep-alive к
|
||||
ней по-прежнему применяется.
|
||||
|
||||
#### Scenario: Остановка после дренажа под нагрузкой
|
||||
|
||||
- **WHEN** через LB с постоянной интенсивностью идут запись с ключом и
|
||||
чтение истории, и реплика остановлена после вывода из LB
|
||||
- **THEN** ни одного неуспешного ответа, в том числе 502, а журнал LB
|
||||
не показывает ошибок соединения с этой репликой
|
||||
|
||||
#### Scenario: Остановка за заявленный срок после дренажа
|
||||
|
||||
- **WHEN** реплика выведена из LB и получила SIGTERM
|
||||
- **THEN** процесс завершается быстрее 10 с с кодом выхода не 137, а в
|
||||
её журнале есть «Shutting down», «Stopped API» и «Finished server
|
||||
process»
|
||||
@@ -0,0 +1,120 @@
|
||||
# Spec Delta
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Поочерёдная замена реплик
|
||||
|
||||
Команда `make rolling_update` (`scripts/rolling-update.sh`) SHALL
|
||||
заменять работающие реплики API на образ из текущего checkout по одной,
|
||||
без остановки обслуживания. Порядок:
|
||||
1. сборка образа;
|
||||
2. миграции, один раз (`db-migrations`);
|
||||
3. для каждой старой реплики:
|
||||
- рядом запускается одна новая;
|
||||
- скрипт ждёт её готовности и состояния `UP` в статистике LB;
|
||||
- старая выводится из LB, дорабатывает запросы, останавливается и
|
||||
удаляется.
|
||||
|
||||
Реплик одновременно SHALL быть не больше `API_REPLICAS` + 1. Число
|
||||
должно помещаться в слоты LB. Правка конфигурации LB и его перезапуск
|
||||
MUST NOT требоваться.
|
||||
|
||||
После успешной замены SHALL работать ровно `API_REPLICAS` реплик. Все
|
||||
они SHALL быть на новом образе и в состоянии `UP` в LB. Контейнеров
|
||||
прежнего образа SHALL не остаться ни работающих, ни остановленных.
|
||||
|
||||
Под постоянной нагрузкой через LB (запись с ключом и чтение истории)
|
||||
замена MUST NOT давать клиенту ошибок. Каждая подтверждённая запись
|
||||
SHALL оставаться доступной.
|
||||
|
||||
Перед заменой скрипт SHALL проверять стенд:
|
||||
- работает ровно `API_REPLICAS` реплик;
|
||||
- остановленных реплик нет;
|
||||
- все реплики `UP` в LB;
|
||||
- для ещё одной реплики есть свободный слот LB.
|
||||
|
||||
Если условие не выполнено, скрипт SHALL завершаться с ненулевым кодом
|
||||
до сборки и ничего не менять.
|
||||
|
||||
#### Scenario: Замена двух реплик
|
||||
|
||||
- **WHEN** работают две реплики прежнего образа, и выполнен `make
|
||||
rolling_update`
|
||||
- **THEN** команда завершается с кодом 0, работают две реплики с новыми
|
||||
`X-Instance-Id` на новом образе, обе `UP` в LB, а контейнеров прежних
|
||||
реплик нет
|
||||
|
||||
#### Scenario: Замена под нагрузкой
|
||||
|
||||
- **WHEN** во время `make rolling_update` через LB с постоянной
|
||||
интенсивностью идут запись с ключом и чтение истории
|
||||
- **THEN** ни один ответ клиенту не ошибочен, в ответах сначала есть
|
||||
только старые `X-Instance-Id`, затем старые и новые, затем только
|
||||
новые, а число сообщений в чате равно числу отправленных ключей
|
||||
|
||||
#### Scenario: Стенд не готов к замене
|
||||
|
||||
- **WHEN** одна реплика остановлена `scripts/stop-one.sh`, или работает
|
||||
не `API_REPLICAS` реплик
|
||||
- **THEN** скрипт завершается с ненулевым кодом до сборки, называет
|
||||
причину и предлагает `make replicas`, а контейнеры не меняются
|
||||
|
||||
### Requirement: Вывод реплики из балансировщика перед остановкой
|
||||
|
||||
Перед плановой остановкой реплики LB SHALL перестать направлять ей
|
||||
новые запросы. Запросы, которые она уже обрабатывает, SHALL
|
||||
дорабатываться. Остановка SHALL начинаться после того, как запросов в
|
||||
полёте у неё не осталось, или по истечении срока ожидания, большего
|
||||
`timeout server` LB. Управление LB SHALL быть доступно только изнутри
|
||||
контейнера LB. Из сети compose и с хоста оно MUST NOT быть доступно.
|
||||
|
||||
Состояние слота, выставленное при замене, SHALL сниматься, когда адрес
|
||||
удалённой реплики ушёл из слота. Слот, который потом получит новая
|
||||
реплика, SHALL включаться по обычным проверкам готовности.
|
||||
|
||||
#### Scenario: Выведенная реплика не получает запросов
|
||||
|
||||
- **WHEN** слот реплики переведён в дренаж, и через LB идут запросы
|
||||
- **THEN** все новые ответы приходят от других реплик, а запросы,
|
||||
начатые до дренажа, получают ответ
|
||||
|
||||
#### Scenario: Управление LB недоступно из сети
|
||||
|
||||
- **WHEN** контейнер в сети стенда или процесс на хосте обращается к
|
||||
портам LB
|
||||
- **THEN** изменить состояние реплики он не может: канал управления LB
|
||||
слушает только loopback внутри контейнера LB
|
||||
|
||||
#### Scenario: Слот после замены
|
||||
|
||||
- **WHEN** замена завершена
|
||||
- **THEN** в статистике LB нет слотов в дренаже или в обслуживании,
|
||||
выставленном вручную; свободные слоты — только в обслуживании по DNS
|
||||
|
||||
### Requirement: Сбой поочерёдной замены
|
||||
|
||||
Если новая реплика не стала готовой в LB за срок ожидания, скрипт
|
||||
SHALL удалить её и завершиться с ненулевым кодом. Старые реплики,
|
||||
которые ещё не заменены, SHALL остаться в работе.
|
||||
|
||||
Если замена прервана (Ctrl+C, ошибка) после того, как новая реплика
|
||||
стала `UP`, скрипт SHALL довести вывод текущей старой реплики до
|
||||
удаления. Только после этого он завершается.
|
||||
|
||||
В любом исходе SHALL работать `API_REPLICAS` готовых реплик. Слоты LB
|
||||
SHALL быть без состояния, выставленного вручную. Реплики разных версий
|
||||
допустимы: миграция совместима с обеими. Повторный запуск SHALL
|
||||
доводить замену до конца.
|
||||
|
||||
#### Scenario: Новая реплика не готова
|
||||
|
||||
- **WHEN** новая реплика не стала `UP` в LB за срок ожидания
|
||||
- **THEN** она удалена, скрипт завершился с ненулевым кодом и назвал
|
||||
шаг, работают `API_REPLICAS` реплик, все `UP`, и запросы через LB
|
||||
обслуживаются
|
||||
|
||||
#### Scenario: Прерывание во время дренажа
|
||||
|
||||
- **WHEN** скрипт прерван Ctrl+C, пока старая реплика выводится из LB
|
||||
- **THEN** старая реплика остановлена и удалена, новая работает,
|
||||
реплик `API_REPLICAS`, а слот старой реплики без ручного состояния
|
||||
@@ -0,0 +1,166 @@
|
||||
# Spec Delta
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Фиксированный стенд
|
||||
|
||||
Стенд SHALL состоять из балансировщика (LB), реплик приложения,
|
||||
PostgreSQL и Valkey. Число реплик SHALL задаваться методикой, по
|
||||
умолчанию одна. Приложение SHALL запускаться в контейнерах из образа,
|
||||
собранного из текущего checkout тем же `Dockerfile`. Исключение —
|
||||
профиль поочерёдной замены. Он стартует на образе commit, заданного
|
||||
методикой: образ собирается тем же `Dockerfile` из файлов этого commit
|
||||
без изменения рабочего дерева. Заканчивается профиль на образе текущего
|
||||
checkout. LB SHALL
|
||||
запускаться из того же образа и с той же конфигурацией, что у рабочего
|
||||
стенда. PostgreSQL и Valkey SHALL запускаться из тех же образов, что у
|
||||
рабочего стенда. Valkey получает ту же конфигурацию. PostgreSQL
|
||||
получает те же настройки образа плюс модуль записи планов, выключенный
|
||||
вне снятия плана. Схема БД SHALL применяться миграциями до наполнения.
|
||||
|
||||
Лимиты SHALL быть одинаковыми во всех прогонах профиля:
|
||||
- у каждой реплики приложения — лимит CPU и памяти без swap, заданный
|
||||
методикой (в профилях лабы 2 — 1 CPU и 2 ГБ);
|
||||
- у LB, PostgreSQL и Valkey — свои лимиты CPU и памяти без swap,
|
||||
заданные методикой.
|
||||
|
||||
Healthcheck образа приложения SHALL быть отключён: готовность реплик
|
||||
проверяет LB. Порты стенда на хост MUST NOT публиковаться. Настройки
|
||||
приложения и хранилищ SHALL браться из методики стенда, а не из `.env`
|
||||
и `config.toml` рабочего стенда. Пароли хранилищ SHALL генерироваться
|
||||
на прогон. Генератор нагрузки SHALL работать в той же docker-сети и
|
||||
обращаться к приложению через LB по имени сервиса, минуя проброс
|
||||
портов хоста. Стенд SHALL считаться готовым, когда LB видит готовыми
|
||||
все реплики.
|
||||
|
||||
#### Scenario: Лимиты в паспорте
|
||||
|
||||
- **WHEN** прогон завершён
|
||||
- **THEN** паспорт стенда содержит число реплик и лимиты CPU и памяти
|
||||
реплики приложения, LB, PostgreSQL и Valkey, прочитанные у запущенных
|
||||
контейнеров, и они одинаковы для всех размеров
|
||||
|
||||
#### Scenario: Нехватка памяти
|
||||
|
||||
- **WHEN** процесс приложения превысил лимит памяти и был убит
|
||||
- **THEN** прогон помечен как проваленный из-за OOM, а не записан как
|
||||
обычный результат
|
||||
|
||||
#### Scenario: Настройки рабочего стенда не влияют
|
||||
|
||||
- **WHEN** `.env` и `config.toml` рабочего стенда изменены или
|
||||
отсутствуют
|
||||
- **THEN** стенд запускается с теми же настройками приложения и
|
||||
хранилищ, а окружение приложения в паспорте то же
|
||||
|
||||
#### Scenario: Схема до наполнения
|
||||
|
||||
- **WHEN** начинается наполнение размера
|
||||
- **THEN** миграции применены до последней ревизии, и приложение
|
||||
отвечает готовностью
|
||||
|
||||
#### Scenario: Одна реплика за балансировщиком
|
||||
|
||||
- **WHEN** профиль лабы 2 (`full`, `quick`, `restore`,
|
||||
`restore_quick`) запущен с одной репликой
|
||||
- **THEN** все запросы генератора проходят через LB, прогон завершается
|
||||
с кодом 0, а таблицы прогонов и сводка содержат те же столбцы и
|
||||
разделы, что раньше
|
||||
|
||||
#### Scenario: Образ прежнего commit
|
||||
|
||||
- **WHEN** запускается профиль поочерёдной замены
|
||||
- **THEN** реплики стартуют на образе commit из методики, схема — на
|
||||
его последней ревизии, рабочее дерево не меняется, а commit и образы
|
||||
до и после записаны в паспорт
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Профиль поочерёдной замены
|
||||
|
||||
Команда `make bench_rollout` (метка `ROLLOUT_LABEL`) SHALL на свежем
|
||||
стенде с лимитами рабочего стенда и `API_REPLICAS` по методике
|
||||
выполнять поочерёдную замену реплик (`scripts/rolling-update.sh`,
|
||||
`load-balancing`) под нагрузкой. Реплики стартуют на образе прежнего
|
||||
commit и заменяются на образ текущего checkout. Команда `make
|
||||
bench_rollout_quick` делает то же с короткими окнами, метка
|
||||
`quick-rollout-…`, в git она не идёт. Результаты SHALL сохраняться в
|
||||
`evidence/rollout/<метка>/`. Занятая метка SHALL давать отказ до
|
||||
запуска стенда.
|
||||
|
||||
Нагрузка — постоянная интенсивность, заданная методикой: запись
|
||||
сообщения с `Idempotency-Key` и чтение страницы истории. Скрипт
|
||||
замены SHALL запускаться через заданное методикой время после начала
|
||||
нагрузки. Нагрузка SHALL продолжаться после его завершения. Скрипт
|
||||
SHALL быть тем же, что у рабочего стенда, и выполняться против проекта
|
||||
compose стенда.
|
||||
|
||||
SHALL сохраняться посекундная шкала от начала замены (создание
|
||||
контейнера миграции):
|
||||
- успешные записи и чтения;
|
||||
- ошибки по кодам;
|
||||
- доля успешных;
|
||||
- p50 и p95 задержки успешных;
|
||||
- число успешных ответов старых и новых реплик;
|
||||
- распределение ответов по `X-Instance-Id`.
|
||||
|
||||
По каждой заменённой реплике SHALL сохраняться:
|
||||
- время от запуска новой реплики до её `UP` в LB;
|
||||
- время дренажа старой реплики;
|
||||
- время её остановки;
|
||||
- время замены целиком.
|
||||
|
||||
Для прогона целиком SHALL сохраняться:
|
||||
- длительность замены;
|
||||
- ошибки по кодам до, во время и после замены;
|
||||
- минимальная доля успешных в секунде;
|
||||
- контейнеры, их образы и ревизия схемы до и после.
|
||||
|
||||
После прогона каждая неподтверждённая запись SHALL повторяться с тем
|
||||
же ключом и телом до 201. Число сообщений чата записи SHALL совпадать
|
||||
с числом отправленных ключей, одинаковых текстов MUST NOT быть.
|
||||
|
||||
Команда SHALL завершаться с ненулевым кодом в случаях:
|
||||
- скрипт замены вернул ненулевой код;
|
||||
- генератор упал;
|
||||
- PostgreSQL или Valkey падал;
|
||||
- сверка не сошлась;
|
||||
- в конце работает не `API_REPLICAS` реплик;
|
||||
- среди работающих реплик есть реплика прежнего образа;
|
||||
- не все реплики `UP` в LB.
|
||||
|
||||
Ошибки клиента при замене — результат, а не отказ команды: они
|
||||
считаются и показываются.
|
||||
|
||||
#### Scenario: Полный профиль
|
||||
|
||||
- **WHEN** выполнен `make bench_rollout`
|
||||
- **THEN** в `evidence/rollout/<метка>/` есть посекундная шкала, таблица
|
||||
шагов по каждой заменённой реплике, сводка, контейнеры и образы до и
|
||||
после, код выхода 0
|
||||
|
||||
#### Scenario: Быстрый профиль
|
||||
|
||||
- **WHEN** выполнен `make bench_rollout_quick`
|
||||
- **THEN** за несколько минут проходит замена всех реплик, код выхода 0,
|
||||
каталог метки в git не попадает
|
||||
|
||||
#### Scenario: Версии в ответах
|
||||
|
||||
- **WHEN** замена завершена
|
||||
- **THEN** шкала показывает, как доля ответов старых реплик падает до
|
||||
нуля, а новых растёт до всех, а ответов прежних `X-Instance-Id` после
|
||||
удаления их контейнеров нет
|
||||
|
||||
#### Scenario: Без потерь и дублей при замене
|
||||
|
||||
- **WHEN** нагрузка с записью шла всё время замены
|
||||
- **THEN** после повтора неподтверждённых записей с тем же ключом в чате
|
||||
записи столько сообщений, сколько отправлено ключей, без одинаковых
|
||||
текстов
|
||||
|
||||
#### Scenario: Замена не удалась
|
||||
|
||||
- **WHEN** скрипт замены завершился с ненулевым кодом
|
||||
- **THEN** команда завершается с ненулевым кодом, называет шаг из
|
||||
журнала скрипта, сохраняет частичные результаты и удаляет стенд
|
||||
@@ -0,0 +1,179 @@
|
||||
# Tasks
|
||||
|
||||
Как строить — `design.md` (дальше «решение N»). Что должно получиться —
|
||||
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
|
||||
`balancer.md`, `docker.md`, `migrations.md`, `bench.md`,
|
||||
`run-modes.md`, `repo-layer.md`, `service-layer.md`.
|
||||
|
||||
Рабочий стенд `mtusi-lab3` до задачи 6.1 не трогать миграциями и
|
||||
пересборкой. Его база должна остаться на ревизии `7652184b7016`, а
|
||||
реплики — на прежнем образе: это исходное состояние демонстрации
|
||||
совместимости. Не запускать `make run_docker`, `make upgrade`, `make
|
||||
revision`. Сборка `make test_isolated` двигает тег
|
||||
`mtusi-messenger:lab3`, но не реплики и не базу стенда; задача 6.1 всё
|
||||
равно собирает прежний образ заново.
|
||||
|
||||
Evidence снимается с закоммиченного кода: коммит кода → evidence →
|
||||
коммит evidence. Замер для отчёта (`make bench_rollout`) — только после
|
||||
проверки хоста по брифу, рабочий стенд на время замера остановлен.
|
||||
|
||||
## 1. Приложение: колонка `messages.instance_id`
|
||||
|
||||
- [ ] 1.1 Модель `Message` и ревизия alembic по решению 7:
|
||||
- `instance_id: Mapped[str | None]` (Text, NULL) с комментарием;
|
||||
- ревизия `added message instance id` через `uv run alembic revision
|
||||
--autogenerate` против базы на прежней ревизии, только чтение схемы.
|
||||
Затем вручную: `SET LOCAL lock_timeout = '5s'` первой строкой
|
||||
`upgrade` и комментарий про expand и contract.
|
||||
|
||||
Проверка: `uv run alembic upgrade head` и `downgrade -1` / `upgrade
|
||||
head` на временной базе (не рабочей); `alembic check` после `upgrade`
|
||||
— без расхождений.
|
||||
- [ ] 1.2 `insert_message(..., instance_id)` в repo и передача
|
||||
`settings.app.instance_id` из `MessageService.send_message`; DTO и
|
||||
ответ API не меняются. Проверка: `make lint`; после задачи 5.2 строка
|
||||
сообщения, записанного через API, содержит `instance_id` =
|
||||
`X-Instance-Id` ответа.
|
||||
|
||||
## 2. Балансировщик и скрипт замены
|
||||
|
||||
- [ ] 2.1 `infra/haproxy/haproxy.cfg`: `stats socket
|
||||
ipv4@127.0.0.1:9999 level admin` в `global` с комментарием (решение
|
||||
2). Проверка: `haproxy -c` в закреплённом образе с `API_PORT=8080` —
|
||||
`Configuration file is valid`.
|
||||
- [ ] 2.2 `scripts/rolling-update.sh` по решениям 1–6 (исполняемый бит
|
||||
в git). Внутри:
|
||||
- предусловия;
|
||||
- сборка из рабочего дерева или `ROLLOUT_COMMIT`;
|
||||
- миграция один раз, `ROLLOUT_MIGRATE=0` — пропуск;
|
||||
- цикл замены: ожидание `healthy` и `UP` по адресу, `drain` →
|
||||
`scur` = 0 → `maint` → `stop` → `rm` → адрес ушёл → `ready`;
|
||||
- итоговая проверка;
|
||||
- `trap` с состояниями решения 5;
|
||||
- строки `HH:MM:SS rolling-update: …` с контейнером, слотом и адресом;
|
||||
- секретов не печатает.
|
||||
|
||||
Цель `make rolling_update` (`API_REPLICAS`, `COMMIT`, `MIGRATE`).
|
||||
Проверка: задачи 5.2 и 6.1–6.2.
|
||||
|
||||
## 3. Профиль `rollout` стенда `bench/`
|
||||
|
||||
- [ ] 3.1 `bench/rollout.py` (решение 8): разбор строк скрипта, событий
|
||||
Docker проекта и журнала LB по шагам замены; шкала с `old_ok` /
|
||||
`new_ok`; окна до, во время и после; строка прогона; строки по
|
||||
репликам; `summary.md`. Только stdlib, парсеры — из `failover.py`.
|
||||
- [ ] 3.2 `bench/run.py`:
|
||||
- профили `rollout` и `rollout_quick`, поля `Profile`;
|
||||
- `--from` для отладки;
|
||||
- образ прежнего commit через `git archive`, тег `bench-from` и
|
||||
`docker tag`;
|
||||
- общая подготовка с `failover`;
|
||||
- запуск `scripts/rolling-update.sh` с окружением compose стенда;
|
||||
- сбор событий, журнала LB и строк скрипта;
|
||||
- повтор, сверка, итоговые проверки;
|
||||
- каталог `evidence/rollout/<метка>/`, снятие тега при уборке.
|
||||
|
||||
Цели `bench_rollout` (`ROLLOUT_LABEL ?= baseline`) и
|
||||
`bench_rollout_quick` в `Makefile`, `evidence/rollout/quick-*/` в
|
||||
`.gitignore`. Проверка: `make lint`; `make bench_rollout_quick` —
|
||||
код 0, замена двух реплик, сверка сошлась, `summary.md` и
|
||||
`replicas.csv` с шагами; занятая метка — отказ до стенда.
|
||||
|
||||
## 4. Документы
|
||||
|
||||
- [ ] 4.1 Правила под решения:
|
||||
- `balancer.md` — порядок «сборка → миграции», дренаж, состояния
|
||||
слота, сбой, runtime API;
|
||||
- `migrations.md` — новая ревизия, `lock_timeout`, откат кода без
|
||||
отката схемы;
|
||||
- `bench.md` — профиль `rollout`;
|
||||
- `run-modes.md` — 502 гонки keep-alive остаётся только у остановки
|
||||
без дренажа;
|
||||
- `docker.md` — `run_docker` и обновление по решению 9.
|
||||
|
||||
`AGENTS.md`:
|
||||
- команды — `rolling_update`, `bench_rollout`, `bench_rollout_quick`;
|
||||
- карта кода — `rolling-update.sh` без «(лаба 3)», `bench/rollout.py`,
|
||||
`evidence/rollout/`;
|
||||
- «Переходное состояние» — закрытый пункт убрать.
|
||||
|
||||
Скилл `run-mtusi-messenger` — новая цель. Проверка: `grep -n
|
||||
"rolling-update" AGENTS.md .claude/rules/*.md` — нет обещаний «будет».
|
||||
|
||||
## 5. Общая проверка кода и коммит
|
||||
|
||||
- [ ] 5.1 `make lint`, `make check`, `openspec validate rolling-update
|
||||
--strict`, `haproxy -c`. Проверка: все с кодом 0.
|
||||
- [ ] 5.2 Самопроверки на своих стендах, рабочий не трогается:
|
||||
- `make test_isolated` — новая ревизия на временной базе, smoke и
|
||||
набор;
|
||||
- `make failure_checks`;
|
||||
- `make bench_rollout_quick`;
|
||||
- `make bench_failover_quick`;
|
||||
- `make bench_quick`.
|
||||
|
||||
Затем коммит кода (`feat: …`). Проверка: все с кодом 0, рабочее
|
||||
дерево чистое.
|
||||
|
||||
## 6. Evidence с commit кода
|
||||
|
||||
- [ ] 6.1 Совместимость и `make run_docker` на рабочем стенде (решения 6,
|
||||
7, 9; `evidence/rollout/compatibility.md`):
|
||||
- реплики на образе `c50b721` (`git archive`), LB пересоздан с новым
|
||||
`haproxy.cfg`, ревизия `7652184b7016`, `make test`;
|
||||
- `docker compose build api` и `docker compose --dry-run up -d` —
|
||||
исход решения 9;
|
||||
- `docker compose run --rm migrate` — новая ревизия при прежних
|
||||
репликах, затем `make test` и `make student_test` на них;
|
||||
- `make rolling_update` под `tests/load.py`;
|
||||
- откат `make rolling_update COMMIT=c50b721 MIGRATE=0` под нагрузкой;
|
||||
- снова `make rolling_update`;
|
||||
- `make test` и `make student_test`;
|
||||
- `docker compose ps` и образы на каждом шаге;
|
||||
- `instance_id` сообщений по версиям.
|
||||
|
||||
Исход решения 9 — в `KNOWN_ISSUES.md` (и `Makefile`, если дефект
|
||||
подтвердился). Проверка: в файле на каждом шаге команда, код выхода и
|
||||
наблюдение.
|
||||
- [ ] 6.2 Отказы скрипта (`evidence/rollout/script-failures.md`):
|
||||
- остановленная реплика (`stop-one.sh`) и `API_REPLICAS=3` —
|
||||
отказ до сборки;
|
||||
- `ROLLOUT_READY_TIMEOUT=1` — новая удалена, N реплик `UP`;
|
||||
- Ctrl+C во время дренажа — старая доведена до удаления, слоты
|
||||
чистые;
|
||||
- миграция не получила блокировку (открытая транзакция на `messages`
|
||||
в `psql`) — замена не начиналась, повтор после конца транзакции
|
||||
прошёл (на временной базе или до 6.1);
|
||||
- порт 9999 LB из другого контейнера сети — отказ соединения.
|
||||
|
||||
Проверка: после каждого случая `make lb_stats` — N реплик `UP`, слотов
|
||||
`DRAIN` / `MAINT` вне DNS нет.
|
||||
- [ ] 6.3 Регрессия на commit кода (`evidence/tests/rolling-update-checks.md`):
|
||||
- `make test`, `make student_test` через LB;
|
||||
- `make test-persistence ACTION_SCRIPT=scripts/restart.sh`;
|
||||
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` в режимах
|
||||
`stop` и `kill`, `make replicas` между ними;
|
||||
- выводы 5.1–5.2.
|
||||
|
||||
Проверка: в шапке — спеки, change, дата, commit, стенд, хост.
|
||||
- [ ] 6.4 Хост по брифу: питание, давление на память, `docker ps`,
|
||||
`docker info`, `vm_stat` (`Swapouts`) до и после. Затем `make stop`,
|
||||
`nohup make bench_rollout` с журналом, после — снова рабочий стенд.
|
||||
Проверка: `evidence/rollout/baseline/` со статусом `complete`, сверка
|
||||
сошлась; плохой хост — Telegram и остановка (бриф).
|
||||
- [ ] 6.5 `REPORT.md` по решению 10:
|
||||
- строки доказательств уровня «4» вместо TODO;
|
||||
- процедура замены;
|
||||
- раздел профиля `rollout` в «Эксперименты и отказы»;
|
||||
- ограничения;
|
||||
- ответы на вопросы защиты.
|
||||
|
||||
Проверка: у каждой новой строки есть команда, наблюдение и файл; в
|
||||
evidence и отчёте нет паролей, токенов и абсолютных путей домашнего
|
||||
каталога.
|
||||
- [ ] 6.6 Финал:
|
||||
- `make lint`, `openspec validate rolling-update --strict`;
|
||||
- отметить задачи, коммит evidence и отчёта (`docs: …`);
|
||||
- `graphify update .`;
|
||||
- рабочий стенд `mtusi-lab3` поднят, все реплики `UP`;
|
||||
- рабочее дерево чистое.
|
||||
Reference in New Issue
Block a user