УвійтиЗамовити брифінг

Розділ 2.28

Випуск вашого розширення

Як плагін або пакет проходить шлях від успішної збірки до підрозділів, які його запускають, і як він виводиться з експлуатації. Версії, перевірка релізу, канали та встановлення, підписання, погодження змін, запис ідентичності доставлення, міграції, відкат і виведення версії з обігу.

Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

18 хв читання

Cold chain 0.4.0 став нашим першим релізом, який запитував більше, ніж попередній. Він додав надсилання пошти та одну зовнішню адресу для сповіщень про рефрижератори. Збірка була зеленою, тести пройшли на всіх трьох синтетичних філіях, і все одно реліз пробув у dev-просторі два дні, поки двоє людей читали, що він запитує, а третя затверджувала адресу. Саме так і має відчуватися випуск релізів у Nexus: код — це найпростіша частина, а докази й затвердження і є релізом.

У цьому розділі описано все, що відбувається між зеленою збіркою та версією, яка працює для всіх підрозділів, а також способи відкату. Сам шлях просування, від dev-простору до staging, до пілотного підрозділу й до всіх підрозділів, представлено в розділі 2.24 «Створення власної вертикалі від початку до кінця», і я не повторюватиму тут його контрольні точки. Усе це визначає одне правило. Розгортання виконується лише через канали релізів інсталяції. Немає бічних дверей для термінового виправлення, і ніхто не редагує запущений образ вручну.

Версії

У релізі пакета змінюються три номери версій, і варто чітко розрізняти їх.

Що Де зберігається Приклад Правило
Плагін version у nexus.manifest.json 0.4.0 Семантична версія; допускається суфікс попереднього релізу, наприклад -rc.1
Пакет version у pack.json 0.4.0 Змінюється разом із лінзами, словами та кластерами пакета
Модель знань Власна версія моделі З 1.3 на 1.4 Змінюється лише через запит на зміну графа

Збірка для розробки має суфікс 0.4.0-dev, доки не потрапить у staging. Тримайте версії плагіна й пакета однаковими, коли вони постачаються разом; це позбавить суперечок на кожному огляді релізу про те, до якого номера належать докази.

Дві інші версії закріплюються, а не обираються. Версія шаблону пакета (domain-pack@1.6.0 для Cold chain) фіксується під час створення пакета і змінюється лише як перевірена зміна. SDK (набір засобів розробки) встановлюється з точною версією, ніколи не діапазоном, тому та сама збірка дасть той самий результат і наступного місяця:

npm install --save-exact @adverant-nexus/plugin-sdk@2.50.0

Навички Skills Engine також мають версії, але поводяться інакше. Кожна опублікована версія незмінна, а live, canary і shadow — це мітки на версіях. Повернення назад переміщує мітку, а вже запущені виконання завершуються на тій версії, з якої почалися.

Перед запитом на перевірку: маніфест

Сторінка «Маніфест і дозволи» порівнює те, що декларує цей реліз, з останнім релізом: його області дії, сховища, вихідні адреси та профіль пісочниці. Прочитайте її, перш ніж просити когось про огляд, адже вона точно показує, що саме рецензентам буде запропоновано прийняти.

Маніфест і дозволи
Маніфест і дозволи
Що декларує Cold chain 0.4.0 порівняно з 0.3.2. Зверніть увагу на два рядки, позначені як розширення, — надсилання пошти та одну зовнішню адресу, — і на плашку, яка повідомляє, що реліз не вийде за межі dev-простору, доки два рецензенти їх не приймуть.

Реліз, який запитує більше, ніж раніше декларував його маніфест, утримується на місці з MANIFEST_SCOPE_WIDENED, доки два рецензенти не приймуть ширший маніфест. Зовнішня адреса також потребує затвердження від особи, відповідальної за зовнішні адреси в клієнта; таке затвердження надається на фіксований строк, і наше було на 12 місяців. У вас є два шляхи: видалити ці рядки або запросити огляд. Сторінка пропонує обидві кнопки.

Кожен рядок на цій сторінці застосовується під час виконання, а не лише перевіряється на огляді. Кожен виклик інструмента звіряється із задекларованими областями дії, зовнішня адреса блокується, якщо її немає в списку, а профіль пісочниці не дозволяє жодної іншої мережі. Плагін, який намагається звернутися до чогось незадекларованого, отримує відмову, і єдине виправлення — новий реліз, який це декларує.

