Версія 1.0.0-alpha.1найновіша
Розділ 2.3
Планування інсталяції
Що потрібно для встановлення Nexus у Kubernetes ще до введення першої команди, який обсяг ресурсів необхідний, а також два незворотні рішення: назва інсталяції та зберігачі ключів. Наприкінці наведено заповнений робочий аркуш планування для Harrow Port Authority.
Цю сторінку перекладено за допомогою ШІ з англійського оригіналу. Якщо щось незрозуміло, орієнтуйтеся на англійську версію сторінки. Читати цю сторінку англійською

Коли ми встановлювали Nexus у Harrow Port Authority, виконання команд зайняло пів дня. Планування забрало тиждень, і більша частина цього тижня пішла на два питання, які не мають жодного стосунку до Kubernetes: як ми назвемо інсталяцію та хто з людей зберігатиме її ключі відновлення. Обидві відповіді є остаточними. Усе інше в цьому розділі можна змінити пізніше за допомогою файлу значень і helm upgrade.
Я Томас Райлі (Tomás Reilly), інженер платформи в Harrow. У Harrow працюють дві інсталяції. У цьому розділі описано планування підключеної до мережі інсталяції в нашій корпоративній мережі, де ми спочатку запустили пілотну версію Community. Операційна мережа порту, яка не має виходу в інтернет, отримала власну інсталяцію пізніше; їй присвячено розділ 2.10 «Встановлення в ізольованому середовищі (Air-gapped)». Цей розділ містить те, що я хотів би мати першого ж ранку: який кластер очікує Nexus, на які імена він відгукується, скільки ресурсів вимагає від ваших вузлів і які рішення потрібно узгодити з вашим керівником ІТ-відділу перед встановленням. Завершується він робочим аркушем, який Іфа Бреннан (Aoife Brennan), наша керівниця ІТ-відділу, затвердила перед тим, як ми почали. Розділ 2.4 «Отримання та перевірка релізу» описує завантаження й перевірку релізу, а розділ 2.5 «Попередня перевірка за допомогою nexusctl» перевіряє ваш кластер на відповідність усьому, що тут викладено.
Що має бути в кластері
Nexus встановлюється як один Helm-чарт, nexus, версії 1.0.0-alpha.1. Чарт містить сервіси платформи та їхній рівень даних і відмовляється встановлюватися на кластер, у якому відсутні наведені нижче компоненти.
| Вимога | Що очікує Nexus | Чому |
|---|---|---|
| Kubernetes | 1.33 або новішої версії. Протестовано на k3s v1.33.6+k3s1 |
Параметр kubeVersion чарту має значення >=1.33.0-0, і helm install примусово застосовує цю вимогу |
| cert-manager | v1.21.3, встановлений перед Nexus |
Чарт створює власний локальний центр сертифікації (CA) та сертифікати, які його сервіси використовують для взаємодії один з одним |
| Helm | v4 (ми використовували v4.3.1) | Helm 4 за замовчуванням чекає на завершення хук-завдань (Jobs) чарту, від яких залежить встановлення |
| Клас сховища (Storage class) | Позначений як стандартний (default) або вказаний вами в storage.className |
Кожне сховище даних запитує постійний том (persistent volume) |
| Клас вхідного трафіку (Ingress class) | Позначений як стандартний (default) або вказаний вами в ingress.className |
Три публічні адреси є звичайними ресурсами Ingress версії networking.k8s.io/v1 |
| Порти 80 та 443 | Відкриті на ingress-контролері як сервіс типу LoadBalancer або NodePort | Користувачі звертаються до Nexus через ingress-контролер |
| Архітектура | Вузли linux/amd64 або linux/arm64 |
Кожен образ зібрано для обох архітектур |
Дві речі відсутні в цій таблиці навмисно. Nexus не потребує сервісної сітки (service mesh): взаємний TLS (mTLS, безпека транспортного рівня в обох напрямках) між сервісами забезпечується локальним центром сертифікації чарту через cert-manager. Чарт має ключ istio.enabled, який за замовчуванням дорівнює false, і вам варто залишити це значення. Крім того, Nexus не потребує власного механізму політик допуску (admission policy engine).
На вашій робочій станції вам знадобляться kubectl, Helm v4, cosign v3 для перевірки підписів, age для створення ключів зберігачів (custodian keys) та nexusctl — інтерфейс командного рядка (CLI) оператора Nexus. У розділі 2.4 «Отримання та перевірка релізу» вказано, де знаходяться всі файли для завантаження Nexus.
Три адреси
Кожна інсталяція відповідає за трьома іменами хостів. У чарті вони називаються ідентифікатором інсталяції (installation identity), і жоден сервіс не запуститься без них.
| Ключ у файлі значень | Ім'я в Harrow | Що відповідає за цією адресою |
|---|---|---|
hosts.console |
console.harrow.example |
Консоль — вебзастосунок, у який входять користувачі |
hosts.api |
api.harrow.example |
Шлюз, який обслуговує програмний інтерфейс застосунків (API) та маршрутизує кожен запит до штучного інтелекту (ШІ) |
hosts.auth |
auth.harrow.example |
Сервіс входу, nexus-auth |
Параметр global.domain містить домен, у якому розташовані ці три хости; у нашому випадку це harrow.example. Кожен хост сам по собі є повним ім'ям і може належати до будь-якого контрольованого вами домену. Ми розмістили всі три в одному домені, оскільки тоді їх можна покрити одним сертифікатом.
Створіть запис у системі доменних імен (DNS) для кожного з трьох хостів, спрямувавши його на адресу вашого ingress-контролера. Зробіть це до попередньої перевірки (preflight). Утиліта nexusctl preflight шукає кожне ім'я з вашої робочої станції та перериває встановлення, якщо для якогось із них немає запису, оскільки користувач не зможе звернутися за ім'ям, яке не розв'язується.
Вибір способу термінації TLS
Параметр tls.mode чарту визначає, хто відповідає за сертифікати для трьох публічних адрес. Є три варіанти, і ви можете змінити свій вибір пізніше під час оновлення.
tls.mode |
Що надаєте ви | Що робить чарт |
|---|---|---|
existing (за замовчуванням) |
TLS Secret Kubernetes у просторі імен nexus, ім'я якого вказано в tls.existingSecret |
Усі три ресурси Ingress використовують цей єдиний Secret |
cert-manager |
Підтримуваний вами ресурс ClusterIssuer, ім'я якого вказано в tls.clusterIssuer |
Додає анотації до кожного ресурсу Ingress, щоб cert-manager випустив nexus-console-tls, nexus-api-tls та nexus-auth-tls |
none |
Зовнішній компонент перед кластером, який термінує TLS, наприклад ваш власний балансувальник навантаження | Генерує ресурси Ingress без секції TLS |
У варіанті existing один сертифікат обслуговує всі три хости, тому в ньому мають бути вказані всі три імені — або як три альтернативні імена суб'єкта (SAN), або як груповий символ (wildcard) для вашого домену. Ми використали сертифікат від внутрішнього центру сертифікації Harrow. Попередня перевірка (preflight) зчитує Secret перед встановленням і видає попередження, якщо термін дії сертифіката спливає менш ніж через 30 днів.
У варіанті з cert-manager та видавцем на базі автоматизованого середовища керування сертифікатами (ACME) чарт не додає власного перенаправлення, тож запит /.well-known/acme-challenge/ на порт 80 доходить до обробника перевірки без змін. Не додавайте на своєму ingress-контролері перенаправлення з HTTP на HTTPS, яке спрацьовує перед шляхом перевірки (challenge path); сертифікат, який не може оновитися, тихо перестане працювати через кілька тижнів.
Незалежно від того, що ви оберете для публічного периметра, сервіси всередині простору імен завжди взаємодіють через TLS від локального центру сертифікації чарту. Ця частина є обов'язковою, і саме тому cert-manager є передумовою навіть тоді, коли параметр tls.mode має значення existing або none.
Що виходить за межі кластера, а що — ні
Чарт генерує мережеву політику заборони за замовчуванням (default-deny) для простору імен nexus. Після цього дозволеними залишаються лише такі потоки трафіку:
- трафік між подами Nexus усередині простору імен;
- DNS-запити до DNS-сервісу кластера;
- API-сервер Kubernetes — для кількох сервісів, які перевіряють токени робочих навантажень;
- простір імен ingress-контролера — до трьох публічних сервісів (Services);
- будь-які діапазони безкласової міждоменної маршрутизації (CIDR), які ви перелічите в
networkPolicy.externalEgressCIDRs.
Останній список за замовчуванням порожній. Якщо ви використовуватимете поштовий ретранслятор або сервер моделей за межами кластера, сюди потрібно додати його діапазон адрес. Телеметрію вимкнено, і вона залишається вимкненою: схема приймає лише значення telemetry.enabled: false, а власні механізми звітування про використання у сховищах даних також вимкнені.
Під час встановлення чарт зчитує адреси API-сервера з кластера. Якщо ваш обліковий запис не має прав на читання ресурсу Endpoints kubernetes у просторі імен default, вкажіть їх самостійно в networkPolicy.apiServerCIDRs у вигляді діапазонів /32. Параметр proxy.trustedCIDRs задає мережу подів, у якій розташований ваш ingress-контролер, щоб nexus-auth знав, чиєму заголовку X-Forwarded-For можна довіряти. Значення за замовчуванням, 10.42.0.0/16, відповідає мережі подів k3s.
Оцінка розміру ресурсів
Стандартні запити ресурсів (requests) чарту сумарно становлять близько 2.05 ядра центрального процесора (CPU) та 6.7 GiB оперативної пам'яті. Це те, що резервує планувальник; ліміти (limits) є вищими, і сховища даних поступово заповнюють їх у міру додавання користувачів і файлів.
| Компонент | Запитано CPU | Запитано пам'яті |
|---|---|---|
| Дев'ять сервісів платформи (console, бекенд для фронтенду (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) | 1.1 ядра | 2.6 GiB |
Сервіс ключів, nexus-keys |
0.05 ядра | 64 MiB |
| PostgreSQL | 0.25 ядра | 1 GiB |
| Neo4j | 0.25 ядра | 2 GiB |
| Valkey, Qdrant та об'єктне сховище разом | 0.25 ядра | 640 MiB |
| Два сервери OpenBao сховища ключів | 0.15 ядра | 384 MiB |
Стандартні томи сумарно займають 142 GiB:
| Сховище | Ключ у файлі значень | Стандартний розмір |
|---|---|---|
| PostgreSQL 16 з PostGIS 3 та pgvector 0.8 | dataTier.postgres.size |
50Gi |
| Об'єктне сховище (SeaweedFS) | dataTier.objectStore.size |
50Gi |
| Neo4j 5.26 Community Edition | dataTier.neo4j.size |
20Gi |
| Qdrant | dataTier.qdrant.size |
10Gi |
| Valkey | dataTier.valkey.size |
5Gi |
| Сховище ключів та його розблокувальник (unsealer) | keys.openbao.storage.keystore, keys.openbao.storage.unsealer |
5Gi та 1Gi |
| Квитанції сервісу ключів | keys.receiptsStorage |
1Gi |
Для одного вузла плануйте 8 vCPU, 32 GiB оперативної пам'яті (RAM) та твердотільний накопичувач (SSD) на 250 GB. Для ознайомчої версії вистачить 4 vCPU, 16 GiB та 200 GB. Дисковий образ інсталятора відмовляється працювати на машині з менш ніж 16 GiB пам'яті (див. розділ 2.9 «Дисковий образ інсталятора»), і я б радив вважати це абсолютним мінімумом усюди.
Вузли з графічними процесорами є необов'язковими. Без вузла з графічним процесором (GPU) асистент відповідає через зовнішню (hosted) модель, використовуючи власний ключ організації. Попередня перевірка (preflight) повідомляє про це як про попередження, а не помилку. Обидва варіанти описано в розділі 2.14 «Провайдери та моделі ШІ».
Кожне сховище даних також може працювати за межами кластера: встановіть для параметра dataTier.<store>.mode значення external та вкажіть його хост і Secret. Зовнішній базі даних PostgreSQL потрібен обліковий запис суперкористувача для початкової ініціалізації під час встановлення, а також сертифікат, який Nexus зможе перевірити. Це описано в розділі 2.11 «Варіації: зовнішні сховища, TLS та ingress». Якщо ви залишаєте їх у кластері, розміщуйте їх у класі сховища, за яким стоять реальні диски. База даних — це та частина, втрата якої буде найбільш відчутною, якщо вийде з ладу локальний диск вузла.
Назва інсталяції є постійною
Параметр keys.installationName — це те, як оператори називають цю інсталяцію. Він має відповідати регулярному виразу ^[a-z][a-z0-9-]{0,62}$: мала літера, після якої йде до 62 малих літер, цифр або дефісів.
Під час першого запуску сховище ключів генерує ідентифікатор інсталяції під цим ім'ям, і цей ідентифікатор фіксується назавжди. Ліцензія від Adverant випускається саме для цього ідентифікатора, тому ліцензія, створена для однієї інсталяції, буде відхилена на іншій із помилкою LICENCE_OTHER_INSTALLATION. Перейменування означатиме нову інсталяцію, новий ідентифікатор і нові ліцензії.
У чарті немає значення за замовчуванням для цього імені. Він відмовляється від встановлення без імені (INSTALLATION_NAME_MISSING) і відхиляє ім'я-приклад із власних демонстраційних файлів значень (INSTALLATION_NAME_EXAMPLE). Попередня перевірка повідомляє про обидві ситуації ще до того, як ви дійдете до цього етапу.
У Harrow ми витратили на це більше часу, ніж мені хотілося б визнавати. Ми зупинилися на harrow-port-authority: ця назва вказує на організацію, нічого не говорить про те, на якому кластері вона працює, і залишатиметься актуальною після заміни обладнання. Уникайте назв на кшталт prod-k3s-2, які описують поточні машини.
Зберігання ключів
Nexus зберігає ключі кожної організації у власному сховищі ключів усередині кластера. Ви не керуєте ним у повсякденній роботі, але перед встановленням маєте вирішити, хто зможе відновити його роботу після перезапуску. Це рішення, помилка в якому обійдеться найдорожче.
Сховище ключів складається з двох серверів OpenBao. Основний, openbao, зберігає ключі й розблоковує себе (unseals) через другий, менший сервер — openbao-unsealer. Цей розблокувальник (unsealer) заблоковано за схемою Шаміра: п'ять часток ключа, будь-які три з яких відкривають його. Під час встановлення спеціальне завдання керування ключами (custody Job) ініціалізує обидва сервери всередині кластера. У власній оперативній пам'яті це завдання шифрує частки ключа розблокувальника та ключі відновлення сховища ключів для кожного вказаного вами зберігача (custodian), зберігає лише зашифрований текст (у ресурсах Secret openbao-unseal-shares-encrypted та openbao-recovery-keys-encrypted) і відкликає обидва кореневі токени перед завершенням роботи. Жодна частка ключа у відкритому вигляді ніколи не потрапляє на диск або в журнали.
Після будь-якого перезапуску вузла, на якому працює розблокувальник, він запускається в заблокованому стані. Сховище ключів чекає на нього, і жоден компонент, якому потрібен ключ, не працюватиме, доки хтось зі зберігачів не розблокує його. Для цього потрібне одне розшифрування за допомогою особистого приватного ключа зберігача. Цю процедуру описано в розділі 2.15 «День другий: експлуатація Nexus».
Створення ключа зберігача
Зберігач визначається за відкритою частиною ключа age, яка називається його отримувачем (recipient). Кожен зберігач створює власний ключ на своїй машині й передає вам лише рядок отримувача:
age-keygen -o custodian.keyРядок # public key: у файлі — це і є отримувач, який починається з age1. Зберігач із комп'ютером Mac може натомість зберігати ключ у чипі Secure Enclave свого Mac, щоб приватна частина ніколи не залишала чип, а кожне використання вимагало відбитка пальця:
age-plugin-se keygen --access-control=any-biometry -o custodian.keyТакий отримувач починається з age1se1. Завдання керування ключами шифрує дані для п'яти форматів отримувачів: age1 (X25519), age1tag1 і age1tagpq1 (тег), age1pq1 (гібридний постквантовий) та age1se1 (Secure Enclave). Воно відхиляє будь-які інші формати плагінів, наприклад age1yubikey1; натомість укажіть такий ключ в одному з підтримуваних форматів.
Чарт перевіряє кожного отримувача під час генерації маніфестів. Отримувач із друкарською помилкою не проходить перевірку контрольної суми bech32 і відхиляється, тож дані ніколи не будуть зашифровані ключем, якого ні в кого немає. Якщо хтось помилково вставить у список приватний ключ, чарт відхилить його, не виводячи вміст на екран. Отримувач-приклад із власних файлів значень чарту також відхиляється (KEYS_CUSTODIAN_EXAMPLE), оскільки ніхто не володіє його приватною частиною.
Скільки має бути зберігачів
Кожна частка ключа шифрується для кожного зберігача, тому будь-який один зберігач може виконати розблокування самостійно. Більша кількість зберігачів означає більше способів відновлення та більше людей, кожен із яких може діяти незалежно. У Harrow ми обрали трьох: Іфу, мене та ключ Secure Enclave на запасному ноутбуці, який лежить у сейфі порту. Два — це мінімум, на який я б погодився. Один — це єдина точка відмови, яка рано чи пізно опиниться у відпустці саме тоді, коли перезапуститься вузол.
Вибір редакції
Параметр edition має значення community або enterprise, і enterprise.enabled повинен збігатися з ним. Чарт відхиляє розбіжності, а також будь-яку редакцію, відмінну від цих двох.
Редакція також визначає, які образи ви встановлюєте. Кожен пакет чарту містить файл фіксації образів (images lock) — список усіх образів за їхніми хеш-сумами (digest) для однієї редакції. Інсталяція Community використовує лише образи Community. Інсталяція Enterprise використовує файл фіксації Enterprise, який включає образи Community плюс збірки Enterprise, і завантажує їх за допомогою токена доступу (pull token) з вашого облікового запису Adverant. У розділі 2.4 «Отримання та перевірка релізу» пояснюється принцип роботи файлу фіксації, а в розділі 2.2 «Редакції зсередини» описано, що містить кожна редакція.
Вам не обов'язково приймати остаточне рішення одразу. Інсталяція Community оновлюється до Enterprise на місці, зберігаючи своїх користувачів, файли та історію; у розділі 2.7 «Встановлення Enterprise та застосування ліцензії» показано, як це зробити. У Harrow ми запустили Community для пілотного проєкту й перейшли на Enterprise через шість тижнів.
Ліцензія ніколи не є частиною цього плану встановлення. Це не значення в чарті й не змонтований файл: ви імпортуєте її після встановлення через консоль, nexusctl або API.
Вибір форми постачання
| Форма постачання | Коли підходить | Розділ |
|---|---|---|
Helm-чарт із registry.adverant.ai |
Ваш власний кластер Kubernetes із доступом до реєстру образів | 2.6 та 2.7 |
nexusctl install |
Той самий кластер, але попередня перевірка та перевірка підписів виконуються автоматично для вас | 2.6 |
nexusctl install --single-node |
Одна машина, де nexusctl також налаштовує сам кластер |
2.8 |
| Дисковий образ інсталятора | Фізичний сервер або віртуальна машина (VM), які ви волієте не готувати вручну | 2.9 |
| Офлайн-пакет | Повна відсутність виходу в зовнішню мережу; образи та чарт постачаються на диску | 2.10 |
Сам чарт однаковий у кожній формі постачання. Змінюється лише те, хто створює кластер і звідки беруться образи.
Робочий аркуш планування
Це робочий аркуш Harrow у тому вигляді, як його затвердила Іфа. Скопіюйте ліві два стовпці й заповніть правий для власної інсталяції.
| Рішення | Ключ у файлі значень або команда | Harrow Port Authority |
|---|---|---|
| Kubernetes та версія | (зчитується під час попередньої перевірки) | k3s v1.33.6+k3s1, три вузли |
| Контекст Kube для встановлення | --context |
harrow-prod |
| Простір імен (Namespace) | --namespace |
nexus |
| Редакція | edition, enterprise.enabled |
community для пілотного проєкту, потім enterprise |
| Реєстр образів | global.imageRegistry |
registry.adverant.ai |
| Домен | global.domain |
harrow.example |
| Адреса консолі | hosts.console |
console.harrow.example |
| Адреса API | hosts.api |
api.harrow.example |
| Адреса сервісу входу | hosts.auth |
auth.harrow.example |
| TLS на периметрі | tls.mode, tls.existingSecret |
existing, Secret harrow-public-tls від внутрішнього центру сертифікації Harrow |
| Клас вхідного трафіку (Ingress class) | ingress.className |
traefik |
| Простір імен ingress-контролера | networkPolicy.ingressNamespace |
kube-system |
| Клас сховища (Storage class) | storage.className |
local-path |
| Сховища даних | dataTier.<store>.mode |
Усі in-cluster, стандартні розміри |
| Вихідні діапазони адрес | networkPolicy.externalEgressCIDRs |
Лише діапазон поштового ретранслятора |
| Ім'я інсталяції (незмінне) | keys.installationName |
harrow-port-authority |
| Зберігачі ключів (фактично незмінні) | keys.custody.recipients |
Троє: Aoife Brennan, Tomás Reilly, ноутбук у сейфі (age1se1) |
| Вузли з графічними процесорами | (зчитується під час попередньої перевірки) | Немає для підключеного до мережі пілотного проєкту; зовнішня модель із власним ключем Harrow |
| Перший адміністратор | nexusctl claim-code --administrator |
aoife.brennan@harrow.example |
Два рядки в цій таблиці неможливо скасувати: ім'я інсталяції та зберігачів ключів — у тому сенсі, що втрата їх усіх означає втрату сховища ключів. Узгодьте ці два пункти під підпис із кимось, хто має повноваження ухвалювати такі рішення. Усе інше можна змінити у файлі значень.
Коли робочий аркуш буде заповнено, переходьте до розділу 2.4 «Отримання та перевірка релізу» та завантажте реліз.
