Log indBook en briefing

Kapitel 2.8

Installationer på én maskine

Installer Nexus på én Linux-server med nexusctl, eller evaluer det på en bærbar computer med k3d, og tilgå konsollen via HTTPS, så login og adgangsnøgler fungerer.

Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

18 minutters læsetid

Før Harrow Port Authority lagde Nexus på sit produktions-cluster, ønskede Tomás Reilly to mindre installationer. Den ene var et pilotprojekt på en ledig Linux-server i driftsbygningen til de tolv personer, der skulle afprøve det først. Den anden kørte på hans egen bærbare computer, så han kunne ødelægge ting, uden at nogen opdagede det. Dette kapitel dækker begge. De bruger samme chart, de samme images og samme første kørsel som en fuld Kubernetes-installation, så det, du lærer på én maskine, kan overføres direkte.

Server-vejen består af én kommando: nexusctl install --single-node opretter et k3s-cluster på maskinen, installerer cert-manager og installerer derefter Nexus. Laptop-vejen kræver mere manuelt arbejde. Du opretter selv et k3d-cluster, installerer cert-manager og chartet med Helm og udfører derefter en ekstra opgave, der driller næsten alle: Du lægger konsollen bag HTTPS på din egen maskine, fordi en almindelig port-forward aldrig kan logge nogen ind.

Hvor stor maskinen skal være

Nexus anmoder om ca. 2.05 CPU-kerner (central processing unit) og 6.7 GiB hukommelse i requests med chartets standardindstillinger, og dets volumes løber op i 142 GiB. Dette samlede tal udgøres af PostgreSQL 50, Valkey 5, Neo4j 20, Qdrant 10, objektlageret 50, de to OpenBao-lagre 1 og 5 samt kvitterings-volumet 1. Requests er det, som scheduleren reserverer, og det reelle forbrug er højere, når folk først arbejder i systemet.

Maskine CPU Hukommelse (RAM, random-access memory) Disk
Anbefalet til enkelt node 8 vCPU 32 GiB 250 GB SSD (solid-state drive)
Minimum til evaluering 4 vCPU 16 GiB 200 GB

En bærbar computer, der opfylder minimumskravet til evaluering, kan køre Nexus, men det er Dockers egen hukommelsesgrænse, der tæller, ikke den bærbare computers. Tildel Docker mindst 16 GiB, før du begynder.

Begge veje kræver Kubernetes 1.33 eller nyere. Enkeltnode-vejen medbringer sin egen: k3s v1.33.6+k3s1, som er den distribution, hver udgivelse testes på.

Del ét: én Linux-server med nexusctl

Tomás' pilotserver er en maskine med 8 kerner, 32 GiB hukommelse og en 500 GB SSD, der kører en opdateret Linux uden andet installeret. Installationen kræver root-adgang, fordi den installerer k3s som en systemtjeneste.

Hent nexusctl, og kontroller den

  1. Download nexusctl til din arkitektur fra https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ sammen med udgivelsens offentlige nøgle. Gem nøglen som release.pub. Kapitel 2.4, Hentning og verificering af en udgivelse, forklarer, hvordan du kontrollerer nøglens fingeraftryk mod det, som Adverant offentliggør.
  2. Kontroller den binære fil og udgivelsen med nøglen:
nexusctl version --json
nexusctl verify

nexusctl verify kontrollerer det downloadede mod Adverants udgivelsesnøgle og afviser alt, hvad den ikke kan verificere. Hvis det mislykkes, skal du stoppe og downloade igen. Kør aldrig en installation fra en fil, der ikke kunne verificeres.

Opret nøgleforvalternøglen

Installationens nøglelager forsegler sine gendannelsesnøgler til en eller flere nøgleforvaltere (custodians). En nøgleforvalter er en person, der opbevarer en age-identitetsfil offline, og chartet nægter at installere uden mindst én. På nøgleforvalterens egen maskine:

