Versie 1.0.0-alpha.1nieuwste
Hoofdstuk 2.6
Community installeren op Kubernetes
Een genummerde installatie van de Community-editie met Helm, van cert-manager tot het gereed zijn van elke workload, met het values-bestand sleutel voor sleutel uitgelegd, waarom er geen --wait is, de volgorde waarin de hooks van de chart worden uitgevoerd, en de installatieroute met nexusctl als alternatief.
Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

De installatie zelf is één helm install. Alles eromheen is er zodat die ene opdracht de eerste keer meteen werkt: cert-manager ervoor, een values-bestand dat u regel voor regel hebt doorgelezen, en een wachttijd erna die weet waar hij op moet wachten. Bij Harrow Port Authority installeerden we eerst Community, voor een proefperiode van zes weken, op het k3s-cluster met drie nodes uit ons planningswerkblad. De release draaide in ongeveer twintig minuten, en niemand kon zich aanmelden totdat we deze hadden geclaimd, precies zoals het hoort.
Dit hoofdstuk gaat ervan uit dat u al drie dingen hebt gedaan: het planningswerkblad doorgewerkt (hoofdstuk 2.3, Een installatie plannen), de release opgehaald en gecontroleerd (hoofdstuk 2.4, Een release ophalen en verifiëren), en de preflight uitgevoerd (hoofdstuk 2.5, Preflight met nexusctl). Als een van deze stappen nog openstaat, ga dan terug. De installatie weigert de meeste fouten bij naam, maar een paar fouten, zoals een beheerder van wie u de sleutel al bent kwijtgeraakt, kan hij niet zien.
Stap 1: bevestig uw tools en context
Controleer of Helm versie 4 is.
helm versionDe installatie vertrouwt erop dat Helm 4 standaard wacht op de hook-Jobs van de chart. Wij gebruikten v4.3.1.
Laat
kubectlverwijzen naar het cluster op uw werkblad en bevestig dit.kubectl config use-context harrow-prod kubectl get nodesElke node moet
Readyaangeven. Preflight heeft dit al gecontroleerd, maar een node kan uitvallen tussen de preflight en de installatie, en het is sneller om dat hier te zien.
Stap 2: installeer eerst cert-manager
De chart maakt zijn eigen lokale certificaatautoriteit (CA) met cert-manager, en elke service communiceert met de andere via certificaten die hij uitgeeft: een zelfondertekende Issuer, een lokaal CA-certificaat voor tien jaar en kortlevende certificaten voor de services. Daarom moet cert-manager draaien vóór Nexus. De release vereist v1.21.3 en heeft geen trust-manager nodig.
Installeer cert-manager vanuit zijn eigen chart, met zijn aangepaste resources:
helm install cert-manager <cert-manager-chart> -n cert-manager --create-namespace \ --set crds.enabled=true --wait --timeout 10m<cert-manager-chart>is de cert-manager v1.21.3-chart uit de eigen release van het cert-manager-project. Wachten is hier op zijn plaats; het is de eigen installatie van cert-manager, zonder hooks die ergens anders van afhankelijk zijn.Wacht op de bijbehorende webhook, waar elke certificaataanvraag doorheen gaat:
kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300sdeployment "cert-manager-webhook" successfully rolled out
Stap 3: maak de namespace en het TLS-Secret aan
Met tls.mode: existing verwacht de chart uw certificaat vóór de installatie als een Kubernetes Secret in de namespace. Transport Layer Security (TLS) voor alle drie de adressen komt uit dit ene Secret, dus het bijbehorende certificaat moet alle drie de hosts vermelden.
kubectl create namespace nexus
kubectl -n nexus create secret tls harrow-public-tls \
--cert=harrow-public.crt --key=harrow-public.keyharrow-public.crt is het certificaat met de bijbehorende keten, en harrow-public.key is de privésleutel ervan. Als u tls.mode: cert-manager of none hebt gekozen in hoofdstuk 2.3, Een installatie plannen, slaat u het Secret over; u kunt de namespace nu al aanmaken, of dit door Helm laten doen met --create-namespace in stap 6.
Stap 4: schrijf het values-bestand
Dit is het values-bestand van Harrow voor de proefperiode. Elke sleutel erin is een sleutel die het schema van de chart accepteert; het schema weigert elke andere sleutel, zodat een verkeerd gespelde sleutel de installatie laat mislukken in plaats van stilzwijgend te worden genegeerd.
# 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>"Elke <recipient-...> is de openbare age-ontvanger van één beheerder, de age1...- of age1se1...-regel die deze naar u heeft gestuurd. Hier is elke sleutel die we hebben ingesteld, en waarom.
global.imageRegistry is het register waar uw nodes uit ophalen. De chart heeft geen standaardwaarde; hij bouwt elke image op als <this>/nexus/<service>@<digest>. Voor een verbonden installatie is dat registry.adverant.ai. Als u de images naar uw eigen register hebt gekopieerd, is het die host.
global.domain is het domein waaronder de drie adressen vallen.
hosts.console, hosts.api en hosts.auth vormen de identiteit van de installatie: de drie namen die mensen en programma's gebruiken. Elke naam moet al worden omgezet in het Domain Name System (DNS), wat door preflight is gecontroleerd.
edition en enterprise.enabled moeten overeenkomen: community met false, of enterprise met true. De chart weigert al het andere, en weigert een editie waarvoor de images-vergrendeling niet is gemaakt.
tls.mode en tls.existingSecret bepalen hoe de openbare rand zijn certificaat krijgt. Met cert-manager stelt u in plaats daarvan tls.clusterIssuer in, en met none geen van beide.
ingress.className benoemt de ingress-klasse. Laat dit oningesteld om de standaardklasse van het cluster te gebruiken.
storage.className benoemt de opslagklasse voor elk datavolume. Laat dit oningesteld om de standaardwaarde te gebruiken.
networkPolicy.ingressNamespace is de namespace waarin uw ingress-controller draait. De standaardwaarde, kube-system, is juist voor Traefik van k3s; we stellen deze toch in zodat het expliciet in het bestand staat.
networkPolicy.externalEgressCIDRs vermeldt adresbereiken, in Classless Inter-Domain Routing (CIDR)-notatie, buiten de namespace die de services mogen bereiken, naast DNS en de Kubernetes application programming interface (API)-server. Die van ons bevat het ene adres van de mailrelay; als de lijst leeg is, is er niets buiten de namespace bereikbaar.
keys.installationName is de permanente naam waaronder de sleutelopslag de installatie-identiteit aanmaakt.
keys.custody.recipients vermeldt de openbare age-ontvangers van de beheerders. De custody-Job versleutelt elk unseal-aandeel en elke herstelsleutel voor elk van hen.
Sleutels die u mogelijk nodig hebt, en sleutels waar u vanaf moet blijven
| Sleutel | Wanneer in te stellen |
|---|---|
networkPolicy.apiServerCIDRs |
Wanneer de chart de adressen van de API-server niet kan lezen uit de kubernetes-Endpoints. Geef ze op als /32-bereiken |
proxy.trustedCIDRs |
Wanneer de pods van uw ingress-controller niet op 10.42.0.0/16 van k3s staan |
ai.localProvider.baseUrl |
Wanneer de organisatie een eigen OpenAI-compatibele server voor kunstmatige intelligentie (AI)-modellen beheert (hoofdstuk 2.14, AI-aanbieders en -modellen) |
ai.installationHosts |
Wanneer die modelserver op privénamen binnen de installatie staat |
dataTier.<store>.size |
Wanneer een opslag meer nodig heeft dan het standaardvolume |
dataTier.<store>.mode |
external voor een opslag die u zelf beheert (hoofdstuk 2.11, Variaties: externe opslag, TLS en ingress) |
components.<service>.replicas, components.<service>.resources |
Wanneer u een service opschaalt |
auth.rateLimitPerMinute |
Wanneer zware automatisering meer dan 5.000 verzoeken per minuut per persoon vereist |
schemaWait.timeoutSeconds |
Wanneer de eerste migraties door een trage schijf meer dan 30 minuten duren |
Laat istio.enabled op false staan; Nexus heeft geen service mesh nodig. Laat telemetry.enabled op false staan; het schema accepteert geen andere waarde. Laat orchestrator.platformServiceUserId en probitas.flags zoals de chart ze instelt.
Inloggegevens zijn nooit een chart-waarde. Er is geen sleutel voor de API-sleutel van een modelaanbieder, een mailwachtwoord of een pull-token. De services genereren hun eigen interne geheimen bij de installatie en behouden deze bij een upgrade, en de modelsleutels van elke organisatie gaan na het eerste gebruik vanuit de console naar de eigen sleutelpool.
Stap 5: voer preflight uit op het definitieve bestand
nexusctl preflight --context harrow-prod --values harrow-values.yamlDe uitvoering moet eindigen met 0 failed. Hoofdstuk 2.5, Preflight met nexusctl, legt elke rij uit. Als u sinds de laatste uitvoering iets hebt gewijzigd, zelfs een grootte, voer deze dan opnieuw uit.
Stap 6: installeer, zonder --wait
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
--namespace nexus -f harrow-values.yaml --timeout 45mAls u de namespace niet in stap 3 hebt aangemaakt, voeg dan --create-namespace toe. Als u installeert vanuit een chart-bestand dat u hebt gedownload en gecontroleerd, zet dan het pad ernaartoe op de plaats van de oci://-verwijzing.
Voeg --wait niet toe. De database-bootstrap van de chart draait als een post-install hook, nadat de eigen resources van de release bestaan, en het is die hook die elke service zijn databaserol en wachtwoord geeft. --wait zou de installatie vasthouden totdat elke Deployment Available is, en geen enkele Deployment kan Available worden voordat de hook waarop deze wacht, is uitgevoerd. De services blijven hun database-aanmeldingen weigeren en Helm wacht op ze tot de time-out. Zonder --wait wacht Helm 4 nog steeds op elke hook-Job, op volgorde, en dat is het wachten dat u wilt.
Wanneer de laatste hook is voltooid, drukt Helm zijn samenvatting af:
NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1
STATUS: deployed betekent dat elke hook is geslaagd. Het betekent nog niet dat elke service actief is; stap 7 wacht daarop.
Wat er draait, en in welke volgorde
Helm voert de hooks uit op gewicht, het laagste eerst, en wacht op elke hook voordat de volgende start. Elke migratie-Job heeft backoffLimit: 0: een mislukte migratie laat de installatie mislukken en wordt nooit achter uw rug om opnieuw geprobeerd. Een Job die slaagt, wordt verwijderd; een Job die mislukt, blijft staan met zijn logboek, zodat u het kunt lezen.
| Gewicht | Hook | Wat deze doet |
|---|---|---|
| -30 | Vereisten | Het hook-account nexus-migrations, het uitsluitend voor hooks bestemde Secret nexus-migrations-env met de gegenereerde database-inloggegevens, en het account, de rol, de configuratie en het certificaat van de custody-Job |
| -20 | nexus-db-bootstrap |
Maakt de databases en rollen aan, waarvan geen enkele een superuser is en geen enkele in staat is om row-level security (RLS) te omzeilen; voegt de extensies toe, waaronder PostGIS en pgvector; maakt het release-grootboek aan |
| -15 | nexus-openbao-custody-init |
Initialiseert de sleutelopslag en de bijbehorende unsealer, versleutelt de aandelen en herstelsleutels voor uw beheerders, trekt beide root-tokens in en maakt de installatie-identiteit aan onder keys.installationName |
| -12 | nexus-graphrag-migrations |
Legt eerst het schema van de graph-service vast, omdat het schema van de aanmeldservice verwijst naar objecten waarvan deze eigenaar is |
| -10 | nexus-auth-migrations |
Legt het schema van de aanmeldservice en de twee bijbehorende runtime-rollen vast |
| -5 | nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations |
Het eigen schema van elke service; probitas draait na auth omdat het eerst de tabellen van auth controleert |
| 0 | nexus-alpha-bff-migrations |
Richt de backend for frontend (BFF)-database en de bijbehorende rollen in en past vervolgens de migraties ervan toe |
Elke migratie-hook eindigt met het schrijven van één rij in het release-grootboek, nexus_release.schema_applied: de naam van de keten en de digest van de image die deze heeft uitgevoerd. Hij schrijft die rij pas nadat de migratie-runner zonder fouten is voltooid. De bootstrap-Job drukt db-bootstrap: done af; de SQL-migratie-hooks drukken schema-ledger: recorded <chain> for this release's image af als hun laatste regel. De eigen migratie-hook van de console, nexus-alpha-bff-migrations, legt zijn rij op dezelfde manier vast en drukt vervolgens bff-migrate: done af.
Hoe de services wachten op hun schema
De Deployments starten zodra Helm ze aanmaakt, terwijl de hooks nog draaien. Een service die zou starten tegen een database zonder rol, zonder wachtwoord of zonder schema, zou crashen en herstarten totdat de hooks klaar zijn. Daarom bevat elke Deployment die de database gebruikt een init-container, wait-for-schema, die de pod in plaats daarvan tegenhoudt.
Deze leest het release-grootboek als nexus_ledger_reader, een login die alleen die ene tabel kan lezen en niets anders, en wacht totdat het grootboek zijn ketens voor de image-digests van deze release toont. Hij peilt elke schemaWait.intervalSeconds (standaard 3), drukt zijn status af wanneer deze verandert en bij elke twintigste peiling, en geeft het op na schemaWait.timeoutSeconds (standaard 1.800) met een foutmelding die de service bij naam noemt.
| Implementatie | Wacht op |
|---|---|
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 |
Om het wachten van één service live te volgen, leest u het logboek van de bijbehorende init-container:
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
Omdat het wachten is gekoppeld aan de image-digest en niet aan een aantal bestanden, wachten de pods van een latere upgrade op de rijen van de nieuwe release, en vindt een pod die herstart na een wijziging van alleen de values zijn rij onmiddellijk.
Stap 7: wacht op elke workload
Wacht op de Deployments, met een tijdslimiet:
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
Vervolgens de StatefulSets. De twee servers voor sleutelopslag worden alleen bijgewerkt wanneer u hun pods verwijdert, en kubectl rollout status weigert die updatestrategie, dus wacht in plaats daarvan op het aantal dat gereed is:
for s in $(kubectl -n nexus get statefulset -o name); do
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'=1 --timeout=900s
doneElke opdracht drukt condition met af. Op ons cluster duurden beide wachttijden samen minder dan vijf minuten nadat Helm klaar was.
Hoe gereed eruitziet
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
Tien Deployments en zeven StatefulSets, allemaal gereed. Daarnaast vindt u drie CronJobs, nexus-keys-rotate-epoch, nexus-keys-run-schedule en nexus-keys-export-receipts, het nachtelijke onderhoud van de sleutelservice. kubectl -n nexus get jobs zou geen hook-Jobs moeten tonen: de geslaagde zijn verwijderd.
Twee dingen zijn de moeite waard voordat u de terminal verlaat. Leg het values-bestand vast op de plek waar uw team configuraties bewaart; elke upgrade begint hiermee. En blijf af van het Secret nexus-generated. De chart genereert de interne wachtwoorden en sleutels één keer, bij de installatie, bewaart ze daar en leest ze bij elke upgrade weer in, dus als u het verwijdert, kunnen de services niet meer bij hun eigen gegevens.
Gereed betekent dat het platform draait en nog niet is geclaimd. Open https://console.harrow.example en u komt bij het installatieprogramma, niet bij een aanmeldpagina: niemand kan zich aanmelden totdat iemand de installatie claimt. Dat is het eerste gebruik, in hoofdstuk 2.12, Het eerste gebruik.
Als dit mislukt
De meeste fouten noemen zichzelf bij naam. Lees de melding voordat u iets wijzigt.
| Wat u ziet | Oorzaak | Wat te doen |
|---|---|---|
INSTALLATION_NAME_MISSING of INSTALLATION_NAME_EXAMPLE |
keys.installationName is leeg of bevat de voorbeeldwaarde |
Stel uw eigen permanente naam in |
KEYS_CUSTODIAN_MISSING of KEYS_CUSTODIAN_EXAMPLE |
Geen beheerders, of de voorbeeldbeheerder | Stel de eigen ontvangers van uw beheerders in |
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ |
Hoofdletters, punten of een cijfer aan het begin | Gebruik kleine letters, cijfers en koppeltekens, beginnend met een letter |
keys.custody.recipients: ... en een reden |
Een ontvanger bevat een typfout, is een privésleutel, of heeft een vorm waarnaar de custody-Job niet kan versleutelen | Vraag de beheerder opnieuw om zijn ontvanger |
hosts.console is required (the installation identity) |
Een host is niet ingesteld | Stel alle drie de hosts in |
tls.existingSecret is required when tls.mode is existing |
Geen Secret opgegeven | Stel het in, of wijzig tls.mode |
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read |
Uw account kan de adressen van de API-server niet lezen | Geef ze op als /32-bereiken |
global.imageRegistry is required |
Het register is niet ingesteld | Stel het in |
Helm wacht tot zijn time-out; nexus-auth logt password authentication failed |
--wait is meegegeven |
Verwijder de installatie en installeer opnieuw zonder --wait |
Error: ... job failed met de naam van een hook |
Een migratie is mislukt | kubectl -n nexus logs job/<hook-name> en lees de laatste regels |
Een pod blijft hangen in Init |
De bijbehorende wait-for-schema wacht nog steeds |
Lees het logboek ervan: het noemt de keten die ontbreekt |
wait-for-schema: FAILED |
De hook van de keten heeft zijn rij nooit geschreven | Zoek eerst de fout van die hook |
ImagePullBackOff |
De node kan niet ophalen uit global.imageRegistry |
Controleer of de node het register kan bereiken en, voor Enterprise, over het pull-token beschikt |
Elke hook die wacht op PostgreSQL wacht een begrensde tijd en meldt dat ook, waiting for postgres (12/60), zodat een vastgelopen database binnen een minuut zichtbaar is in het logboek van de hook.
De installatieroute met nexusctl
nexusctl install voert dezelfde installatie uit, waarbij de controles eromheen voor u worden uitgevoerd. Het gebruikt hetzelfde values-bestand:
nexusctl install --context harrow-prod --values harrow-values.yamlHet voert preflight opnieuw uit en stopt als een controle inmiddels mislukt. Het verifieert de handtekening van de chart-bundel aan de hand van de releasesleutel. Daarna installeert het, wacht het de hooks en de workloads af, en drukt het elke stap af met de tijd die het kostte. --edition community vermeldt de editie zowel op de opdrachtregel als in het bestand. --ca-bundle <file> voegt uw eigen CA-certificaten toe, net als bij preflight. Om de helm- en kubectl-bewerkingen te zien die het zou uitvoeren, zonder ze daadwerkelijk uit te voeren, voegt u --explain toe:
nexusctl install --context harrow-prod --values harrow-values.yaml --explainWanneer het klaar is, drukt het het claimadres, een eenmalige claimcode en de vingerafdruk van de installatie af:
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>
De code bestaat uit drie groepen en staat vijf pogingen toe; de vingerafdruk bestaat uit acht groepen van vier tekens, en de browser toont dezelfde acht groepen zodat u deze kunt vergelijken voordat u claimt.
Overdracht naar de eerste ingebruikname
Als u met Helm hebt geïnstalleerd, maakt u de claimcode zelf aan, waarbij u de persoon opgeeft die de eerste beheerder wordt:
nexusctl claim-code --administrator aoife.brennan@harrow.exampleHet voert de eigen claimcode-opdracht van de sleutelservice uit in de nexus-keys-pod met uw clustertoegang, en drukt het adres, de code en de vingerafdruk af zoals hierboven. De code werkt gedurende 30 minuten; voer de opdracht opnieuw uit voor een nieuwe code.
Vanaf hier neemt de browser het over: claim de installatie, maak de eerste beheerder aan met een passkey en doorloop de zes punten voordat iemand zich aanmeldt. Dat is hoofdstuk 2.12, Het eerste gebruik. Als u meteen een licentie voor Enterprise wilt activeren, lees dan eerst hoofdstuk 2.7, Enterprise installeren en een licentie toepassen, want de licentie is een van die zes punten.

