УвійтиЗамовити брифінг

Розділ 2.5

Попередня перевірка за допомогою nexusctl

Кожна перевірка, яку виконує `nexusctl preflight`, що саме вона зчитує та за яких умов завершується помилкою, звіт, який вона виводить і зберігає, як цей звіт потрапляє на сторінку попередньої перевірки в консолі, а також опис усіх прапорців.

Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

16 хв читання

Наша перша попередня перевірка в 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 «Перший запуск»).

Попередню перевірку неможливо продовжити
Попередню перевірку неможливо продовжити
Сторінка консолі для запуску попередньої перевірки, який неможливо продовжити. Перевірки, що завершилися помилкою, наведено першими — кожна з текстовим описом і виявленими даними, а встановлення залишається заблокованим, доки вони не пройдуть успішно.
Три стовпці. Ліворуч — «Робоча станція оператора»: блок «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 (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.