age-keygen -o custodian.key

Filen starter med en linje # public key: age1.... Denne offentlige halvdel er den, der skal ind i values-filen. Selve identitetsfilen forlader aldrig nøgleforvalterens maskine. På en Mac med Secure Enclave opretter age-plugin-se keygen --access-control=any-biometry -o custodian.key en nøgle, der kræver Touch ID for at blive brugt, og dens offentlige halvdel starter med age1se1.

Skriv values-filen

# harrow-pilot-values.yaml (Helm values)
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
keys:
  installationName: harrow-pilot
  custody:
    recipients:
      - "<custodian-age-recipient>"

<custodian-age-recipient> er age1...-linjen fra custodian.key. Tilføj ét listepunkt pr. nøgleforvalter.

keys.installationName er permanent. Ved første opstart af nøglelageret oprettes installationens identitet under dette navn, og intet kan omdøbe den bagefter. Det skal matche ^[a-z][a-z0-9-]{0,62}$: små bogstaver, startende med et bogstav og højst 63 tegn. Kopier ikke nexus-example eller eksempelmodtageren fra chartets egne eksempelfiler. Chartet afviser begge ved navn, og forhåndskontrollen (preflight) rapporterer de samme koder først.

De tre værtsnavne udgør installationens identitet. Alle tjenester nægter at starte uden dem, og ethvert login, enhver cookie og enhver adgangsnøgle (passkey) er bundet til hosts.console. Vælg navne, som du også ønsker at bruge om fem år.

Peg de tre navne mod serveren

Brugere tilgår konsollen, API'et (application programming interface) og logintjenesten gennem den indbyggede ingress-controller i k3s, Traefik, på serverens port 80 og 443. Tilføj tre DNS-poster (Domain Name System) for console.harrow.example, api.harrow.example og auth.harrow.example, der hver især peger på serverens adresse. Forhåndskontrollen kontrollerer hvert navn og fortæller dig, hvilket der mangler en post.

Chartets netværkspolitik tillader kun ét namespace at nå de tre offentlige tjenester. Dets standardværdi, kube-system, er der, hvor k3s kører Traefik, så på en enkelt node skal du lade networkPolicy.ingressNamespace være urørt.

Kør forhåndskontrol, og installer derefter

  1. Kør forhåndskontrollen med flaget for enkelt node. Den aflæser maskinen og din values-fil og ændrer intet.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml
  1. Læs opsummeringslinjen til sidst. En advarsel blokerer aldrig installationen, men det gør en fejl, og hver række, der fejler, indeholder en fix-linje.
 ────────────────────────────────────────────────────────────
 9 passed · 1 warning · 0 failed   You can install. Warnings do not block; fix them when you can.
 Report saved to preflight-2026-11-12-0902.txt · nothing was changed
  1. Installer. Flaget --edition skal stemme overens med edition i values-filen.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community
  1. Se den køre. Den kører forhåndskontrollen igen, installerer k3s v1.33.6+k3s1, installerer cert-manager v1.21.3, installerer Nexus og venter på, at hver tjeneste svarer på sit sundhedstjek. På Tomás' server tog det lidt under ti minutter.
 done   Preflight again        9 passed · 1 warning
 done   k3s v1.33.6+k3s1       node Ready
 done   cert-manager v1.21.3   ready
 done   Database and search    ready
 done   Engines                started
 done   Console                https://console.harrow.example
 Installed. 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:
 3F9A C21B 77E0 5D4C 9B12 A6F3 0E88 41D7

Behold dette fingeraftryk på skærmen. Du skal sammenligne det i browseren, når du gør krav på installationen med koden. Hvis koden udløber, før du når at bruge den, opretter nexusctl claim-code --administrator <email> en ny. Kapitel 2.12, Den første kørsel, tager over herfra.

Installer Community-udgaven
Installer Community-udgaven
Community-installationen på én server består af download, kontrol, forhåndskontrol og installation, efterfulgt af den første administrator. Der er intet licenstrin.

