Logga inBoka en genomgång

Kapitel 2.8

Installationer på en enskild maskin

Installera Nexus på en Linux-server med nexusctl, eller utvärdera det på en bärbar dator med k3d, och nå konsolen via HTTPS så att inloggning och nycklar (passkeys) fungerar.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

18 minuters läsning

Innan Harrow Port Authority lade Nexus på sitt produktionskluster ville Tomás Reilly ha två mindre installationer. Den ena var en pilot på en ledig Linux-server i driftbyggnaden, för de tolv personer som skulle prova det först. Den andra kördes på hans egen bärbara dator, så att han kunde ta sönder saker utan att någon märkte det. Det här kapitlet behandlar båda. De använder samma chart, samma avbildningar och samma första körning som en fullständig Kubernetes-installation, så det ni lär er på en maskin kan ni ta med er vidare.

Servervägen är ett enda kommando: nexusctl install --single-node bygger ett k3s-kluster på maskinen, installerar cert-manager och installerar sedan Nexus. Vägen för bärbar dator kräver mer handpåläggning. Ni bygger ett k3d-kluster själva, installerar cert-manager och charten med Helm, och utför sedan ett extra moment som nästan alla fastnar på: ni sätter konsolen bakom HTTPS på er egen maskin, eftersom en enkel portvidarebefordran aldrig kan logga in någon.

Hur stor maskinen måste vara

Nexus begär omkring 2.05 CPU-kärnor (central processing unit) och 6.7 GiB minne med chartens standardvärden, och dess volymer uppgår till totalt 142 GiB. Den summan består av PostgreSQL 50, Valkey 5, Neo4j 20, Qdrant 10, objektlagringen 50, de två OpenBao-lagren 1 och 5 samt kvittovolymen 1. Begärda resurser (requests) är vad schemaläggaren reserverar, och den faktiska förbrukningen blir högre när användarna väl börjar arbeta.

Maskin CPU Minne (RAM, random-access memory) Disk
Rekommenderad enskild nod 8 vCPU 32 GiB 250 GB SSD (solid-state drive)
Minimum för utvärdering 4 vCPU 16 GiB 200 GB

En bärbar dator som uppfyller minimikraven för utvärdering kan köra Nexus, men det är Dockers egen minnesgräns som räknas, inte datorns. Ge Docker minst 16 GiB innan ni börjar.

Båda vägarna kräver Kubernetes 1.33 eller senare. Vägen för en enskild nod har med sig sin egen: k3s v1.33.6+k3s1, den distribution som varje utgåva testas på.

Del ett: en Linux-server med nexusctl

Tomás pilotserver är en maskin med 8 kärnor, 32 GiB minne och en 500 GB SSD, som kör en aktuell Linux-version utan något annat installerat. Installationen kräver root-behörighet, eftersom den installerar k3s som en systemtjänst.

Hämta nexusctl och kontrollera den

  1. Ladda ner nexusctl för er arkitektur från https://downloads.adverant.ai/nexus/1.0.0-alpha.1/, tillsammans med utgåvans publika nyckel. Spara nyckeln som release.pub. Kapitel 2.4, Hämta och verifiera en utgåva, förklarar hur ni kontrollerar nyckelns fingeravtryck mot det som Adverant publicerar.
  2. Kontrollera binärfilen och utgåvan med nyckeln:
nexusctl version --json
nexusctl verify

nexusctl verify kontrollerar nedladdningen mot Adverants utgivningsnyckel och avvisar allt som inte kan verifieras. Om det misslyckas, avbryt och ladda ner på nytt. Kör aldrig en installation från en fil som inte har verifierats.

Skapa förvaltarnyckeln

Installationens nyckellager förseglar sina återställningsnycklar till en eller flera nyckelförvaltare (custodians). En nyckelförvaltare är en person som förvarar en age-identitetsfil offline, och charten vägrar att installera utan minst en sådan. På nyckelförvaltarens egen maskin:

age-keygen -o custodian.key

