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

Глава 2.5

Предварителна проверка с nexusctl

Всяка проверка, която `nexusctl preflight` прави, какво чете всяка от тях и как се проваля, отчетът, който извежда и записва, как този отчет достига до страницата за предварителна проверка в конзолата, както и всеки флаг.

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

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

Първата ни предварителна проверка (preflight) в Harrow Port Authority не премина четири теста, а два от тях щяха да ни струват много повече от един следобед. Бяхме започнали файла със стойности (values), като копирахме примера от чарта (chart), и предварителната проверка отхвърли както примерното име на инсталацията, така и примерния пазител на ключове (custodian). Никой не притежава частния ключ на този пазител. Инсталация, запечатана с него, никога не може да бъде разпечатана след рестартиране на възел (node). Предварителната проверка улови това за няколко секунди, преди да съществува каквото и да е, което може да бъде загубено.

nexusctl preflight прочита вашия клъстер и файла със стойности, извежда какво е открил, запазва отчет и не променя нищо в клъстера. Стартирайте го преди всяка инсталация и всяко надграждане. Тази глава обхваща всяка проверка, която той прави, формата на отчета, къде отива отчетът и флаговете.

Експлоатация

Предварителната проверка се нуждае от две неща: kube контекста на клъстера, на който ще инсталирате, и файла със стойности, който инсталацията ще използва. Първо напишете файла със стойности; глава 2.6, Инсталиране на Community върху Kubernetes, разглежда всеки ключ. След това:

nexusctl preflight --context harrow-prod --values harrow-values.yaml

Той чете клъстера чрез client-go само с извиквания get и list. Ако вашият tls.mode е existing, създайте пространството от имена (namespace) nexus и обекта Secret за сигурност на транспортния слой (Transport Layer Security – TLS), преди да го стартирате (глава 2.6, Инсталиране на Community върху Kubernetes, стъпка 3), в противен случай проверката за сертификат ще докладва, че обектът Secret липсва.

Флаг Какво прави По подразбиране
--context <name> Kube контекстът за проверка. Задължителен няма
--values <file> Файлът със стойности, който инсталацията ще използва. Задължителен няма
--namespace <name> Къде се инсталира Nexus nexus
--release <version> Изданието, което се проверява собствената версия на включения чарт
--report-dir <dir> Къде се запазват двата отчетни файла текущата папка
--record <mode> auto, always или never: дали отчетът да се предаде на услугата за ключове на тази инсталация, за да се показва на нейната инсталационна страница auto
--kubeconfig <file> Kubeconfig файлът за четене KUBECONFIG, след това ~/.kube/config
--ca-bundle <file> Вашите собствени сертификати на сертифициращ орган (CA), за верига, на която проверките да се доверяват няма
--single-node Проверка на една машина за инсталация на единична машина (глава 2.8, Инсталации на единична машина) изключено

Минималната версия за Kubernetes на изданието не е записана твърдо в nexusctl. Тя прочита долната граница на собствения kubeVersion от чарта, който носи, така че проверката и helm install никога не могат да се разминават.

Какво извежда едно изпълнение

Ето първото изпълнение за Harrow, както бе изведено:

Adverant Nexus 1.0.0-alpha.1 · preflight · Tue 10 Nov 2026 08:40 · read-only

Failed first
  FAIL  Address (api)             api.harrow.example → no record    people reach Nexus by this name
        fix  add a DNS record for api.harrow.example that points at the ingress, then run preflight again
  FAIL  Address (auth)            auth.harrow.example → no record   people reach Nexus by this name
        fix  add a DNS record for auth.harrow.example that points at the ingress, then run preflight again
  FAIL  Key custodians            the example custodian of the chart's values-community.yaml and values-enterprise.yaml (age1u63etg5v…)   the key store seals its recovery keys to them; no one holds the example custodian's key
        fix  replace it in keys.custody.recipients in harrow-values.yaml with your custodians' own recipients: each custodian makes a key on their own machine with `age-keygen -o custodian.key` (the `# public key: age1...` line is the recipient), or `age-plugin-se keygen --access-control=any-biometry -o custodian.key` for a Secure Enclave key, keeps the identity file offline, and gives you only the recipient
  FAIL  Installation name         nexus-example, the example name of the chart's values-community.yaml and values-enterprise.yaml   the first key-store bootstrap mints the installation identity under it, permanently
        fix  set keys.installationName in harrow-values.yaml to this installation's own name