Læg certifikatet på plads

Med tls.mode: existing benytter de tre ingress-ruter certifikatet i den Secret, der er angivet ved tls.existingSecret. Det skal dække alle tre værtsnavne. Forhåndskontrollen læser denne Secret, når den findes, og advarer, når certifikatet udløber inden for 30 dage. Når denne Secret endnu ikke findes, giver rækken dig besked om at oprette den, og det er en advarsel, ikke en fejl.

På en enkelt node eksisterer clusteret ikke, før installationen har oprettet det, så opret denne Secret umiddelbart efter installationen. Udskriv først clusterets kubeconfig (det sidste afsnit i dette kapitel forklarer hvordan), og opret derefter din Secret med den:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus create secret tls harrow-public-tls --cert=harrow-public.crt --key=harrow-public.key

harrow-public.crt indeholder certifikatet efterfulgt af eventuelle mellemliggende certifikater, og harrow-public.key indeholder dets private nøgle. Hvis dine certifikater stammer fra en privat CA (certificate authority), tager nexusctl preflight og nexusctl install imod --ca-bundle <file>, så de kan kontrollere kæden. De andre måder at håndtere TLS (Transport Layer Security) på findes i kapitel 2.11, Variationer: eksterne lagre, TLS og ingress.

Hvis dette fejler

Hvad du ser Hvad det betyder Hvad du skal gøre
PREFLIGHT_FAILED (409) Forhåndskontrollen fandt en fejl, så installationen startede ikke. Intet blev installeret. Ret hver fejlet række ved hjælp af dens fix-linje, og kør installationen igen.
INSTALLATION_NAME_MISSING keys.installationName er tom. Angiv installationens eget permanente navn.
INSTALLATION_NAME_EXAMPLE Navnet er det, der stammer fra chartets eksempelværdier. Vælg dit eget navn.
KEYS_CUSTODIAN_MISSING keys.custody.recipients er tom. Tilføj hver nøgleforvalters offentlige age1...-modtager.
KEYS_CUSTODIAN_EXAMPLE En modtager er chartets eksempel-nøgleforvalter, hvis identitet ingen ligger inde med. Erstat den med dine nøgleforvalteres modtagere.

nexusctl afslutter med koden 0, når den kan fortsætte, 1 når en kontrol blokerede den, og 2 når den slet ikke kunne køre (en ulæselig values-fil eller et forkert flag). Et script kan forgrene sig ud fra disse tre.

Del to: en evaluering på en bærbar computer med k3d

k3d kører k3s inde i Docker-containere, så et helt cluster ligger på en bærbar computer og forsvinder med én kommando. De udgivelsesværktøjer, der tester hver Nexus-udgivelse, bygger deres clusters på nøjagtig denne måde, og ved at kopiere deres indstillinger slipper du for at genopdage de problemer, de allerede er stødt på.

Du skal bruge Docker, k3d 5.8.3, kubectl, Helm v4 og Chrome. Tomás brugte sin Mac.

Opret clusteret

k3d cluster create harrow-eval --agents 0 --wait --timeout 300s \
  --image rancher/k3s:v1.33.6-k3s1 \
  --k3s-arg "--disable=traefik@server:0"
k3d kubeconfig get harrow-eval > harrow-eval.kubeconfig
chmod 600 harrow-eval.kubeconfig
export KUBECONFIG=$PWD/harrow-eval.kubeconfig

Hvert flag har en årsag.

  • --agents 0 giver én servernode og ingen workers. Nexus kører fint på én node, og en ekstra koster blot hukommelse.
  • --image rancher/k3s:v1.33.6-k3s1 fastlåser den k3s-version, som hver udgivelse testes på. Uden dette får du den version, som k3d bruger som standard.
  • --disable=traefik@server:0 udelader Traefik. En bærbar computer har ingen offentlig adresse at betjene, og du tilgår i stedet konsollen gennem din egen HTTPS-front (nedenfor).
  • --wait --timeout 300s vender først tilbage, når clusteret svarer, eller fejler efter fem minutter.

