Files
mtusi2026lab3/evidence/rollout/compatibility.md
T

15 KiB
Raw Blame History

Совместимость миграции и поочерёдная замена на рабочем стенде

Спеки db-migrations «Совместимость миграции с работающей версией» — «Старый образ на новой схеме», «Запись прежней версии»; «Однократные миграции при замене реплик» — «Одна миграция на замену»; load-balancing «Поочерёдная замена реплик» — «Замена двух реплик», «Замена под нагрузкой»; «Вывод реплики из балансировщика перед остановкой» — «Слот после замены»
Change rolling-update, задача 6.1 (design, решения 1, 3, 6, 7, 9)
Дата 2026-10-10, 21:50–21:55 UTC; шаг G — 22:02–22:06 UTC
Commit шаги A–F — d2148ac (код change); шаг G — de654a1 (исправление шага миграций в скрипте, найдено регрессией); прежняя версия — c50b721 (последний commit до change, образ собран git archive c50b721 | docker build)
Стенд make run_docker: проект mtusi-lab3, HAProxy на 127.0.0.1:8080, api × 2 (API_REPLICAS=2), Postgres и Valkey с данными прежних проверок
Хост Docker Desktop 29.8.2 (Compose 5.5.1, хранилище образов containerd), macOS 26.6.2 arm64; ВМ Docker: 12 CPU, 7,7 GiB RAM

Нагрузка во время замены — публичный tests/load.py (закрытая модель, 4 клиента, новое соединение на запрос, POST сообщения с ключом) через LB. Снимки стенда — ID реплик, digest конфигурации образа контейнера, ревизия схемы и make lb_stats. Короткие ID и digest обрезаны до 12 знаков.

A. Реплики на образе прежнего commit, схема прежняя

git archive --format=tar c50b721 | docker build -q -t mtusi-messenger:lab3 -
docker compose up -d --no-build                       # реплики и migrate пересозданы на образе c50b721
docker compose up -d --no-deps --force-recreate haproxy   # haproxy.cfg с runtime API
tag mtusi-messenger:lab3 -> sha256:b356ab3d4f29
container              instance      state    image-config          started
mtusi-lab3-api-1       08712146e7fb  running  sha256:b356ab3d4f29   2026-10-10T21:50:25
mtusi-lab3-api-2       dbbdd88923ce  running  sha256:b356ab3d4f29   2026-10-10T21:50:25
revision: 7652184b7016
api-1          172.30.0.5:8080  UP      L7OK
api-2          172.30.0.4:8080  UP      L7OK

make test — PASS: lab3 public API scenario.

B. Пересборка и make run_docker (пункт KNOWN_ISSUES.md)

KNOWN_ISSUES.md утверждал: после пересборки образа make run_docker не пересоздаёт работающие api. Проверка, design, решение 9:

  1. В шаге A тег mtusi-messenger:lab3 указывал на образ, собранный make test_isolated из рабочего дерева. Реплики при этом работали на более раннем образе: docker ps показывал у них 04f700d0d939, а не имя тега. docker compose up -d --no-build после смены тега пересоздал обе реплики: новые ID 08712146e7fb, dbbdd88923ce.

  2. docker compose build api (образ d2148ac), затем docker compose --dry-run up -d:

    tag now: sha256:6ed315047cd7 platform manifest: sha256:93a0ad718b78
    mtusi-lab3-api-1 image sha256:b356ab3d4f29 label sha256:043a9c9b6cde
    mtusi-lab3-api-2 image sha256:b356ab3d4f29 label sha256:043a9c9b6cde
     Container mtusi-lab3-migrate-1 Recreate
     Container mtusi-lab3-api-1 Recreate
     Container mtusi-lab3-api-2 Recreate
    

    Compose пересоздал бы обе реплики. --dry-run ничего не менял: реплики после него — те же 08712146e7fb, dbbdd88923ce.

  3. Пересборка без изменений кода (после шага G) даёт новый digest тега: sha256:4e3c79dd7c34 вместо 16beb9f9faeb — индекс образа содержит отметки времени сборки. --dry-run up -d при этом пересоздал бы только migrate, а реплики оставил бы (api-7 Running, api-8 Running).

Вывод: дефект не воспроизводится. Compose сравнивает метку контейнера com.docker.compose.image (манифест платформы) с манифестом тега и пересоздаёт реплики только при изменении содержимого образа. В хранилище containerd у образа три разных digest: индекс (docker image inspect тега), манифест платформы (метка контейнера) и конфигурация (поле .Image контейнера). docker ps показывает у реплик digest конфигурации, а не имя тега. Отсюда, вероятно, и ошибка диагностики verify replicas-lb. Пункт закрыт. make run_docker пересоздаёт изменённые реплики разом (простой), без простоя — make rolling_update.

C. Новая миграция, реплики прежние

