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

Розділ 2.15

Повсякденна експлуатація Nexus

Регулярні завдання з обслуговування інсталяції після першого тижня роботи: від розблокування сховища ключів після перезапуску до видалення системи.

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

18 хв читання

Коли в серверній Harrow Port Authority вперше зникло живлення, після відновлення запрацювало все, крім компонентів, яким були потрібні ключі. Поди мали статус Running, і консоль завантажилася. Ніхто не міг відкрити жодного файлу. Tomás Reilly читав про це, та все одно йому знадобилося двадцять хвилин, щоб згадати причину. Служба розблокування сховища ключів запускається в заблокованому стані після кожного перезапуску свого вузла, і розблокувати її може лише зберігач ключів.

У цьому розділі описано поточну роботу оператора після першого тижня: від сховища ключів і його зберігачів до видалення системи. Кожна команда nexusctl тут приймає прапорець --explain, який виводить операції kubectl та helm, що мають бути виконані, без їх фактичного запуску. Використовуйте його під час першого запуску будь-яких команд у продуктивному кластері.

Управління сховищем ключів

Інсталяція має два сервери OpenBao у своєму просторі імен. Сховище ключів, openbao, зберігає всі ключі, які використовує Nexus. Служба розблокування, openbao-unsealer, — це другий, невеликий сервер OpenBao, єдине завдання якого — розблоковувати сховище ключів. Сховище ключів розблоковується автоматично за допомогою транзитного ключа служби розблокування; сама ж служба розблокування захищена за схемою Шаміра з 5 частками, з яких будь-які 3 дозволяють її розблокувати.

Під час першого встановлення завдання Job для налаштування зберігання ініціалізує обидва сервери всередині кластера. Воно у власній пам'яті шифрує частки служби розблокування та ключі відновлення сховища ключів для кожного зберігача, зазначеного в keys.custody.recipients, і зберігає лише зашифрований текст (об'єкти Secret openbao-unseal-shares-encrypted та openbao-recovery-keys-encrypted). Воно також відкликає обидва кореневі токени в межах того самого завдання Job. Пакет кожного зберігача містить достатньо часток для самостійного розблокування, тож після перезапуску достатньо лише одного зберігача.

Після перезапуску вузла

Після будь-якого перезапуску вузла, на якому працює служба розблокування (вимкнення живлення, перезавантаження машини, перезапуск середовища виконання контейнерів), вона запускається в заблокованому стані. Доки зберігач її не розблокує, сховище ключів також залишається заблокованим, і все, що потребує ключів, не працює. Консоль відповідає, і користувачі можуть входити в систему, але будь-яка дія, що потребує ключа зі сховища ключів, очікує: відкриття зашифрованого вмісту, запит прав, перевірка скомпільованого компонента.

Опитайте сам сервер OpenBao всередині кожного пода. Це служба розблокування:

kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
  bao status -format=json -address=https://127.0.0.1:8200 \
  -ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"

Виконайте ту саму команду для openbao-0 із параметром -tls-server-name=openbao для сховища ключів. Команда bao status повертає код виходу 0, коли сервер розблоковано, 2 — коли його заблоковано, і 1 — коли він не зміг відповісти. Код виходу 1 ні про що не свідчить, оскільки под, можливо, ще не запустився. Зачекайте хвилину та повторіть запит. Якщо службу розблокування вже розблоковано, а сховище ключів досі заблоковане, це означає, що сховище ключів розблоковується самостійно і вам нічого не потрібно робити.

Ліворуч: піктограма людини з підписом «Зберігач із власним ключем ідентифікації age». Стрілка веде праворуч до блоку «unseal.sh на машині зберігача (одноразове розшифрування)». Звідти стрілка з підписом «kubectl port-forward, протокол захисту транспортного рівня (TLS) перевіряється за центром сертифікації (CA) служби розблокування» веде до блоку «openbao-unsealer (5 часток Шаміра, будь-які 3)». Від служби розблокування друга стрілка з підписом «транзитний ключ, автоматично» веде до блоку «openbao, сховище ключів». Від сховища ключів віялом розходяться стрілки до менших блоків «nexus-keys», «nexus-auth», «інші сервіси». Примітка під зберігачем: «ключ ідентифікації ніколи не залишає цю машину».
Дії зберігача після перезапуску вузла.

Розблокування