Hvis du spejler udgivelses-registryet på din bærbare computer, skal du tilføje --registry-config <registries.yaml> for at sende image-pulls til spejlet og --k3s-arg "--disable-default-registry-endpoint@server:0", så intet falder tilbage på et upstream-registry. Udgivelsesværktøjerne kører på denne måde, hvor hvert image udelukkende kommer gennem spejlet.

Installer cert-manager

Chartet opretter sin egen lokale CA, nexus-local-ca, som en cert-manager-udsteder (issuer), og hver tjeneste får sit certifikat derfra. Uden cert-managers ressourcer i clusteret afviser helm install chartet i løbet af få sekunder. Installer først cert-manager v1.21.3 fra det chart, som cert-manager-projektet udgiver:

helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
  --create-namespace --set crds.enabled=true --wait --timeout 10m

Nexus behøver intet andet fra cert-manager og navnlig ingen trust-manager.

Installer Nexus

  1. Skriv en values-fil til den bærbare computer. TLS slutter ved din egen front, så tls.mode er none.
# harrow-eval-values.yaml (Helm values)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
tls:
  mode: none
keys:
  installationName: harrow-eval
  custody:
    recipients:
      - "<custodian-age-recipient>"
  1. Installer chartet fra registryet, og udelad --wait (advarslen nedenfor forklarer hvorfor).
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
  -n nexus --create-namespace -f harrow-eval-values.yaml --timeout 45m
  1. Vent derefter selv på dine workloads:
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
for s in $(kubectl -n nexus get sts -o name); do
  want=$(kubectl -n nexus get "$s" -o jsonpath='{.spec.replicas}')
  kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'="$want" --timeout=900s
done

StatefulSet-løkken er der, fordi nogle af dem opdaterer én pod ad gangen efter anmodning, og kubectl rollout status afviser disse. At vente på readyReplicas fungerer for enhver opdateringsstrategi.

Når begge kommandoer vender tilbage, er hvert Deployment i tilstanden Available, og hvert StatefulSet har sine pods klar. Ingen kan logge ind endnu. Det er helt korrekt: Ingen har gjort krav på installationen endnu.

Hvorfor en port-forward aldrig kan logge Dem ind

Det oplagte næste træk er kubectl port-forward svc/nexus-alpha 3000:3000 og en browser på http://127.0.0.1:3000. Konsollens sider indlæses, så det ser ud til at virke. Det gør det ikke, og ingen indstilling vil få det til at virke. Tre ting står i vejen, hver især med fuldt overlæg.

Hvad der stopper det Hvorfor
Oprindelsen (origin) Konsollens login afviser en anmodning, hvis oprindelse (origin) ikke er https://<hosts.console>, her https://console.harrow.example. En side, der leveres fra http://127.0.0.1:3000, har den forkerte oprindelse, så loginprocessen starter aldrig.
Cookien Sessionen er en __Host--cookie markeret med Secure. Browsere gemmer kun en sådan cookie over HTTPS, uden domæneattribut, for nøjagtig den vært, der satte den. Over almindelig HTTP smider browseren den væk.
Adgangsnøglen (passkey) Den første administrator logger ind med en adgangsnøgle (passkey), og en adgangsnøgle kræver en sikker kontekst med et gyldigt certifikat. Chrome nægter at oprette en adgangsnøgle bag en certifikatadvarsel, selv en du har klikket dig videre fra.

Browseren er altså nødt til at tale med https://console.harrow.example med et certifikat, den stoler på, og dette navn skal føre til din bærbare computer.

Adgang til konsollen via HTTPS på Deres bærbare computer

