ВходЗапазете среща

Глава 2.3

Планиране на инсталация

От какво се нуждае една инсталация на Nexus в Kubernetes, преди да въведете команда, колко е голяма и двете решения, които не можете да промените обратно – името на инсталацията и пазителите на ключове. Завършва с попълнения работен лист за планиране на Harrow Port Authority.

Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

16 минути за четене

Когато инсталирахме Nexus в Harrow Port Authority, изпълнението на командите отне един следобед. Планирането отне една седмица, като по-голямата част от нея отиде за два въпроса, които нямат нищо общо с Kubernetes: как ще наречем инсталацията и кои хора ще държат нейните ключове за възстановяване. И двата отговора са окончателни. Всичко останало в тази глава може да бъде променено по-късно с файл със стойности (values файл) и helm upgrade.

Аз съм Tomás Reilly, платформеният инженер в Harrow. Harrow поддържа две инсталации. Тази глава планира свързаната инсталация в нашата корпоративна мрежа, където първо направихме пилотно внедряване на Community. Оперативната мрежа на пристанището, която няма връзка с интернет, получи своя собствена инсталация по-късно; глава 2.10, Инсталация в изолирана мрежа (Air-gapped), я разглежда. Тази глава е това, което ми се искаше да имам в първата сутрин: клъстера, който Nexus очаква, имената, на които отговаря, колко ресурси изисква от вашите възли (nodes), и решенията, които трябва да уточните с вашия ИТ директор преди инсталацията. Тя завършва с работния лист, който 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 по подразбиране изчаква hook Job задачите на чарта, от които зависи инсталацията
Клас за съхранение (Storage class) Един, маркиран като такъв по подразбиране, или такъв, който посочите в storage.className Всяко хранилище за данни изисква постоянен том (persistent volume)
Ingress клас (Ingress class) Един, маркиран като такъв по подразбиране, или такъв, който посочите в ingress.className Трите публични адреса са обикновени networking.k8s.io/v1 Ingress ресурси
Портове 80 и 443 Отворени на ingress контролера, като LoadBalancer или NodePort Service Хората достигат до Nexus през ingress контролера
Архитектура linux/amd64 или linux/arm64 възли Всеки образ е компилиран и за двете архитектури

Две неща умишлено отсъстват от тази таблица. Nexus не се нуждае от service mesh: взаимният TLS (mTLS, Transport Layer Security в двете посоки) между услугите идва от локалния CA на чарта чрез cert-manager. Чартът има ключ istio.enabled, чиято стойност по подразбиране е false, и трябва да я оставите така. Nexus също така не се нуждае от собствен механизъм за политики за допускане (admission policy engine).

На вашата работна станция ще ви трябват kubectl, Helm v4, cosign v3 за проверка на подписи, age за създаване на ключове за пазители (custodian keys) и nexusctl, интерфейсът с команден ред (CLI) за оператора на Nexus. Глава 2.4, Изтегляне и проверка на издание, посочва къде се намира всеки файл за изтегляне на Nexus.

Три адреса

Всяка инсталация отговаря на три имена на хостове. Чартът ги нарича идентичност на инсталацията и всяка услуга отказва да стартира без тях.

Ключ във values Името при Harrow Какво отговаря там
hosts.console console.harrow.example Конзолата – уеб приложението, в което хората влизат
hosts.api api.harrow.example Шлюзът (gateway), който обслужва приложния програмен интерфейс (API) и маршрутизира всяка заявка за изкуствен интелект (ИИ)
hosts.auth auth.harrow.example Услугата за влизане, nexus-auth

global.domain съдържа домейна, под който се намират трите хоста, harrow.example в нашия случай. Всеки хост е пълно име само по себе си и може да се намира под всеки домейн, който контролирате. Ние запазихме и трите под един домейн, защото така един сертификат можеше да ги покрие.

Създайте запис в системата за имена на домейни (DNS) за всяко от трите имена, сочещ към адреса на вашия ingress контролер. Направете го преди предварителната проверка (preflight). nexusctl preflight търси всяко име от вашата работна станция и прекратява инсталацията с грешка, ако за някое от тях няма запис, тъй като човек не може да достигне до име, което не се преобразува в адрес.

Вляво са показани три DNS имена: console.harrow.example, api.harrow.example и auth.harrow.example, всяко със стрелка към едно каре с надпис „ingress controller, ports 80 and 443“. От това каре три стрелки водят към по-голямо каре с надпис „namespace nexus“: стрелката за console към „nexus-alpha :3000“, стрелката за api към „nexus-gateway :9092“ и стрелката за auth към „nexus-auth :9101“. Пунктирана рамка около пространството от имена носи надпис „default deny; only the ingress namespace may reach these three“.
Как трите публични имена достигат до услугите зад тях.