docker compose run --rm --no-deps -T migrate          # образ d2148ac
"event": "Running upgrade 7652184b7016 -> e656d6bbe1a4, added message instance id"
container              instance      state    image-config
mtusi-lab3-api-1       08712146e7fb  running  sha256:b356ab3d4f29
mtusi-lab3-api-2       dbbdd88923ce  running  sha256:b356ab3d4f29
revision: e656d6bbe1a4

На прежнем образе и новой схеме:

  • make test — PASS: lab3 public API scenario;
  • make student_test через LB — 131 passed, 15 deselected, гонка ключа через обе реплики {'08712146e7fb': 5, 'dbbdd88923ce': 5};
  • отправка через прежнюю реплику (X-Instance-Id: 08712146e7fb) — 201, в строке сообщения instance_id = NULL: прежний код колонку не знает.

D. make rolling_update под нагрузкой

python3 tests/load.py --duration 45 --concurrency 4 &   # через LB
make rolling_update                                     # через 6 с после старта нагрузки
21:51:53 rolling-update: start: 2 replicas 08712146e7fb dbbdd88923ce, image mtusi-messenger:lab3 from working tree
21:51:53 rolling-update: build done in 0s
21:51:55 rolling-update: migrate done in 2s
21:51:56 rolling-update: replica 1/2: started new 6e54da9d61bc
21:51:58 rolling-update: replica 1/2: new 6e54da9d61bc addr 172.30.0.7 slot api-3 UP in 2s
21:51:58 rolling-update: replica 1/2: drain old 08712146e7fb addr 172.30.0.5 slot api-1
21:51:58 rolling-update: replica 1/2: old 08712146e7fb idle after 0s
21:51:58 rolling-update: replica 1/2: maint slot api-1, stopping old 08712146e7fb
21:51:59 rolling-update: replica 1/2: removed old 08712146e7fb (stop 1s)
21:52:00 rolling-update: replica 1/2: slot api-1 ready
21:52:00 rolling-update: replica 2/2: started new 6985db2f2de9
21:52:03 rolling-update: replica 2/2: new 6985db2f2de9 addr 172.30.0.5 slot api-1 UP in 3s
21:52:03 rolling-update: replica 2/2: drain old dbbdd88923ce addr 172.30.0.4 slot api-2
21:52:03 rolling-update: replica 2/2: old dbbdd88923ce idle after 0s
21:52:03 rolling-update: replica 2/2: maint slot api-2, stopping old dbbdd88923ce
21:52:04 rolling-update: replica 2/2: removed old dbbdd88923ce (stop 1s)
21:52:06 rolling-update: replica 2/2: slot api-2 ready
21:52:06 rolling-update: done: 2 replicas 6e54da9d61bc 6985db2f2de9 UP in 13s

Код выхода 0. Миграция в этом запуске — no-op: схема уже на e656d6bbe1a4 (шаг C), строки Running upgrade нет. Нагрузка tests/load.py: 25 347 успешных, 0 неуспешных за 45 с, p95 10,5 мс, p99 14,5 мс.

Журнал LB (docker compose logs -t haproxy, строки слотов):

21:51:57.888 Server api/api-3 is UP, reason: Layer7 check passed
21:51:58.403 Server api/api-1 enters drain state
21:51:58.582 Server api/api-1 is going DOWN for maintenance. … 0 sessions active
21:52:00.404 Server api/api-1 is leaving forced maintenance but remains in maintenance.
21:52:01.018 Server api/api-1 ('api') is DOWN/READY (resolves again).
21:52:03.007 Server api/api-1 is UP, reason: Layer7 check passed
21:52:03.628 Server api/api-2 enters drain state
21:52:03.802 Server api/api-2 is going DOWN for maintenance. … 0 sessions active
21:52:06.365 Server api/api-2 is leaving forced maintenance but remains in maintenance.

Новая реплика второго шага (6985db2f2de9) получила адрес 172.30.0.5 и слот api-1 только что удалённой старой: IPAM Docker переиспользует адрес сразу. Поэтому слот возвращается в ready до следующего --scale: в maint её бы не включили. Ошибок соединения с выводимой репликой нет, она не получала запросов: econ 0, hrsp_5xx 0 у всех слотов после замены.

container              instance      state    image-config
mtusi-lab3-api-3       6e54da9d61bc  running  sha256:590bff231344
mtusi-lab3-api-4       6985db2f2de9  running  sha256:590bff231344
revision: e656d6bbe1a4
api-1          172.30.0.5:8080  UP  L7OK  scur 0  stot 11689  econ 0  hrsp_5xx 0
api-3          172.30.0.7:8080  UP  L7OK  scur 0  stot 8973   econ 0  hrsp_5xx 0
free slots: 6

Отправка через новую реплику: X-Instance-Id: 6e54da9d61bc, в строке сообщения instance_id = 6e54da9d61bc.

E. Откат на прежний образ под нагрузкой