Чарт постачає скрипт unseal.sh у своїй папці files/custody/, який побайтово ідентичний у кожному випуску. Зберігач запускає його на власній машині. Скрипт зчитує зашифрований об'єкт Secret, одноразово розшифровує його за допомогою ключа ідентифікації зберігача (ключ у Secure Enclave один раз запитує підтвердження Touch ID), передає частки службі розблокування та підтверджує її розблокування. Жодна частка ніколи не записується у файл і не передається в командному рядку.

Harrow запускає його в прямому режимі через перенаправлення портів:

kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &

AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh

<path-to-your-custodian-identity> — це файл ідентифікації age зберігача, приватна частина одного з отримувачів у keys.custody.recipients. UNSEAL_RESOLVE — це ім'я, зазначене в сертифікаті служби розблокування (<namespace> — це простір імен, у якому встановлено Nexus, за замовчуванням nexus), тож TLS перевіряється за власним центром сертифікації (CA) служби розблокування, навіть якщо з'єднання встановлюється з 127.0.0.1. Скрипт ніколи не вимикає перевірку сертифікатів.

Код виходу Останній рядок Значення
0 UNSEALED nexus/openbao-unsealer-0 Розблоковано. Якщо вже було розблоковано, нічого не надсилалося
1 STILL-SEALED … Досі заблоковано, або виклик розблокування завершився помилкою
2 UNSEAL-REFUSED … Відсутній обов'язковий компонент, зазначений у повідомленні
3 UNSEAL-REFUSED … Цей ключ ідентифікації не може розшифрувати частки, отже він не належить зберігачу цієї інсталяції. Нічого не надсилалося

Протягом хвилини сховище ключів розблоковується самостійно. Перевірте за допомогою kubectl -n nexus get deploy,statefulset, чи все знову готове до роботи.

Зберігачів обирають перед встановленням, і кожен із них створює власний ключ на своїй машині. Чарт бачить лише публічну частину ключа:

age-keygen -o custodian.key
age-plugin-se keygen --access-control=any-biometry -o custodian.key

Перша команда створює звичайний ключ ідентифікації age; його отримувачем є рядок # public key: age1... у файлі. Друга створює ключ, що зберігається в Secure Enclave на Mac, з отримувачем, який починається на age1se1. Будь-який із цих отримувачів додається до keys.custody.recipients. Файл ідентифікації залишається у свого зберігача в офлайн-режимі.

Резервне копіювання та відновлення

Сторінка «Резервне копіювання та відновлення» показує кожне сховище з датою його останньої резервної копії та часом останнього фактичного тестування відновлення з неї. Надійність резервної копії доведена лише тоді, коли з неї було виконано відновлення, тому сторінка відстежує обидва показники. Резервне копіювання виконується для шести сховищ. Основна база даних зберігає дані про людей і налаштування, завдання та журнал аудиту. Поруч із нею розташовані граф знань і пошуковий індекс, а далі — файлове сховище та сховище пам'яті. Ключі — це шосте сховище; вони заблоковані та зберігаються окремо від даних. Резервні копії надсилаються до вашого власного сховища, зашифровані вашими власними ключами, і Adverant не може їх прочитати. Коли сховище не проходило тестового відновлення згідно з вашим правилом, на сторінці відображається плашка RESTORE_TEST_OVERDUE із кнопкою «Протестувати зараз». Тестове відновлення виконується в окремому просторі й залишається непомітним для користувачів.

Ті самі дві дії доступні з командного рядка:

nexusctl backup now
nexusctl backup verify

backup now створює резервну копію всіх сховищ одночасно. backup verify перевіряє останню резервну копію. Виконуйте обидві команди перед будь-якими змінами, щодо яких ви хвилюєтеся.

Резервне копіювання та відновлення
Резервне копіювання та відновлення
Кожне сховище з його останньою резервною копією та останнім протестованим відновленням. Для пошукового індексу прострочено час тестування, і плашка пропонує запустити його зараз.

Щоб виконати відновлення, вкажіть назву резервної копії:

nexusctl restore --from <backup-id>

Значення <backup-id> береться зі списку на сторінці «Резервне копіювання та відновлення». Відновлення потребує підтвердження другою особою, і під час його виконання смуга перебігу показує стан процесу, час початку та особу, яка його підтвердила. Під час відновлення всі користувачі працюють у режимі лише для читання — це відрізняється від повного блокування доступу: люди можуть входити в систему та переглядати дані. Завдання не запускаються (розклади очікують і надолужують пізніше), а пошук відновлює роботу після повернення пошукового індексу. Усі дані, записані після створення резервної копії, втрачаються, тому у звіті про відновлення їх перелічено за власниками, щоб ті могли відтворити їх.

