Версия 1.0.0-alpha.1последно
Глава 2.10
Инсталация в изолирана среда
Пренесете подписан офлайн пакет в обект без интернет, проверете го спрямо ключ, който сте внесли отделно, заредете го в собствения си регистър и инсталирайте. Лицензите, обновленията и списъците с анулирани сертификати също преминават изолираната зона на ръка.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Оперативната мрежа на Harrow Port Authority няма маршрут към интернет – както по закон, така и по проект. В нея се намират трафикът на плавателните съдове, плановете за кейовите места и митническите задържания и нищо в нея няма право да прави изходящи връзки. Когато Tomás Reilly инсталира Nexus там, всеки байт пристигна на диск, донесен от куриер до портала, и всеки байт беше проверен вътре в обекта, преди каквото и да било да го използва.
Тази глава описва именно тази инсталация. Получавате подписан офлайн пакет, проверявате го с ключ, достигнал до Вас по различен маршрут, копирате неговите образи във Вашия собствен регистър, проверявате ги отново там и инсталирате чарта с името на Вашия регистър в стойностите. След това идват нещата, които един изолиран (air-gapped) обект прави ръчно, а свързаният получава наготово: k3s и cert-manager без изтегляне, актуализации на носител, лицензи чрез офлайн обмен и списъци с оттеглени лицензи, които импортирате сами.
Какво съдържа офлайн пакетът
Пакетът представлява една редакция на едно издание като некомпресиран tar архив с файл за контролна сума до него: nexus-alpha-1.0.0-alpha.1-enterprise.tar и nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256. Пакетите Community са публични в downloads.adverant.ai. Пакетите Enterprise идват от Вашия профил в Adverant на адрес https://account.adverant.ai, до Вашия лиценз, и никога анонимно.
Разархивиран, той изглежда така:
nexus-alpha-1.0.0-alpha.1-enterprise/
release/facts.json the release facts: version, edition, architectures, key fingerprint
release/facts-gaps.json the release facts the build couldn't record, each with its reason
release/images.lock.json every image by digest: index, per platform, its SBOMs
release/source-offer.json the sources of every copyleft data-tier image
release/source-offer.sha256 a checksum for each of those source files
images/<svc>/ one cosign save layout per image
charts/nexus-1.0.0-alpha.1.tgz the Helm chart
sbom/<edition>/<svc>-<arch>.spdx.json
source-offer/ the source files themselves
docs/INSTALL-AIRGAP.md
docs/example-values.yaml
docs/RELEASE-NOTES.md
SHA256SUMS a checksum for every file above
SHA256SUMS.sigstore.json the signature over SHA256SUMS, made with the release key
Всяка директория images/<svc>/ е това, което записва cosign save. Тя съдържа индекса на образа и образите за двете платформи, linux/amd64 и linux/arm64, със сигнатурата от cosign, SPDX SBOM (списък със софтуерни материали) атестация за всяка платформа и атестация за произход, всички създадени с ключа за издания на Adverant. Същите SBOM файлове се намират в sbom/ като обикновени файлове, за да може екипът по сигурността да ги прочете без cosign.
Слоят за данни включва copyleft софтуер: PostgreSQL с PostGIS и Neo4j Community Edition наред с други. Пакетът носи изходния код на всеки образ от слоя за данни, който доставя, и release/source-offer.json указва това за всеки образ. Пакет, който би доставил copyleft бинарен файл без неговия изходен код, не се компилира.
release/facts.json посочва изданието, редакцията, архитектурите и пръстовия отпечатък на ключа за издания, с който е подписан пакетът, като sha256:<hex>.
Публичният ключ се пренася отделно
Пакетът никога не съдържа ключа, който го проверява. Пакет, който носи собствения си ключ, би могъл да бъде подменен заедно с ключа от всекиго и всяка проверка пак би преминала успешно. Скриптът за проверка отхвърля ключ, който се намира вътре в директорията на пакета.
Вземете публичния ключ за издания еднократно, на свързана машина, от https://downloads.adverant.ai/nexus/1.0.0-alpha.1/. Запазете го като release.pub. Неговият пръстов отпечатък е SHA-256 сумата на файла:
sha256sum release.pubСравнете го с пръстовия отпечатък, който Adverant публикува, и с този в бележките към изданието, които сте получили по отделен канал. Глава 2.4, Получаване и проверка на издание, съдържа подробностите. След това пренесете release.pub в обекта, по различен маршрут от пакета, ако можете, и го съхранявайте там. Екипът на Tomás го държи във файловия ресурс на оперативната мрежа с бележка за датата на внасяне. Всяко следващо издание се проверява спрямо този инсталиран ключ и никога спрямо нещо, което дискът носи със себе си.
Проверка на пакета
verify-bundle.sh е скриптът, който проверява пакет, публикуван с всяко издание. Дисковият образ на инсталатора изпълнява същия скрипт при първо стартиране. Той се нуждае от cosign v3, helm v4 и sha256sum или shasum. Не чете нищо от никоя мрежа и не се нуждае от Python, така че работи както на базов инсталационен възел, така и на работна станция.
- Проверете tar архива спрямо неговата контролна сума, след което го разархивирайте:
sha256sum -c nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256
tar -xf nexus-alpha-1.0.0-alpha.1-enterprise.tar- Стартирайте проверката с ключа, който сте внесли:
./verify-bundle.sh nexus-alpha-1.0.0-alpha.1-enterprise release.pubТрети аргумент задава файл със стойности за проверките на чарта. Без него скриптът използва docs/example-values.yaml от пакета.
- Прочетете последния ред, който трябва да бъде
VERIFY-BUNDLE PASS, преди да продължите нататък.
1 SHA256SUMS OK files=<n>
2 SHA256SUMS signature OK
3 images signed + SBOM-attested: <n>
4 helm lint --strict OK nexus-1.0.0-alpha.1.tgz
5 coverage OK rendered=<n> lock=<n>
6 source offer OK images=5 files=<n>
VERIFY-BUNDLE PASS files=<n> images=<n>
Скриптът спира при първата неуспешна проверка. Ето какво прави всяка от тях.
| Стъпка | Какво проверява |
|---|---|
| 1 | Всеки файл, изброен в SHA256SUMS, съвпада със своята контролна сума и не присъства нито един файл, който списъкът пропуска. Подхвърлен допълнителен файл води до неуспех също толкова сигурно, колкото и променен такъв. |
| 2 | SHA256SUMS.sigstore.json е валидна сигнатура върху SHA256SUMS от ключа, който сте подали. Със стъпки 1 и 2 заедно всеки байт в пакета е байтът, подписан от Adverant. |
| 3 | За всяка директория с образи: дайджестът на индекса на образа е в release/images.lock.json; има сигнатура от cosign, чийто обект е точно този дайджест, и тя се верифицира спрямо Вашия ключ; както cosign verify, така и cosign verify-attestation --type spdxjson преминават успешно върху запазената структура. |
| 4 | helm lint --strict преминава успешно върху чарта с примерните стойности или с Вашите. |
| 5 | Всеки образ в заключващия файл е запазен в images/ и всеки образ, който чартът рендерира, е дайджест в заключващия файл. Нищо, което чартът инсталира, не идва от друго място. |
| 6 | Когато заключващият файл съдържа образи от слоя за данни, release/source-offer.json е пълен, посочва всеки един от тях и всеки файл с изходен код, който изброява, присъства с правилната контролна сума. |
Стъпка 3 проверява самата сигнатура по дайджест, освен че изпълнява cosign verify. Причината е собственото поведение на cosign: cosign verify върху запазена структура също завършва с код 0, когато структурата съдържа само атестация от ключа, но не и сигнатура. Скриптът не приема това.
Ако това не успее
Неуспехът завършва с VERIFY-BUNDLE FAIL step=<k> <why>.
| Последен ред | Какво означава | Какво да предприемете |
|---|---|---|
step=0 the public key must come from outside the bundle |
Ключът, който сте посочили, се намира вътре в директорията на пакета. | Използвайте ключа, който сте внесли отделно. |
step=1 checksum mismatch |
Файл е бил променен след създаването на списъка или е бил повреден при преноса. | Копирайте пакета отново от оригиналния носител и проверете пак. |
step=1 files not covered by SHA256SUMS |
Към пакета е бил добавен файл. | Третирайте носителя като ненадежден. Не инсталирайте от него. |
step=2 SHA256SUMS signature does not verify |
Списъкът с контролни суми не е подписан с ключа за издания, който притежавате. | Спрете. Докладвайте на Вашия екип по сигурността и поискайте от Adverant нов носител. |
step=3 image <svc>: ... |
Сигнатурата на образ или SBOM атестацията липсва или не преминава проверката. | Спрете, както при стъпка 2. |
step=4, step=5 |
Чартът или неговият списък с образи са несъвместими. | Поискайте от Adverant нов пакет. |
step=6 ... |
Предложението за изходен код е непълно. | Поискайте от Adverant нов пакет. |
Неуспех при стъпки 2 и 3 е случаят, заради който съществува цялата тази архитектура. Това означава, че файловете не са тези, които Adverant е подписал. Запазете носителя за Вашия екип по сигурността.
Зареждане на образите във Вашия собствен регистър
Вашите възли изтеглят образи от регистър вътре в обекта. Този на Harrow е registry.harrow.example. Всеки образ на Nexus отива в пътя nexus/ в този регистър, тъй като чартът се обръща към всеки образ като <global.imageRegistry>/nexus/<svc>@<digest>.
- Влезте във Вашия регистър с инструмента, който обикновено използвате, за да може
cosignда качва в него. - От вътрешността на директорията на пакета заредете всеки образ и го проверете отново на новото му място:
REG=registry.harrow.example
jq -r '.images[] | "\(.svc) \(.index)"' release/images.lock.json | while read -r svc digest; do
cosign load --dir "images/$svc" "$REG/nexus/$svc"
cosign verify --key release.pub --insecure-ignore-tlog=true "$REG/nexus/$svc@$digest" > /dev/null \
&& cosign verify-attestation --key release.pub --insecure-ignore-tlog=true --type spdxjson "$REG/nexus/$svc@$digest" > /dev/null \
&& echo "verified $svc"
donecosign load пренася сигнатурата и всяка атестация заедно с образа, така че копието в регистъра се проверява спрямо същия ключ. Проверката тук е тази, която има значение за Вашия клъстер: тя доказва, че това, което Вашите възли ще изтеглят, е това, което Adverant е подписал.
verified nexus-alpha
verified nexus-auth
verified nexus-postgres
...
Всеки образ в заключващия файл трябва да изведе един ред verified. Липсващ ред означава, че зареждането или проверката на този образ са се провалили, а грешката му е изведена точно отгоре.
Няма дневник за прозрачност (transparency log) за изданията на Nexus, затова --insecure-ignore-tlog=true е необходим при всяка проверка. Ключът за издания е целият корен на доверие. Без този флаг cosign отказва с not enough verified log entries from transparency log: 0 < 1.
Инсталиране от Вашия регистър
Файлът със стойности за изолирана инсталация се различава от този за свързана с един ред: global.imageRegistry посочва Вашия регистър.
# harrow-prod-values.yaml (Helm values)
global:
imageRegistry: registry.harrow.example
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: enterprise
enterprise:
enabled: true
tls:
mode: existing
existingSecret: harrow-public-tls
storage:
className: harrow-ssd
keys:
installationName: harrow-port
custody:
recipients:
- "<custodian-one-age-recipient>"
- "<custodian-two-age-recipient>"Записите в <custodian-...-age-recipient> са публичните редове age1... на хората, които държат ключовете за възстановяване на хранилището за ключове. Глава 2.8, Инсталации на една машина, обяснява как всеки от тях си създава такъв. harrow-ssd е собственият клас за съхранение на Harrow: сложете Вашия или пропуснете storage.className, за да използвате този по подразбиране за клъстера.
- Изпълнете предварителната проверка (preflight) спрямо клъстера с този файл, както е описано в глава 2.5, Предварителна проверка с nexusctl.
- Инсталирайте от чарта на пакета и пропуснете
--wait.
helm install nexus charts/nexus-1.0.0-alpha.1.tgz -n nexus --create-namespace \
-f harrow-prod-values.yaml --timeout 45m
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900shelm install --wait води до взаимно блокиране (deadlock) с този чарт: кука след инсталиране (post-install hook) дава на всяка услуга нейната парола за базата данни, а --wait задържа куките, докато услугите не стартират. Глава 2.8, Инсталации на една машина, съдържа цикъла, който изчаква и ресурсите StatefulSet.
С nexusctl същата инсталация е nexusctl install --context <kube-context> --values harrow-prod-values.yaml.
Нищо в чарта не излиза извън пространството от имена (namespace), освен DNS (Domain Name System), Kubernetes API (приложен програмен интерфейс) за проверки на токени и всеки адрес, който изброите в networkPolicy.externalEgressCIDRs, който по подразбиране е празен. Никаква телеметрия не напуска инсталацията, а telemetry.enabled не може да бъде зададен на нищо друго освен на false. За ИИ (изкуствен интелект) в обект без интернет организацията свързва свой собствен OpenAI-съвместим сървър за модели вътре в обекта, посочен в ai.localProvider.baseUrl; глава 2.14, Доставчици и модели на ИИ, разглежда това.
Лицензът не е стойност в чарта. Импортирате го след инсталацията, както е описано по-долу.
k3s и cert-manager без изтегляне
Ако Nexus ще се слага на k3s клъстер, който изграждате сами, k3s също трябва да се инсталира без мрежа. Дисковият образ на инсталатора прави това вместо Вас (глава 2.9, Дисковият образ на инсталатора). Ръчно, на всеки възел:
- Пренесете файловете на изданието k3s v1.33.6+k3s1 за Вашата архитектура: бинарния файл
k3s(k3s-arm64при arm64),install.sh,k3s-airgap-images-<arch>.tar.zstиsha256sum-<arch>.txt. k3s публикува контролни суми за тези файлове, но не и сигнатура. Проверете всеки файл спрямоsha256sum-<arch>.txtи уточнете ясно с Вашия екип по сигурността, че това е контролна сума от същия източник, а не сигнатура. - Поставете бинарния файл и системните образи там, където k3s ги търси, и инсталирайте с изключени изтегляния:
sudo install -m 0755 k3s /usr/local/bin/k3s
sudo mkdir -p /var/lib/rancher/k3s/agent/images
sudo cp k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/
sudo INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC="--write-kubeconfig-mode=0600" sh install.sh
sudo k3s kubectl wait --for=condition=Ready node --all --timeout=600scert-manager v1.21.3 е предварително изискване: собственият CA (сертифициращ орган) на чарта е издател на cert-manager. Пренесете чарта на cert-manager, cert-manager-v1.21.3.tgz, и неговите образи. От свързаната страна проверете образите със собствения ключ на проекта cert-manager, преди да бъдат пренесени:
cosign verify --signature-digest-algorithm sha512 --insecure-ignore-tlog=true \
--key cert-manager-pubkey-2021-09-20.pem quay.io/jetstack/<image>@<digest>Вътре в обекта импортирайте образите в хранилището за контейнери на всеки възел под имената, които чартът на cert-manager изисква, quay.io/jetstack/cert-manager-<name>:v1.21.3, след което ги проверете и инсталирайте:
sudo k3s ctr -n k8s.io images import --all-platforms cert-manager-images.tar
sudo k3s ctr -n k8s.io images ls -q | grep cert-manager
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10m--wait е правилен за cert-manager. Само Nexus не трябва да го има.
Обновленията и новите компоненти пристигат на подписан носител
Изолираният обект се надгражда също от диск. В конзолата Import from media на страниците This installation зарежда издание от диск, внесен в обекта. Проверява се контролната сума на всеки файл, след това сигнатурата спрямо ключа за издания, който вече е инсталиран в обекта, и никога спрямо ключ, донесен от диска, а след това дали изданието е по-ново от работещото в момента. Импортирането само копира и проверява. Хората продължават да работят на текущото издание и нищо не се променя, докато не изберете да надградите.
От командния ред същото издание се въвежда с nexusctl:
nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar
nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tarplan показва какво ще се промени и не променя нищо. apply първо прави резервно копие и след това надгражда. Глава 2.15, Ден втори: работа с Nexus, разглежда надгражданията изцяло.
Когато сигнатурата на диска не съвпада, импортирането се отказва с MEDIA_SIGNATURE_INVALID. Нищо не се зарежда или копира, а текущото издание продължава да работи. Страницата показва кои проверки са преминали успешно, къде е спрял процесът, както и очаквания ключ до намерения ключ. Запазете диска за Вашия екип по сигурността и поискайте от Adverant нов.
Частите от Enterprise, които лицензът включва, идват по същия начин в изолиран обект: на диска с изданието, чрез Import from media, преди да ги включите. Всяка част се проверява спрямо ключа за издания на Adverant, преди да бъде активирана, така че никога не копирате бинарен файл в клъстера на ръка.
Лицензи без интернет
Свързаната инсталация получава своя лиценз сама. Изолираната обменя файлове с Adverant ръчно, чрез офлайн обмена.
- Страниците за лицензи в конзолата създават малък файл със заявка за лиценз. Инсталацията го подписва със своя собствен ключ, за да може Adverant да разпознае коя инсталация е направила заявката.
- Някой изнася файла на USB флаш памет до компютър с интернет, влиза в профила в Adverant на адрес
https://account.adverant.aiи го качва на страницата Offline exchange. - По същия начин донасят обратно лицензния файл.
- Импортирайте го. В конзолата отворете Licence and what it unlocks и натиснете Import a new licence. От командния ред:
nexusctl licence import harrow-port-licence.jsonЛицензът се проверява офлайн, вътре в обекта, спрямо ключовете на Adverant. Adverant подписва всеки лиценз с два независими ключа и двете сигнатури трябва да преминат проверката успешно.
Същият обмен изнася и годишния отчет за потреблението. Той съдържа само броячи (работни места, устройства, групи функции) и администраторът го прочита ред по ред в Usage statement for Adverant, преди да бъде изнесен.
| Код | Състояние | Какво означава |
|---|---|---|
LICENCE_SIGNATURE_INVALID |
422 | Файлът не е лиценз, подписан от Adverant, или някой байт е бил променен след подписването. Нищо не се променя. |
LICENCE_OTHER_INSTALLATION |
409 | Лицензът е истински, но е издаден за друга инсталация. Поискайте такъв, издаден за идентификатора на тази инсталация. |
LICENCE_CLOCK_BEHIND_FLOOR |
409 | Часовникът показва по-ранно време от последното време, което тази инсталация е регистрирала. Връщането на часовника назад не съживява изтекъл лиценз. |
LICENCE_REVOKED |
403 | Adverant е оттеглил лиценза чрез подписано оттегляне. Частите от Enterprise спират да се предлагат; Community и експортирането остават. |
Глава 2.13, Лицензи, разглежда състоянията, гратисния период и подновяването.
Списъците с оттеглени лицензи се импортират ръчно
Когато Adverant оттегли лиценз, той публикува подписан списък с оттеглени лицензи. Списъкът е кумулативен: всеки съдържа всички лицензи, оттеглени преди него. Свързаната инсталация научава за това автоматично. Изолираната научава само когато някой импортира списъка, затова внасяйте най-новия списък с всеки диск с издание и го импортирайте чрез функцията за импортиране на оттегляния на страниците за лицензи на инсталацията или през адреса /api/v1/installation/licence/revocations на хоста за влизане.
Това е нож с две остриета. Изолирана инсталация, която никога не импортира списък, никога не научава, че даден лиценз е бил оттеглен, включително лиценз, подписан с ключ, за който по-късно е установено, че е компрометиран. Импортирането на списъка е единственият начин тази новина да премине през изолацията.
Суверенният запечатан пакет: nexus-airgap
Някои суверенни обекти искат изданието като един запечатан, подписан файл, чийто собствен манифест забранява мрежовия достъп. За тях има втори формат – запечатаният пакет (sealed bundle), и неговият инструмент nexus-airgap от пакета @adverant/nexus-sovereign. Инсталирайте инструмента от регистъра с пакети на Adverant, отделно от всеки пакет, който той ще проверява. Един пакет не може да гарантира сам за себе си.
Запечатаният пакет представлява единичен подписан tar архив (tarball). Неговият манифест е подписан с Ed25519 и изброява SHA-256 сума за всеки файл. Инструментът има четири команди.
| Команда | Какво прави |
|---|---|
nexus-airgap bundle |
Изгражда запечатан пакет от подготвена директория и подписва неговия манифест. |
nexus-airgap verify --bundle <file> --trusted-key <pem> --profile <profile> |
Проверява сигнатурата спрямо доверения ключ, хешира отново всеки файл, отхвърля всеки файл, който не е изброен в манифеста, и отхвърля пакет, чието мрежово правило не е празният списък с разрешени адреси с трафик на агента само локално. Не променя нищо. |
nexus-airgap install |
Проверява, след което изпълнява плана за инсталиране по ред: зареждане на образите, прилагане на манифестите, изпълнение на миграциите, зареждане на уменията, провизиране на ключовете. |
nexus-airgap open |
Отваря опционалния криптиран експорт на пакета със собствения пазител на ключове на обекта, който в изолиран обект е TPM (Trusted Platform Module) чипът на машината. |
Проверете преди всичко останало:
nexus-airgap verify --bundle nexus-alpha-1.0.0-alpha.1.tar.gz \
--trusted-key release.pub --profile airgap --keep-staging > verify.json
jq '{ok, bundleId, profile, artifactsVerified}' verify.json--keep-staging запазва провереното, разархивирано копие и го посочва като stagingDir в изхода, така че да работите от това, което е било проверено.
Ако проверката се провали с BUNDLE_INTEGRITY_VIOLATION, файл вътре в пакета е бил променен след подписването му. Спрете дотук. Инструментът има флаг --no-strict, който пропуска проверката за неизброени файлове. Не го използвайте върху издание.
В деня, в който пристигне следващият диск
Tomás държи кратък контролен списък, залепен от вътрешната страна на шкафа в портала, който си струва да бъде копиран. Проверете .sha256 на tar архива. Изпълнете verify-bundle.sh с инсталирания ключ и прочетете последния ред. Импортирайте най-новия списък с оттеглени лицензи. Тогава и само тогава импортирайте изданието от носителя и планирайте надграждането. Диск, който се провали на някоя от тези стъпки, се връща обратно в плика си, надписан за екипа по сигурността, а в мрежата не се е променило нищо.