Warnings
  warn  Graphics nodes            none                   the assistant will need a hosted model
        fix  add a node with a graphics card and its device plugin, or have the assistant use a hosted model
  warn  Certificate               secret harrow-public-tls not found in nexus   the public address needs it before people sign in
        fix  create the TLS secret harrow-public-tls in nexus before installing, or change tls.existingSecret in harrow-values.yaml

Passed
  pass  Kubernetes version        1.33.6+k3s1            needs 1.33 or later
  pass  Nodes ready               3 of 3
  pass  Storage class             local-path (default)
  pass  Resources                 24 cores, 93.9 GiB     needs 2.1 cores, 6.7 GiB
  pass  Ingress class             traefik (default)
  pass  Ingress ports             traefik (LoadBalancer) on 80 and 443
  pass  Address (console)         console.harrow.example → 10.20.4.10
────────────────────────────────────────────────────────────────────────────
7 passed · 2 warnings · 4 failed   Install cannot continue until the failures pass.
Nothing was changed. Report saved to preflight-2026-11-10-0840.txt

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

Коригирахме стойностите, добавихме двата записа в системата за имена на домейни (Domain Name System – DNS), създадохме обекта Secret и го стартирахме отново:

Adverant Nexus 1.0.0-alpha.1 · preflight · Thu 12 Nov 2026 09:02 · read-only

Cluster
  pass  Kubernetes version        1.33.6+k3s1            needs 1.33 or later
  pass  Nodes ready               3 of 3
  pass  Storage class             local-path (default)
  pass  Resources                 24 cores, 93.9 GiB     needs 2.1 cores, 6.7 GiB
  warn  Graphics nodes            none                   the assistant will need a hosted model
        fix  add a node with a graphics card and its device plugin, or have the assistant use a hosted model

Network
  pass  Ingress class             traefik (default)
  pass  Ingress ports             traefik (LoadBalancer) on 80 and 443
  pass  Address (console)         console.harrow.example → 10.20.4.10
  pass  Address (api)             api.harrow.example → 10.20.4.10
  pass  Address (auth)            auth.harrow.example → 10.20.4.10
  pass  Certificate               ends 3 Nov 2027

Time and keys
  pass  Key custodians            3 custodians
  pass  Installation name         harrow-port-authority
────────────────────────────────────────────────────────────────────────────
12 passed · 1 warning · 0 failed   You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed on the cluster

Изпълнение без неуспешни проверки изброява проверките под техните три заглавия: Cluster (Клъстер), Network (Мрежа) и Time and keys (Време и ключове). Предупрежденията никога не блокират процеса. Оставихме предупреждението за графични процесори нарочно: на този свързан пилотен клъстер асистентът на Harrow използваше хостван модел със собствен ключ на пристанището.

Преди да инсталирате
Преди да инсталирате
Предварителна проверка в терминала на оператора, с бройките до нея. Забележете, че всяко предупреждение има изведено решение под себе си и че изпълнението ясно указва, че не е променило нищо в клъстера.

Кодове за изход

Код Значение
0 Инсталацията може да продължи. Предупрежденията не блокират процеса
1 Инсталацията е блокирана: поне една проверка е неуспешна
2 Предварителната проверка не можа да се стартира: kubeconfig файлът, контекстът, файлът със стойности или приложно-програмният интерфейс (API) на клъстера не можаха да бъдат прочетени, или даден флаг е грешен

Скриптовете трябва да четат кода за изход (exit code), а не думите. Нашият стартира предварителната проверка като първа стъпка от всяко надграждане и спира при всичко, различно от 0.

Стартирайте nexusctl на изданието, към което преминавате, а не на това, с което сте инсталирали. Изискванията идват от чарта, който то носи, така че по-ново издание може да вдигне минималната версия на Kubernetes или да поиска повече памет, и само неговият собствен nexusctl знае това. --release променя версията, която отчетът назовава; не променя правилата на кой чарт се прилагат. В Harrow пазим nexusctl на всяко издание до неговия чарт в записа за промени, така че евентуално връщане към стара версия (rollback) се проверява от инструмента, който му съответства.

Всяка проверка

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