Відновлення
Відновлення
Триває відновлення. Сховища повертаються до роботи по черзі, користувачі працюють у режимі лише для читання до відновлення останнього з них, а повідомлення на кожній сторінці інформує про очікуваний час завершення.

Зберігайте разом зі своїми резервними копіями ще один елемент: об'єкт Secret nexus-generated у просторі імен nexus. Чарт створює згенеровані паролі та ключі шифрування інсталяції під час першого встановлення і зчитує їх із цього об'єкта Secret під час кожного оновлення. Дані, зашифровані за допомогою EXTERNAL_KEY_ENCRYPTION_KEY, можна відкрити лише цим ключем. Зберігайте копію цього об'єкта Secret там само, де ви тримаєте найконфіденційніші матеріали, оскільки кожен, хто має до нього доступ, володіє цими ключами.

Оновлення версій

Tomás виконує оновлення у два кроки. Спочатку він запитує, що саме зміниться:

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

План містить перелік змін у випуску, будь-які зміни в структурі бази даних, а також інформацію про те, чи можна їх скасувати. Потім він застосовує оновлення:

nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Під час застосування спочатку створюється резервна копія та виконується попередня перевірка. Потім рушії оновлюються хвилями, і кожна наступна хвиля чекає, доки попередня не пропрацює без збоїв протягом 10 хвилин. Сторінка «Оновлення» показує перебіг кожної хвилі та поточний стан працездатності інсталяції. На ній також зазначено, до якого моменту залишається доступним відкат; після цієї дати для повернення знадобиться відновлення з резервної копії. Якщо на якомусь кроці стається збій, Nexus відкочує всі рушії до попереднього випуску та перевіряє їх. Повідомлення UPGRADE_ROLLED_BACK вказує крок, на якому стався збій, і підтверджує, що дані не було змінено. Інструкція з виправлення відображається перед кнопкою «Спробувати знову», а пакет підтримки доступний в один клік.

Для інсталяції без зовнішнього підключення пакет доставляється на фізичному носії. Функція імпорту з носія перевіряє підпис випуску за допомогою ключа випусків Adverant, встановленого в інсталяції, і контролює, щоб версії змінювалися лише за зростанням. Файли, підписані будь-ким іншим, відхиляються з помилкою MEDIA_SIGNATURE_INVALID: нічого не завантажується, а поточний випуск продовжує працювати.

Оновлення
Оновлення
Триває оновлення. Спочатку було створено резервну копію, зараз виконується друга з трьох хвиль, а можливість відкату залишається відкритою до зазначеної дати.
Збій оновлення та відкат змін
Збій оновлення та відкат змін
Хвиля завершилася збоєм через брак місця на томі. Усі рушії повернуто до попереднього випуску зі збереженням даних, а перед кнопкою «Спробувати знову» наведено спосіб виправлення.

Що відбувається всередині

Команда nexusctl upgrade apply запускає helm upgrade для чарту. Якщо ви оновлюєте систему за допомогою Helm самостійно, діють ті самі правила:

helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

Схема бази даних оновлюється до розгортання нових подів. Міграції чарту — це хуки попереднього оновлення (pre-upgrade hooks), які виконуються послідовно: спочатку початкове налаштування бази даних, потім міграції кожного сервісу, а після них — міграції BFF (backend for frontend) консолі. Завдання Job для налаштування зберігання також запускається: у вже ініціалізованій інсталяції воно просто підтверджує цей стан і нічого не змінює. Кожне завдання Job хука має ліміт повторних спроб (backoff limit) 0, тож помилка міграції зупиняє оновлення і ніколи не повторюється непомітно: перед повторною спробою перегляньте журнал за допомогою kubectl -n nexus logs job/<hook-job>.

Под кожного сервісу очікує в ініціалізаційному контейнері wait-for-schema, доки в реєстрі випусків не з'явиться запис про застосування його міграцій для образу нового випуску. Після відкату або оновлення, яке змінило лише параметри (values), перезапущений под одразу знаходить свій рядок і запускається.

Перед оновленням