Filen börjar med en rad # public key: age1.... Den publika halvan är vad som ska läggas in i värdefilen. Själva identitetsfilen lämnar aldrig nyckelförvaltarens maskin. På en Mac med Secure Enclave skapar age-plugin-se keygen --access-control=any-biometry -o custodian.key en nyckel som kräver Touch ID för att användas, och dess publika halva börjar med age1se1.

Skriv värdefilen

# 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> är age1...-raden från custodian.key. Lägg till en listpost per nyckelförvaltare.

keys.installationName är permanent. Vid den första starten av nyckellagret skapas installationens identitet under det namnet, och ingenting kan byta namn på den i efterhand. Det måste matcha ^[a-z][a-z0-9-]{0,62}$: gemener, börja med en bokstav, högst 63 tecken. Kopiera inte nexus-example eller exempelmottagaren från chartens egna exempelfiler. Charten avvisar båda vid namn, och förkontrollen (preflight) rapporterar samma koder först.

De tre värdnamnen utgör installationens identitet. Varje tjänst vägrar att starta utan dem, och varje inloggning, kaka (cookie) och lösenordsnyckel (passkey) är bunden till hosts.console. Välj namn som ni fortfarande kommer att vilja ha om fem år.

Peka de tre namnen mot servern

Användare når konsolen, API:et (application programming interface) och inloggningstjänsten genom den inbyggda ingress-controllern i k3s, Traefik, på portarna 80 och 443 på servern. Lägg till tre DNS-poster (Domain Name System) för console.harrow.example, api.harrow.example och auth.harrow.example, som var och en pekar på serverns adress. Förkontrollen kontrollerar varje namn och talar om för er vilket som saknar post.

Chartens nätverkspolicy tillåter endast en namnrymd att nå de tre publika tjänsterna. Dess standardvärde, kube-system, är där k3s kör Traefik, så på en enskild nod lämnar ni networkPolicy.ingressNamespace orörd.

Kör förkontrollen och installera sedan

  1. Kör förkontrollen med flaggan för enskild nod. Den läser av maskinen och er värdefil och ändrar ingenting.
sudo nexusctl preflight --single-node --values harrow-pilot-values.yaml
  1. Läs sammanfattningsraden på slutet. En varning blockerar aldrig installationen, men det gör ett fel, och varje rad som underkänns innehåller en fix-rad.
 ────────────────────────────────────────────────────────────
 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. Installera. Flaggan --edition måste stämma överens med edition i värdefilen.
sudo nexusctl install --single-node --values harrow-pilot-values.yaml --edition community
  1. Följ körningen. Den kör förkontrollen igen, installerar k3s v1.33.6+k3s1, installerar cert-manager v1.21.3, installerar Nexus och väntar på att varje tjänst ska svara på sin hälsokontroll. På Tomás server tog det strax under tio minuter.
 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

Behåll det fingeravtrycket på skärmen. Ni kommer att jämföra det i webbläsaren när ni gör anspråk på installationen med koden. Om koden hinner gå ut innan ni använder den skapar nexusctl claim-code --administrator <email> en ny. Kapitel 2.12, Den första körningen, tar vid därifrån.

Installera Community-utgåvan
Installera Community-utgåvan
Community-installationen på en server består av nedladdning, kontroll, förkontroll och installation, och därefter den första administratören. Det finns inget licenssteg.

Lägg certifikatet på plats

Med tls.mode: existing presenterar de tre ingress-rutterna certifikatet i den Secret som anges av tls.existingSecret. Det måste täcka alla tre värdnamnen. Förkontrollen läser denna Secret när den finns och varnar när certifikatet löper ut inom 30 dagar. När denna Secret inte finns där ännu uppmanar raden er att skapa den, och det är en varning, inte ett fel.

På en enskild nod existerar inte klustret förrän installationen har skapat det, så skapa denna Secret direkt efter installationen. Skriv först ut klustrets kubeconfig (det sista avsnittet i det här kapitlet förklarar hur), och skapa sedan er Secret med hjälp av 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 innehåller certifikatet följt av eventuella mellanliggande certifikat, och harrow-public.key dess privata nyckel. Om era certifikat kommer från en privat CA (certificate authority) tar nexusctl preflight och nexusctl install emot --ca-bundle <file> så att de kan kontrollera kedjan. De andra sätten att hantera TLS (Transport Layer Security) finns i kapitel 2.11, Variationer: externa lager, TLS och ingress.