Перевірка релізу

Сторінка «Огляд релізу» зводить докази для одного релізу в одну таблицю для рецензента, який не є автором.

Огляд релізу
Перевірка релізу
Вигляд Cold chain 0.4.0 для другого рецензента з таблицею доказів, різницею областей дії та коментарями. Зверніть увагу на плашку праворуч: автор не може затвердити власний реліз.
Доказ Що він показав для 0.4.0
Тести 66 із 66, на трьох синтетичних філіях
Перевірки якості Документація та код узгоджуються
Політика Кожна лінза лише звужує; персональні поля за замовчуванням вимкнено
Підписи Образ і пакет підписано конвеєром
Різниця областей дії Додає надсилання пошти та одну зовнішню адресу з її затвердженням
Сумісність Версія платформи та версія базового пакета, на яких його протестовано
Зміна моделі Пробний запуск запиту на зміну графа: 1 284 зв'язки перейменовано, нічого не видалено

Під таблицею розміщено коментарі до зміни та походження: який конвеєр її зібрав, з якої зміни, дайджест образу та шаблон. Рецензенти затверджують за допомогою свого ключа доступу (passkey). Затверджують два рецензенти, які не є автором, після чого конвеєр переміщує реліз у staging. Автор ніколи не зараховується як рецензент, і спроба відхиляється з NEEDS_SECOND_PERSON. Запит на огляд втрачає чинність через 3 дні.

Відповідайте на запитання рецензентів у коментарях, а не у вікні чату. Під час нашого огляду наш спеціаліст із комплаєнсу запитав, чому суму претензії класифіковано як комерційну, а другий рецензент попросив план відкату для зміни моделі. Обидві відповіді тепер є частиною запису релізу, і саме туди дивитиметься наступний рецензент.

Погодження за політикою змін

Огляд релізу охоплює реліз загалом. Блок changePolicy у маніфесті йде далі: він визначає, які класи змін у розгортуваних компонентах вашого плагіна потребують затвердження і від скількох людей.

"changePolicy": {
  "enabled": true,
  "classes": ["website", "bff", "migration"],
  "approvals": { "website": 1, "bff": 1, "migration": 2 }
}

Три класи — це website (вебзастосунок), bff (бекенд для фронтенду) і migration (міграція бази даних). Кожен клас, названий у classes, повинен мати власну кількість у approvals, від 1 до 10. Клас, який ви пропустили, не регулюється, і схема змушує вас записати це як свідомий вибір, а не дійти до цього через пропуск. Ми вимагаємо двох затверджень для міграцій, оскільки міграція — це та єдина зміна, яку важко скасувати.

Затвердження рахуються за різними людьми, і ініціатор зміни ніколи не входить до їхнього числа. Правила, на яких це тримається, варто знати, адже кожне з них має свою відмову:

  • Затвердження від особи, яка запропонувала зміну, відхиляється з TRUST_APPROVAL_SELF_APPROVAL.
  • Особа, якій узагалі не дозволено вносити зміни цього класу, отримує відмову з CHANGE_CLASS_NOT_PERMITTED.
  • Якщо будь-який коміт у зміні підписано ідентичністю агента організації, кворум становить звичайний мінімум плюс один, а власний голос агента не враховується.
  • Кожне затвердження фіксує різницю та head, які бачив рецензент. Якщо зміна оновлюється після останнього затвердження, її злиття відхиляється з HASH_MISMATCH, і затвердження доведеться зібрати знову для нового вмісту.

Це третє правило важливе, якщо ви розробляєте за допомогою інструмента кодування на базі ШІ (штучного інтелекту), як описано в розділі 2.26 «Розробка з інструментами кодування на базі ШІ». Робота, написана агентом, потребує на одне затвердження людини більше, ніж робота, написана людиною. Плануйте це заздалегідь.

Підписання та верифікація

Кожен образ і пакет підписується конвеєром, який його зібрав, і підписаний образ є однією з контрольних точок для входу в staging. Dev-простір від самого початку запускає лише підписані образи. В Enterprise адміністратор налаштовує кожен простір імен або на реєстрацію непідписаних образів, або на їх відхилення, і переводить простори імен у режим відхилення по одному, тож зрештою у production працюють лише образи, зібрані й підписані конвеєром. Підписування є частиною збірки, а не чимось, що ви додаєте перед релізом.