Під час планування варто врахувати три моменти з приміток до випуску:

  1. Виконуйте оновлення в період низького навантаження. Під час першого оновлення інсталяції, створеної зі старішого чарту, завдання початкового налаштування скасовує старі права доступу до таблиць за замовчуванням, і кожен сервіс повертає власні права під час виконання своєї міграції. Доки ця міграція не завершиться, сервіс не може використовувати свої таблиці. Ця пауза триває лічені секунди. Якщо секунди мають значення, спочатку масштабуйте сервіси до нуля та підніміть їх після завершення завдань міграції.
  2. Призначте організацію кожному ключу прикладного програмного інтерфейсу (API). Ключ без організації відхиляється з помилкою 403 TOKEN_ORG_MISSING усіма сервісами, які перевіряють ключі через nexus-auth, включно з nexus-graphrag. Перед оновленням призначте кожному такому ключу організацію або випустіть новий ключ. Старі ключі bcrypt продовжують працювати до дати їх примусового відкликання.
  3. Очистьте кешовані ключі API після оновлення. Доки ви цього не зробите, кешовані записи ключів можуть зберігати неправильну назву застосунку протягом години. Виконайте цю команду для кешу nexus-auth — сервера Valkey інсталяції (nexus-valkey, пароль в об'єкті Secret nexus-generated у полі VALKEY_PASSWORD):
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
  'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"

Це стосується стандартного сховища всередині кластера. Якщо використовується dataTier.valkey.mode: external, такого пода немає: виконайте те саме сканування та видалення на власному хості Valkey, використовуючи пароль з об'єкта Secret, зазначеного в dataTier.valkey.external.existingSecret.

Відкат

Протягом часового вікна, показаного на сторінці «Оновлення», кнопка «Повернутися» відкочує кожен рушій до попереднього випуску. Після завершення цього вікна повернення означає відновлення з резервної копії, створеної перед початком оновлення.

Два параметри повинні залишатися незмінними під час будь-якого оновлення чи відкату.

Параметр keys.installationName є постійним. Під час першого початкового налаштування сховища ключів на його основі формується ідентифікатор інсталяції, і саме цей ідентифікатор зазначається у вашій ліцензії. Використовуйте точно те саме значення в кожному файлі параметрів (values), який ви будь-коли застосовуєте до цієї інсталяції.

Об'єкт Secret nexus-generated має залишатися незмінним. Під час кожного оновлення чарт зчитує з нього EXTERNAL_KEY_ENCRYPTION_KEY та перевіряє його формат. Значення, яке не є ані рядком base64 із 32 байтів, ані необробленим 32-байтовим ключем старішої інсталяції, зупиняє генерацію шаблонів із помилкою EXTERNAL_KEY_ENCRYPTION_KEY_INVALID, причому чарт ніколи не виводить саме значення. Це означає, що хтось відредагував або замінив об'єкт Secret. Поверніть ключ, яким зашифровано дані цієї інсталяції, у форматі base64 його 32 байтів (printf %s "$OLD" | base64) і повторіть оновлення. Новий випадковий ключ зробить усі дані, зашифровані старим ключем, непридатними для читання.

Масштабування

Кожен компонент має перемикач і налаштування розміру у файлі параметрів (values). Обов'язкові компоненти не можна вимкнути: чарт запускає їх незалежно від стану перемикача. Іншим компонентам можна виділити більше реплік і ресурсів.

# harrow-values.yaml (Helm values): scaling
components:
  gateway:
    replicas: 2
    resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
  graphrag:
    replicas: 2
  workflows:
    replicas: 2
workflows:
  concurrency: "8"
dataTier:
  qdrant:
    resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }

Застосуйте зміни за допомогою helm upgrade, як описано вище. Розміри томів задаються в dataTier.<store>.size; перш ніж збільшувати том, переконайтеся, що ваш клас сховища (storage class) підтримує розширення томів. Сторінка стану інсталяції показує графіки завантаженості процесорів і пам'яті кластера, а також залишок вільних ресурсів. Розширюйте те, що вичерпується першим.

Пакети діагностики для підтримки

Коли Harrow потребує допомоги Adverant, Tomás створює пакет підтримки:

nexusctl support-bundle --out harrow-support-4471.tar.gz

Сторінка «Пакет підтримки» в консолі створює такий самий файл. Вона збирає журнали роботи рушіїв за останні 24 години разом із даними про стан працездатності та версії. Налаштування додаються без секретів, разом зі звітами про попередню перевірку та встановлення. Перш ніж будь-що буде записано, функція знеособлення замінює імена та секрети на заповнювачі, і ви можете попередньо переглянути точний вміст пакета перед відправленням. Власний контент користувачів ніколи не збирається. Пакет передається до Adverant або шляхом завантаження на сторінку «Підтримка та пакети підтримки» вашого облікового запису, або як файл на зовнішньому носії. Відкрити його можуть лише інженери підтримки, зазначені в запиті, а через 30 днів він видаляється.

