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

Глава 2.10

Инсталация в изолирана среда

Пренесете подписан офлайн пакет в обект без интернет, проверете го спрямо ключ, който сте внесли отделно, заредете го в собствения си регистър и инсталирайте. Лицензите, обновленията и списъците с анулирани сертификати също преминават изолираната зона на ръка.

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

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

Оперативната мрежа на Harrow Port Authority няма маршрут към интернет – както по закон, така и по проект. В нея се намират трафикът на плавателните съдове, плановете за кейовите места и митническите задържания и нищо в нея няма право да прави изходящи връзки. Когато Tomás Reilly инсталира Nexus там, всеки байт пристигна на диск, донесен от куриер до портала, и всеки байт беше проверен вътре в обекта, преди каквото и да било да го използва.

Тази глава описва именно тази инсталация. Получавате подписан офлайн пакет, проверявате го с ключ, достигнал до Вас по различен маршрут, копирате неговите образи във Вашия собствен регистър, проверявате ги отново там и инсталирате чарта с името на Вашия регистър в стойностите. След това идват нещата, които един изолиран (air-gapped) обект прави ръчно, а свързаният получава наготово: k3s и cert-manager без изтегляне, актуализации на носител, лицензи чрез офлайн обмен и списъци с оттеглени лицензи, които импортирате сами.

Отляво поле „connected side“ съдържа „downloads.adverant.ai“ и „your Adverant account“. Две отделни стрелки пресичат дебела вертикална линия с надпис „the gap“. Горната стрелка с надпис „once, by a separate route; fingerprint checked out of band“ пренася „release.pub“. Долната стрелка с надпис „every release, on a disk“ пренася „nexus-alpha-1.0.0-alpha.1-enterprise.tar“. Отдясно, вътре в „Harrow operations network“, и двете пристигат в поле „verify-bundle.sh: VERIFY-BUNDLE PASS“, което води към „registry.harrow.example (cosign load, cosign verify)“ и след това към „the cluster (helm install)“.
Как едно издание и неговото доверие преминават през изолацията по два отделни маршрута.

Какво съдържа офлайн пакетът

Пакетът представлява една редакция на едно издание като некомпресиран 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, така че работи както на базов инсталационен възел, така и на работна станция.

  1. Проверете tar архива спрямо неговата контролна сума, след което го разархивирайте:
sha256sum -c nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256
tar -xf nexus-alpha-1.0.0-alpha.1-enterprise.tar
  1. Стартирайте проверката с ключа, който сте внесли:
./verify-bundle.sh nexus-alpha-1.0.0-alpha.1-enterprise release.pub

Трети аргумент задава файл със стойности за проверките на чарта. Без него скриптът използва docs/example-values.yaml от пакета.

  1. Прочетете последния ред, който трябва да бъде 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>.

  1. Влезте във Вашия регистър с инструмента, който обикновено използвате, за да може cosign да качва в него.
  2. От вътрешността на директорията на пакета заредете всеки образ и го проверете отново на новото му място:
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"
done

cosign 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, за да използвате този по подразбиране за клъстера.

  1. Изпълнете предварителната проверка (preflight) спрямо клъстера с този файл, както е описано в глава 2.5, Предварителна проверка с nexusctl.
  2. Инсталирайте от чарта на пакета и пропуснете --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=900s

helm 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, Дисковият образ на инсталатора). Ръчно, на всеки възел:

  1. Пренесете файловете на изданието k3s v1.33.6+k3s1 за Вашата архитектура: бинарния файл k3s (k3s-arm64 при arm64), install.sh, k3s-airgap-images-<arch>.tar.zst и sha256sum-<arch>.txt. k3s публикува контролни суми за тези файлове, но не и сигнатура. Проверете всеки файл спрямо sha256sum-<arch>.txt и уточнете ясно с Вашия екип по сигурността, че това е контролна сума от същия източник, а не сигнатура.
  2. Поставете бинарния файл и системните образи там, където 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=600s

cert-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 зарежда издание от диск, внесен в обекта. Проверява се контролната сума на всеки файл, след това сигнатурата спрямо ключа за издания, който вече е инсталиран в обекта, и никога спрямо ключ, донесен от диска, а след това дали изданието е по-ново от работещото в момента. Импортирането само копира и проверява. Хората продължават да работят на текущото издание и нищо не се променя, докато не изберете да надградите.

Импортиране от носител (без интернет)
Импортиране от носител (без интернет)
Издание на диск се импортира в Harrow. Сигнатурата се проверява спрямо ключа, инсталиран в обекта, а работещата версия остава непокътната, докато някой не извърши надграждане.

От командния ред същото издание се въвежда с 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.tar

plan показва какво ще се промени и не променя нищо. apply първо прави резервно копие и след това надгражда. Глава 2.15, Ден втори: работа с Nexus, разглежда надгражданията изцяло.

Когато сигнатурата на диска не съвпада, импортирането се отказва с MEDIA_SIGNATURE_INVALID. Нищо не се зарежда или копира, а текущото издание продължава да работи. Страницата показва кои проверки са преминали успешно, къде е спрял процесът, както и очаквания ключ до намерения ключ. Запазете диска за Вашия екип по сигурността и поискайте от Adverant нов.

Импортирането от носител е неуспешно
Импортирането от носител е неуспешно
Отказано импортиране. Всяка контролна сума съвпадна, но сигнатурата беше направена от непознат ключ, така че нищо не беше заредено и работещото издание остана непокътнато.

Частите от Enterprise, които лицензът включва, идват по същия начин в изолиран обект: на диска с изданието, чрез Import from media, преди да ги включите. Всяка част се проверява спрямо ключа за издания на Adverant, преди да бъде активирана, така че никога не копирате бинарен файл в клъстера на ръка.

Лицензи без интернет

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

  1. Страниците за лицензи в конзолата създават малък файл със заявка за лиценз. Инсталацията го подписва със своя собствен ключ, за да може Adverant да разпознае коя инсталация е направила заявката.
  2. Някой изнася файла на USB флаш памет до компютър с интернет, влиза в профила в Adverant на адрес https://account.adverant.ai и го качва на страницата Offline exchange.
  3. По същия начин донасят обратно лицензния файл.
  4. Импортирайте го. В конзолата отворете Licence and what it unlocks и натиснете Import a new licence. От командния ред:
nexusctl licence import harrow-port-licence.json

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

Офлайн обмен
Офлайн обмен
Страницата Offline exchange в профила в 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 с инсталирания ключ и прочетете последния ред. Импортирайте най-новия списък с оттеглени лицензи. Тогава и само тогава импортирайте изданието от носителя и планирайте надграждането. Диск, който се провали на някоя от тези стъпки, се връща обратно в плика си, надписан за екипа по сигурността, а в мрежата не се е променило нищо.