Правило, яке проходить крізь усе це: невдалий підпис — це відмова, а не попередження. Перевірка, яка отримує SIG_INVALID, зупиняється. Вона не переходить на непідписану версію і не продовжує роботу з приміткою в журналі, адже попередження в журналі збірки є дозволом для кожного, хто його не прочитав.

Те саме правило стосується всього, що ви передаєте на носіях. Запечатаний пакет для клієнта з ізольованим середовищем (air-gapped) перевіряється за вашим відкритим ключем перед будь-яким розпакуванням, а розділ 2.25 «Розробка для кожної редакції» показує відповідну команду.

Ідентичність доставлення

Плагін постачається через кілька елементів, кожен з яких має назву: його репозиторії, ключ підпису, простір імен розгортання, префікс реєстру, схему бази даних, набір доменів і політику змін. Будь-який із них — це місце, де два плагіни можуть зіткнутися або один плагін може відхилитися. Ідентичність постачання — це один підписаний запис на плагін, який містить їх усі, тож кожна перевірка на шляху релізу зчитує ту саму відповідь і відхиляє реліз у разі невідповідності.

Ви вносите свою частину через маніфест і більше ніяк: schema, db, domains, changePolicy та URL репозиторію. Платформа доповнює запис рештою і підписує його. Ви ніколи не вказуєте власний простір імен, префікс реєстру чи ключ підпису. Їх вам призначають, і маніфест, який спробував би їх задекларувати, висував би твердження, якому перевірки змушені були б не довіряти.

Підписаний запис містить одинадцять полів: slug плагіна, організацію-власника, організацію, яка його збирає, його репозиторії, назву його ключа підпису, його простір імен розгортання, його префікс реєстру, його схему бази даних, його домени, його політику змін і короткий список старіших назв образів, які він використовував до появи свого префікса реєстру. Цей останній список може лише скорочуватися. Оскільки він підписаний, новий підпис може видалити запис, але ніщо не може непомітно додати новий. Підпис — це Ed25519 над стандартною канонічною формою JSON цих одинадцяти полів, тож запис із «Tomás» чи «Sinéad» перевіряється однаково всюди.

Коли реліз не відповідає своєму запису, спрацьовує перша відмова:

Код Коли виникає HTTP
DELIVERY_IDENTITY_MISSING Для плагіна немає запису 403
DELIVERY_PATH_REFUSED Надсилання образу поза префіксом реєстру, якого немає в підписаному списку старіших назв 403
NAMESPACE_MISMATCH Розгортання, націлене на інший простір імен 403
IMAGE_NAME_COLLISION Назва образу, на яку вже претендує інший плагін 409
CHANGE_CLASS_NOT_PERMITTED Клас змін, який політика не регулює 403

IMAGE_NAME_COLLISION — це та відмова, яка дивує людей. Оберіть іншу назву і ніколи не використовуйте її повторно: спільна назва образу означає, що просування одного плагіна може переміщувати pod-и іншого плагіна.

Зафіксовані та обмежені за областю дії міграції

Міграція постачається всередині образу вашого плагіна і виконується до запуску нової версії через єдиний виконавець міграцій SDK, nexus-migrate. Ви не пишете власний засіб застосування. Перш ніж будь-який реліз зможе просунутися, той самий виконавець застосовує ваші міграції по одному файлу до тимчасової бази даних, тож міграція, яка має збій, зазнає його саме там. Тіньова збірка шаблону викликає виконавця один раз для кожного файлу, по порядку, і фіксує кожен файл так, як це зробить production.

Правила виконавця — це ті самі правила, які перевіряють контрольні точки, записані у вигляді коду:

  1. Він підключається з роллю мігратора вашої схеми і виконує кожен файл від імені власника схеми. Будь-який інший вхід, і насамперед суперкористувач, відхиляється. Файл, який сам намагається змінити роль, відхиляється ще до виконання будь-чого.
  2. Файл тенантності з номером 0 ніколи не редагується після застосування. Зміна тенантності отримує власний файл ревізії, 000_tenancy_r<N>.sql, який nexus-tenancy render --revision <N> створює за вас.
  3. Зазвичай виконавець керує транзакцією кожного файлу і відхиляє BEGIN або COMMIT усередині нього. Файл, який сам керує своїми транзакціями, декларує, що виконується по інструкціях, і тоді кожен відкритий ним BEGIN повинен мати відповідність.
  4. Він веде журнал, по одному рядку на файл, із SHA-256 файлу та способом його виконання. Застосований файл ніколи не змінюється на місці; зміна — це новий пронумерований файл.
