Перейти к основному содержимому

Migration Guides (руководства по миграции)

Заметки version-to-version и vendor-migration для интеграторов. Ломающие публичные контракты должны попадать сюда (и в Changelog) в той же docs-волне, что и код (EN+RU).

Как пользоваться разделом​

СитуацияКуда смотреть
Breaking change Runtime / OpenAPIЗапись ниже + API Reference
Rename / retire кода ошибкиКаталог ошибок
Major bump SDKChangelog пакета в публичном SDK-репо (SDKs)
Политика ключей / device identityКлючи лицензий · Идентичность устройства
Trust / crypto profileПроверка доверия (JWKS)

Опубликованные миграции​

Wave 74.15​

Переход на каноническую authority License и Edge Gateway — 2026-08

Wave 74.15 отключает три compatibility-пути, которые могли обходить каноническую identity Product и Customer. Это поведенческий cutover без удаления схемы: существующие строки License, signed artifacts и legacy storage Relay не переписываются, но больше не могут быть authority для новых решений.

Затронутые пути и замена​

Отключённый путьТекущий результатЗамена
POST /api/v1/licenses410 с license_legacy_compatibility_disabledВыпускайте License из проверенной Subscription через POST /api/v1/licenses/subscription-issues; см. выпуск License из Subscription
POST /api/v1/licenses/bulk/create410 с license_legacy_compatibility_disabledВыпускайте каждую подходящую Subscription через канонический workflow; не синтезируйте Product или Customer identity в bulk body
Compatibility-вход productId offline requestПринимается для source compatibility, но игнорируетсяПолучайте Product из актуального проверенного runtime snapshot License; mismatch или отсутствие snapshot означает deny
Local Relay только с legacy entitlement rows или историческим code-derived leaseValidate и refresh возвращают deny с relay.host.no_snapshotЗарегистрируйте Gateway и примените актуальный подписанный V2 bundle со snapshot License до LAN activation, validation или refresh

entitlement.Code остаётся идентификатором функции или лимита. Его нельзя копировать, разбирать или преобразовывать в ProductId. Поля request, конфигурация, default и unknown также не являются Product authority.

Существующие чтения License и lifecycle-операции остаются доступны согласно обычному состоянию. Сохранённые для compatibility формы публичных request и response не означают, что deprecated-поля всё ещё несут authority.

Подготовка​

  1. Найдите все интеграции, которые вызывают отключённые generic create routes, передают ProductId offline request как authority или запускают Local Relay без V2 Gateway bundle synchronization.
  2. До выпуска каждой новой License проверьте точные same-tenant Product, Customer, Published OfferVersion, active CustomerSubscription и immutable policy snapshot.
  3. Переведите issue traffic на POST /api/v1/licenses/subscription-issues и используйте новый стабильный Idempotency-Key для каждой логической попытки.
  4. Обновите и зарегистрируйте каждый Local Relay, завершите pull/ack подписанного V2 bundle и убедитесь, что нужная License входит в active generation. Количество legacy entitlements не доказывает готовность.
  5. В non-production проверьте, что два отключённых create routes возвращают 410, offline artifacts несут ProductId из snapshot, а LAN validate/refresh успешны только после доставки V2 snapshot.

Переключение​

  1. Остановите producers generic single и bulk License create.
  2. Разверните интеграцию канонического Cloud issue и проверьте durable receipt, прежде чем включать следующего producer.
  3. Пересоздайте offline request/response artifacts через актуальный workflow. Не редактируйте и не переподписывайте исторические artifacts, вставляя вычисленный ProductId.
  4. Синхронизируйте и подтвердите актуальный V2 bundle на каждом Relay до направления LAN-клиентов на него.
  5. Наблюдайте стабильные shutdown codes. license_legacy_compatibility_disabled означает немигрировавший producer; relay.host.no_snapshot означает отсутствие локальной V2 authority, а не проблему entitlement или offline grace.

Восстановление​

  • Если канонический License issue отклонён, оставьте issue traffic остановленным и исправьте отсутствующие owner evidence Product, Customer, Subscription, OfferVersion или policy. Не возвращайтесь к generic routes.
  • Если offline issuance не имеет валидного snapshot, восстановите канонический runtime snapshot и создайте новый request. Не доверяйте игнорируемому request ProductId и не повторяйте artifact с несовпадающей identity.
  • Если Relay возвращает relay.host.no_snapshot, восстановите outbound-связь или примените актуальный доверенный V2 air-gap bundle, затем проверьте active generation. Offline grace и исторические code-derived leases не обходят это состояние.

Граница rollback​

Rollback означает остановку traffic или roll-forward с исправленной канонической evidence. Возврат к software или configuration, которые снова разрешают legacy writes, request ProductId authority или leases из entitlement.Code, не поддерживается и небезопасен. Wave 74.15 не выполняет destructive cleanup, поэтому исторические данные остаются для диагностики. Удаление схемы/таблиц, переписывание истории и оценка готовности cleanup принадлежат отдельно одобряемой Wave 74.15.5.

Связанное​

Дальше​