Версия 1.0.0-alpha.1последно
Глава 2.9
Дисковият образ на инсталатора
Стартирайте физически сървър или виртуална машина от инсталационния образ на Nexus и той ще инсталира операционната система, k3s, cert-manager и Nexus без мрежа, като проверява всеки файл преди употреба.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Офисът на капитана на пристанището на източния кей в Harrow разполага с един сървър, няма интернет и на място няма никой, който да работи с Kubernetes. Въпреки това на Tomás Reilly му беше нужен Nexus на този сървър. Той записа образа на USB (Universal Serial Bus) флаш памет, постави до нея втора, малка флаш памет с четири реда настройки и стартира сървъра. Час по-късно екранът показа адреса на конзолата и трите реда, които да се добавят във файла hosts. Той не написа нито една команда за Kubernetes.
Това е задачата на инсталационния дисков образ. Той записва минимална операционна система на диска на сървъра, след което при първото стартиране проверява всеки файл, който носи, спрямо ключа за издания на Adverant, инсталира k3s без мрежа, импортира всеки образ, инсталира cert-manager и Nexus и проверява дали всеки под работи. Всяка стъпка спира с посочена причина в момента, в който нещо не е наред. Никъде няма резервен режим с ограничена функционалност, нито парола по подразбиране.
Двата образа
Всяко издание се предлага като два вида образи за две процесорни архитектури – amd64 и arm64.
| Файл | Какво съдържа | Кой може да го изтегли |
|---|---|---|
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso |
Само инсталаторът: операционната система, k3s v1.33.6+k3s1, cert-manager v1.21.3 и инсталаторът при първо стартиране. Работи и за двете издания и не съдържа образи на Nexus. | Всеки, от downloads.adverant.ai |
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso |
Същият инсталатор, към който офлайн пакетът за съответното издание е добавен като втори дял с етикет NEXUS-BUNDLE. Един носител инсталира всичко. |
Community: всеки. Enterprise: само от профила Ви в Adverant |
<arch> е amd64 или arm64, а <edition> е community или enterprise.
Инсталаторът търси единствено файлова система с етикет NEXUS-BUNDLE. При комбинирания образ (all-in-one) това е дялът в самия образ. При образа само с инсталатор носите пакета на втори диск или флаш памет с този етикет, което е удобно, когато инсталирате на няколко обекта от една инсталационна флаш памет и сменяте само пакета. Глава 2.10, Инсталация в изолирана среда (air-gapped), описва пакета.
Образите и пакетите за Enterprise никога не са анонимни. Изтегляте ги от профила си в Adverant на адрес https://account.adverant.ai, от страницата Downloads (Изтегляния), до Вашия лиценз. Образите и пакетите за Community са публични.
От какво е изграден образът
Операционната система е базирана на Debian 13 и не е официален образ на Debian. Тя съдържа базовата система на Debian и нищо друго: никакви допълнителни пакети, никаква работна среда и никакво огледално хранилище (mirror). k3s предоставя собствена среда за изпълнение на контейнери и мрежова функционалност. Веригата за стартиране (shim, GRUB, ядрото и началният ramdisk) съвпада байт по байт с тази, която доставя Debian, така че машина с включен Secure Boot я стартира като всеки инсталатор на Debian.
Две компилации на едно и също издание дават идентични образи, байт по байт, и изданието не се публикува, докато това не се постигне. Пакетите с изходен код на Debian за всеки двоичен файл в образа се публикуват до него като nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, в същия списък с контролни суми.
Проверете изтегления файл, преди да го запишете
Директорията с образи в downloads.adverant.ai съдържа образите, файл SHA256SUMS, обхващащ всеки публикуван файл, и SHA256SUMS.sigstore.json – подписа върху този списък, направен с ключа за издания на Adverant. Вземете публичния ключ за издания отделно, запазете го като release.pub и проверете отпечатъка му, както е описано в глава 2.4, Получаване и проверка на издание.
- Проверете подписа върху списъка с контролни суми. Няма регистър за прозрачност (transparency log) за изданията на Nexus, затова флагът, който пропуска търсенето в регистъра, е задължителен.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
--bundle SHA256SUMS.sigstore.json SHA256SUMSVerified OK
- Проверете изтегления образ спрямо списъка:
grep nexus-alpha-community-1.0.0-alpha.1-amd64.iso SHA256SUMS | sha256sum -c -nexus-alpha-community-1.0.0-alpha.1-amd64.iso: OK
На Mac използвайте shasum -a 256 -c - вместо sha256sum -c -.
- Запишете образа на USB флаш памет с инструмента, който обикновено използвате, или го прикачете към виртуалната машина като оптичен диск.
k3s публикува контролни суми за файловете от своите издания, но не и подпис, затова файловете на k3s вътре в образа се проверяват спрямо контролните суми, които k3s публикува, от същия източник като самите файлове. Всичко, изградено от Adverant, е подписано.
Пакети на части
Пакет, който пренасяте на отделна флаш памет, е няколко гигабайта. Някои файлови системи, сред които FAT (File Allocation Table), не могат да съдържат файл с размер 4 GiB или повече, затова файловете на пакетите се публикуват на части от по 2047 MiB, които се побират на всяка флаш памет. Съединете частите обратно в правилния ред и проверете съединения файл спрямо неговия .sha256, преди да го използвате.
Необходимият хардуер
Първото стартиране проверява машината, преди да промени каквото и да било, и отказва да продължи, ако тя е твърде малка.
| Проверка | Базовият минимум | Кога се проверява |
|---|---|---|
| Архитектура | Собствената за образа: образ amd64 на amd64, arm64 на arm64 | Първо стартиране |
| Памет | 16 GiB | Първо стартиране |
| Целеви диск | Точно един празен диск с поне 64 GB или дискът, посочен в seed | Преди да бъде записана операционната система |
Свободно място в / |
50 GB след като операционната система е инсталирана | Първо стартиране |
| Часовник | Не по-стар от датата, на която е компилиран образът | Първо стартиране |
Това са минимални прагове, а не препоръка. С настройките по подразбиране на чарта само томовете на Nexus възлизат на 142 GiB, така че диск от 64 GB преминава проверката на инсталатора, но се запълва за дни. Използвайте това, което трябва да има един самостоятелен възел: 8 vCPU (виртуални централни процесорни единици), 32 GiB памет и 250 GB SSD (твърдотелен диск). Четири vCPU, 16 GiB и 200 GB са достатъчни за тестова оценка.
Проверката на часовника е заложена, тъй като по време на инсталацията сървърът няма мрежа и съответно няма услуга за сверяване на времето. Сертификатите и подписите се проверяват спрямо часовника. Ако хардуерният часовник на машината изостава спрямо датата на компилиране на образа, първото стартиране спира и изисква да го настроите. Настройте го в настройките на фърмуера и стартирайте отново.
Физически сървъри и виртуални машини
Образът се стартира на UEFI (Unified Extensible Firmware Interface) фърмуер, както на физически сървъри, така и на виртуални машини. Той инсталира програмата за начално зареждане (boot loader) както на пътя за сменяеми носители, така и на обичайния път, така че VM (виртуална машина) без запазени записи за стартиране все пак я намира след първото рестартиране. Задайте на виртуалната машина паметта и диска от таблицата по-горе, един празен виртуален диск и образа като CD.
Инсталаторът избира целевия диск по строго правило и никога не избира просто „първия диск“.
- Пропуска носителя, от който е стартиран.
- Пропуска сменяемите дискове, освен ако в seed не е посочен такъв.
- Пропуска всеки диск, който вече има таблица на дяловете от какъвто и да е вид.
- Пропуска дискове под 64 GB и извежда съобщение за това на конзолата.
- Инсталира само когато остане точно един диск.
На сървър с два празни диска той спира и Ви моли да изберете. Избирате, като посочите диска в seed с wipe: true, което е единственият начин той изобщо да запише върху диск, който вече има дялове.
Томът NEXUS-SEED
Томът с начални настройки (seed) е малък том, обикновено USB флаш памет, с файлова система с етикет NEXUS-SEED и файл seed.yaml в основната си директория. Инсталаторът го монтира само за четене, прочита настройките и го премонтира с права за запис едва в самия край, за да Ви остави паролата за операционната система.
# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m| Ключ | Какво задава | Когато липсва |
|---|---|---|
domain |
Домейнът на инсталацията. Инсталаторът извлича трите хоста от него: console.<domain>, api.<domain> и auth.<domain>. |
Изисква се на конзолата на сървъра |
adminEmail |
Имейлът на лицето, което ще бъде първият администратор | Изисква се на конзолата на сървъра |
edition |
community или enterprise. Когато е зададено, трябва да съвпада с изданието на пакета. |
Взема се от пакета |
timeout |
Колко време може да отнеме инсталирането на cert-manager и Nexus, като продължителност, например 30m или 1h |
30m |
time |
Текущото време в UTC във формата, който отпечатва съобщението за часовника (2026-11-14T09:00:00Z), за машина, чийто хардуерен часовник не може да бъде настроен или не запазва настройката си. Машина без мрежа няма сървър за време, към който да се обърне. |
Използва се хардуерният часовник |
disk |
Целевият диск, като /dev/<name>, използва се само заедно с wipe: true |
Правилото за празен диск по-горе |
wipe |
true позволява на инсталатора да изтрие диска, посочен от disk |
Никога не се изтрива диск |
За Enterprise поставете лицензния файл на същия том като licence.json. Без него първото стартиране спира на стъпката за seed и съобщава, че лицензът липсва. Community не се нуждае от лиценз и при Community целият seed не е задължителен: инсталаторът изисква домейна и имейла на конзолата и продължава.
Инсталаторът чете всеки ред като key: value в началото на реда. Пишете по един ключ на ред, на най-горното ниво, без кавички и без отстъп. Стойност в кавички се прочита заедно с кавичките.
При първото стартиране инсталаторът пита на конзолата и за пазителя (custodian) на хранилището за ключове: публичната половина от ключ за age, age1..., създаден на собствената машина на пазителя с age-keygen -o custodian.key. Хранилището за ключове запечатва своите ключове за възстановяване с него. Глава 2.8, Инсталации на една машина, обяснява ролята на пазителите. Пазителят съхранява частната половина офлайн и на сигурно място: без нея никой не може да разпечата хранилището за ключове след рестартиране.
Какво се случва – от включването до адреса на конзолата
Първи етап: операционната система
Образът стартира автоматизиран инсталатор на Debian. Той не конфигурира мрежа, не използва огледално хранилище и не инсталира никакви пакети извън базовата система. Задава часовата зона на UTC (координирано универсално време), деактивира влизането като root и създава един потребител, nexus, чиято парола е заключена. Избира целевия диск по правилото по-горе и записва GPT (таблица на дяловете с глобално уникален идентификатор) диск със системен дял за EFI (Extensible Firmware Interface) и една коренова файлова система ext4, без swap.
Накрая копира инсталатора на Nexus върху новата система, проверява всеки копиран файл спрямо списъка с контролни суми на образа и активира услуга за първо стартиране. Ако някой копиран файл не съвпада, процесът спира дотук. След това изважда носителя и рестартира.
Втори етап: първото стартиране
При първото стартиране услугата nexus-install се изпълнява веднъж. Всяка стъпка се извежда на конзолата на сървъра и в журнала и се отбелязва като завършена, така че повторен опит започва от първата незавършена стъпка. Услугата като цяло може да работи до четири часа, преди systemd да я спре, което оставя време за бавен диск и един час изчакване за поставяне на флаш паметта с пакета.
- Предварителна проверка (Preflight). Архитектурата, часовникът, паметта и свободното дисково пространство, както са посочени в таблицата по-горе.
- Полезен товар (Payload). Собствените файлове на инсталатора: подписът върху неговия списък с контролни суми спрямо ключа за издания, който носи, а след това и всеки файл спрямо този списък.
- Начални настройки (Seed). Чете
seed.yamlи изисква на конзолата всичко, което липсва. - Пакет (Bundle). Намира тома с етикет
NEXUS-BUNDLEи го монтира само за четене. Ако няма такъв, извеждаwaiting-for-bundleи изчаква до един час да го прикачите. След това изпълнява пълната проверка на пакета, завършваща сVERIFY-BUNDLE PASS, спрямо ключа за издания, който носи, преди каквото и да било да бъде импортирано. Пакет за Enterprise изискваlicence.jsonв seed, а изданието в seed трябва да съвпада с това на пакета. - k3s. Инсталира k3s v1.33.6+k3s1 от собствените файлове на образа при изключени изтегляния и изчаква до десет минути възелът да премине в състояние Ready. След това премахва архива с образи за изолирана среда на k3s, за да не се импортират образите отново при всяко стартиране.
- Импортиране (Import). Импортира всеки проверен образ от пакета, както и образите на cert-manager, в хранилището за контейнери на възела. Нищо и никога не се изтегля от регистър.
- cert-manager, след това Nexus. Инсталира cert-manager v1.21.3, а след това чарта на Nexus от пакета, и двете в рамките на зададеното в seed
timeout. - Приемане (Acceptance). Проверява дали всеки под е в състояние Running и дали всяка задача от тип hook Job е завършила.
- Удостоверение за достъп (Credential). Задава на потребителя на операционната система
nexusнова произволна парола, показва я веднъж на конзолата и я записва вnexus-os-password.txtна тома със seed, когато в тома може да се записва.
Проверката на пакета в стъпка 4 е същият скрипт, който изпълнявате ръчно в глава 2.10, Инсталация в изолирана среда (air-gapped), и отпечатва същите редове:
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>
Ред 3 преброява образите, които носят валиден подпис и подписан SBOM (списък със софтуерни компоненти) – списъкът с това какво съдържа всеки образ. Бройките (<n>) зависят от изданието. Важен е последният ред.
Инсталацията записва стойности в текущата форма на чарта: global.domain и трите имена на hosts.* от домейна в seed, както и keys.custody.recipients от пазителя, който сте въвели на конзолата. Инсталира се от собствения чарт и образи на пакета, така че изданието на диска е точно изданието, което е било проверено.
Последните редове на конзолата
Когато всяка стъпка премине успешно, конзолата показва веднъж паролата за операционната система и адреса, който трябва да отворите:
nexus-install: OS login: user nexus, password <shown-once> (shown once; change it with passwd)
nexus-install: DONE: https://console.harrow.example (add to /etc/hosts: 10.20.4.15 console.harrow.example api.harrow.example auth.harrow.example)
Запишете си паролата или я вземете от флаш паметта със seed, след което влезте като nexus и я сменете с passwd. Никой, включително Adverant, не знае парола по подразбиране за тази машина, защото такава няма.
Адресът в реда за hosts е собственият адрес на сървъра. Тъй като на кея нямаше DNS (Domain Name System), Tomás добави този единствен ред във файла hosts на всеки лаптоп, който щеше да използва конзолата. На обект с DNS вместо това добавете записи за трите имена.
След инсталацията
Инсталацията е непотвърдена (unclaimed). Никой не може да влезе, докато някой не я заяви в браузър, сравнявайки отпечатъка на инсталацията с този, който показва сървърът. Глава 2.12, Първото стартиране, разглежда заявяването, първия администратор и ключа за достъп (passkey). Първият администратор трябва да бъде лицето, чийто имейл е посочен в seed.
Собственият kubeconfig на възела се намира в /etc/rancher/k3s/k3s.yaml и може да се чете само от root. За да работите по клъстера от работна станция, nexusctl kubeconfig го отпечатва, както е описано в глава 2.8, Инсталации на една машина.
Обновленията пристигат по същия начин, по който и инсталацията: издание на подписан носител, проверено спрямо ключа, който вече е инсталиран на сървъра, и никога спрямо ключ, който дискът носи със себе си. Глава 2.10, Инсталация в изолирана среда (air-gapped), описва тази проверка.
Ако това не успее
Всеки неуспех отпечатва nexus-install: FAILED <step>: <what is missing> на конзолата и записва същото в /var/lib/nexus/install.state. Отстранете причината и пуснете инсталацията отново от първата стъпка, която не е завършена:
sudo nexus-install retry| Съобщение | Какво означава | Какво да предприемете |
|---|---|---|
FAILED preflight: payload is for arm64, this machine is amd64 |
Стартирали сте образа за другата архитектура. | Използвайте образа за архитектурата на тази машина. |
FAILED preflight: memory 11 GiB, need >= 16 GiB |
Машината има по-малко от минималния праг. | Добавете памет или задайте повече на виртуалната машина. |
FAILED preflight: free disk 38 GB on /, need >= 50 GB |
Кореновата файлова система е твърде малка. | Инсталирайте на по-голям диск. |
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed |
Хардуерният часовник изостава спрямо датата на компилиране на инсталатора. | Настройте часовника във фърмуера или задайте time в seed.yaml и опитайте отново. |
FAILED payload: SHA256SUMS signature does not verify |
Собствените файлове на инсталатора не са това, което Adverant е подписал. | Спрете. Изтеглете образа отново и го проверете преди записване. |
FAILED seed: the installation domain and the first administrator e-mail are required |
Нито seed, нито конзолата са ги предоставили. | Добавете ги в seed.yaml или отговорете на подканите. |
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) |
Пакетът е Enterprise, а в seed няма лиценз. | Поставете licence.json на тома със seed. |
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h |
Не е бил прикачен пакет навреме. | Прикачете флаш паметта с пакета и опитайте отново. |
FAILED bundle: the bundle does not verify with this installer's release key |
Проверката на пакета не е завършила с VERIFY-BUNDLE PASS. Собственият й изход над съобщението посочва стъпката. |
Спрете. Не използвайте този пакет. Вземете нов. |
FAILED bundle: the seed asks for enterprise, the bundle is community |
Seed и пакетът се разминават. | Коригирайте edition в seed или донесете правилния пакет. |
FAILED k3s: node not Ready within 10 min |
k3s не се е стартирал. | Проверете журнала за k3s, след което опитайте отново. |
FAILED nexus: helm install nexus |
Чартът не се е инсталирал в рамките на времето за изчакване. | Прегледайте kubectl -n nexus get pods,jobs, увеличете timeout в seed, ако машината е бавна, и опитайте отново. |
FAILED acceptance: pods not ready |
Някои подове не работят след инсталацията. | Съобщението изброява до пет. Прочетете техните събития (events), отстранете проблема и опитайте отново. |
FAILED acceptance: jobs not complete: <jobs> |
Задача от тип hook Job не е завършила. | Прочетете дневника на посочената задача Job с kubectl -n nexus logs job/<name>, коригирайте това, което тя отчита, и опитайте отново. |
Преди да бъде записана операционната система, изборът на диск също може да спре инсталацията. Съобщението му започва с nexus select-disk: REFUSED:. Често срещаното е found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Посочете диска в seed и стартирайте отново.
Неуспешната проверка на пакета е нещото, което трябва да приемете сериозно. Това означава, че файловете на диска не са файловете, подписани от Adverant, или че е бил добавен файл. Към този момент инсталаторът не е импортирал нищо, така че сървърът е непроменен. Запазете диска за Вашия екип по сигурността.

