{
  "index": 124,
  "slug": "editorial-2024-07-field-release-engineering",
  "title": "Когда версия не доказывает релиз: проверка artifact, migration и rollback",
  "excerpt": "Как связать commit, provenance, digest, migration и точку возврата до approval — с воспроизводимым gate, отрицательным тестом и честными границами rollback.",
  "contentHtml": "<p>В заявке на выпуск стоит <code>2024.07.0</code>. Такое же имя указано у ветки, образа, миграции и выкладки. После запуска сервис отвечает ошибкой схемы: новый код обращается к полю, которого нет в базе. Команда повторяет deploy, потому что все записи выглядят согласованными. Это учебный сценарий, а не отчёт о конкретной production-системе. Его задача — показать, какие факты нужно связать до разрешения релиза.</p>\n<p>Номер версии не доказывает происхождение и содержимое выпуска. Для решения нужны как минимум четыре независимые связи: artifact собран из нужного commit, rollout выбирает тот же digest, migration совместима с текущей схемой, а return point описан отдельно. Если связь неизвестна или ложна, проверка должна остановиться. Повторный deploy не превращает неизвестный факт в доказательство.</p>\n<h2>Что именно проверяет инженер</h2>\n<p><strong>Commit</strong> — точная ревизия исходников. <strong>Artifact</strong> — результат сборки, например контейнерный образ, доступный по digest. <strong>Provenance</strong> — проверяемые сведения о том, где и как собран artifact. <strong>Migration</strong> — изменение схемы или данных с заявленной совместимостью. <strong>Rollout intent</strong> — запись о том, какой artifact и какую migration собираются применить. <strong>Return point</strong> — заранее известный вариант возврата к предыдущему коду и описание границы данных.</p>\n<p>Это не одна сущность с полем <code>version</code>. Для каждого объекта нужен источник и владелец. Поле <code>artifact.sourceCommitId</code> ниже — проектный контракт учебной модели, а не универсальное поле Docker или Kubernetes. Аналогично, <code>migration.compatibleWith</code> требует договорённости команды: инструменты миграций называют такие сведения по-разному.</p>\n<figure><img src=\"/assets/editorial/2024/release-engineering-2024-evidence-gate.svg\" alt=\"Схема сверки commit, provenance, digest образа, migration, rollout и точки возврата перед релизом\" loading=\"lazy\" /><figcaption>Учебная схема показывает порядок сверки и стоп-ветку. Это не лог CI, registry, кластера, базы данных или реально выполненного rollout.</figcaption></figure>\n<h2>Почему одного tag недостаточно</h2>\n<p>Tag удобен для человека, но это изменяемая ссылка. Один и тот же tag может указывать на другой образ после следующей сборки. Digest адресует содержимое образа. Docker документирует загрузку образа по форме <code>name@sha256:...</code> и объясняет, что такой идентификатор фиксирует выбранную версию содержимого. Поэтому в rollout-записи храните digest, а tag оставляйте только как дополнительную подпись для чтения.</p>\n<p>Digest отвечает лишь на вопрос «какое содержимое выбрано». Он не отвечает на вопросы «из какого commit оно собрано», «кто его собрал» и «совместима ли схема». Для этого нужен provenance и политика проверки. В SLSA v1.2 проверка включает сопоставление subject с digest artifact, доверенный builder, подпись и ожидаемые параметры сборки. Это отдельный gate, а не синоним успешной загрузки образа.</p>\n<p>У attestation тоже есть граница. Подписанное утверждение связывает metadata с artifact, но не утверждает, что migration выполнилась, сервис принимает трафик или решение о выкладке одобрил нужный человек. Эти факты должны появиться в собственных системах и проверках.</p>\n<h2>Минимальный воспроизводимый gate</h2>\n<p>Следующая команда запускается в Node.js без зависимостей. Все значения синтетические: она не обращается к Git, registry, CI, Kubernetes API или базе. Код проверяет только заранее подготовленные записи и завершает процесс с ненулевым статусом при расхождении. Сохраните его как команду через heredoc или вставьте в локальный терминал.</p>\n<pre><code>node --input-type=module &lt;&lt;'NODE'\nconst current = { schemaVersion: '2024.06.3' };\nconst release = { version: '2024.07.0' };\nconst commit = { id: 'commit-7f4a0c1' };\nconst artifact = {\n  digest: 'sha256:release-070-a1',\n  sourceCommitId: 'commit-7f4a0c1',\n};\nconst migration = {\n  version: '2024.07.0',\n  targetSchemaVersion: '2024.07.0',\n  compatibleWith: '2024.06.3',\n};\nconst rollout = {\n  artifactDigest: 'sha256:release-070-a1',\n  migrationVersion: '2024.07.0',\n};\nconst returnPoint = {\n  artifactDigest: 'sha256:release-069-z9',\n  schemaVersion: '2024.06.3',\n};\n\nconst checks = {\n  source: artifact.sourceCommitId === commit.id,\n  release: migration.version === release.version,\n  compatibility: migration.compatibleWith === current.schemaVersion,\n  artifact: rollout.artifactDigest === artifact.digest,\n  migration: rollout.migrationVersion === migration.version,\n  returnPoint: Boolean(returnPoint.artifactDigest && returnPoint.schemaVersion),\n};\nconst ready = Object.values(checks).every(Boolean);\n\nconsole.log(JSON.stringify({ checks, ready }, null, 2));\nif (!ready) process.exitCode = 1;\nNODE</code></pre>\n<p>При исходных данных команда печатает <code>\"ready\": true</code> и завершается с кодом 0. Измените <code>rollout.artifactDigest</code> на <code>sha256:release-070-other</code>: поле <code>artifact</code> станет <code>false</code>, а процесс завершится с кодом 1. Такой отрицательный тест важнее красивого положительного fixture: он показывает, что gate не угадывает правильную запись.</p>\n<p>Положительный результат означает только согласованность шести полей в памяти. Он не доказывает, что digest существует в registry, provenance подписан, миграция запущена, а старый artifact умеет работать с новой схемой. Эти вопросы нельзя «досчитать» из примера.</p>\n<h2>Диагностика: симптом → причина → проверка → действие</h2>\n<div class=\"table-scroll\"><table><caption>Классификация расхождения до запуска</caption><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td>Tag совпадает, а digest другой.</td><td>Rollout использует изменяемую ссылку вместо содержимого.</td><td>Сверить digest в intent с digest из registry и записи сборки.</td><td>Остановить запуск; пересоздать intent после выбора exact artifact.</td></tr><tr><td>Artifact указывает на другой commit.</td><td>Образ собран из другой ревизии, либо provenance неполон.</td><td>Сопоставить commit, provenance subject и ожидаемый source repository.</td><td>Не объявлять образ релизом; пересобрать или исправить запись после расследования.</td></tr><tr><td>Новая схема не совместима со старым кодом.</td><td>Миграцию выполнили как необратимый шаг до перехода reader/writer.</td><td>Проверить порядок expand, переключение читателей и contract-шаг.</td><td>Остановить удаление/изменение данных; привлечь владельца схемы.</td></tr><tr><td>После stop предлагают повторить deploy.</td><td>Retry используют вместо объяснения первой ложной связи.</td><td>Найти первый mismatch и назвать источник каждого значения.</td><td>Сначала reconcile записей, затем повторить только проверку.</td></tr></tbody></table></div>\n<p>Таблица разделяет происхождение, содержимое и совместимость. Это помогает не лечить ошибку схемы заменой образа и не считать зелёный rollout доказательством корректности данных. Если один источник недоступен, статус должен быть «не проверено», а не «вероятно совпадает».</p>\n<h2>Порядок проверки перед approval</h2>\n<ol><li><strong>Определите объект релиза.</strong> Зафиксируйте имя сервиса, среду, release version и владельцев commit, artifact, migration и deploy. Не смешивайте тестовые и production-записи.</li><li><strong>Сверьте исходники и сборку.</strong> Возьмите полный commit id из системы контроля версий. Проверьте source repository, builder и параметры provenance; короткий tag или название ветки их не заменяет.</li><li><strong>Зафиксируйте artifact.</strong> Получите digest из registry или результата push. В deployment-манифесте используйте ссылку с digest, если это поддерживает ваша платформа. Для Docker-пути пример выглядит как <code>registry.example/app@sha256:...</code>.</li><li><strong>Опишите migration.</strong> Назовите текущую и целевую схему, совместимость reader/writer, порядок шагов и отдельное действие для данных. Не прячьте SQL и условия возврата в комментарии к образу.</li><li><strong>Сверьте intent.</strong> Digest artifact и digest rollout должны совпасть, как и версия migration. Несовпадение переводит запись в stop.</li><li><strong>Проверьте return point.</strong> Запишите предыдущий digest, revision, способ переключения и проверку здоровья. Отдельно укажите, можно ли вернуть данные, и кто принимает это решение.</li><li><strong>Повторите gate после исправления.</strong> Положительный результат открывает human approval, но не выдаёт автоматическое право на deploy. Авторизованный процесс всё равно должен проверить свои policy, права и наблюдаемость.</li></ol>\n<h2>Что действительно означает rollback</h2>\n<p>В Kubernetes новая revision Deployment появляется, когда меняется Pod template, например image или labels. Команда <code>kubectl rollout undo</code> возвращает предыдущую ревизию этого шаблона. Значит, такой rollback касается описания Pod: образа, переменных и других полей template. Он не является отменой произвольного SQL, удалённой строки, уже отправленного сообщения или изменения внешней системы.</p>\n<p>Проблема особенно заметна при миграции. Если новая версия добавила поле и старый код его не ожидает, возврат image может вернуть работоспособность. Если новая версия удалила или изменила смысл поля, старый код может не запуститься на текущей схеме. До релиза нужен либо совместимый expand/contract-переход, либо проверенная обратная миграция, либо восстановление из резервной копии. Выбор зависит от базы, инструмента и договора владельцев данных.</p>\n<p>Практичная формулировка return point состоит из двух утверждений: «этот artifact можно снова запустить» и «для этой схемы есть разрешённое действие». Первое не даёт права утверждать второе. Если доказан только возврат Pod template, так и пишите в release record: «rollback кода определён; rollback данных не подтверждён».</p>\n<h2>Границы применимости и безопасный stop</h2>\n<p>Метод подходит как предварительная проверка связей в release record и как шаблон для CI-gate. Он не заменяет security review, проверку подписи, тест совместимости, backup/restore drill, smoke-тест, анализ метрик или approval согласно правилам организации. Названия полей и формат provenance в вашем toolchain могут отличаться; переносите инварианты, а не имена из учебного примера.</p>\n<p>SLSA проверяет provenance относительно заданных ожиданий, но сами ожидания должны быть сформированы и защищены командой. GitHub artifact attestations доступны только при соответствующей настройке workflow и permissions; команда <code>gh attestation verify</code> требует доступного GitHub-контекста и не проверяет вашу migration. Kubernetes хранит историю Deployment с ограничениями revision history, поэтому старый Pod template может быть недоступен, если историю сократили или образ удалён.</p>\n<p>Статус должен быть отрицательным, если отсутствует полный commit id, digest, источник provenance, compatibility statement или return point. Не подставляйте «последний main», не ищите образ по tag и не объявляйте rollback данных по факту <code>kubectl rollout undo</code>. Остановка на первой неизвестной границе дешевле расследования после повреждения данных.</p>\n<h2>Критерий готовности</h2>\n<p>Перед human approval второй инженер без устных пояснений должен найти exact commit id, source repository, artifact digest, связь artifact с commit, результат provenance verification, текущую и целевую схему, compatibility statement, rollout digest, migration version и return point. Для каждого значения указаны источник, владелец и действие при mismatch.</p>\n<p>Готовность здесь — не одно зелёное число. Это воспроизводимый набор утверждений: все обязательные связи истинны, неизвестные значения не замаскированы, а возврат коду не выдан за возврат данным. Если хотя бы одно утверждение нельзя показать, релиз остаётся на проверке с конкретной причиной остановки.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://slsa.dev/spec/v1.2/verifying-artifacts\" target=\"_blank\" rel=\"noopener noreferrer\">SLSA v1.2: Verifying artifacts</a> — описывает проверку subject digest, подписи, builder identity и ожиданий provenance.</li><li><a href=\"https://slsa.dev/spec/v1.2/build-track-basics\" target=\"_blank\" rel=\"noopener noreferrer\">SLSA v1.2: Build Track Basics</a> — объясняет, зачем provenance связывает artifact с источниками и процессом сборки.</li><li><a href=\"https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations\" target=\"_blank\" rel=\"noopener noreferrer\">GitHub Docs: Using artifact attestations</a> — содержит настройку attestations и команду проверки binary/container image.</li><li><a href=\"https://docs.docker.com/reference/cli/docker/image/pull/\" target=\"_blank\" rel=\"noopener noreferrer\">Docker Docs: docker image pull</a> — показывает синтаксис pull по digest и границу между tag и immutable identifier.</li><li><a href=\"https://kubernetes.io/docs/concepts/workloads/controllers/deployment/\" target=\"_blank\" rel=\"noopener noreferrer\">Kubernetes Docs: Deployments</a> — описывает rollout history и то, что rollback возвращает Pod template, а не произвольные изменения данных.</li></ul>"
}