python3 tests/load.py --duration 40 --concurrency 4 &
make rolling_update COMMIT=c50b721 MIGRATE=0
21:53:00 rolling-update: start: 2 replicas 6e54da9d61bc 6985db2f2de9, image mtusi-messenger:lab3 from c50b721
21:53:01 rolling-update: build done in 1s
21:53:01 rolling-update: migrate skipped (ROLLOUT_MIGRATE=0)
…
21:53:10 rolling-update: done: 2 replicas 81ce353200b0 d82b6f337b9f UP in 10s

Код выхода 0. Нагрузка — 20 114 успешных, 0 неуспешных. Реплики снова на образе c50b721, схема осталась e656d6bbe1a4, make test — PASS. Откат кода не потребовал отката схемы.

F. Снова вперёд под нагрузкой

python3 tests/load.py --duration 40 --concurrency 4 &
make rolling_update

Код выхода 0, замена за 14 с (f8d83d5a98e8, a9decf1ea3fa); миграция — no-op. Нагрузка — 20 713 успешных, 0 неуспешных.

mtusi-lab3-api-7 Up About a minute (healthy)
mtusi-lab3-api-8 Up About a minute (healthy)
mtusi-lab3-haproxy-1 Up 4 minutes (healthy)
mtusi-lab3-migrate-1 Exited (0) 4 minutes ago
mtusi-lab3-postgres-1 Up About an hour (healthy)
mtusi-lab3-valkey-1 Up About an hour (healthy)

Контейнеров прежних реплик нет ни работающих, ни остановленных. make test — PASS. make student_test — 131 passed, гонка ключа через обе новые реплики {'a9decf1ea3fa': 5, 'f8d83d5a98e8': 5}. В журналах реплик записей alembic нет: миграции выполнял только одноразовый контейнер.

G. Регрессия нашла дефект: контейнер migrate прежнего образа (commit de654a1)

После шагов A–F регрессия make test-persistence ACTION_SCRIPT=scripts/restart.sh упала: FAIL: restart hook failed. Ручной запуск hook:

mtusi-lab3-migrate-1 fa0b32e4ccc5 Exited (255) 5 seconds ago
 Container mtusi-lab3-migrate-1 Error service "migrate" didn't complete successfully: exit 255

Причина. Скрипт на d2148ac выполнял миграции одноразовым docker compose run --rm migrate. Контейнер самого сервиса migrate оставался от шага A, на образе c50b721. restart.sh делает start api, а compose при этом запускает зависимость migrate, тот же контейнер. Миграции c50b721 не знают ревизии e656d6bbe1a4 → «Can't locate revision», exit 255, реплики не стартуют.

Исправление (de654a1, design, решение 1): скрипт пересоздаёт контейнер сервиса на новом образе и выполняет миграцию в нём — docker compose up --no-deps --no-build --force-recreate --abort-on-container-exit --exit-code-from migrate migrate. Код выхода миграции передаётся, ошибка по-прежнему останавливает замену до новых реплик (evidence/rollout/script-failures.md, случай 5, повтор).

Повтор на рабочем стенде с de654a1 (стенд вернули docker compose up --no-deps --force-recreate … migrate и docker compose start api haproxy):

python3 tests/load.py --duration 35 --concurrency 4 &   # через LB
make rolling_update
22:05:02 rolling-update: start: 2 replicas 4180517b395f 5985a2b69f72, image mtusi-messenger:lab3 from working tree
22:05:05 rolling-update: migrate done in 2s
22:05:13 rolling-update: done: 2 replicas a7126827af39 b167830351fc UP in 11s
load: 19 199 успешных, 0 неуспешных

mtusi-lab3-api-12     sha256:0bf9d024b759…
mtusi-lab3-api-13     sha256:0bf9d024b759…
mtusi-lab3-migrate-1  sha256:0bf9d024b759…   Exited (0)

migrate теперь на том же образе, что реплики. make test-persistence ACTION_SCRIPT=scripts/restart.sh — PASS: перезапущены LB, обе реплики, Postgres и Valkey, у всех новый StartedAt (evidence/tests/rolling-update-checks.md).

Какая версия записала сообщения

Сообщения за время шагов D–F (21:51:40–21:54:40 UTC) по колонке instance_id:

instance_id  | count | first    | last
NULL         | 31234 | 21:51:47 | 21:54:00
6e54da9d61bc | 10821 | 21:51:58 | 21:53:03
6985db2f2de9 | 10516 | 21:52:03 | 21:53:08
f8d83d5a98e8 |  7543 | 21:53:54 | 21:54:24
a9decf1ea3fa |  6063 | 21:54:00 | 21:54:24
  • NULL — записи реплик образа c50b721: до замены D и между откатом E и шагом F.
  • Остальное — реплики образа d2148ac, значение равно их X-Instance-Id.

Версии сменяли друг друга без ошибок клиента. Обе пишут в одну схему.