Metoden nedenfor bruger chartets egen CA til at udstede certifikatet, en port-forward til at nå konsollen og en separat Chrome-profil, der stoler på netop denne ene CA og knytter konsollens navn til din bærbare computer. Dit systems tillidslager (trust store) og /etc/hosts forbliver uændrede.

Diagrammet viser Chrome til venstre med teksten "separate profile: trusts nexus-local-ca only; console.harrow.example:443 mapped to 127.0.0.1:28443". En pil med teksten "HTTPS" går til en boks med teksten "HTTPS front on 127.0.0.1:28443 (certificate from nexus-local-ca)". En pil med teksten "HTTP, Host kept, X-Forwarded-Proto https" går til "kubectl port-forward 127.0.0.1:3000", og en sidste pil går ind i boksen med k3d-clusteret til "Service nexus-alpha, port http (3000)". En stiplet linje fra cert-manager inde i clusteret til frontboksen har teksten "issues the certificate".
Sådan når en browser på den bærbare computer konsollen i k3d-clusteret over HTTPS.

Udsted et certifikat til konsollens navn

  1. Bed cert-manager om et certifikat til konsolværten, signeret af chartets udsteder:
# console-front-certificate.yaml (a cert-manager Certificate)
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: nexus-console-front
  namespace: nexus
spec:
  secretName: nexus-console-front-tls
  dnsNames: [console.harrow.example]
  duration: 24h
  usages: [server auth, digital signature, key encipherment]
  privateKey: { algorithm: ECDSA, size: 256, rotationPolicy: Always }
  issuerRef: { name: nexus-local-ca, kind: Issuer, group: cert-manager.io }
kubectl apply -f console-front-certificate.yaml
kubectl -n nexus wait --for=condition=Ready certificate/nexus-console-front --timeout=120s

cert-manager signerer det inde i clusteret. Du aflæser aldrig CA'ens private nøgle.

  1. Kopier certifikatet, dets nøgle og CA-certifikatet ud af denne Secret:
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.crt}' | base64 -d > tls.crt
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.tls\.key}' | base64 -d > tls.key
kubectl -n nexus get secret nexus-console-front-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt
chmod 600 tls.key
  1. Find CA'ens pin. Chrome identificerer en betroet nøgle ved hjælp af base64 SHA-256 af dens offentlige nøgle:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64

Fastlås (pin) CA'ens nøgle, ikke certifikatets. Certifikatet varer én dag og får en ny nøgle, hver gang cert-manager fornyer det, mens CA'en forbliver den samme.

Sæt en HTTPS-front foran en port-forward

  1. Videresend konsollens Service. Dens port er den med navnet http, hvilket er 3000 i denne udgivelse:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000
  1. Kør en HTTPS-lytter på 127.0.0.1:28443, der videresender til 127.0.0.1:3000. Enhver reverse proxy, du allerede stoler på, kan bruges, så længe den gør fire ting:
    • leverer tls.crt efterfulgt af ca.crt som kæden, med tls.key;
    • beholder Host-headeren som console.harrow.example;
    • sætter X-Forwarded-Proto: https;
    • slipper WebSocket-opgraderinger igennem, fordi konsollen bruger dem.

En port-forward til en Service binder sig til den ene pod, den valgte, da den startede. Når en opgradering eller genstart udskifter konsol-pod'en, forbliver videresendelsen aktiv, men sender til ingenting, og browseren viser en bad gateway-fejl. Genstart din port-forward, hver gang konsol-pod'en skifter.

Åbn Chrome med pin og navnetilknytning

På en Mac:

open -na "Google Chrome" --args --user-data-dir="$HOME/.nexus-eval-chrome" \
  "--host-resolver-rules=MAP console.harrow.example:443 127.0.0.1:28443" \
  "--ignore-certificate-errors-spki-list=<ca-pin>" \
  https://console.harrow.example/install

<ca-pin> er outputtet fra openssl-linjen. På Linux skal du starte Chrome med de samme tre flag.

