ВходЗапазете среща

Глава 2.4

Получаване и проверка на версия

Къде се намира всяка част от дадена версия на Nexus, как се извличат образите за Enterprise с токен за изтегляне и как да докажете офлайн, преди да инсталирате каквото и да било, че всеки образ, чарт и изтеглен файл са дошли от Adverant непроменени.

Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

15 минути за четене

Всяко изображение в издание на Nexus е подписано с ключа за издания на Adverant и всяко изображение се именува чрез неговия дайджест, а никога чрез етикет (tag). Чартът ще рендерира само изображения, описани по дайджест в собствения си заключващ файл за изображения (images lock). Взето заедно, това означава, че можете да докажете на собствената си работна станция и без връзка с когото и да било, че това, което предстои да стартирате, е точно това, което 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/ Публичния ключ на изданието и неговия отпечатък (fingerprint), изпълнимите файлове на nexusctl и офлайн пакетите
https://account.adverant.ai Вашия профил в Adverant: Изтегляния (Downloads), Токени за изтегляне и команди за инсталиране (Pull tokens and install commands), Внедрявания (Deployments) и страниците за лицензи

Community изображенията и Community чартът са публични; можете да ги изтеглите без влизане в профил. Enterprise изображенията се изтеглят с токен за изтегляне от Вашия профил, а Enterprise чартът и пакетът се намират на страницата Изтегляния (Downloads) в профила, чието съдържание зависи от Вашия лиценз.

Изтегляния
Изтегляния
Изтегляния в профила в Adverant по версия и канал. До всеки файл стоят неговата контролна сума и подпис, а частите извън обхвата на лиценза остават в списъка в сиво, заедно с причината за това.

Прочетете бележките към версията преди всичко останало

Бележките към изданието се доставят във всеки пакет като docs/RELEASE-NOTES.md, описан в неговия SHA256SUMS, а същите бележки са налични и на страницата на изданието във Вашия профил. Прочетете ги, преди да инсталирате или надграждате. За 1.0.0-alpha.1 те са кратки. Това е първото издание, така че при чиста инсталация не важат точките за надграждане, описани там, а списъкът с известни проблеми гласи, че нищо в него не засяга чиста инсталация, която следва документираните стъпки. В по-късните издания всеки известен проблем е описан заедно с версията, която го отстранява.

Страницата на изданието също така посочва в три реда какво обещава едно алфа издание: функциите може да се променят преди първата стабилна версия, надграждането запазва данните Ви и първо прави резервно копие, а поправките по сигурността пристигат в рамките на 7 дни. В Harrow разпечатахме тази страница и я приложихме към записа за промяна, защото това е най-близкото до декларация за поддръжка, която комисията по промените би поискала.

Стъпка 1: вземете ключа на версията и го проверете по втори канал

Всичко по-долу се опира на един файл: публичния ключ за издания на Adverant. Ключ, който идва от същото място като нещото, за което гарантира, доказва твърде малко, затова проверете отпечатъка му спрямо копие, достигнало до Вас по друг път.

  1. Изтеглете ключа от папката на изданието в Изтегляния (Downloads).

    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 и в бележките към изданието. На страницата Изтегляния (Downloads) отпечатъкът също е публикуван, но това копие е дошло по същия път като ключа, така че не служи за проверка.

Ако дори един знак се различава, спрете. Не инсталирайте и не търсете друго копие на ключа в интернет. Отворете заявка за поддръжка от профила си и цитирайте това, което сте видели.

Стъпка 2: вземете nexusctl

nexusctl е интерфейсът с команден ред (CLI) за оператора на Nexus. Той се изпълнява на Вашата работна станция и чете клъстера Ви чрез Вашия kubeconfig. На страницата Изтегляния (Downloads) се предлагат четири компилации:

Файл Платформа
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 и не се записват в публичен дневник за прозрачност (transparency log), така че проверката на дадено издание никога не се нуждае от връзка с когото и да било, включително 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 изображенията са защитени с токен за изтегляне. Можете да създадете такъв в профила си, на страницата Токени за изтегляне и команди за инсталиране (Pull tokens and install commands):

  1. Натиснете Добавяне на токен (Add a token).
  2. Посочете за кой клъстер е предназначен, какво може да извлича и кога изтича валидността му.
  3. Натиснете Копиране на токена (Copy the token) и го поставете директно там, където съхранявате идентификационните си данни, защото страницата го показва само веднъж.

Всеки токен е ограничен до това, което може да извлича, и има крайна дата. Оттеглянето му спира новите изтегляния веднага; изображенията, които даден клъстер вече е изтеглил, продължават да работят. В Harrow направихме по един токен на клъстер, така че оттеглянето на токена за тестовия клъстер никога не засяга продукционната среда. Инсталацията на Community не се нуждае от никакъв токен; създавате такъв само когато преминете към Enterprise, като можете да го направите в същия ден.

Токени за изтегляне и команди за инсталиране
Токени за изтегляне и команди за инсталиране
Токени за изтегляне в профила в Adverant. Всеки токен показва какво може да извлича, кой го е създал и кога изтича; новият токен се показва само веднъж, а оттеглянето му спира новите изтегляния, без да спира нищо, което вече работи.

Чартът няма стойност за pull-secret. Вашите възли (nodes) изтеглят изображенията, така че токенът принадлежи на средата за изпълнение на контейнери (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 да сочи към него; всеки възел трябва да се доверява на сертификата за сигурност на транспортния слой (TLS) на този регистър. Глава 2.11, Вариации: външни хранилища, TLS и ingress, разглежда това, а глава 2.10, Инсталация в изолирана среда (air-gapped), разглежда същото копиране за обект без външна свързаност.

Стъпка 4: прочетете заключващия файл за образите

Чартът на Nexus никога не именува изображение чрез етикет (tag). Той именува всяко едно чрез дайджеста на неговия многоплатформен индекс, взет от заключващия файл за изображения – файл, който чартът съдържа като 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

Най-горното ниво на заключващия файл показва към кое издание и коя редакция (edition) принадлежи. Всеки запис под 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 file) си противоречат
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, офлайн“.
Кое за какво гарантира – от проверения от Вас ключ до подовете (pods), които се изпълняват.

Двете платформи и какво да запазите

Всеки индекс на изображение съдържа два манифеста на платформи, 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/ Бележките към изданието, ръководството за инсталиране в изолирана среда (air-gap) и примерни стойности
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, Инсталация в изолирана среда (air-gapped), поема работата с пакета оттам нататък: зареждане на изображенията във Вашия собствен регистър, повторна проверка на всяко едно от тях там и собствената цялостна проверка на пакета.

Как да проверите изтеглен файл
Как да проверите изтеглен файл
Как да проверите изтеглен файл в профила в Adverant. Две офлайн проверки, илюстрация на успешен и неуспешен резултат и отпечатъка на ключа на изданието на групи от по четири знака за визуално сравнение.

Когато даден подпис не премине проверката

Спрете. Не инсталирайте и не променяйте командата, докато не премине успешно. Неуспешната проверка на подписа означава, че системата работи: файлът, който имате, не е файлът, подписан от Adverant, или ключът, който държите, не е на Adverant.

Какво виждате Какво означава Какво да предприемете
accepted signatures do not match threshold, Found: 0, Expected 1 (код за изход 1) Изображението е подписано, но не с подадения от Вас ключ Проверете дали сте използвали ключа на изданието, чийто отпечатък проверихте в стъпка 1
no signatures found (код за изход 10) Нищо на този дайджест не е подписано Проверете дали дайджестът идва от заключващия файл; никога не проверявайте по етикет (tag)
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.