Версия 1.0.0-alpha.1последно
Глава 2.6
Инсталиране на Community в Kubernetes
Номерирана инсталация на изданието Community с Helm – от cert-manager до готовност на всяко работно натоварване, с обяснение на файла със стойности ключ по ключ, защо няма --wait, реда, в който се изпълняват куките (hooks) на чарта, и маршрута с nexusctl install като алтернатива.
Тази страница е преведена от ИИ от английския оригинал. Ако нещо е неясно, английската страница е референтна. Прочетете тази страница на английски

Самата инсталация се свежда до една команда helm install. Всичко около нея е там, за да може тази една команда да сработи от първия път: cert-manager преди нея, файл със стойности (values), който сте прочели ред по ред, и изчакване след това, което знае какво точно да чака. В Harrow Port Authority първо инсталирахме Community за шестседмичен пилотен проект върху тривъзловия k3s клъстер от нашия работен лист за планиране. Изданието заработи за около двадесет минути и никой не можеше да влезе, докато не го заявихме за управление, както и трябва да бъде.
Тази глава предполага, че вече сте направили три неща: преминали сте през работния лист за планиране (глава 2.3, Планиране на инсталация), изтеглили сте и сте проверили изданието (глава 2.4, Изтегляне и проверка на издание) и сте изпълнили предварителната проверка (глава 2.5, Предварителна проверка с nexusctl). Ако някое от тези неща все още е незавършено, върнете се назад. Инсталацията отхвърля повечето грешки, като ги назовава по име, но някои – като попечител, чийто ключ вече сте загубили – няма как да види.
Стъпка 1: потвърдете Вашите инструменти и контекст
Проверете дали Helm е версия 4.
helm versionИнсталацията разчита на това, че Helm 4 по подразбиране изчаква задачите (Jobs) на куките (hooks) в чарта. Ние използвахме 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, без куки, които да зависят от нещо друго.Изчакайте неговия webhook, през който преминава всяка заявка за сертификат:
kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300sdeployment "cert-manager-webhook" successfully rolled out
Стъпка 3: създайте пространството от имена и TLS Secret
При tls.mode: existing чартът очаква вашия сертификат като Kubernetes Secret в пространството от имена преди инсталацията. Защитата на транспортния слой (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 е неговият частен ключ. Ако сте избрали tls.mode: cert-manager или none в глава 2.3, Планиране на инсталация, пропуснете този 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. Чартът отхвърля всяка друга комбинация, както и издание, за което неговият заключващ файл за образи не е бил създаден.
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 получатели на попечителите. Задачата (Job) за попечителство криптира всеки дял за разпечатване (unseal share) и ключ за възстановяване за всеки от тях.
Ключове, които може да ви потрябват, и ключове, които да не пипате
| Ключ | Кога да се зададе |
|---|---|
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. Първоначалната подготовка (bootstrap) на базата данни на чарта се изпълнява като кука след инсталиране (post-install hook), след като собствените ресурси на изданието вече съществуват, и именно тази кука дава на всяка услуга нейната роля и парола за базата данни. --wait би задържал инсталацията, докато всеки Deployment не стане Available, а никой Deployment не може да стане Available, преди да се е изпълнила куката, която той чака. Услугите стоят и отхвърлят влизанията си в базата данни, а Helm ги чака до изтичане на времето за изчакване (timeout). Без --wait Helm 4 все пак изчаква всяка задача (Job) на кука по ред и точно това е изчакването, което искате.
Когато последната кука приключи, Helm отпечатва своето обобщение:
NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1
STATUS: deployed означава, че всяка кука е завършила успешно. Това все още не означава, че всяка услуга обслужва заявки; стъпка 7 изчаква това.
Какво се изпълнява и в какъв ред
Helm изпълнява куките според теглото им, като започва от най-ниското, и изчаква всяка да завърши преди следващата. Всяка задача (Job) за миграция има backoffLimit: 0: неуспешна миграция проваля инсталацията и никога не се повтаря скришом. Задача, която успее, се изтрива; задача, която се провали, остава заедно със своя дневник, за да можете да го прочетете.
| Тежест | Кука (Hook) | Какво прави |
|---|---|---|
| -30 | Предварителни изисквания | Акаунтът за куки nexus-migrations, предназначеният само за куки Secret nexus-migrations-env с генерираните идентификационни данни за базата данни, както и акаунтът, ролята, конфигурацията и сертификатът на задачата за попечителство |
| -20 | nexus-db-bootstrap |
Създава базите данни и ролите, като никоя от тях не е суперпотребител и никоя не може да заобикаля сигурността на ниво ред (RLS); добавя разширенията, сред които PostGIS и pgvector; създава регистъра на изданието (release ledger) |
| -15 | nexus-openbao-custody-init |
Инициализира хранилището за ключове и неговия механизъм за разпечатване (unsealer), криптира дяловете и ключовете за възстановяване за вашите попечители, отменя и двата root токена и създава идентичността на инсталацията под 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: името на нейната верига и контролната сума (digest) на образа, който я е изпълнил. Тя записва този ред само след като нейният инструмент за миграция е приключил без грешка. Задачата за първоначална подготовка (bootstrap) отпечатва db-bootstrap: done; куките за SQL миграция отпечатват schema-ledger: recorded <chain> for this release's image като свой последен ред. Собствената кука за миграция на конзолата, nexus-alpha-bff-migrations, записва своя ред по същия начин и след това отпечатва bff-migrate: done.
Как услугите изчакват своята схема
Обектите Deployment се стартират веднага щом Helm ги създаде, докато куките все още се изпълняват. Услуга, която стартира срещу база данни без роля, без парола или без схема, би се сривала и рестартирала, докато куките не приключат. Затова всеки Deployment, който използва базата данни, съдържа инициализиращ контейнер (init container), wait-for-schema, който вместо това задържа пода.
Той чете регистъра на изданието като nexus_ledger_reader – акаунт за влизане, който може да чете само тази единствена таблица и нищо друго – и изчаква, докато регистърът не покаже неговите вериги за контролните суми на образите от това издание. Той проверява на всеки schemaWait.intervalSeconds (3 по подразбиране), отпечатва състоянието си при промяна и на всяка двадесета проверка, и се отказва след schemaWait.timeoutSeconds (1,800 по подразбиране) с грешка, която посочва името на услугата.
| Внедряване | Изчаква |
|---|---|
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 |
За да наблюдавате изчакването на една услуга в реално време, прочетете дневника на нейния инициализиращ контейнер:
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 не трябва да показва никакви задачи (Jobs) на куки: успешните са били изтрити.
Две неща си струва да направите, преди да затворите терминала. Запишете (commit) файла със стойности там, където вашият екип съхранява конфигурациите; всяко надграждане започва от него. И не пипайте обекта 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 изчаква до изтичане на времето си (timeout); 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 и прилагане на лиценз, тъй като лицензът е едно от тези шест неща.