Om detta misslyckas

Vad ni ser Vad det innebär Vad du ska göra
PREFLIGHT_FAILED (409) Förkontrollen hittade ett fel, så installationen startade inte. Ingenting installerades. Åtgärda varje rad som underkänts med hjälp av dess fix-rad, och kör installationen igen.
INSTALLATION_NAME_MISSING keys.installationName är tom. Ange installationens eget permanenta namn.
INSTALLATION_NAME_EXAMPLE Namnet är det som kommer från chartens exempelvärden. Välj ert eget namn.
KEYS_CUSTODIAN_MISSING keys.custody.recipients är tom. Lägg till varje nyckelförvaltares publika age1...-mottagare.
KEYS_CUSTODIAN_EXAMPLE En mottagare är chartens exempelnyckelförvaltare, vars identitet ingen innehar. Ersätt den med era nyckelförvaltares mottagare.

nexusctl avslutas med 0 när den kan gå vidare, 1 när en kontroll blockerade den, och 2 när den inte kunde köras alls (en oläsbar värdefil, en felaktig flagga). Ett skript kan förgrena sig baserat på dessa tre.

Del två: en utvärdering på en bärbar dator med k3d

k3d kör k3s inuti Docker-containrar, så ett helt kluster ryms på en bärbar dator och försvinner med ett enda kommando. Utgivningsverktygen som testar varje Nexus-utgåva bygger sina kluster på exakt det här sättet, och genom att kopiera deras inställningar slipper ni återupptäcka de problem som de redan har stött på.

Ni behöver Docker, k3d 5.8.3, kubectl, Helm v4 och Chrome. Tomás använde sin Mac.

Skapa klustret

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

Varje flagga har ett syfte.

  • --agents 0 ger en servernod och inga arbetarnoder (workers). Nexus körs utmärkt på en nod, och en andra nod kostar bara minne.
  • --image rancher/k3s:v1.33.6-k3s1 låser den k3s-version som varje utgåva testas på. Utan den får ni vad k3d än har som standard.
  • --disable=traefik@server:0 utelämnar Traefik. En bärbar dator har ingen publik adress att betjäna, och ni når konsolen genom er egen HTTPS-front i stället (se nedan).
  • --wait --timeout 300s returnerar först när klustret svarar, eller avbryter med fel efter fem minuter.

Om ni speglar utgivningsregistret på er bärbara dator, lägg till --registry-config <registries.yaml> för att skicka hämtningar av avbildningar till spegeln, och --k3s-arg "--disable-default-registry-endpoint@server:0" så att ingenting faller tillbaka på ett uppströmsregister. Utgivningsverktygen körs på det här sättet, där varje avbildning enbart kommer via spegeln.

Installera cert-manager

Charten skapar sin egen lokala CA, nexus-local-ca, som en cert-manager-utfärdare (issuer), och varje tjänst får sitt certifikat från den. Utan resurserna från cert-manager i klustret avvisar helm install charten inom några sekunder. Installera cert-manager v1.21.3 först, från den chart som cert-manager-projektet publicerar:

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 ingenting annat från cert-manager, och i synnerhet ingen trust-manager.

Installera Nexus

  1. Skriv en värdefil för den bärbara datorn. TLS avslutas vid er egen front, så tls.mode är 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. Installera charten från registret och utelämna --wait (varningen nedan förklarar varför).
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. Vänta sedan in arbetslasterna på egen hand:
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-loopen finns där eftersom vissa av dem uppdaterar en podd i taget på begäran, och kubectl rollout status avvisar dessa. Att vänta på readyReplicas fungerar för alla uppdateringsstrategier.

När båda kommandona returnerar är varje Deployment tillgänglig (Available) och varje StatefulSet har sina poddar redo. Ingen kan logga in ännu. Det är helt i sin ordning: ingen har gjort anspråk på installationen ännu.