ID на проверка Секция Задължителна Изискване, което извежда
kubernetes-version cluster yes Kubernetes 1.33 или по-нова версия
nodes-ready cluster yes Всеки възел е в състояние на готовност (Ready)
storage-class cluster yes Клас за съхранение (storage class) за данните
resources cluster yes Достатъчно CPU и памет за изданието
graphics-nodes cluster no Графични възли
ingress-class network yes Клас за входящ трафик (ingress class) за трите адреса
ingress-ports network yes Контролерът за входящ трафик (ingress controller) е отворен на портове 80 и 443
address-console, address-api, address-auth network yes Адресът за console, api или auth се разрешава в DNS
certificate network no Сертификатът е валиден за още 30 дни
custodians time-and-keys yes Хората, които държат ключовете за възстановяване на тази инсталация
installation-name time-and-keys yes Собственото постоянно име на тази инсталация

kubernetes-version

Прочита версията на API сървъра и я сравнява с минималното изискване на чарта. Открива например 1.33.6+k3s1. Под 1.33 не успява с решение upgrade the cluster to 1.33 or later. Ако низът на версията не е такъв, който nexusctl може да прочете, проверката се проваля, вместо да гадае.

nodes-ready

Изброява възлите и преброява тези, чието условие Ready е вярно (true), като 3 of 3. Всеки възел, който не е готов, се назовава по име, а решението ви казва да го върнете в състояние Ready и да прочетете условията му. Клъстер без никакви възли се проваля с подсказка, че контекстът може да сочи към грешен клъстер.

storage-class

Ако вашите стойности задават storage.className, проверката търси този клас и се проваля с <name> does not exist, когато той липсва. Ако не го задават, тя търси клас, маркиран по подразбиране (default), и го докладва като local-path (default). Ако няма такъв по подразбиране, се проваля с none marked default, а колоната за нужди обяснява защо това има значение: the database cannot claim a disk. Ако два класа са маркирани по подразбиране, клъстерът дава на новата заявка по-новия, така че той е този, който се докладва.

resources

Изчислява какво изисква изданието от чарта и вашите стойности, след което сумира разпределимите ядра на централния процесор (CPU) и паметта на всеки възел, който е Ready, не е изолиран (cordoned) и няма ограничение (taint) NoSchedule или NoExecute. Подовете (pods) на чарта нямат толерации (tolerations), така че възел с ограничение не може да ги стартира и не се брои. Клъстер с недостиг не преминава проверката с точния дефицит, като например add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Нуждите се закръгляват нагоре, а наличността – надолу, така че проверката никога не ви ласкае.

graphics-nodes

Търси възел в състояние Ready с графичен процесор (GPU), който може да разпредели, nvidia.com/gpu. При липса на такъв предупреждава: the assistant will need a hosted model. Предварителната проверка третира това като съвет и никога не блокира заради него, тъй като асистентът може да отговаря вместо това чрез хостван модел на изкуствен интелект (ИИ). Глава 2.14, Доставчици и модели на ИИ, обхваща и двата пътя.

ingress-class

Ако ingress.className е зададен, проверката търси този клас. Ако не е, търси точно един клас, маркиран по подразбиране (default). Два класа, маркирани по подразбиране, също водят до неуспех, тъй като тогава API сървърът отхвърля Ingress без клас. Проверката се пропуска и нейният ред се изпуска, когато ingress.enabled е false.

ingress-ports

Търси в пространството от имена, посочено от networkPolicy.ingressNamespace (по подразбиране kube-system, където k3s стартира Traefik), една услуга (Service) от тип LoadBalancer или NodePort, която предоставя едновременно портове 80 и 443. Мрежовата политика на чарта позволява само на това пространство от имена да достига до трите публични услуги, така че контролер за входящ трафик на всяко друго място не би могъл да обслужва Nexus, дори и да слуша. Решението посочва и двата изхода: експонирайте контролера там или задайте networkPolicy.ingressNamespace на мястото, където той работи. Пропуска се, когато ingress.enabled е false.

address

Търси hosts.console, hosts.api и hosts.auth от вашата работна станция, по пет секунди за всеки, и извежда по един ред на хост. Хост без запис се проваля с <host> → no record. Незададен хост се проваля с hosts.<key> is not set. Когато едно име има няколко адреса, редът показва първия (IPv4 пред IPv6) и колко още има.

