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

Розділ 2.4

Отримання та перевірка релізу

Де зберігається кожна частина релізу Nexus, як завантажуються образи Enterprise за допомогою токена доступу (pull token), і як офлайн, ще до початку встановлення, довести, що кожен образ, чарт і завантажений файл надійшли від Adverant без змін.

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

15 хв читання

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

У Harrow Port Authority ми перевірили все перед першим встановленням. Це зайняло близько двадцяти хвилин, і більша частина цього часу пішла на цикл перевірки образів. Цей розділ проводить тим самим шляхом: де розміщена кожна частина релізу, токен завантаження (pull token) для образів Enterprise, файл блокування образів, перевірки cosign з їхніми точними командами та що робити, якщо перевірка не проходить.

Де розміщено реліз

Адреса Що ви звідти завантажуєте
registry.adverant.ai Образи платформи за адресою registry.adverant.ai/nexus/<service>@sha256:<digest> та чарт Helm за адресою oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ Відкритий релізний ключ та його відбиток, бінарні файли nexusctl та офлайн-пакети
https://account.adverant.ai Ваш обліковий запис Adverant: сторінки Завантаження (Downloads), Токени завантаження та команди встановлення (Pull tokens and install commands), Розгортання (Deployments) та сторінки ліцензії

Образи Community та чарт Community є публічними; ви можете завантажувати їх без входу в систему. Образи Enterprise завантажуються за допомогою токена завантаження з вашого облікового запису, а чарт і пакет Enterprise розміщені на сторінці Завантаження в обліковому записі відповідно до вашої ліцензії.

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

Насамперед прочитайте примітки до релізу

Примітки до релізу постачаються всередині кожного пакета як файл docs/RELEASE-NOTES.md, вказаний у його SHA256SUMS, і ті самі примітки доступні на сторінці релізу у вашому обліковому записі. Прочитайте їх перед встановленням або оновленням. Для 1.0.0-alpha.1 вони короткі. Це перший реліз, тому чисте встановлення не має жодного з описаних там пунктів щодо оновлення, а в списку відомих проблем зазначено, що ніщо в ньому не впливає на чисте встановлення, виконане за задокументованими кроками. У наступних релізах кожна відома проблема наводиться разом із версією, у якій її виправлено.

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

Крок 1: отримайте ключ релізу та перевірте його через другий канал

Усе описане нижче спирається на один файл: відкритий релізний ключ Adverant. Ключ, отриманий із того самого місця, що й об'єкт, який він засвідчує, доводить дуже мало, тому звірте його відбиток із копією, яка надійшла до вас іншим шляхом.

  1. Завантажте ключ із папки релізу на сторінці Завантаження.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Обчисліть його відбиток. Відбиток — це геш SHA-256 (Secure Hash Algorithm 256) самого файлу ключа.

    sha256sum release.pub

    У macOS команда shasum -a 256 release.pub дає такий самий результат.

  3. Порівняйте його, символ за символом, із відбитком, надрукованим у вашому контракті з Adverant та в примітках до релізу. На сторінці Завантаження відбиток також опубліковано, але ця копія надійшла тим самим шляхом, що й ключ, тому це не є надійною перевіркою.

Якщо хоча б один символ відрізняється — зупиніться. Не виконуйте встановлення і не шукайте іншу копію ключа в інтернеті. Створіть запит до служби підтримки зі свого облікового запису та наведіть отриманий результат.

Крок 2: отримайте nexusctl

nexusctl — це інтерфейс командного рядка (CLI) оператора Nexus. Він запускається на вашій робочій станції та зчитує дані вашого кластера через kubeconfig. На сторінці Завантаження доступні чотири збірки:

Файл Платформа
nexusctl-linux-amd64 Linux на базі Intel або AMD
nexusctl-darwin-arm64 macOS на базі Apple silicon
nexusctl-darwin-amd64 macOS на базі Intel
nexusctl-windows-amd64.exe Windows

Поруч із кожним файлом міститься його пакет підпису з тією самою назвою та закінченням .sigstore.json. Перевірте бінарний файл перед запуском:

curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64.sigstore.json
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle nexusctl-linux-amd64.sigstore.json nexusctl-linux-amd64
Verified OK

Потім додайте його до змінної PATH і перевірте версію:

install -m 0755 nexusctl-linux-amd64 /usr/local/bin/nexusctl
nexusctl version