Varför en portvidarebefordran aldrig kan logga in er

Det uppenbara nästa steget är kubectl port-forward svc/nexus-alpha 3000:3000 och en webbläsare på http://127.0.0.1:3000. Konsolens sidor laddas, så det ser ut att fungera. Det gör det inte, och ingen inställning kommer att få det att fungera. Tre saker står i vägen, var och en helt avsiktligt.

Vad som stoppar det Varför
Ursprunget (origin) Konsolens inloggning avvisar en begäran vars ursprung (origin) inte är https://<hosts.console>, i det här fallet https://console.harrow.example. En sida som levereras från http://127.0.0.1:3000 har fel ursprung, så inloggningen startar aldrig.
Kakan (cookie) Sessionen är en __Host--kaka markerad som Secure. Webbläsare lagrar en sådan kaka endast över HTTPS, utan domänattribut, för exakt den värd som satte den. Över vanlig HTTP kastar webbläsaren bort den.
Lösenordsnyckeln (passkey) Den första administratören loggar in med en lösenordsnyckel (passkey), och en lösenordsnyckel kräver en säker kontext med ett giltigt certifikat. Chrome vägrar att skapa en lösenordsnyckel bakom en certifikatvarning, även om ni har klickat er förbi den.

Webbläsaren måste alltså tala med https://console.harrow.example, med ett certifikat som den litar på, och det namnet måste leda till er bärbara dator.

Nå konsolen via HTTPS på er bärbara dator

Metoden nedan använder chartens egen CA för att utfärda certifikatet, en portvidarebefordran för att nå konsolen, samt en separat Chrome-profil som litar på just denna CA och mappar konsolens namn till er bärbara dator. Ert systems certifikatförråd och /etc/hosts förblir oförändrade.

Diagrammet visar Chrome till vänster, märkt ”separate profile: trusts nexus-local-ca only; console.harrow.example:443 mapped to 127.0.0.1:28443”. En pil märkt ”HTTPS” går till en ruta ”HTTPS front on 127.0.0.1:28443 (certificate from nexus-local-ca)”. En pil märkt ”HTTP, Host kept, X-Forwarded-Proto https” går till ”kubectl port-forward 127.0.0.1:3000”, och en sista pil går in i k3d-klusterrutan till ”Service nexus-alpha, port http (3000)”. En streckad linje från cert-manager inuti klustret till frontrutan är märkt ”issues the certificate”.
Hur en webbläsare på den bärbara datorn når konsolen i k3d-klustret över HTTPS.

Utfärda ett certifikat för konsolens namn

  1. Be cert-manager om ett certifikat för konsolvärden, signerat av chartens utfärdare:
# 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 signerar det inuti klustret. Ni läser aldrig den privata nyckeln för CA.

  1. Kopiera ut certifikatet, dess nyckel och CA-certifikatet ur denna 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. Ta fram CA-nyckelns pin-värde. Chrome identifierar en betrodd nyckel genom base64 SHA-256 av dess publika nyckel:
openssl x509 -in ca.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64

Lås (pinna) CA-nyckeln, inte certifikatets nyckel. Certifikatet gäller i ett dygn och får en ny nyckel varje gång cert-manager förnyar det, medan CA förblir densamma.

Sätt en HTTPS-front framför en portvidarebefordran

  1. Vidarebefordra konsolens Service. Dess port är den som heter http, vilket är 3000 i den här utgåvan:
kubectl -n nexus port-forward svc/nexus-alpha 3000:3000
  1. Kör en HTTPS-lyssnare på 127.0.0.1:28443 som vidarebefordrar till 127.0.0.1:3000. Vilken omvänd proxy som helst som ni redan litar på duger, så länge den gör fyra saker:
    • presenterar tls.crt följt av ca.crt som kedja, med tls.key;
    • behåller huvudet (headern) Host som console.harrow.example;
    • sätter X-Forwarded-Proto: https;
    • släpper igenom WebSocket-uppgraderingar, eftersom konsolen använder dem.

