Версія 1.0.0-alpha.1найновіша
Розділ 2.5
Попередня перевірка за допомогою nexusctl
Кожна перевірка, яку виконує `nexusctl preflight`, що саме вона зчитує та за яких умов завершується помилкою, звіт, який вона виводить і зберігає, як цей звіт потрапляє на сторінку попередньої перевірки в консолі, а також опис усіх прапорців.
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

Наша перша попередня перевірка в Harrow Port Authority не пройшла чотири етапи, і два з них коштували б нам значно дорожче за витрачений післяобідній час. Ми почали створювати файл значень, скопіювавши приклад із чарту, і попередня перевірка відхилила як демонстраційне ім'я інсталяції, так і демонстраційного зберігача ключів. Ніхто не володіє приватним ключем цього зберігача. Запечатану ним інсталяцію неможливо розпечатати після перезапуску вузла. Попередня перевірка виявила це за кілька секунд — ще до того, як з'явилося щось, що можна було б втратити.
Команда nexusctl preflight зчитує ваш кластер і файл значень, виводить знайдену інформацію, зберігає звіт і нічого не змінює в кластері. Запускайте її перед кожним встановленням та оновленням. У цьому розділі описано кожну перевірку, яку вона виконує, формат звіту, місце його збереження та прапорці.
Експлуатація
Для попередньої перевірки потрібні дві речі: контекст kube кластера, у який виконуватиметься встановлення, та файл значень, який використовуватиметься під час встановлення. Спершу напишіть файл значень; у розділі 2.6 «Встановлення редакції Community у Kubernetes» детально розглянуто кожен ключ. Потім виконайте:
nexusctl preflight --context harrow-prod --values harrow-values.yamlВона зчитує дані кластера через client-go лише за допомогою викликів get і list. Якщо для параметра tls.mode задано значення existing, створіть простір імен nexus та об'єкт Secret для протоколу захисту транспортного рівня (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. Останні два рядки — це підсумок та шлях до файлу звіту.
Ми виправили значення, додали два записи до системи доменних імен (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) кластера, чи вказано неправильний прапорець |
Скрипти мають зчитувати код завершення, а не текст. Наш скрипт запускає попередню перевірку як перший крок кожного оновлення та зупиняється за будь-якого коду, крім 0.
Запускайте nexusctl того релізу, на який ви переходите, а не того, з яким виконували встановлення. Вимоги беруться з чарту, який він містить, тому новіший реліз може підвищити мінімальну версію Kubernetes або вимагати більше пам'яті, і про це знає лише його власний nexusctl. Прапорець --release змінює версію, зазначену у звіті, але не змінює те, правила якого чарту застосовуються. У Harrow ми зберігаємо nexusctl кожного релізу поруч із його чартом у журналі змін, щоб відкочування перевірялося відповідним інструментом.
Усі перевірки
Усього є одинадцять перевірок. Десять із них формують по одному рядку кожна; перевірка адрес формує по одному рядку на кожен хост, тож повний запуск містить тринадцять рядків. Дев'ять перевірок є обов'язковими, і невідповідність у них вважається помилкою. Дві перевірки — вузлів із графічними процесорами та сертифіката — є рекомендованими, і невідповідність у них видає попередження. Останній стовпець містить текст вимоги, який кожен рядок переносить у звіт; абревіатура CPU в ньому означає центральний процесор.
| ID перевірки | Секція | Обов'язкова | Вимога, яку вона виводить |
|---|---|---|---|
kubernetes-version |
cluster | так | Kubernetes 1.33 або новішої версії |
nodes-ready |
cluster | так | Усі вузли готові |
storage-class |
cluster | так | Клас сховища для даних |
resources |
cluster | так | Достатньо ресурсів CPU та пам'яті для релізу |
graphics-nodes |
cluster | ні | Вузли з графічними процесорами |
ingress-class |
network | так | Клас Ingress для трьох адрес |
ingress-ports |
network | так | Контролер Ingress відкритий на портах 80 і 443 |
address-console, address-api, address-auth |
network | так | Адреса console, api або auth розпізнається в DNS |
certificate |
network | ні | Сертифікат дійсний ще щонайменше 30 днів |
custodians |
time-and-keys | так | Особи, які зберігають ключі відновлення цієї інсталяції |
installation-name |
time-and-keys | так | Власне постійне ім'я цієї інсталяції |
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, який не заблоковано (not cordoned) і який не має обмежень (taints) NoSchedule або NoExecute. Поди чарту не мають допусків (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. Мережева політика чарту дозволяє доступ до трьох публічних служб Service лише з цього простору імен, тому контролер Ingress у будь-якому іншому місці не зміг би обслуговувати 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, щоб інсталятор консолі міг показати його на своїй сторінці попередньої перевірки до того, як хтось заявить права на інсталяцію. Прапорець --record визначає, чи робити таку спробу:
--record |
Що відбувається |
|---|---|
auto |
Передає звіт лише тоді, коли в просторі імен є об'єкт Deployment nexus-keys |
always |
Вимагає передавання; попередня перевірка завершується з кодом 2, якщо звіт немає куди передати |
never |
Не передає звіт |
Тому під час запуску перед першим встановленням передавати звіт нікуди, і він залишається на вашій робочій станції. Запуск після встановлення, але до заявлення прав на інсталяцію, записує звіт у систему.
Для передавання використовується ваш власний доступ до кластера. nexusctl запускає /app/nexus-keys preflight-record у контейнері keys готового пода nexus-keys і передає звіт через стандартний потік введення. Це те саме, що й виконання команди:
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 (ingress classes);
- служби (Services) у просторі імен Ingress;
- об'єкт TLS Secret у просторі імен встановлення, коли виконується перевірка сертифіката.
Якщо в доступі на читання відмовлено, у рядку виводиться could not read <what> (the cluster refused), а в рекомендації зазначається, який саме дозвіл на читання потрібно надати. Текст ніколи не містить адреси сервера чи його власного повідомлення про помилку, оскільки звіт може показуватися до входу в систему. Для передавання звіту також потрібен дозвіл pods/exec для подів nexus-keys; без нього за умови auto файли зберігаються і виводиться попередження, а за умови always робота завершується з кодом 2.
Коли сама попередня перевірка не може запуститися
Код завершення 2 означає, що звіт не було створено. Повідомлення у стандартному потоці помилок пояснює причину:
| Повідомлення | Що робити |
|---|---|
--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.