Надалі nexusctl verify може виконувати перевірку файлів за вас. Розділ 2.5, Попередня перевірка за допомогою nexusctl, описує його основне завдання — попередню перевірку (preflight).

Чому прапорець містить слово «insecure»

Кожна команда cosign у цьому розділі містить прапорець --insecure-ignore-tlog=true. Релізи Nexus підписуються ключем Adverant і не записуються в жоден публічний журнал прозорості, щоб для перевірки релізу ніколи не було потрібне підключення до сторонніх сервісів, включно з Sigstore. За замовчуванням cosign вимагає наявності запису в журналі; цей прапорець наказує покладатися виключно на ключ. Без нього перевірка завершується помилкою, як показано нижче:

Error: not enough verified log entries from transparency log: 0 < 1

Коли прапорець встановлено, cosign все одно виводить речення «Existence of the claims in the transparency log was verified offline». Це фіксоване формулювання в cosign; за ним немає жодного запису в журналі. Перевірка підпису за допомогою ключа є справжньою, і саме ця частина має значення.

Крок 3: токен для завантаження образів (для Enterprise)

Образи Enterprise захищені токеном завантаження. Ви створюєте його у своєму обліковому записі на сторінці Токени завантаження та команди встановлення:

  1. Натисніть Додати токен (Add a token).
  2. Вкажіть, для якого кластера він призначений, що йому дозволено завантажувати та коли закінчується термін його дії.
  3. Натисніть Скопіювати токен (Copy the token) і одразу вставте його туди, де ви зберігаєте облікові дані, оскільки сторінка показує його лише один раз.

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

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

Чарт не має параметра pull-secret. Образи завантажуються вашими вузлами, тому токен належить середовищу виконання контейнерів (container runtime) на вузлах. У k3s додайте реєстр до файлу /etc/rancher/k3s/registries.yaml на кожному вузлі та перезапустіть там k3s:

# /etc/rancher/k3s/registries.yaml (on every node)
configs:
  "registry.adverant.ai":
    auth: {username: "<registry-user>", password: "<pull-token>"}

<registry-user> — це ім'я користувача реєстру у вашому запрошенні від Adverant, а <pull-token> — скопійований вами токен. Цей файл містить облікові дані, тому залиште права на його читання лише користувачу root.

У керованому кластері, вузли якого не читають цей файл, скопіюйте образи до реєстру, якому ваші вузли вже довіряють, і вкажіть його в параметрі global.imageRegistry; кожен вузол повинен довіряти сертифікату Transport Layer Security (TLS) цього реєстру. Це описано в розділі 2.11, Варіації: зовнішні сховища, TLS та ingress, а розділ 2.10, Встановлення в ізольованому середовищі (Air-gapped), описує таке саме копіювання для майданчика без виходу в зовнішню мережу.

Крок 4: прочитайте файл фіксації образів (images lock)

Чарт Nexus ніколи не звертається до образу за тегом. Він називає кожен образ за дайджестом його багатоплатформного індексу, взятим із файлу блокування образів, який міститься в чарті під назвою files/images.lock.json. Офлайн-пакет містить такий самий файл блокування як release/images.lock.json.

Завантажте чарт і розпакуйте його, щоб прочитати файл блокування:

helm pull oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1
tar -xzf nexus-1.0.0-alpha.1.tgz
jq -r '.version, .edition' nexus/files/images.lock.json
1.0.0-alpha.1
community

На верхньому рівні файлу блокування вказано, до якого релізу та якої редакції він належить. Кожен запис у розділі images описує один образ:

Поле Що містить
svc Сервіс, наприклад nexus-auth або nexus-postgres
index Дайджест sha256: індексу образу, який охоплює як linux/amd64, так і linux/arm64
edition community, enterprise або all для рівня даних
kind service, migrations або data-tier для п'яти сховищ даних та OpenBao
verified Час, коли під час збирання релізу було перевірено його підпис та атестації

Чарт формує посилання на кожен образ у вигляді <global.imageRegistry>/nexus/<svc>@<index>. Тож із global.imageRegistry: registry.adverant.ai сервіс входу матиме вигляд registry.adverant.ai/nexus/nexus-auth@sha256:, після чого йдуть 64 шістнадцяткові символи, і ніщо в кластері не зможе підмінити його чимось іншим із такою самою назвою.

Файл блокування є окремим для кожної редакції. Файл блокування Community містить лише образи з редакцією community або all. Файл блокування Enterprise містить ці образи плюс збірки Enterprise. Чарт перевіряє це щоразу під час генерації маніфестів і відмовляється продовжувати роботу замість того, щоб робити припущення:

Що повідомляє чарт Чому
edition=enterprise but enterprise.enabled=false: they must agree Два значення редакції у вашому файлі values суперечать одне одному
files/images.lock.json is the community lock; this install is edition enterprise Ви встановлюєте редакцію Enterprise із чарту Community або навпаки
image nexus-auth is not in files/images.lock.json Чарт і його файл блокування не відповідають одне одному; завантажте чарт заново
image ... is in the lock but was never verified by build-all Запис у файлі блокування не містить часу перевірки; не встановлюйте з нього
NEXUS_EDITION_INVALID Параметр edition порожній або не дорівнює одному зі значень community чи enterprise
RELEASE_VERSION_MISSING У файлі блокування не вказано версію

Виведіть список усіх образів і дайджестів однією командою:

jq -r '.images[] | "\(.svc) \(.index)"' nexus/files/images.lock.json

Крок 5: перевірте підпис кожного образа

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

jq -r '.images[] | "\(.svc)@\(.index)"' nexus/files/images.lock.json |
while read -r ref; do
  cosign verify --key release.pub --insecure-ignore-tlog=true \
    "registry.adverant.ai/nexus/$ref" > /dev/null && echo "OK $ref" || echo "FAILED $ref"
done

Кожен рядок має починатися з OK. На нашому каналі зв'язку цикл зайняв кілька хвилин, більшість з яких пішла на очікування відповіді від реєстру. Він зчитує лише підписи й не завантажує шари образів, завдяки чому його легко повторювати після кожного оновлення. Рядок FAILED означає, що потрібно зупинитися: у наступному розділі пояснюється, що означає кожне повідомлення.

Для перевірки одного окремого образу приберіть перенаправлення виводу і прочитайте, що саме перевірив cosign:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
The following checks were performed on each of these signatures:
  - Existence of the claims in the transparency log was verified offline
  - The signatures were verified against the specified public key

<digest> — це 64 шістнадцяткові символи з поля index у файлі блокування для цього образу. Для цієї перевірки образам Enterprise потрібен ваш токен завантаження, як і для будь-якого завантаження з реєстру.

Вертикальний ланцюжок із п'яти блоків, з'єднаних стрілками вниз. Перший зверху: «Відкритий релізний ключ, відбиток звірено з вашим контрактом». Другий: «Пакет чарту nexus-1.0.0-alpha.1, підписаний». Третій: «Файл блокування образів усередині чарту: кожен образ за дайджестом індексу, одна редакція». Четвертий: «Кожен індекс образу, підписаний, з атестаціями специфікації програмного забезпечення (SBOM) та походження». Нижній: «Поди в просторі імен nexus, завантажені за дайджестом». Бічна стрілка від верхнього блока вказує на другий і четвертий блоки та має підпис «cosign verify, офлайн».
Що за що ручається: від перевіреного вами ключа до подів, які запускаються.

Обидві платформи та що потрібно зберегти

Кожен індекс образу містить два маніфести платформ — linux/amd64 та linux/arm64, і кожен із них також підписаний. Команда cosign verify успішно спрацьовує як для дайджесту індексу, так і для дайджесту будь-якої з платформ, тому кластер зі змішаними вузлами охоплюється тією самою перевіркою. Щоб побачити дві платформи за індексом, запитайте у реєстру необроблений індекс:

docker buildx imagetools inspect registry.adverant.ai/nexus/nexus-auth@sha256:<digest> --raw

Його список manifests містить один запис amd64 та один запис arm64.

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

Крок 6: прочитайте атестації

Кожен образ також містить дві підписані атестації, створені з образу під час збирання: специфікацію програмного забезпечення (SBOM) та заяву про походження (provenance statement).

SBOM має формат Software Package Data Exchange (SPDX), по одному на кожну платформу, тож індекс містить два таких документи. У ньому перелічено кожен пакет в образі разом із його ліцензією. Перед релізом ці ліцензії перевіряються за списком заборонених; жоден образ Community не містить коду під ліцензіями GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) або Business Source License (BUSL). Заява про походження відповідає стандарту Supply-chain Levels for Software Artifacts (SLSA) v1. У ній вказано коміт вихідного коду, з якого було зібрано образ, дайджести базових образів, а також інструменти збирання та їхні версії, завдяки чому образ можна простежити до перевіреного вихідного коду без звернення до Adverant.

