Files
mtusi2026lab3/openspec/changes/rolling-update/design.md
T
ricoromaandClaude Opus 5.5 d2148ac566 feat: add rolling update with LB drain and rollout load profile
scripts/rolling-update.sh (make rolling_update) replaces API replicas one
by one: build, migrations once, new replica UP in HAProxy, old replica
drained and put into maintenance through the LB runtime API on loopback,
then stopped and removed; the slot is reset once DNS drops the address.
Expand migration adds messages.instance_id with a lock timeout. The bench
rollout profile runs the same script under constant load, starting from
the image of an older commit built with git archive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 00:49:50 +03:00

490 lines
35 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.
# 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 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 при замене;
- раздел «Обновление без простоя и миграции» в ответах на вопросы
защиты.
## 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 переиспользует адрес сразу. В 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 haproxy`). Это короткий
перерыв точки входа, а не реплик. Делается один раз, до первой
замены: без канала управления скрипт останавливается в предусловиях.
2. Откат кода — `make rolling_update COMMIT=<прежний> MIGRATE=0`. Схема
остаётся новой, прежний код на ней работает. Колонку удаляет только
отдельная contract-миграция, когда прежнего кода точно нет.