npx -p @adverant-nexus/plugin-sdk@2.50.0 nexus-tenancy render --manifest nexus.manifest.json --revision 2 --out migrations/000_tenancy_r2.sql

Обмеженість означає, що кожна нова таблиця містить organization_id, owner_user_id і business_unit_id, а також стовпець-маркер is_demo, якщо тільки gates/demo-exempt.json не звільняє таблицю із зазначенням причини, має первинний ключ, що починається з організації, і зовнішні ключі, які її містять, а також примусово ввімкнену безпеку на рівні рядків. Контрольна точка migrations-are-scoped перевіряє ці правила в кожному файлі, а migrations-commit-what-they-open перевіряє, що кожен файл фіксує те, що відкриває. Друга контрольна точка існує тому, що одного разу міграція, яка непомітно відкотилася, завершилася з кодом 0, а таблиця, яку вона мала створити, так і не з'явилася.

Ще один файл належить до кожного релізу. scripts/ci/required-env виводить змінні середовища, потрібні вашому сервісу для запуску, у вигляді масиву JSON, взятого з вашого завантажувача конфігурації. Шлях релізу запускає його та відхиляє реліз, розгортання якого не задає кожну з них, тож відсутня змінна виявляється до релізу, а не через pod, який не запускається.

node scripts/ci/required-env

Випуск навичок

Два види навичок доходять до людей різними шляхами, тому й випускайте їх по-різному.

Навичка маніфесту, типізований рядок у skills[] вашого плагіна, постачається разом із плагіном і проходить те саме просування, що й решта плагіна. Підключення синхронізує весь набір навичок із реєстром під час кожного релізу. Якщо пропустити навичку в наборі, її буде вимкнено, а в Enterprise синхронізація з однією некоректною навичкою не приймає жодної з них, тож продовжує працювати попередня версія, а не половина нової.

Навичка Skills Engine публікується з бібліотеки. У тарифі Enterprise навичка, що додає інструмент запису, очікує, доки двоє визначених людей схвалять її своїми ключами доступу (passkeys), і автор пропозиції не може бути одним із них. Схвалена версія потім працює в тіньовому режимі, далі в режимі canary для одного підрозділу за визначеними контрольними умовами, а потім для всіх, і вона зупиняється сама, якщо контрольну умову не виконано. Якщо ваш плагін і навичка Skills Engine залежать одне від одного, спочатку опублікуйте навичку й дочекайтеся, доки вона стане доступною для всіх, перш ніж випуск плагіна, що її викликає, вийде за межі пілоту.

Канали та встановлення

Щойно випуск пройшов пілот і став доступним для всіх підрозділів, його пропонують у каналі, і кожен підрозділ обирає свій канал. Його адміністратор погоджує кожен перехід. Сторінка «Канали та встановлення» показує, які підрозділи використовують яку версію, а частоту помилок — лише у вигляді кількості: ви бачите, як поводиться ваше розширення, але ніколи не бачите, що хтось із ним робив.

Канали та інсталяції
Канали та встановлення
Які підрозділи використовують яку версію carrier-sync, із відкритим відкатом для одного підрозділу. Зверніть увагу, що, за словами модального вікна, змінюється, що залишається незмінним, і що для цього потрібна друга людина — власний адміністратор підрозділу.

Наш плагін carrier-sync працює одночасно у трьох версіях, і це нормально. Більшість підрозділів використовує поточний випуск, один підрозділ залишається на старішій версії в каналі, що підтримується до визначеної дати, а кандидат на випуск розміщено в каналі, який ще ніхто не обрав. Не боріться з цим: підрозділ, якому потрібна стабільність на час аудиту, має на неї право.

Журнали та метрики вашого розширення

Сторінка журналів і метрик вашого пакета обмежена вашими власними робочими навантаженнями в тих підрозділах, де вам дозволено їх переглядати. Ви можете фільтрувати за підрозділом і середовищем, і бачите кількості, тривалості та стани.

Журнали й метрики вашого пакета
Журнали й метрики вашого пакета
Власні журнали й метрики Cold chain, відфільтровані за пілотом у Роттердамі. Подивіться на рядки журналу: особу, яка повідомила про відхилення, приховано, а текст примітки до претензії взагалі ніколи не записується в журнал.