Пакет підтримки
Пакет підтримки
Створення пакета підтримки. Попередній перегляд знеособлення показує приховані дані до відправлення, а відкрити пакет можуть лише призначені інженери.

Експорт доказових даних

Аудитори та ваш власний відділ комплаєнсу часто вимагають доказів того, що платформа працює відповідно до опису. Команда nexusctl evidence export формує такий звіт:

nexusctl evidence export --out harrow-evidence-2027-01

Окрім експорту записів, команда запускає приймальні тести платформи: маршрутизатор штучного інтелекту (ШІ) доступний і відповідає, завдання UNO надсилається і виконується, а читання даних між різними організаціями відхиляється. Результати цих перевірок зберігаються у файлі probes.json у вихідній папці.

Загальний огляд стану

Команда nexusctl status --json показує, чи справна інсталяція і в якому стані перебуває кожен компонент. Вона також повідомляє стан ліцензії з датою закінчення терміну дії, редакцію та поточний випуск. Кожен скомпільований компонент перелічено з його контрольною сумою (digest) та підписом. Саме цю команду варто підключити до вашої власної системи моніторингу.

Видалення

nexusctl uninstall --profile <profile-file>

<profile-file> — це профіль розгортання для кластера, той самий файл, який ви передавали в nexusctl handoff --profile <profile-file> --out <dir>, якщо кластером керує ваша інфраструктурна команда. Функція передачі (Handoff) формує для цієї команди зрозумілий опис вимог Nexus до кластера та відповідні маніфести для їх виконання. Видалення (Uninstall) прибирає лише простори імен Nexus і нічого більше, зберігаючи ваші резервні копії. Ідентифікатор інсталяції видаляється разом із нею. Подальше встановлення в тому самому кластері буде вже новою інсталяцією з новим ідентифікатором, тому для неї знадобляться новий запит прав і нова ліцензія.

Сторінки розділу «Ця інсталяція» (This installation)

Оператори інсталяції мають власну групу в меню — «Ця інсталяція», і саме на її сторінках у консолі виконується більшість дій, описаних у цьому розділі. Користувач без відповідних прав, який відкриває одну з цих сторінок, бачить сторінку «Не адміністратор» із переліком осіб, які мають право виконувати ці дії.

Сторінка Призначення
Ліцензія та що вона відкриває Ліцензія та її групи функцій (розділ 2.13, Ліцензії)
Якщо термін дії ліцензії закінчується Текстовий опис етапів завершення дії з датами цієї ліцензії
Скомпільовані компоненти Кожен ліцензований модуль із його щонічною перевіркою підпису
Звіт про використання для Adverant Річні лічильники, доступні для перегляду перед відправленням
Версії та оновлення Кожна встановлена версія із зазначенням того, хто і коли її встановив
Оновлення Поетапне оновлення та можливість відкату
Резервне копіювання та відновлення Кожне сховище, його остання резервна копія та останнє протестоване відновлення
Стан інсталяції Вузли, потужність і поточні витрати з попередженнями
Ключі та стирання даних Ключ кожної організації та функція стирання із зазначенням причини й підтвердженням другою особою
Інциденти Відкриті й закриті проблеми з описом виконаних дій
Незабаром виводяться з експлуатації Функції, що вимикаються, з датами, експортом і заміною
Статус Стан кожного компонента Nexus зараз і за 30 днів, описаний зрозумілою кожному мовою
Пакет підтримки Які дані надсилаються до Adverant і яким чином

Дві з цих сторінок варті окремої уваги. Сторінка «Скомпільовані компоненти» щоночі перевіряє кожен ліцензований модуль на відповідність підпису Adverant. Змінена копія модуля відхиляється і ніколи не завантажується, тоді як підписана копія продовжує працювати, а сторінка підраховує кількість відхилень за місяцями, щоб жодна спроба підміни не залишилася непоміченою. Сторінка «Стан» написана так, щоб її міг зрозуміти будь-хто в організації. Вона відображає стан кожного компонента Nexus зараз і за останні 30 днів у вигляді шкали днів із запланованим обслуговуванням та нещодавніми інцидентами, і з цієї ж сторінки оператор може додати інцидент або вікно обслуговування.

Інсталяція редакції Community має одну сторінку — «Ця інсталяція (Community)», де показано її версію, стан працездатності та оновлення. Сторінки редакції Enterprise відображаються на ній як ознайомчі блоки із зазначенням того, хто може їх увімкнути.