Избор къде приключва TLS

Ключът tls.mode на чарта определя кой държи сертификатите за трите публични адреса. Има три възможности за избор и можете да превключвате между тях по-късно чрез надграждане (upgrade).

tls.mode Вие предоставяте Какво прави чартът
existing (по подразбиране) Kubernetes TLS Secret в пространството от имена nexus, именуван в tls.existingSecret И трите Ingress ресурса използват този единствен Secret
cert-manager ClusterIssuer, който поддържате, именуван в tls.clusterIssuer Анотира всеки Ingress ресурс, така че cert-manager да издаде nexus-console-tls, nexus-api-tls и nexus-auth-tls
none Нещо пред клъстера, което терминира TLS, като например ваш собствен балансьор на натоварването (load balancer) Генерира Ingress ресурсите без TLS секция

При existing един сертификат обслужва и трите хоста, така че трябва да включва имената и на трите – или като три алтернативни имена на субекта (SAN), или като wildcard сертификат за вашия домейн. Ние използвахме сертификат от вътрешния CA на Harrow. Предварителната проверка (preflight) прочита този Secret преди инсталацията и предупреждава, ако валидността на сертификата му изтича в рамките на 30 дни.

При cert-manager и издател чрез Automatic Certificate Management Environment (ACME), чартът не добавя собствено пренасочване, така че заявка към /.well-known/acme-challenge/ на порт 80 достига до механизма за проверка (solver) непокътната. Не добавяйте пренасочване от HTTP към HTTPS във вашия ingress контролер, което се изпълнява преди пътя за проверка (challenge path); сертификат, който не може да се поднови, се проваля тихо седмици по-късно.

Каквото и да изберете за публичния край (edge), услугите вътре в пространството от имена винаги комуникират чрез TLS от локалния CA на чарта. Тази част не подлежи на избор и това е причината cert-manager да е задължително предварително условие, дори когато tls.mode е existing или none.

Какво напуска клъстера и какво не

Чартът генерира мрежова политика за отказ по подразбиране (default-deny) за пространството от имена nexus. След това са разрешени само следните потоци:

  • трафик между Nexus подовете вътре в пространството от имена;
  • DNS заявки към DNS услугата на клъстера;
  • API сървъра на Kubernetes, за няколкото услуги, които проверяват токени на работни натоварвания (workload tokens);
  • пространството от имена на ingress контролера, към трите публични услуги (Services);
  • всякакви Classless Inter-Domain Routing (CIDR) диапазони, които изброите в networkPolicy.externalEgressCIDRs.

Този последен списък е празен по подразбиране. Ако ще използвате пощенски релеен сървър (mail relay) или сървър за модели извън клъстера, неговият диапазон се задава там. Телеметрията е изключена и остава изключена: схемата приема само telemetry.enabled: false, а собственото отчитане на потреблението на хранилищата за данни също е изключено.

Чартът прочита адресите на API сървъра от клъстера по време на инсталацията. Ако вашият акаунт не може да прочете kubernetes Endpoints в пространството от имена 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 памет. Това е, което диспечерът (scheduler) резервира; лимитите (limits) са по-високи и хранилищата за данни растат до тях, докато добавяте хора и файлове.

Част Заявен CPU Заявена памет
Девет платформени услуги (конзола, бекенд за фронтенд (BFF), удостоверяване (auth), оркестратор, работни потоци, шлюз, 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:

Хранилище Ключ във values Размер по подразбиране
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) и 250 GB твърдотелен диск (SSD). За тестова оценка 4 vCPU, 16 GiB и 200 GB ще са достатъчни. Дисковият образ на инсталатора отказва машина с по-малко от 16 GiB памет (вижте глава 2.9, Дисковият образ на инсталатора) и бих третирал това като абсолютния минимум навсякъде.

Графичните възли са по избор. Без възел, който предлага графичен процесор (GPU), асистентът отговаря чрез хостван модел, използвайки собствения ключ на организацията. Предварителната проверка (preflight) отчита това като предупреждение, никога като грешка. Глава 2.14, Доставчици и модели на ИИ, обхваща и двата варианта.

Всяко хранилище може да работи и извън клъстера: задайте dataTier.<store>.mode на external и посочете неговия хост и Secret. Външен PostgreSQL се нуждае от акаунт на суперпотребител за първоначалното инициализиране (bootstrap) при инсталацията и сертификат, който 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). Предварителната проверка (preflight) сигнализира и за двете, преди да стигнете дотам.

