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>
44 KiB
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: файла.
-
Предусловия (ничего не меняют):
- работает ровно
API_REPLICASреплик (по умолчанию 2); - остановленных реплик сервиса нет. Иначе
up --scaleзапустил бы остановленную старую вместо новой; - все реплики
UPв LB; API_REPLICAS+ 1 ≤ числа слотов LB;- нет слотов с ручным
drainилиmaint(решение 12).
Нарушение — код 2 и подсказка
make replicas. - работает ровно
-
Сборка. По умолчанию
docker compose build apiиз рабочего дерева. СROLLOUT_COMMIT=<commit>образ собирается из файлов commit (решение 6) под тем же тегом сервиса. Тег берётся из.Config.Imageработающей реплики:docker compose config --images apiпечатает ещё и образы зависимостей. -
Миграции один раз — на только что собранном образе. Ошибка — код 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падал. -
Новая реплика:
docker compose up -d --no-deps --no-recreate --no-build --scale api=N+1 api. Новая — та, ID которой не было до команды. -
Ожидание готовности (решение 4).
-
Вывод и удаление старой (решение 3).
-
Шаги 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/ready503 и ещё ≥ 1,5 с принимает запросы, пока LB её не исключит. Минусы:- меняется спек
graceful-shutdown(«после SIGTERM новые соединения не принимаются»); - нужен свой обработчик сигнала поверх uvicorn;
- остановка удлиняется до 1,5 + 8 с — впритык к
stop_grace_period10 с; - срок
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. Состояния слота старой реплики
set server api/<слот> state drain. Новых запросов нет, начатые дорабатывают (разведка).- Ожидание
scur= 0 (запросов в полёте) не дольшеROLLOUT_DRAIN_TIMEOUT= 12 с. Это большеtimeout server10 с: дольше запрос через LB не живёт. По сроку — предупреждение и остановка: оставшееся доработает graceful uvicorn (8 с). state maint— проверки слота остановлены. Гибель процесса не пишет в журналDOWNс ошибкой соединения, и слот не может вернуться в распределение по проверкам, пока процесс ещё отвечает.docker stop --timeout 10(=stop_grace_period),docker rm. Простаивающие соединения LB с репликой uvicorn закрывает при SIGTERM. LB их больше не выбирает: слот выведен. Поэтому гонки keep-alive нет.- Ожидание, пока адрес уйдёт из слота: DNS
hold1 с, не дольше 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 с:
- Контейнер
healthy, если у него есть healthcheck (рабочий стенд: healthcheck образа,start_interval1 с), иначеrunning. На стендеbench/healthcheck выключен. - Слот с адресом новой реплики в состоянии
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= до + бюджет + после,PHASE1. Через «до» секунд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измеряется по строкам скрипта (секунды). - события Docker:
-
Окна ошибок. «До» — запросы, завершённые до
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, затем:
docker compose build api(новый образ);docker compose --dry-run up -d;- метки контейнеров против
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_timeout5 с равнялсяstatement_timeoutприложения (5 с). Повтор случая «миграция не получила блокировку» под нагрузкой (4 записи и 2 чтения подряд через LB): все 6 запросов, вставших в очередь заALTER, через 5,03 с получили 503 —canceling statement due to statement timeoutв журнале реплик. Их срок истекал одновременно с отказом миграции. Теперьlock_timeout2 с: очередь ждёт до 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_timeout2 с может не хватить под тяжёлой записью] → миграция падает без изменений, замена не начинается, повтор проходит. Это лучше, чем очередь всех записей за миграцией. Без нагрузки блокировка берётся за миллисекунды. Больше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
- Код, ревизия, скрипт и конфиг LB коммитятся. Рабочий стенд получает
их одной командой
make rolling_update: новая ревизия применяется, реплики заменяются.haproxy.cfgс runtime API подхватывается пересозданием LB (docker compose up -d --force-recreate --no-deps haproxy: правку смонтированного файла compose не видит). Это короткий перерыв точки входа, а не реплик. Делается один раз, до первой замены: без канала управления скрипт останавливается в предусловиях. - Откат кода —
make rolling_update COMMIT=<прежний> MIGRATE=0. Схема остаётся новой, прежний код на ней работает. Колонку удаляет только отдельная contract-миграция, когда прежнего кода точно нет.