With lock_timeout equal to statement_timeout (5 s) every request queued behind a migration waiting for its lock failed with 503 together with the migration. A 2 s lock timeout lets the queue proceed once the migration gives up. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
578 lines
44 KiB
Markdown
578 lines
44 KiB
Markdown
# 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;
|
||
- нет слотов с ручным `drain` или `maint` (решение 12).
|
||
|
||
Нарушение — код 2 и подсказка `make replicas`.
|
||
1. **Сборка.** По умолчанию `docker compose build api` из рабочего
|
||
дерева. С `ROLLOUT_COMMIT=<commit>` образ собирается из файлов
|
||
commit (решение 6) под тем же тегом сервиса. Тег берётся из
|
||
`.Config.Image` работающей реплики: `docker compose config --images
|
||
api` печатает ещё и образы зависимостей.
|
||
2. **Миграции один раз** — на только что собранном образе. Ошибка —
|
||
код 1 до замены. Скрипт миграций не запускает при
|
||
`ROLLOUT_MIGRATE=0` (откат, решение 6). Порядок «сборка →
|
||
миграции», а не наоборот, как в `balancer.md`: новые ревизии лежат в
|
||
новом образе. Правило исправляется.
|
||
|
||
Команда — `docker compose up --no-deps --no-build --force-recreate
|
||
--abort-on-container-exit --exit-code-from migrate migrate`:
|
||
пересоздаётся контейнер самого сервиса `migrate`. Первый вариант
|
||
(`docker compose run --rm --no-deps migrate`) регрессия apply
|
||
опровергла. Одноразовый контейнер оставлял в стенде `migrate`
|
||
прежнего образа. `scripts/restart.sh` (`start api` запускает его
|
||
как зависимость) гонял старые миграции на новой схеме — «Can't
|
||
locate revision», exit 255, реплики не стартовали, `make
|
||
test-persistence` падал.
|
||
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` (в том числе внутри `up --scale`, когда ID новой ещё не известен — её находит уборка, решение 12) | `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 = '2s'` (в apply было 5 с, решение 12):
|
||
- чужая долгая транзакция не заставит миграцию держать очередь;
|
||
- по сроку миграция падает, схема не меняется, и замена не
|
||
начинается (спек `db-migrations`);
|
||
- запросы, вставшие в очередь за миграцией, дожидаются её отказа и
|
||
выполняются: срок меньше `statement_timeout` приложения (5 с);
|
||
- повторный запуск проходит.
|
||
- `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 events --since` после прогона. Демон хранит
|
||
только последние 256 событий, а каждый `docker exec` (скрипт опрашивает
|
||
LB, оркестратор — статистику) даёт три. В первой самопроверке событий
|
||
миграции и старых реплик к концу прогона уже не было. Шаги каждой
|
||
реплики берутся из трёх источников:
|
||
- события 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 при замене;
|
||
- раздел «Обновление без простоя и миграции» в ответах на вопросы
|
||
защиты.
|
||
|
||
### 11. Найдено в apply (2026-10-10)
|
||
|
||
- **Миграция в контейнере сервиса `migrate`, а не `run --rm`** (решение
|
||
1, шаг 2). Регрессия `make test-persistence` после замены упала:
|
||
`restart.sh` запускал оставшийся `migrate` прежнего образа, и тот
|
||
падал на новой ревизии (exit 255). Исправлено в `de654a1`, evidence
|
||
переснято (`compatibility.md`, шаг G; `script-failures.md`, случай 5).
|
||
- **Поток событий Docker в профиле `rollout`** (решение 8). Буфер
|
||
демона — 256 событий, `docker exec` их вытесняют. Тот же риск у
|
||
профиля `failover` — в `KNOWN_ISSUES.md`.
|
||
- **Неготовая новая реплика убирается `docker rm -f` после `maint`
|
||
слота** (Risks). Её SIGTERM теряется, пока процесс с PID 1 не
|
||
поставил обработчики (`KNOWN_ISSUES.md`).
|
||
- **IPAM переиспользует адрес сразу** (решение 3) — подтверждено, отсюда
|
||
порядок «адрес ушёл → `ready` → следующий `--scale`».
|
||
- **`make run_docker`** — дефект не воспроизвёлся (решение 9, первый
|
||
исход). Пункт `KNOWN_ISSUES.md` закрыт, в `docker.md`, `Makefile` и
|
||
`REPORT.md` — что делает `run_docker` и чем обновлять без простоя.
|
||
|
||
### 12. Найдено в verify (2026-10-11)
|
||
|
||
- **Уборка теряла новую реплику при прерывании внутри `up --scale`.**
|
||
`state=starting` выставлялся до `up --scale`, а `new_id` — после поиска
|
||
новой. Ctrl+C внутри `up` на первом шаге: `new_id` пуст, уборка
|
||
печатала `docker rm -f` без ID и оставляла N + 1 реплик (воспроизведено
|
||
на `69ebf5c` настоящим Ctrl+C через псевдотерминал: «3 api replicas
|
||
running»). На втором шаге хуже: в `new_id` ещё лежала новая реплика
|
||
первого шага, уже рабочая, и уборка удалила бы её. Исправление:
|
||
`new_id` сбрасывается до `state=starting`, а `remove_new` при пустом
|
||
ID ищет новую сама — контейнер, которого не было до `up --scale`
|
||
(`find_new`).
|
||
- **Слот, оставленный в ручном состоянии, не виден.** Если уборка сама
|
||
не удалась, слот остаётся в `maint` или `drain`. У слота без адреса
|
||
`show stat` и `make lb_stats` показывают `MAINT (resolution)` и для
|
||
ручного, и для DNS-обслуживания; различает только `srv_admin_state`
|
||
в `show servers state` (флаги 1 — `maint`, 8 — `drain`, 32 — DNS).
|
||
Следующая реплика в таком слоте не получила бы запросов, и замена
|
||
упала бы через 60 с ожидания `UP`. Теперь это предусловие: код 2 до
|
||
сборки, имя слота и готовая команда `set server … state ready`. Та же
|
||
команда целиком — в подсказках ручной уборки.
|
||
- **Код выхода старой реплики** — в строке `removed old … (stop Ns, exit
|
||
N)`: 0 — graceful, 137 — SIGKILL по сроку (спек `graceful-shutdown`,
|
||
«Остановка за заявленный срок после дренажа»). Контейнер удаляется
|
||
сразу, без строки код выхода не восстановить.
|
||
- **`lock_timeout` 5 с равнялся `statement_timeout` приложения (5 с).**
|
||
Повтор случая «миграция не получила блокировку» под нагрузкой (4
|
||
записи и 2 чтения подряд через LB): все 6 запросов, вставших в очередь
|
||
за `ALTER`, через 5,03 с получили 503 — `canceling statement due to
|
||
statement timeout` в журнале реплик. Их срок истекал одновременно с
|
||
отказом миграции. Теперь `lock_timeout` 2 с: очередь ждёт до 2 с и
|
||
выполняется после отказа миграции. Ревизия `e656d6bbe1a4` правится на
|
||
месте, а не новой ревизией поверх: новая ревизия не изменила бы, как
|
||
выполняется уже записанный `ALTER`. Правка меняет только срок
|
||
ожидания, а не итоговую схему, и ревизия ещё не применена ни к одной
|
||
долгоживущей базе: рабочий стенд пересоздан на `7652184b7016` для
|
||
повтора совместимости, стенды `bench/`, `test_isolated` и проверок
|
||
отказов временные.
|
||
- **Откат оставляет тег на прежнем образе.** `docker compose up` без
|
||
сборки пересоздал бы `migrate` на прежнем образе, и он упал бы на
|
||
новой ревизии. Это ограничение отката без отката схемы, а не дефект
|
||
скрипта: правило и отчёт называют его, вперёд — `make
|
||
rolling_update` или `make run_docker`.
|
||
- **Evidence переснято на итоговом commit:** `compatibility.md` и
|
||
`script-failures.md` (их шаги A–F и случаи 1–4 снимались на
|
||
`d2148ac`, до исправления шага миграций), самопроверки быстрых
|
||
профилей — на чистом дереве. Замер `baseline` не переснимался: правки
|
||
не меняют порядок замены и то, что видит клиент (одна `docker
|
||
inspect` после остановки; `lock_timeout` действует только при чужой
|
||
блокировке, а в замере миграция получает её за миллисекунды), а
|
||
быстрый профиль на итоговом commit это подтверждает.
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- **[Канал управления LB — admin-уровень]** → слушает только
|
||
`127.0.0.1` внутри контейнера LB. Проверка — попытка подключиться к
|
||
порту 9999 LB из другого контейнера сети (`script-failures.md`).
|
||
Доступ через `docker exec` равен доступу к Docker, то есть ко всему
|
||
стенду.
|
||
- **[`lock_timeout` 2 с может не хватить под тяжёлой записью]** →
|
||
миграция падает без изменений, замена не начинается, повтор проходит.
|
||
Это лучше, чем очередь всех записей за миграцией. Без нагрузки
|
||
блокировка берётся за миллисекунды. Больше `statement_timeout`
|
||
приложения (5 с) срок брать нельзя, равным — тоже: запросы в очереди
|
||
за миграцией получили бы 503 вместе с её отказом (решение 12).
|
||
- **[Новый код на старой схеме падает]** → только если миграцию
|
||
пропустить при движении вперёд. Скрипт пропускает её лишь по явному
|
||
`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 переиспользует адрес сразу. В apply новая
|
||
реплика второго шага получила адрес и слот только что удалённой
|
||
старой. Поэтому `ready` выставляется после ухода адреса и до
|
||
следующего `--scale`. Слот новой реплики проверяется в шаге ожидания
|
||
по её адресу: если он застрял в ручном состоянии, замена падает по
|
||
сроку с понятной причиной, а не тихо.
|
||
- **[SIGTERM новой реплике во время её старта теряется]** → найдено в
|
||
apply. Процесс с PID 1 без обработчика сигнала SIGTERM игнорирует, а
|
||
обработчики uvicorn ставит только на старте сервера. Поэтому `docker
|
||
stop` неготовой реплики ждал все 10 с. За это время реплика успела
|
||
стать `UP` и получала запросы, пока её не убил SIGKILL. Убирает
|
||
неготовую новую реплику функция `remove_new`:
|
||
- слот уже есть — сначала `maint`;
|
||
- реплика не `UP` — `docker rm -f` без SIGTERM;
|
||
- реплика `UP` — graceful stop.
|
||
|
||
Сама потеря сигнала до старта — в `KNOWN_ISSUES.md`.
|
||
- **[Один хост]** → профиль показывает поведение замены и порядок
|
||
величин, а не распределение. Генератор, LB, реплики, сборка и
|
||
PostgreSQL делят ВМ Docker.
|
||
|
||
## Migration Plan
|
||
|
||
1. Код, ревизия, скрипт и конфиг LB коммитятся. Рабочий стенд получает
|
||
их одной командой `make rolling_update`: новая ревизия применяется,
|
||
реплики заменяются. `haproxy.cfg` с runtime API подхватывается
|
||
пересозданием LB (`docker compose up -d --force-recreate --no-deps
|
||
haproxy`: правку смонтированного файла compose не видит). Это короткий
|
||
перерыв точки входа, а не реплик. Делается один раз, до первой
|
||
замены: без канала управления скрипт останавливается в предусловиях.
|
||
2. Откат кода — `make rolling_update COMMIT=<прежний> MIGRATE=0`. Схема
|
||
остаётся новой, прежний код на ней работает. Колонку удаляет только
|
||
отдельная contract-миграция, когда прежнего кода точно нет.
|