В Harrow отделихме на това повече време, отколкото ми се иска да призная. Спряхме се на harrow-port-authority: то назовава организацията, не казва нищо за това на кой клъстер работи и ще продължи да бъде вярно, когато хардуерът бъде подменен. Избягвайте имена като prod-k3s-2, които описват днешните машини.

Съхранение на ключове

Nexus пази ключовете на всяка организация в нейно собствено хранилище за ключове, вътре в клъстера. Не го управлявате в ежедневната си работа, но преди инсталацията решавате кой може да го възстанови след рестартиране. Това е решението, което струва най-скъпо, ако го сбъркате.

Хранилището за ключове се състои от два OpenBao сървъра. Основният, openbao, държи ключовете и се разпечатва (unseals) сам чрез втори, по-малък сървър, openbao-unsealer. Механизмът за разпечатване (unsealer) е запечатан със схемата на Шамир (Shamir): пет дяла, всеки три от които го отварят. Когато инсталирате, задача (Job) за попечителство инициализира и двата сървъра вътре в клъстера. В паметта на тази задача тя криптира дяловете на механизма за разпечатване и ключовете за възстановяване на хранилището за ключове за всеки посочен от вас пазител (custodian), съхранява само шифротекста (в Secret ресурсите openbao-unseal-shares-encrypted и openbao-recovery-keys-encrypted) и отменя и двата root токена, преди да завърши. Нито един дял в открит текст никога не достига до диск или лог файл.

След всяко рестартиране на възела на механизма за разпечатване, той стартира запечатан. Хранилището за ключове го изчаква и нищо, което се нуждае от ключ, не работи, докато някой пазител не го разпечата. Това изисква едно декриптиране със собствения частен ключ на пазителя. Процедурата е описана в глава 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 (tag), age1pq1 (хибриден постквантов) и age1se1 (Secure Enclave). Тя отхвърля всяка друга форма на плъгин, като например age1yubikey1; вместо това посочете този ключ в една от приетите форми.

Чартът проверява всеки получател при генериране на шаблоните. Грешно изписан получател не преминава проверката за контролна сума bech32 и се отхвърля, така че нищо никога да не бъде запечатано с ключ, който никой не притежава. Ако някой по погрешка постави частен ключ в списъка, чартът го отхвърля, без да го извежда обратно на екрана. Примерният получател в собствените файлове със стойности на чарта също се отхвърля (KEYS_CUSTODIAN_EXAMPLE); никой не притежава неговата частна половина.

Колко пазители

Всеки дял е криптиран за всеки пазител, така че всеки един пазител може да извърши разпечатването самостоятелно. Повече пазители означават повече начини за възстановяване и повече хора, всеки от които може да действа сам. Ние избрахме трима в Harrow: Aoife, мен и ключ в 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 и прилагане на лиценз, показва как. Ние работихме с Community за пилотното внедряване в Harrow и преминахме шест седмици по-късно.

Лицензът никога не е част от този план. Той не е стойност в чарта или монтиран файл: импортирате го след инсталацията през конзолата, nexusctl или API.

Избор на форма на доставка

Форма Кога е подходяща Глава
Helm чарт от registry.adverant.ai Ваш собствен Kubernetes клъстер с маршрутизация към регистъра 2.6 и 2.7
nexusctl install Същият клъстер, като предварителната проверка и проверката на подписа се изпълняват вместо вас 2.6
nexusctl install --single-node Една машина, където nexusctl настройва и самия клъстер 2.8
Дисковият образ на инсталатора Чист физически сървър (bare server) или виртуална машина (VM), които предпочитате да не подготвяте ръчно 2.9
Офлайн пакетът Без никаква външна връзка; образите и чартът идват на диск 2.10

Чартът е един и същ във всяка форма. Това, което се променя, е кой създава клъстера и откъде идват образите.

Изтегляне на изданието
Изтегляне на изданието
Това е страницата на изданието в акаунта в Adverant. Обърнете внимание на ясното описание какво обещава едно алфа издание, размера и подписа до всеки файл и офлайн командите за проверка на изтегления файл.

Работният лист за планиране

Това е работният лист на Harrow, както Aoife го одобри и подписа. Копирайте левите две колони и попълнете дясната за вашата собствена инсталация.

Решение Ключ във values или команда Harrow Port Authority
Kubernetes и версия (предварителната проверка го прочита) k3s v1.33.6+k3s1, три възела
Kube контекст за инсталацията --context harrow-prod
Пространство от имена --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 в края на мрежата (at the edge) tls.mode, tls.existingSecret existing, Secret harrow-public-tls от вътрешния CA на Harrow
Ingress клас ingress.className traefik
Пространство от имена на Ingress networkPolicy.ingressNamespace kube-system
Клас за съхранение 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, Изтегляне и проверка на издание, и изтеглете изданието.