Версія 1.0.0-alpha.1найновіша
Розділ 2.6
Встановлення редакції Community у Kubernetes
Покрокове встановлення редакції Community за допомогою Helm — від cert-manager до готовності всіх робочих навантажень, із поясненням кожного ключа у файлі значень (values), чому не використовується прапорець --wait, у якому порядку виконуються хуки чарту, а також альтернативний спосіб встановлення через nexusctl install.
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

Саме встановлення — це одна команда helm install. Усе інше навколо неї потрібне для того, щоб ця єдина команда спрацювала з першого разу: попередньо запущений cert-manager, файл значень, який ви прочитали рядок за рядком, та подальше очікування, яке точно знає, на що саме чекати. В Harrow Port Authority ми спершу встановили редакцію Community для шеститижневого пілотного проєкту на тривузловому кластері k3s із нашого робочого аркуша планування. Реліз запрацював приблизно за двадцять хвилин, і ніхто не міг увійти в систему, доки ми не заявили на нього права, — саме так і має бути.
У цьому розділі передбачається, що ви вже зробили три речі: опрацювали робочий аркуш планування (розділ 2.3, «Планування встановлення»), завантажили та перевірили реліз (розділ 2.4, «Отримання та перевірка релізу») і виконали попередню перевірку (розділ 2.5, «Попередня перевірка за допомогою nexusctl»). Якщо щось із цього ще не завершено, поверніться назад. Процес встановлення відхиляє більшість помилок, прямо називаючи їх, але деякі — наприклад, зберігача, чий ключ ви вже втратили, — він розпізнати не може.
Крок 1: перевірте інструменти та контекст
Переконайтеся, що використовується Helm версії 4.
helm versionПроцес встановлення покладається на те, що Helm 4 за замовчуванням очікує завершення завдань хуків (hook Jobs) чарту. Ми використовували версію v4.3.1.
Спрямуйте
kubectlна кластер із вашого робочого аркуша та перевірте підключення.kubectl config use-context harrow-prod kubectl get nodesКожен вузол має показувати статус
Ready. Попередня перевірка вже це визначала, але вузол може вийти з ладу в проміжку між нею та встановленням, і тут це побачити швидше.
Крок 2: спочатку встановіть cert-manager
Чарт створює власний локальний центр сертифікації (CA) за допомогою cert-manager, і всі сервіси взаємодіють між собою, використовуючи видані ним сертифікати: самопідписаний Issuer, десятирічний сертифікат локального CA та короткострокові сертифікати для сервісів. Тому cert-manager має працювати ще до запуску Nexus. Для релізу потрібна версія v1.21.3, а trust-manager не потрібен.
Встановіть cert-manager із його власного чарту разом із користувацькими ресурсами (CRD):
helm install cert-manager <cert-manager-chart> -n cert-manager --create-namespace \ --set crds.enabled=true --wait --timeout 10m<cert-manager-chart>— це чарт cert-manager версії v1.21.3 із власного релізу проєкту cert-manager. Очікування тут цілком доречне: це власне встановлення cert-manager без жодних хуків, які залежать від чогось іншого.Дочекайтеся готовності його вебхука, через який проходить кожен запит на сертифікат:
kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300sdeployment "cert-manager-webhook" successfully rolled out
Крок 3: створіть простір імен (namespace) та TLS Secret
Якщо вказано tls.mode: existing, чарт очікує, що ваш сертифікат буде збережено як Secret Kubernetes у просторі імен ще до початку встановлення. Протокол захисту транспортного рівня (TLS) для всіх трьох адрес забезпечується цим єдиним об'єктом Secret, тому його сертифікат має містити імена всіх трьох хостів.
kubectl create namespace nexus
kubectl -n nexus create secret tls harrow-public-tls \
--cert=harrow-public.crt --key=harrow-public.keyharrow-public.crt — це сертифікат разом із ланцюжком, а harrow-public.key — його закритий ключ. Якщо в розділі 2.3, «Планування встановлення», ви вибрали tls.mode: cert-manager або none, пропустіть створення Secret; ви все одно можете створити простір імен зараз або дозволити Helm зробити це за допомогою --create-namespace на кроці 6.
Крок 4: напишіть файл значень (values)
Це файл значень Harrow для пілотного проєкту. Кожен ключ у ньому підтримується схемою чарту; будь-який інший ключ схема відхиляє, тому помилка в написанні ключа призведе до збою встановлення, а не буде мовчки проігнорована.
# harrow-values.yaml (Helm values, Community)
global:
imageRegistry: registry.adverant.ai
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: community
enterprise:
enabled: false
tls:
mode: existing
existingSecret: harrow-public-tls
ingress:
className: traefik
storage:
className: local-path
networkPolicy:
ingressNamespace: kube-system
externalEgressCIDRs: ["10.20.9.25/32"]
keys:
installationName: harrow-port-authority
custody:
recipients:
- "<recipient-aoife>"
- "<recipient-tomas>"
- "<recipient-safe-laptop>"Кожне значення <recipient-...> — це відкритий отримувач age одного зі зберігачів ключа, тобто рядок age1... або age1se1..., який він вам надіслав. Нижче наведено кожен заданий нами ключ із поясненням, навіщо він потрібен.
global.imageRegistry — це реєстр, з якого ваші вузли завантажують образи. У чарті немає значення за замовчуванням; він формує шлях до кожного образу як <this>/nexus/<service>@<digest>. Для встановлення з підключенням до інтернету це registry.adverant.ai. Якщо ви скопіювали образи у власний реєстр, вкажіть його хост.
global.domain — це домен, у якому розташовані всі три адреси.
hosts.console, hosts.api та hosts.auth визначають ідентичність інсталяції: це три імені, якими користуються люди та програми. Кожне з них уже має розв'язуватися в системі доменних імен (DNS), що було перевірено під час попередньої перевірки.
Значення edition та enterprise.enabled мають узгоджуватися: community із false або enterprise із true. Чарт відхиляє будь-які інші комбінації, а також відхиляє редакцію, для якої не призначений файл фіксації образів (images lock).
tls.mode та tls.existingSecret визначають спосіб отримання сертифіката для публічного периметра. У разі використання cert-manager натомість потрібно задати tls.clusterIssuer, а для none не потрібно вказувати жодного з них.
ingress.className задає ім'я класу ingress. Залиште його порожнім, щоб використовувати клас кластера за замовчуванням.
storage.className задає клас сховища для кожного тому даних. Залиште його порожнім, щоб використовувати клас за замовчуванням.
networkPolicy.ingressNamespace — це простір імен, у якому працює ваш контролер ingress. Значення за замовчуванням, kube-system, підходить для Traefik у k3s; ми все одно вказали його явно, щоб це було зафіксовано у файлі.
networkPolicy.externalEgressCIDRs містить перелік діапазонів адрес у нотації безкласової міждоменної маршрутизації (CIDR) за межами простору імен, до яких сервіси можуть звертатися, окрім DNS та сервера інтерфейсу прикладного програмування (API) Kubernetes. У нашому випадку тут вказано єдину адресу поштового ретранслятора; якщо список порожній, жодні ресурси за межами простору імен недоступні.
keys.installationName — це постійне ім'я, під яким сховище ключів генерує ідентичність інсталяції.
keys.custody.recipients містить перелік відкритих отримувачів age ваших зберігачів. Завдання керування ключами (custody Job) шифрує кожну частку розблокування та ключ відновлення для кожного з них.
Ключі, які можуть знадобитися, і ключі, які не варто чіпати
| Ключ | Коли потрібно задавати |
|---|---|
networkPolicy.apiServerCIDRs |
Коли чарт не може прочитати адреси сервера API з об'єкта Endpoints kubernetes. Вкажіть їх як діапазони /32 |
proxy.trustedCIDRs |
Коли поди вашого контролера ingress розташовані не на 10.42.0.0/16 у k3s |
ai.localProvider.baseUrl |
Коли організація використовує власний сервер моделей штучного інтелекту (ШІ), сумісний з OpenAI (розділ 2.14, «Провайдери та моделі ШІ») |
ai.installationHosts |
Коли цей сервер моделей використовує приватні імена всередині інсталяції |
dataTier.<store>.size |
Коли сховищу потрібен більший обсяг тому, ніж передбачено за замовчуванням |
dataTier.<store>.mode |
external для сховища, яке ви обслуговуєте самостійно (розділ 2.11, «Варіації: зовнішні сховища, TLS та ingress») |
components.<service>.replicas, components.<service>.resources |
Коли потрібно збільшити ресурси для сервісу |
auth.rateLimitPerMinute |
Коли для інтенсивної автоматизації потрібно понад 5,000 запитів на хвилину на одну особу |
schemaWait.timeoutSeconds |
Коли через повільний диск перші міграції тривають понад 30 хвилин |
Залиште istio.enabled зі значенням false; Nexus не потребує сервісної сітки (service mesh). Залиште telemetry.enabled зі значенням false; схема не приймає жодного іншого значення. Залиште orchestrator.platformServiceUserId та probitas.flags такими, як їх встановлює чарт.
Жодні облікові дані ніколи не передаються як значення чарту. Тут немає ключів для API-ключа провайдера моделей, пароля пошти чи токена завантаження образів. Сервіси генерують власні внутрішні секрети під час встановлення і зберігають їх під час оновлення, а ключі моделей кожної організації додаються до її власного пулу ключів через консоль після першого запуску.
Крок 5: запустіть попередню перевірку для фінального файлу
nexusctl preflight --context harrow-prod --values harrow-values.yamlВиконання має завершитися повідомленням 0 failed. У розділі 2.5, «Попередня перевірка за допомогою nexusctl», пояснюється кожен рядок. Якщо після останнього запуску ви щось змінили, навіть розмір ресурсів, запустіть перевірку знову.
Крок 6: виконайте встановлення без прапорця --wait
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
--namespace nexus -f harrow-values.yaml --timeout 45mЯкщо ви не створили простір імен на кроці 3, додайте --create-namespace. Якщо ви встановлюєте систему із завантаженого та перевіреного файлу чарту, вкажіть шлях до нього замість посилання oci://.
Не додавайте прапорець --wait. Ініціалізація бази даних чарту виконується як хук після встановлення (post-install hook), коли власні ресурси релізу вже створено, і саме цей хук надає кожному сервісу його роль та пароль у базі даних. Прапорець --wait затримав би встановлення, доки кожен Deployment не перейде у стан Available, але жоден Deployment не може стати Available, доки не виконається хук, на який він очікує. Сервіси просто висітимуть, отримуючи відмови у вході до бази даних, а Helm чекатиме на них до завершення тайм-ауту. Без --wait Helm 4 все одно по черзі очікує на кожне завдання хука (hook Job), і саме таке очікування вам потрібне.
Коли останній хук завершиться, Helm виведе підсумкове повідомлення:
NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1
Статус STATUS: deployed означає, що кожен хук виконано успішно. Це ще не означає, що всі сервіси готові обслуговувати запити; очікування цього відбувається на кроці 7.
Що і в якому порядку запускається
Helm запускає хуки за їхньою вагою, починаючи з найменшої, і чекає на завершення кожного перед запуском наступного. Кожне завдання міграції має параметр backoffLimit: 0: невдала міграція перериває встановлення і ніколи не повторюється потай від вас. Успішне завдання (Job) видаляється; завдання, що завершилося збоєм, залишається разом із журналом, щоб ви могли його переглянути.
| Вага | Хук | Що він робить |
|---|---|---|
| -30 | Передумови | Обліковий запис хука nexus-migrations, призначений лише для хуків Secret nexus-migrations-env зі згенерованими обліковими даними бази даних, а також обліковий запис, роль, конфігурація та сертифікат завдання керування ключами (custody Job) |
| -20 | nexus-db-bootstrap |
Створює бази даних і ролі, жодна з яких не є суперкористувачем і не може обходити захист на рівні рядків (RLS); додає розширення, зокрема PostGIS та pgvector; створює реєстр релізів |
| -15 | nexus-openbao-custody-init |
Ініціалізує сховище ключів та його механізм розблокування, шифрує частки ключів і ключі відновлення для ваших зберігачів, відкликає обидва кореневі токени та генерує ідентичність інсталяції під ім'ям keys.installationName |
| -12 | nexus-graphrag-migrations |
Першою розгортає схему графового сервісу, оскільки схема сервісу входу посилається на об'єкти, які йому належать |
| -10 | nexus-auth-migrations |
Розгортає схему сервісу входу та дві його ролі середовища виконання |
| -5 | nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations |
Власна схема кожного сервісу; probitas запускається після auth, оскільки спершу перевіряє таблиці auth |
| 0 | nexus-alpha-bff-migrations |
Готує базу даних бекенду для фронтенду (BFF) та її ролі, після чого застосовує її міграції |
Кожен хук міграції завершує роботу записом одного рядка в реєстр релізів, nexus_release.schema_applied: імені свого ланцюжка та дайджесту образу, який його виконав. Цей рядок записується лише після того, як процес міграції завершиться без помилок. Завдання початкового налаштування (bootstrap Job) виводить db-bootstrap: done; хуки SQL-міграції виводять schema-ledger: recorded <chain> for this release's image як свій останній рядок. Власний хук міграції консолі, nexus-alpha-bff-migrations, записує свій рядок у такий самий спосіб, а потім виводить bff-migrate: done.
Як сервіси очікують на свою схему
Об'єкти Deployment запускаються щойно Helm їх створює, поки хуки ще виконуються. Сервіс, який запустився б із базою даних без ролі, пароля чи схеми, аварійно завершував би роботу і перезапускався, доки хуки не закінчать виконання. Тому кожен Deployment, що використовує базу даних, містить init-контейнер wait-for-schema, який натомість притримує запуск пода.
Він читає реєстр релізів від імені nexus_ledger_reader — облікового запису, який може читати лише цю єдину таблицю і нічого більше, — та чекає, доки в реєстрі не з'являться його ланцюжки для дайджестів образів цього релізу. Він опитує таблицю кожні schemaWait.intervalSeconds (за замовчуванням 3), виводить свій стан у разі його зміни та під час кожного двадцятого опитування, і припиняє спроби через schemaWait.timeoutSeconds (за замовчуванням 1,800) з помилкою, у якій вказано ім'я сервісу.
| Deployment | Очікує на |
|---|---|
nexus-auth |
nexus-auth-migrations |
nexus-orchestrator, nexus-workflows |
nexus-orchestrator-migrations |
nexus-gateway |
nexus-gateway-migrations |
nexus-graphrag |
nexus-graphrag-migrations |
nexus-probitas |
nexus-probitas-migrations |
nexus-skills-engine |
nexus-db-bootstrap |
nexus-alpha-bff |
nexus-alpha-bff-migrations |
Щоб у реальному часі спостерігати за очікуванням окремого сервісу, перегляньте журнал його init-контейнера:
kubectl -n nexus logs deploy/nexus-auth -c wait-for-schemawait-for-schema: nexus-auth waits for nexus_release.schema_applied (read as nexus_ledger_reader) to show: nexus-auth-migrations; gives up after 1800s
wait-for-schema: ready after 212s: the release ledger shows nexus-auth-migrations
Оскільки очікування прив'язане до дайджесту образу, а не до кількості файлів, під час подальшого оновлення поди чекатимуть на рядки нового релізу, а под, що перезапускається після зміни лише файлу значень, знаходить свій рядок миттєво.
Крок 7: дочекайтеся готовності всіх робочих навантажень
Дочекайтеся готовності об'єктів Deployment з обмеженням у часі:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900sdeployment.apps/nexus-alpha condition met
deployment.apps/nexus-alpha-bff condition met
deployment.apps/nexus-auth condition met
deployment.apps/nexus-gateway condition met
deployment.apps/nexus-graphrag condition met
deployment.apps/nexus-keys condition met
deployment.apps/nexus-orchestrator condition met
deployment.apps/nexus-probitas condition met
deployment.apps/nexus-skills-engine condition met
deployment.apps/nexus-workflows condition met
Потім черга StatefulSet. Два сервери сховища ключів оновлюються лише тоді, коли ви видаляєте їхні поди, а kubectl rollout status не підтримує таку стратегію оновлення, тому натомість очікуйте на кількість готових реплік:
for s in $(kubectl -n nexus get statefulset -o name); do
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'=1 --timeout=900s
doneКожна команда виводить condition met. На нашому кластері обидва очікування разом зайняли менше п'яти хвилин після завершення роботи Helm.
Як виглядає стан готовності
kubectl -n nexus get deploy,statefulsetNAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/nexus-alpha 1/1 1 1 14m
deployment.apps/nexus-alpha-bff 1/1 1 1 14m
deployment.apps/nexus-auth 1/1 1 1 14m
deployment.apps/nexus-gateway 1/1 1 1 14m
deployment.apps/nexus-graphrag 1/1 1 1 14m
deployment.apps/nexus-keys 1/1 1 1 14m
deployment.apps/nexus-orchestrator 1/1 1 1 14m
deployment.apps/nexus-probitas 1/1 1 1 14m
deployment.apps/nexus-skills-engine 1/1 1 1 14m
deployment.apps/nexus-workflows 1/1 1 1 14m
NAME READY AGE
statefulset.apps/nexus-neo4j 1/1 14m
statefulset.apps/nexus-postgres 1/1 14m
statefulset.apps/nexus-qdrant 1/1 14m
statefulset.apps/nexus-seaweedfs 1/1 14m
statefulset.apps/nexus-valkey 1/1 14m
statefulset.apps/openbao 1/1 14m
statefulset.apps/openbao-unsealer 1/1 14m
Десять об'єктів Deployment та сім StatefulSet — усі готові до роботи. Поряд із ними ви побачите три завдання CronJob: nexus-keys-rotate-epoch, nexus-keys-run-schedule та nexus-keys-export-receipts, які відповідають за щонічне обслуговування сервісу ключів. Команда kubectl -n nexus get jobs не повинна показувати жодних завдань хуків: успішні завдання було видалено.
Перш ніж закрити термінал, варто зробити дві речі. Збережіть (закомітьте) файл значень туди, де ваша команда зберігає конфігурації — з нього починається кожне оновлення. І не чіпайте Secret nexus-generated. Чарт генерує внутрішні паролі та ключі один раз під час встановлення, зберігає їх там і зчитує під час кожного оновлення, тому його видалення призведе до того, що сервіси втратять доступ до власних даних.
Готовність означає, що платформа працює, але права на неї ще не заявлено. Відкрийте https://console.harrow.example, і ви потрапите до інсталятора, а не на сторінку входу: ніхто не зможе увійти, доки хтось не заявить права на інсталяцію. Це етап першого запуску, описаний у розділі 2.12, «Перший запуск».
Якщо виникне помилка
Більшість збоїв прямо вказують на свою причину. Прочитайте повідомлення, перш ніж щось змінювати.
| Що ви бачите | Причина | Що робити |
|---|---|---|
INSTALLATION_NAME_MISSING або INSTALLATION_NAME_EXAMPLE |
Значення keys.installationName порожнє або залишилося з прикладу |
Задайте власне постійне ім'я |
KEYS_CUSTODIAN_MISSING або KEYS_CUSTODIAN_EXAMPLE |
Немає зберігачів або залишився зберігач із прикладу | Вкажіть власних отримувачів ваших зберігачів |
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ |
Великі літери, крапки або цифра на початку | Використовуйте малі літери, цифри та дефіси, починаючи з літери |
keys.custody.recipients: ... із зазначенням причини |
Отримувача вказано з помилкою, передано закритий ключ або формат не підтримується завданням керування ключами для шифрування | Попросіть зберігача надати рядок отримувача ще раз |
hosts.console is required (the installation identity) |
Не задано хост | Задайте всі три хости |
tls.existingSecret is required when tls.mode is existing |
Не вказано ім'я Secret | Задайте його або змініть tls.mode |
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read |
Ваш обліковий запис не може прочитати адреси сервера API | Вкажіть їх як діапазони /32 |
global.imageRegistry is required |
Не задано реєстр | Задайте його |
Helm висить до завершення тайм-ауту; nexus-auth записує в журнал password authentication failed |
Було передано прапорець --wait |
Видаліть реліз і встановіть знову без --wait |
Error: ... job failed із назвою хука |
Збій міграції | Виконайте kubectl -n nexus logs job/<hook-name> і прочитайте останні рядки |
Под завис у стані Init |
Його wait-for-schema все ще очікує |
Прочитайте його журнал: там вказано ланцюжок, якого бракує |
wait-for-schema: FAILED |
Хук цього ланцюжка так і не записав свій рядок | Спершу знайдіть причину збою цього хука |
ImagePullBackOff |
Вузол не може завантажити образ із global.imageRegistry |
Перевірте, чи має вузол доступ до реєстру та (для редакції Enterprise) чи налаштовано токен завантаження |
Кожен хук, який очікує на PostgreSQL, чекає протягом обмеженого часу і повідомляє про це рядком waiting for postgres (12/60), тому зависла база даних проявиться в журналі хука протягом хвилини.
Встановлення через nexusctl
Команда nexusctl install виконує те саме встановлення, але бере всі супутні перевірки на себе. Вона приймає той самий файл значень:
nexusctl install --context harrow-prod --values harrow-values.yamlВона знову запускає попередню перевірку і зупиняється, якщо будь-яка з перевірок не проходить. Вона перевіряє підпис пакета чарту за допомогою ключа релізу. Потім вона виконує встановлення, очікує завершення хуків і запуску робочих навантажень та виводить кожен крок із часом його виконання. Параметр --edition community задає редакцію в командному рядку на додачу до файлу. Параметр --ca-bundle <file> додає ваші власні сертифікати CA, так само як і під час попередньої перевірки. Щоб побачити операції helm та kubectl, які буде виконано, без їх фактичного запуску, додайте --explain:
nexusctl install --context harrow-prod --values harrow-values.yaml --explainПісля завершення команда виводить адресу для заявлення прав, одноразовий код та цифровий відбиток (fingerprint) інсталяції:
Installed in <time>. Nobody can sign in yet.
Open https://console.harrow.example/claim
Code <code> works once, for 30 minutes
Fingerprint of this installation, to compare in the browser:
<eight groups of four>
Код складається з трьох груп і дає п'ять спроб вводу; цифровий відбиток містить вісім груп по чотири символи, і браузер показує ті самі вісім груп, щоб ви могли звірити їх перед тим, як заявити права на інсталяцію.
Перехід до першого запуску
Якщо ви встановлювали систему за допомогою Helm, згенеруйте код заявлення прав самостійно, вказавши особу, яка стане першим адміністратором:
nexusctl claim-code --administrator aoife.brennan@harrow.exampleЦя команда запускає власну команду генерації коду сервісу ключів у поді nexus-keys, використовуючи ваш доступ до кластера, і виводить адресу, код та цифровий відбиток, як показано вище. Код дійсний протягом 30 хвилин; запустіть команду ще раз, щоб отримати новий.
Далі робота переходить у браузер: заявіть права на інсталяцію, створіть першого адміністратора з ключем доступу (passkey) і виконайте шість обов'язкових кроків, перш ніж будь-хто зможе увійти. Це описано в розділі 2.12, «Перший запуск». Якщо ви плануєте одразу активувати ліцензію Enterprise, спершу прочитайте розділ 2.7, «Встановлення Enterprise та застосування ліцензії», оскільки ліцензія — це один із тих шести кроків.