certificate

Изпълнява се само когато tls.mode е existing и tls.existingSecret посочва обект Secret; при cert-manager или none няма ваш сертификат за четене и редът се изпуска. Чете tls.crt от обекта Secret в пространството от имена за инсталация и нищо друго. Сертификат, валиден за 30 или повече дни, преминава успешно като ends 3 Nov 2027. Такъв, който изтича по-скоро, предупреждава с ends in 9 days; вече изтекъл предупреждава с ended 4 days ago. Липсващ Secret или такъв без сертификат в него предупреждава със съответното решение.

custodians

Чете keys.custody.recipients. Ако няма такива, се проваля с код KEYS_CUSTODIAN_MISSING. Ако някой получател е примерният пазител от собствените файлове със стойности на чарта, се проваля с KEYS_CUSTODIAN_EXAMPLE, тъй като никой не притежава този ключ и ключовете за възстановяване на инсталацията биха били запечатани за никого. При успех извежда броя, като например 3 custodians.

installation-name

Чете keys.installationName. Ако не е зададено, се проваля с INSTALLATION_NAME_MISSING. Ако е зададено на примерното име от файловете със стойности на чарта, се проваля с INSTALLATION_NAME_EXAMPLE. При успех извежда името. Колоната за нужди обяснява защо това има по-голямо значение от повечето други: the first key-store bootstrap mints the installation identity under it, permanently.

Последните две проверки докладват точно кодовете, с които самият чарт отказва инсталация. Предварителната проверка просто ви казва първа, преди Helm да е създал каквото и да е.

Файловете с отчети

Всяко изпълнение запазва два файла в --report-dir, именувани според времето на стартиране: preflight-2026-11-12-0902.txt, редовете, както са изведени, без цветови кодове, и preflight-2026-11-12-0902.json, същото изпълнение във фиксиран формат, който програма може да прочете. Изходът в терминала и запазените редове идват от един и същ списък, така че никога не се различават.

Отчетът в JSON формат следва схемата nexus.preflight/v1:

Поле Какво съдържа
schema Точно nexus.preflight/v1
tool Обект: name (nexusctl) и version
release Провереното издание
ran_at Кога е стартирано, в координирано универсално време (UTC)
context Името на kube контекста
values Само базовото име на файла със стойности
read_only Винаги true
checks По един запис на ред: id, section, name, requirement, must_pass, outcome (pass, warn или fail), found, needs, fix, а при неуспех с машинна причина – code
counts passed, warnings и failed
can_install true, когато нищо не се е провалило
report_file Името на файла .txt
transcript Обект: title (nexusctl preflight) и lines, всеки ред със своя kind (prompt, ok, warn, bad, note, out или blank), своите text и at, и понякога marks

Отчетът е създаден да се показва, преди който и да е да влезе в системата, така че не съдържа потребителско име, име на хост на работна станция, път до файл, токен и нищо от вашия kubeconfig. values е базово име, а context е името на контекста. Ако отчетът от дадено изпълнение би нарушил някое от тези правила, nexusctl отказва да го изведе, запази или предаде, и съобщава за това. Един отчет е най-много 256 KiB, с най-много 64 проверки и 512 знака в което и да е текстово поле.

Как отчетът достига до конзолата

Единственият запис, който прави предварителната проверка, е готовият отчет, предаден на услугата за ключове на инсталацията, nexus-keys, така че инсталаторът на конзолата да може да го покаже на своята страница за предварителна проверка, преди някой да е заявил собственост (claim) над инсталацията. --record решава дали да опита:

--record Какво се случва
auto Предава отчета само когато пространството от имена има Deployment nexus-keys
always Настоява; предварителната проверка излиза с 2, ако няма на какво да го предаде
never Не го предава

Така че изпълнение преди първата инсталация няма на какво да предаде отчета и го запазва на вашата работна станция. Изпълнение след инсталацията и преди заявяването на собственост го записва.

Предаването използва вашия собствен достъп до клъстера. nexusctl стартира /app/nexus-keys preflight-record в контейнера keys на готов под nexus-keys и подава отчета на стандартния вход (standard input). Това е същото като:

kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.json

Услугата за ключове проверява отчета спрямо същите правила, които прилага nexusctl, и запазва само последния. Когато бъде предаден, nexusctl извежда още един ред, съобщаващ това, а запазеният JSON получава note, който регистрира предаването.