Персональні поля замінюються до того, як рядок буде записано, а вміст клієнтів, як-от текст претензій, пошта чи вміст документів, ніколи не записується в журнали. Журнали зберігаються 14 днів. Організацію встановлює шлюз, а не ваш запит, тому запит, у якому вказано іншу організацію, відхиляється з TENANT_BOUNDARY. Асистент на панелі може читати ті самі журнали разом із вами, і лише їх: коли я запитав його, чому одного ранку записи про відхилення надходили із запізненням, він простежив 18 хвилин повторних спроб до дубльованих показань від живлення одного причалу.

Відкат

Існує два види відкату, і обидва є змінами, що проходять перевірку, а не перемикачами.

Відкат середовища використовує попередню версію. Кожне середовище зберігає її 30 днів. Відкат готується як зміна до випуску, показує попередній перегляд того, що він зробить, і потребує другої людини; після схвалення конвеєр виконує відкат приблизно за хвилину. Тривалість кожного відкату вимірюється, як і кожного навчального тренування, тож відпрацюйте його, перш ніж він вам знадобиться. Відкат одного підрозділу виконується на сторінці «Канали та встановлення». Модальне вікно відкату вказує, що змінюється (цей підрозділ знову використовує старішу версію, а його частота помилок відстежується протягом години), що залишається незмінним (інші підрозділи, а також налаштування та записи цього підрозділу), причину і хто є другою людиною: адміністратор цього підрозділу.

Налаштування й записи зберігаються під час відкату, тому плануйте кожен випуск, виходячи з того, що попередня версія може знову працювати з даними, які записала новіша. Саме тому на практиці міграції в межах випуску, який ви можете відкотити, мають лише додавати зміни, і саме тому ми просимо двох людей схвалювати кожну з них. Зі зміною моделі так само: рецензент може й повинен запитати план відкату для запиту на зміну графа, перш ніж схвалити його.

Відкат навичок відбувається м’якше. Повернення мітки live на попередню версію — це один крок, а запуски, що вже виконуються, завершуються на тій версії, з якою вони почалися.

Виведення версії з обігу

Створений випуск ніколи не редагується. Версію, яку більше не слід використовувати, відкликають, а виправлення випускається з новим номером версії. Власні канали випусків SDK дотримуються тієї ж практики: невдалу версію SDK відкликають (yank), але ніколи не замінюють іншим вмістом під тим самим номером. Наслідуйте цей підхід, адже номер версії, який може означати дві різні збірки, знецінює будь-які докази щодо неї.

Відкликання плагіна або пакета зупиняє нові встановлення. Підрозділи зберігають версію, яку використовують, доки не перейдуть на іншу, тож відкликання — це сигнал і крайній термін, а не вимикач. Повідомте адміністраторам підрозділів, на яку версію перейти і до якого терміну.

Виведення навички з експлуатації відбувається за тим самим принципом з одним додатковим кроком. Skills Engine переводить усіх викликачів, що залишилися, на заміну після виконання тестових сценаріїв заміни, зупиняє нові запуски та зберігає версії, сценарії й запечатані записи запусків, щоб навичку можна було повернути, якщо заміна виявиться невдалою.

Контрольний список релізу

Це список, який ми переглядаємо перед кожним випуском Cold chain. Він короткий, бо більшу частину платформа перевіряє за нас.

  1. Версії узгоджені: маніфест, pack.json і модель знань, якщо вона змінилася.
  2. Кожна контрольна умова виконується локально з чистого стану, і кожен новий тест спочатку завершувався невдачею.
  3. Сторінка «Маніфест і дозволи» не показує розширення прав, або розширення саме таке, як ми задумали, і рецензенти знають чому.
  4. Кожна міграція — це новий пронумерований файл з обмеженою областю дії, який успішно застосовано до тимчасової бази даних.
  5. scripts/ci/required-env містить перелік усіх змінних, потрібних сервісу, і розгортання встановлює кожну з них.
  6. План відкату описано в зміні, зокрема для будь-якої зміни моделі.
  7. Цього тижня доступні двоє рецензентів, які не є автором.

Останній пункт здається дрібницею. Але саме він затримав більше наших випусків, ніж усі контрольні умови разом узяті.