Версия 1.0.0-alpha.1последно
Глава 2.5
Предварителна проверка с nexusctl
Всяка проверка, която `nexusctl preflight` прави, какво чете всяка от тях и как се проваля, отчетът, който извежда и записва, как този отчет достига до страницата за предварителна проверка в конзолата, както и всеки флаг.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Първата ни предварителна проверка (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, Първото стартиране).
Достъп, от който се нуждае изпълнението
Предварителната проверка се изпълнява от ваше име, с вашия 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.

