Плейбуки миграций
1) Классификация миграций
Схемы БД: добавление/изменение колонок, индексы, шардирование, смена типа ключей.
Данные: массовый backfill/cleanup, нормализация, ретеншн/архивация.
Сервисы и API: смена эндпоинтов, версионирование, рефакторинг контрактов.
Очереди/шины: переезд топиков, изменение ключей партиционирования, формат событий.
Инфраструктура: переход в новый кластер/K8s/облако/регион, смена секретов/KMS.
Хранилища и аналитика: смена движка (OLTP/OLAP), формат/партиционирование датасетов.
Безопасность/комплаенс: ротация ключей, шифрование «на лету», гео-локализация данных.
2) Принципы успешной миграции
1. Expand → Migrate → Contract. Сначала расширяем схему/поведение (совместимо), затем переносим данные/трафик, потом убираем старое.
2. Shadow & Dual. Теневая проверка (shadow read/write) и двойная запись для валидации.
3. Фича-флаги и «красная кнопка». Быстрое отключение, пошаговое включение (персентиль/тенанты/регионы).
4. Идемпотентность и повторяемость. Скрипты и задачи можно перезапускать без побочных эффектов.
5. Наблюдаемость прежде изменений. Дашборды/алерты заранее, маркеры миграции в логах/трейсах.
6. Откат документирован. Runbook отката так же подробен, как и план вперед.
7. Мини-партии и паузы. Мигрируем небольшими порциями, проверяя SLI и бизнес-инварианты.
3) Инвентаризация и анализ зависимости
Карта потребителей: сервисы, джобы, отчеты, внешние партнеры, BI/ETL, вебхуки.
Контракты и схемы: версии API/событий, совместимость backward/forward.
Доступы/секреты: кто читает/пишет, где кеши/реплики.
Инварианты домена: уникальность, баланс, идемпотентность, отчетные сутки.
Объемы/скорости: размер данных, RPS, пиковые окна, RPO/RTO.
4) Канонический шаблон плейбука (YAML-скелет)
yaml playbook: "migrate-orders-to-v2"
owner: "orders-team"
stakeholders: ["platform", "data", "security", "support"]
change_type: ["schema", "data", "api"]
risk_level: "high"
preconditions:
- "Dashboards ready: latency/error/lag"
- "Runbook rollback validated on stage"
- "Backups verified (restore tested)"
plan:
phase_1_prepare:
steps:
- "Add new nullable columns (expand)"
- "Deploy code with dual-write (flag off)"
- "Enable CDC stream to target"
phase_2_shadow:
steps:
- "Shadow-read v2, compare with v1 (1%)"
- "Fix discrepancies; iterate"
phase_3_dual_write:
steps:
- "Enable dual-write (10%→50%→100%)"
- "Start backfill in batches (size=10k, sleep=200ms)"
phase_4_cutover:
steps:
- "Switch reads to v2 by tenants (canary)"
- "Monitor SLI 30m; expand scope"
phase_5_contract:
steps:
- "Drop old indices/columns after T+14d"
- "Disable old topic/api; update docs/SDK"
guardrails:
abort_if:
- "error_rate > 0. 5% for 5m"
- "p95 > baseline1. 5 for 10m"
- "data_mismatch > 0. 01%"
rollback:
steps:
- "Flip flag: reads back to v1"
- "Stop backfill; continue dual-write to v1"
- "Replay missed events (DLQ→v1)"
validation:
checks:
- "Row counts match within epsilon"
- "Business invariants hold (balances, limits)"
comms:
- channel: "on-call-bridge"
- status_updates: "T-24h, T-1h, start, cutover, finish"
window: "low-traffic Sun 02:00–05:00 UTC"5) Паттерны миграций
5.1 Схемы БД (RDBMS/NoSQL)
Добавляйте — не изменяйте. Новые nullable колонки/индексы → код читает старое и новое.
Онлайн-перестроение. Используйте онлайн-индексы/параллельные DDL.
Версии сериализации. Версионируйте payload в колонках JSON/Proto/Avro.
Миграция ключей. При смене PK — временная таблица соответствий + триггер/CDC.
5.2 Данные (backfill/cleanup)
CDC + backfill. Сначала поток изменений (чтобы не отставать), затем пакетный backfill.
Партии и дедлайны. Малые батчи с контролем лагов, чекпойнты и повторный запуск.
Идемпотентные апдейты. Upsert по естественным ключам/версиям.
5.3 События и очереди
Версионирование событий. `event_type@vN`, консьюмеры игнорируют незнакомые поля.
Переезд топиков. Двойная публикация, потребители читают из обоих до стабилизации; затем «резка» старого.
Partition key. Миграция ключа — через переиздание с картой соответствий и идемпотентностью.
5.4 Сервисы и API
Blue/Green/Canary. Прогрев пула, частичный трафик, быстрый откат.
Фича-флаги. По тенантам/регионам/процентам, наблюдаемое включение.
Контракты. CDC-контракты и тесты совместимости — до переключения.
5.5 Регионы/клауды
Гео-двойная запись. Данные записываются в два региона; чтения — по близости.
State transfer. Снимок + репликация; «красная линия» RPO, перевалка DNS/Anycast.
Юрисдикции. Согласия/локализация данных, списки «запрещенных» для выноса наборов.
6) Фазы исполнения (детально)
1. Подготовка
Дашборды, алерты, лимиты, фича-флаги, бэкапы с тестом восстановления, прогон на стейдже.
2. Shadow (теневая проверка)
Зеркалим запросы/записи в новую систему без влияния на пользователей. Сравниваем ответы/состояния.
3. Dual-write / Dual-read
Пишем в обе стороны. Чтения — постепенно переводим на новую систему. Логи несоответствий анализируются.
4. Backfill
Догружаем исторические данные партиями. Контролируем лаг CDC, следим за нагрузкой на сторидж/кэш.
5. Cutover (переключение)
Канарим по сегментам (тенанты/регионы/проценты). Поддерживаем быстрый откат.
6. Contract (очистка)
Отрубаем старые пути, удаляем устаревшие поля/индексы/топики после «периода безопасности».
7. Верификация и ретро
Отчет, метрики, уроки, обновление плейбука/чек-листов.
7) Наблюдаемость и SLO во время миграции
Технические SLI: p50/p95/p99, error rate, retry/timeout, utilization, lag CDC, глубина очередей.
Бизнес-SLI: успех транзакций/конверсий, инварианты (балансы, лимиты, дубликаты).
Специальные метки: `migration_id`, `phase`, `tenant`, `flag_state`.
Алерты-охранники: пороги на хвосты и ошибки, «авто-стоп» (abort) по SLO.
Сравнительные панели: v1 vs v2, «дельта» по ключевым метрикам.
8) Откат и аварийные сценарии
Логический откат: флаги/маршрутизация трафика назад, заморозка backfill.
Данные: «компенсации» (Saga), реплей событий, DLQ → исходная система.
Секреты/ключи: возврат на предыдущий ключ/сертификат (dual-key).
DNS/трафик: «обратный дрифт» Anycast/ALB, TTL короткий в окно миграции.
Коммуникации: заранее согласованный канал и формат статусов.
9) Безопасность, приватность, комплаенс
Минимизация данных. Переносим только необходимые поля; профили анонимизации на копии.
Криптография. Шифрование «на проводе» и «в покое», ротация KMS; журнал операций с ключами.
Доступы по времени. Временные роли для миграционных джобов, отбор прав после завершения.
Следы. Маскирование ПД в логах/трейсах, ограничения экспорта.
10) Управление изменениями и коммуникации
RACI: кто утверждает, кто исполняет, кто информируется.
Freeze-периоды: запрет нерелевантных релизов в окно миграции.
Статусы: T-24h, T-1h, старт, канаринг, cutover, финиш, пост-морем.
Внешние партнеры: окна совместимости, контрактные письма, тестовая песочница.
11) Шаблоны runbook’ов
11.1 Backfill (псевдокод)
for batch in paginate(ids, size=10_000):
try:
rows = read_v1(batch)
upsert_v2 (rows) # idempotently mark_checkpoint (batch. end)
sleep(jitter_ms(100..300))
except Throttle:
sleep (5s) # backpressure respect except Fatal as e:
alert("backfill-failed", e, context=batch)
abort_if_needed()11.2 Проверка一致ности (снэпшот/выборка)
sample = random_ids(n=10_000, stratify=tenant,timestamp)
v1 = fetch_v1(sample); v2 = fetch_v2(sample)
assert schema_compatible(v2)
assert key_invariants_hold (v1, v2) # sum, statuses, versions mismatch_rate = diff (v1, v2). rate()
abort_if(mismatch_rate > 0. 0001)11.3 Переключение чтений
flag. enable("read_from_v2", segment="tenants: cohort_A")
monitor(30m)
if SLO_ok(): expand_segment()
else: rollback_segment()12) Анти-паттерны
«Большой взрыв» вместо expand–migrate–contract.
Backfill без CDC → вечное догоняние и дрейф.
Отсутствие идемпотентности → дубли/грязные данные.
Ручные шаги без скриптов → человеческие ошибки.
Миграция без дашбордов/охранников → «слепой полет».
Неподтвержденный откат → откат не работает, когда нужен.
Игнорирование потребителей (BI/партнеры) → «сломанные» отчеты/интеграции.
13) Чек-лист архитектора
1. Определены цель, границы, тип миграции и инварианты результата?
2. Карта потребителей и контрактов составлена, тесты совместимости зеленые?
3. Подготовлены дашборды, алерты, метки `migration_id`, SLO/guardrails заданы?
4. Реализованы shadow и/или dual-write, backfill идемпотентен?
5. Есть практикуемый rollback runbook, проверки восстановления из бэкапа?
6. Окно/координация/коммуникации согласованы, freeze включен?
7. Пошаговый план с канарингом и критериями расширения/остановки готов?
8. Безопасность/комплаенс: ключи, доступы, PII-санитария?
9. Документация/SDK/спеки обновляются в том же релизном цикле?
10. Пост-морем и обновление плейбука после завершения запланированы?
Заключение
Плейбуки миграций — это архитектурная практика управления риском: мелкие обратимые шаги, прозрачные метрики, готовый откат и дисциплина «expand–migrate–contract». Следуя описанным шаблонам, вы мигрируете схемы, данные, сервисы и регионы без простоя и сюрпризов, сохраняя инварианты бизнеса и доверие пользователей.