Обидві атестації перевіряються за допомогою релізного ключа, який ви вже маєте:

cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type spdxjson registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type slsaprovenance1 registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

Перевірка spdxjson виводить два результати — по одному для SBOM кожної платформи. Щоб переглянути все, що прикріплено до образу, без перевірки, скористайтеся командою cosign tree:

cosign tree registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

Вона виводить один пакет підпису, дві атестації spdx.dev/Document та одну атестацію slsa.dev/provenance/v1. Запит типу, якого образ не містить, наприклад --type cyclonedx, завершується помилкою none of the attestations matched the predicate type: cyclonedx. Ця помилка є очікуваною; реліз прикріплює SPDX, а не CycloneDX.

Крок 7: перевірте чарт і завантажені файли

Чарт у реєстрі підписано за його дайджестом OCI (OCI — це Open Container Initiative, формат образів та артефактів, який використовують реєстри). Команда helm pull виводить дайджест, який вона завантажила; перевірте цей дайджест у такий самий спосіб, як і образ:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/charts/nexus@sha256:<chart-digest>

Для завантаженого файлу чарту або для офлайн-пакета команда nexusctl verify перевіряє файл за допомогою релізного ключа Adverant:

nexusctl verify nexus-1.0.0-alpha.1.tgz

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

Офлайн-пакет — це один нестиснений tar-файл для кожної редакції, nexus-alpha-1.0.0-alpha.1-community.tar або nexus-alpha-1.0.0-alpha.1-enterprise.tar, поруч із яким міститься файл .sha256. Усередині він містить:

Шлях Що це таке
release/images.lock.json Файл блокування образів для цієї редакції
release/facts.json Дані про реліз: версія, редакція, архітектури та відбиток релізного ключа
images/<service>/ Кожен образ для обох платформ, його підпис та його атестації
charts/nexus-1.0.0-alpha.1.tgz Чарт
sbom/ SPDX SBOM кожного образу для кожної платформи
docs/ Примітки до релізу, посібник зі встановлення в ізольованому середовищі та приклади файлів values
SHA256SUMS та SHA256SUMS.sigstore.json Контрольна сума кожного файлу та її підпис

Відкритий релізний ключ ніколи не міститься всередині пакета; ключ, який постачається разом із тим, що він підписує, нічого не доводить. Перевірте весь пакет двома командами зсередини його папки:

sha256sum -c SHA256SUMS
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS

Кожен рядок першої команди має закінчуватися на OK, а друга має вивести Verified OK. У розділі 2.10, Встановлення в ізольованому середовищі, описано подальші дії з пакетом: завантаження образів у ваш власний реєстр, повторна перевірка кожного з них уже там, а також власна наскрізна перевірка пакета.

Як перевірити завантаження
Як перевірити завантаження
Інструкція з перевірки завантаження в обліковому записі Adverant. Дві офлайн-перевірки, приклад успішного та неуспішного результатів, а також відбиток релізного ключа, розбитий на групи по чотири символи для зручного візуального порівняння.

Коли підпис не проходить перевірку

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

Що ви бачите Що це означає Що робити
accepted signatures do not match threshold, Found: 0, Expected 1 (код виходу 1) Образ підписано, але не тим ключем, який ви вказали Перевірте, чи ви використали релізний ключ, відбиток якого перевіряли на кроці 1
no signatures found (код виходу 10) За цим дайджестом немає нічого підписаного Перевірте, чи взято дайджест із файлу блокування; ніколи не перевіряйте за тегом
not enough verified log entries from transparency log: 0 < 1 Відсутній прапорець --insecure-ignore-tlog=true Додайте прапорець; з образом усе гаразд
none of the attestations matched the predicate type Ви запросили тип атестації, якого образ не містить Використовуйте spdxjson або slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature Завантажений файл було змінено після його підписання Завантажте його знову
FAILED від sha256sum -c Файл не відповідає тому файлу, для якого було обчислено контрольну суму Завантажте його знову

Якщо завантаження двічі завершується помилкою, створіть запит до служби підтримки зі свого облікового запису та вкажіть назву файлу й повідомлення про помилку. Збережіть проблемний файл; він може знадобитися вашій команді безпеки.

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

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

Коли ключ, образи та чарт успішно пройшли перевірку, наступним кроком є попередня перевірка (preflight) вашого кластера, описана в розділі 2.5, Попередня перевірка за допомогою nexusctl.