Инсталаторът на конзолата го чете от публичния маршрут GET /v1/installation/preflight на услугата за ключове. Този маршрут отговаря само докато инсталацията е незаявена: преди да е записан какъвто и да е отчет, той отговаря с 404 RECORD_NOT_FOUND, а след като някой заяви собственост над инсталацията, отговаря завинаги с ROUTE_NOT_FOUND, точно както прави маршрутът за заявяване. Отчет, предаден след заявяването на собственост, се отхвърля с INSTALLATION_CLAIMED.

В конзолата изпълнение с неуспешни проверки се появява като „Preflight cannot continue“ (Предварителната проверка не може да продължи): броят на неуспешните, предупрежденията и успешните, след това всяка проверка, групирана под „Must pass“ (Задължителни) и „Should pass“ (Препоръчителни), като тези, които не са преминали, са първи, а откритите стойности са до всяка от тях. Изпълнение без неуспешни проверки не получава тази страница; конзолата преминава направо към заявяването на собственост (глава 2.12, Първото стартиране).

Предварителната проверка не може да продължи
Предварителната проверка не може да продължи
Страницата на конзолата за предварителна проверка, която не може да продължи. Неуспешните проверки са първи, всяка описана с думи и с това, което е било открито, а инсталацията остава блокирана, докато не преминат успешно.
Три колони. Вляво, „Работна станция на оператора“: кутия „nexusctl preflight --context --values“ с два изхода под нея, „preflight-<time>.txt“ и „preflight-<time>.json“. В средата, „Инсталацията, незаявена“: кутия „nexus-keys“ с етикет „preflight-record, само последния отчет“. Стрелка от лявата кутия към nexus-keys е с етикет „pod exec с ваш собствен достъп до клъстера (--record auto или always)“. Вдясно, „Браузър, преди влизане“: кутия „Инсталатор на конзолата, Предварителната проверка не може да продължи“. Стрелка от nexus-keys към нея е с етикет „GET /v1/installation/preflight“. Под средната кутия малка бележка гласи „след заявяването: ROUTE_NOT_FOUND“.
Къде отива един отчет от предварителна проверка – от работната станция на оператора до браузъра.

Достъп, от който се нуждае изпълнението

Предварителната проверка се изпълнява от ваше име, с вашия kubeconfig. Акаунтът трябва да има права за четене на:

  • възли (nodes) – за проверките на версията, готовността, ресурсите и графичните процесори;
  • класове за съхранение (storage classes) и класове за входящ трафик (ingress classes);
  • услуги (Services) в пространството от имена за входящ трафик;
  • обекта TLS Secret в пространството от имена за инсталация, когато се изпълнява проверката за сертификат.

Когато четенето бъде отказано, редът показва could not read <what> (the cluster refused), а решението указва какъв достъп за четене да се предостави. Думите никога не включват адреса на сървъра или неговия собствен текст за грешка, тъй като отчетът може да бъде показан преди влизане в системата. Предаването също така се нуждае от pods/exec върху подовете nexus-keys; без него auto запазва файловете и извежда предупреждение, а always излиза с 2.

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

Код за изход 2 означава, че не е направен отчет. Съобщението на стандартния изход за грешки (standard error) казва защо:

Съобщение Какво да предприемете
--context is required: the kube context to check Добавете --context
--values is required: the values file the install will use Добавете --values
could not read the values file harrow-values.yaml Проверете пътя и правата за достъп до файла
preflight takes flags only Премахнете излишния аргумент
the report breaks its contract and was not printed, saved or handed over Дадено поле би пренесло нещо поверително; докладвайте го на Adverant заедно с флаговете на изпълнението
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to Първо инсталирайте или използвайте --record auto
could not hand the report to this installation Проверете достъпа си за изпълнение на команди (exec) в nexus-keys

Клъстер, чийто API не може да бъде достигнат, също излиза с 2. Коригирайте kubeconfig файла или мрежата и стартирайте отново.

След като предварителната проверка завърши с 0 failed, преминете към глава 2.6, Инсталиране на Community върху Kubernetes, за да инсталирате Community, или глава 2.7, Инсталиране на Enterprise и прилагане на лиценз, за Enterprise.