En portvidarebefordran till en Service binder till den enskilda podd som den valde när den startade. Efter att en uppgradering eller en omstart har ersatt konsolpodden ligger vidarebefordran kvar men leder ingenstans, och webbläsaren visar ”bad gateway”. Starta om portvidarebefordran varje gång konsolpodden byts ut.

Öppna Chrome med pin-värdet och namnmappningen

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> är utskriften från openssl-raden. På Linux startar ni Chrome med samma tre flaggor.

De tre flaggorna samverkar. --host-resolver-rules skickar console.harrow.example på port 443 till er front, enbart inuti den här profilen. --ignore-certificate-errors-spki-list litar på certifikat som utfärdats av just denna CA-nyckel, och Chrome respekterar den endast tillsammans med --user-data-dir. Den separata profilen håller undantaget borta från ert dagliga surfande. Det är inte en generell växel som ignorerar alla certifikatfel: allt som inte är signerat av klustrets CA avvisas fortfarande.

Med den profilen öppen leder https://console.harrow.example/install till sidan för att göra anspråk på installationen, och en lösenordsnyckel kan skapas. Kapitel 2.12, Den första körningen, tar vid härifrån.

När den bärbara datorn startar om

Nyckellagret består av två delar: själva nyckellagret och en liten upplåsare (unsealer) som håller dess upplåsningsnyckel. Efter varje omstart av noden (en omstart av Docker, en omstart av datorn, k3d cluster stop och start) startar upplåsaren i förseglat läge. Nyckellagret låser upp sig självt genom den, så tills en nyckelförvaltare låser upp upplåsaren med sin egen age-identitet fungerar ingenting som behöver en nyckel. Det är en egenskap i själva konstruktionen, och det fungerar likadant på ett produktionskluster. Kapitel 2.15, Dag två: drift av Nexus, visar hur upplåsningen går till.

När ni är klara med utvärderingen:

k3d cluster delete harrow-eval

Att ta bort klustret tar bort installationen och allt i den.

nexusctl kubeconfig

Ett kluster som nexusctl install --single-node har byggt tillhör nexusctl. För att nå det med kubectl, helm eller något annat verktyg, begär ut dess 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 ger fullständig administrativ åtkomst till klustret. Håll den i läge (mode) 600, på maskinerna som tillhör de personer som sköter installationen, och ingen annanstans. Varje senare kommando i Del 2 som tar --context eller läser KUBECONFIG fungerar mot en enskild nod genom den här filen. Detsamma gäller vid en uppgradering: nexusctl upgrade plan --bundle <file> och nexusctl upgrade apply --bundle <file> på en enskild nod uppgraderar även det k3s-kluster som nexusctl äger.

Diagrammet är en stapel med fyra lager på en ruta märkt ”one Linux server”. Nedifrån: ”k3s v1.33.6+k3s1 (Traefik in kube-system, ports 80 and 443)”, sedan ”cert-manager v1.21.3 and the chart's local CA nexus-local-ca”, sedan ”Nexus data tier: PostgreSQL, Valkey, Neo4j, Qdrant, SeaweedFS, OpenBao”, och sedan ”Nexus services: console, sign-in, gateway, and the rest”. Till höger lämnar tre pilar från det översta lagret rutan, märkta console.harrow.example, api.harrow.example och auth.harrow.example. Till vänster pekar en terminalikon märkt ”nexusctl kubeconfig” in i k3s-lagret.
Vad nexusctl install --single-node lägger på en Linux-server.

Vad som följer med till ett kluster

Allt ni har gjort på en enskild maskin har en motsvarighet i ett kluster. Värdefilen är samma fil med ett annat register, TLS-läge eller lagringsklass (storage class), så som kapitel 2.11, Variationer: externa lager, TLS och ingress, visar. Den första körningen är identisk. Det som inte kan flyttas med är själva installationen: installationsnamnet är låst för gott, och en installation kan inte lyftas från en bärbar dator till en server. När Tomás gick från sin bärbara dator till pilotservern började han om med ett nytt namn, harrow-pilot, och behöll harrow-eval för experiment.