De tre flag arbejder sammen. --host-resolver-rules sender console.harrow.example på port 443 til din front, kun inden for denne profil. --ignore-certificate-errors-spki-list stoler på certifikater udstedt af netop denne ene CA-nøgle, og Chrome respekterer det kun sammen med --user-data-dir. Den separate profil holder undtagelsen adskilt fra din daglige brug af browseren. Det er ikke en generel kontakt til at "ignorere certifikatfejl": Alt, der ikke er signeret af clusterets CA, fejler stadig.

Når denne profil er åben, fører https://console.harrow.example/install til siden, hvor du gør krav på installationen, og der kan oprettes en adgangsnøgle (passkey). Kapitel 2.12, Den første kørsel, tager over herfra.

Når den bærbare computer genstarter

Nøglelageret består af to dele: selve nøglelageret og en lille unsealer, der opbevarer dets oplåsningsnøgle. Efter enhver genstart af noden (en genstart af Docker, en genstart af den bærbare computer, k3d cluster stop og start) starter unsealeren i forseglet tilstand. Nøglelageret åbner sin egen forsegling gennem den, så indtil en nøgleforvalter åbner unsealeren med sin egen age-identitet, fungerer intet, der kræver en nøgle. Det er en egenskab ved designet, og det fungerer på samme måde på et produktions-cluster. Kapitel 2.15, Dag to: drift af Nexus, viser, hvordan forseglingen åbnes.

Når du er færdig med evalueringen:

k3d cluster delete harrow-eval

Når du sletter clusteret, slettes installationen og alt i den.

nexusctl kubeconfig

Et cluster, som nexusctl install --single-node har bygget, tilhører nexusctl. For at tilgå det med kubectl, helm eller et hvilket som helst andet værktøj skal du bede om dets kubeconfig:

sudo nexusctl kubeconfig > harrow-pilot.kubeconfig
chmod 600 harrow-pilot.kubeconfig
export KUBECONFIG=$PWD/harrow-pilot.kubeconfig
kubectl -n nexus get deploy,statefulset

Filen giver fuld administratoradgang til clusteret. Opbevar den med rettighederne 600 på maskinerne tilhørende de personer, der driver installationen, og intet andet sted. Hver efterfølgende kommando i Del 2, der tager --context eller læser KUBECONFIG, fungerer mod en enkelt node gennem denne fil. Det samme gælder ved en opgradering: nexusctl upgrade plan --bundle <file> og nexusctl upgrade apply --bundle <file> på en enkelt node opgraderer også det k3s-cluster, som nexusctl ejer.

Diagrammet er en stak med fire lag på en boks med teksten "one Linux server". Nedefra: "k3s v1.33.6+k3s1 (Traefik in kube-system, ports 80 and 443)", derefter "cert-manager v1.21.3 and the chart's local CA nexus-local-ca", derefter "Nexus data tier: PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS, OpenBao", og derefter "Nexus services: console, sign-in, gateway, and the rest". Til højre forlader tre pile fra det øverste lag boksen med teksterne console.harrow.example, api.harrow.example og auth.harrow.example. Til venstre peger et terminalikon med teksten "nexusctl kubeconfig" ind i k3s-laget.
Hvad nexusctl install --single-node lægger på én Linux-server.

Hvad der følger med til en klynge

Alt, hvad du gjorde på én maskine, har et modstykke på et cluster. Values-filen er den samme fil med et andet registry, en anden TLS-tilstand eller en anden storage class, som kapitel 2.11, Variationer: eksterne lagre, TLS og ingress, viser. Den første kørsel er identisk. Det, der ikke kan overføres, er selve installationen: Installationsnavnet er låst for altid, og en installation kan ikke løftes fra en bærbar computer over på en server. Da Tomás flyttede fra sin bærbare computer til pilotserveren, startede han forfra med et nyt navn, harrow-pilot, og beholdt harrow-eval til eksperimenter.