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

Глава 2.6

Инсталиране на Community в Kubernetes

Номерирана инсталация на изданието Community с Helm – от cert-manager до готовност на всяко работно натоварване, с обяснение на файла със стойности ключ по ключ, защо няма --wait, реда, в който се изпълняват куките (hooks) на чарта, и маршрута с nexusctl install като алтернатива.

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

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

Самата инсталация се свежда до една команда helm install. Всичко около нея е там, за да може тази една команда да сработи от първия път: cert-manager преди нея, файл със стойности (values), който сте прочели ред по ред, и изчакване след това, което знае какво точно да чака. В Harrow Port Authority първо инсталирахме Community за шестседмичен пилотен проект върху тривъзловия k3s клъстер от нашия работен лист за планиране. Изданието заработи за около двадесет минути и никой не можеше да влезе, докато не го заявихме за управление, както и трябва да бъде.

Тази глава предполага, че вече сте направили три неща: преминали сте през работния лист за планиране (глава 2.3, Планиране на инсталация), изтеглили сте и сте проверили изданието (глава 2.4, Изтегляне и проверка на издание) и сте изпълнили предварителната проверка (глава 2.5, Предварителна проверка с nexusctl). Ако някое от тези неща все още е незавършено, върнете се назад. Инсталацията отхвърля повечето грешки, като ги назовава по име, но някои – като попечител, чийто ключ вече сте загубили – няма как да види.

Стъпка 1: потвърдете Вашите инструменти и контекст

  1. Проверете дали Helm е версия 4.

    helm version

    Инсталацията разчита на това, че Helm 4 по подразбиране изчаква задачите (Jobs) на куките (hooks) в чарта. Ние използвахме v4.3.1.

  2. Насочете 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.

  1. Инсталирайте 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, без куки, които да зависят от нещо друго.

  2. Изчакайте неговия webhook, през който преминава всяка заявка за сертификат:

    kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300s
    deployment "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.key

harrow-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.

Хоризонтална времева линия, вървяща отляво надясно, означена с "helm install". На горната лента има седем полета за куки по ред: "-30 prerequisites", "-20 db-bootstrap", "-15 custody init", "-12 graphrag migrations", "-10 auth migrations", "-5 orchestrator, gateway, probitas migrations", "0 BFF migrations". Всяко поле за миграция има малка стрелка надолу към цилиндър на средната лента, означен с "release ledger: nexus_release.schema_applied". На долната лента има дълга лента, започваща отляво, означена с "Deployments start, wait-for-schema holds each pod"; къси вертикални стрелки се издигат от нея към регистъра, а лентата на всеки Deployment става плътна, когато се появи неговият собствен ред в регистъра.
Редът на чиста инсталация, с куките и работните натоварвания едни до други.

Как услугите изчакват своята схема

Обектите 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-schema
wait-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=900s
deployment.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,statefulset
NAME                                  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, Първото стартиране.

Тази инсталация (Community)
Тази инсталация (Community)
Собствената страница на инсталация Community, след като бъде заявена: работещата версия, състоянието на ядрото, използването на диска, резервните копия и обещанието за корекции по сигурността, като частите за Enterprise са показани като предварителен преглед, посочващ кой може да ги активира.

Ако това не успее

Повечето грешки сами посочват причината си. Прочетете съобщението, преди да променяте каквото и да било.

Какво виждате Причина Какво да предприемете
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 и прилагане на лиценз, тъй като лицензът е едно от тези шест неща.