Logga inBoka en genomgång

Kapitel 2.3

Planera en installation

Vad en Kubernetes-installation av Nexus kräver innan ni skriver ett kommando, hur stor den är och de två beslut ni inte kan ångra: installationsnamnet och nyckelförvaltarna. Avsnittet avslutas med Harrow Port Authoritys ifyllda planeringsblad.

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

16 minuters läsning

När vi installerade Nexus hos Harrow Port Authority tog kommandona en eftermiddag. Planeringen tog en vecka, och merparten av den veckan ägnades åt två frågor som inte har någonting med Kubernetes att göra: vad vi skulle kalla installationen, och vilka personer som skulle inneha dess återställningsnycklar. Båda svaren är permanenta. Allt annat i det här kapitlet kan ändras senare med en values-fil och helm upgrade.

Jag heter Tomás Reilly och är plattformsingenjör på Harrow. Harrow kör två installationer. Det här kapitlet planerar den anslutna installationen i vårt företagsnätverk, där vi först genomförde en pilot med Community. Hamnens driftnätverk, som saknar väg ut till internet, fick sin egen installation senare; kapitel 2.10, Luftgapad installation, behandlar den. Det här kapitlet är vad jag önskar att jag hade haft den första morgonen: klustret som Nexus förväntar sig, namnen det svarar på, hur mycket det kräver av era noder, och de beslut som måste fattas tillsammans med IT-chefen före installationen. Det avslutas med det arbetsblad som Aoife Brennan, vår IT-chef, godkände innan vi började. Kapitel 2.4, Hämta och verifiera en utgåva, behandlar hur man hämtar och kontrollerar utgåvan, och kapitel 2.5, Förkontroll med nexusctl, kontrollerar ert kluster mot allt som står här.

Vad klustret måste ha

Nexus installeras som ett enda Helm-chart, nexus, version 1.0.0-alpha.1. Chartet innehåller plattformstjänsterna och deras datalager, och det vägrar att installeras på ett kluster som saknar delarna nedan.

Krav Vad Nexus förväntar sig Varför
Kubernetes 1.33 eller senare. Testat på k3s v1.33.6+k3s1 Chartets kubeVersion är >=1.33.0-0, och helm install genomdriver det
cert-manager v1.21.3, installerat före Nexus Chartet skapar sin egen lokala certifikatutfärdare (CA) och de certifikat som dess tjänster använder för att tala med varandra
Helm v4 (vi använde v4.3.1) Helm 4 väntar som standard på chartets hook-Jobs, vilket installationen är beroende av
En lagringsklass En som är markerad som standard, eller en som ni anger i storage.className Varje datalager begär en beständig volym
En ingress-klass En som är markerad som standard, eller en som ni anger i ingress.className De tre publika adresserna är vanliga networking.k8s.io/v1-Ingresser
Port 80 och 443 Öppna på ingress-controllern, som en LoadBalancer- eller NodePort-Service Användare når Nexus via ingress-controllern
Arkitektur linux/amd64- eller linux/arm64-noder Varje avbildning är byggd för båda

Två saker saknas med avsikt i den tabellen. Nexus behöver ingen service mesh: ömsesidig TLS (mTLS, Transport Layer Security i båda riktningarna) mellan tjänster kommer från chartets lokala CA via cert-manager. Chartet har en istio.enabled-nyckel vars standardvärde är false, och ni bör låta den stå kvar där. Nexus behöver inte heller någon egen motor för tillträdespolicyer (admission policy engine).

På er arbetsstation behöver ni kubectl, Helm v4, cosign v3 för att kontrollera signaturer, age för att skapa förvaltarnycklar samt nexusctl, kommandoradsgränssnittet (CLI) för Nexus-operatören. Kapitel 2.4, Hämta och verifiera en utgåva, anger var varje Nexus-nedladdning finns.

Tre adresser

Varje installation svarar på tre värdnamn. Chartet kallar dem installationsidentiteten, och varje tjänst vägrar att starta utan dem.

Values-nyckel Harrows namn Vad som svarar där
hosts.console console.harrow.example Konsolen, webbapplikationen som användare loggar in i
hosts.api api.harrow.example Gatewayen, som betjänar applikationsprogrammeringsgränssnittet (API) och dirigerar varje anrop för artificiell intelligens (AI)
hosts.auth auth.harrow.example Inloggningstjänsten, nexus-auth

global.domain innehåller domänen som de tre ligger under, harrow.example för vår del. Varje värd är ett fullständigt namn i sig och kan ligga under vilken domän som helst som ni kontrollerar. Vi höll alla tre under en och samma domän eftersom ett enda certifikat då kunde täcka dem.

Skapa en post i Domain Name System (DNS) för var och en av de tre, som pekar på er ingress-controllers adress. Gör det före förkontrollen. nexusctl preflight slår upp varje namn från er arbetsstation och avbryter installationen om något av dem saknar post, eftersom en användare inte kan nå ett namn som inte går att slå upp.

Till vänster, tre DNS-namn: console.harrow.example, api.harrow.example och auth.harrow.example, vart och ett med en pil in i en ruta märkt "ingress controller, ports 80 and 443". Från den rutan leder tre pilar in i en större ruta märkt "namespace nexus": console-pilen till "nexus-alpha :3000", api-pilen till "nexus-gateway :9092" och auth-pilen till "nexus-auth :9101". En streckad ram runt namnrymden är märkt "default deny; only the ingress namespace may reach these three".
Hur de tre publika namnen når tjänsterna bakom dem.

Välja var TLS termineras

Chartets tls.mode avgör vem som innehar certifikaten för de tre publika adresserna. Det finns tre val, och ni kan byta mellan dem senare genom en uppgradering.

tls.mode Ni tillhandahåller Vad chartet gör
existing (standardvärdet) En Kubernetes TLS-Secret i namnrymden nexus, namngiven i tls.existingSecret Alla tre Ingresser använder denna enda Secret
cert-manager En ClusterIssuer som ni kör, namngiven i tls.clusterIssuer Annoterar varje Ingress så att cert-manager utfärdar nexus-console-tls, nexus-api-tls och nexus-auth-tls
none Något framför klustret som terminerar TLS, exempelvis er egen lastbalanserare Renderar Ingresserna utan TLS-avsnitt

Med existing betjänar ett certifikat alla tre värdar, så det måste namnge alla tre, antingen som tre alternativa subjektnamn (SAN) eller som ett jokertecken (wildcard) för er domän. Vi använde ett certifikat från Harrows interna CA. Förkontrollen läser er Secret innan ni installerar och varnar om dess certifikat löper ut inom 30 dagar.

Med cert-manager och en utfärdare för Automatic Certificate Management Environment (ACME) lägger chartet inte till någon egen omdirigering, så ett /.well-known/acme-challenge/-anrop på port 80 når lösaren (solver) orört. Lägg inte till en omdirigering från HTTP till HTTPS i er ingress-controller som körs före utmaningssökvägen; ett certifikat som inte kan förnyas slutar fungera i tysthet, veckor senare.

Oavsett vad ni väljer för den publika kanten talar tjänsterna inuti namnrymden alltid över TLS från chartets lokala CA. Den delen är inte valbar, och det är anledningen till att cert-manager är ett förhandskrav även när tls.mode är existing eller none.

Vad som lämnar klustret och vad som inte gör det

Chartet renderar en nätverkspolicy som nekar allt som standard (default-deny) för namnrymden nexus. Därefter är endast dessa flöden tillåtna:

  • trafik mellan Nexus-poddar inuti namnrymden;
  • DNS-uppslagningar mot klustrets DNS-tjänst;
  • Kubernetes API-server, för de få tjänster som granskar arbetslast-tokens;
  • ingress-controllerns namnrymd, till de tre publika Services;
  • eventuella intervall för Classless Inter-Domain Routing (CIDR) som ni anger i networkPolicy.externalEgressCIDRs.

Den sista listan är tom som standard. Om ni ska använda ett e-postrelä eller en modellserver utanför klustret ska dess intervall anges där. Telemetri är avstängd och förblir avstängd: schemat accepterar endast telemetry.enabled: false, och datalagrens egen användningsrapportering är också avstängd.

Chartet läser API-serverns adresser från klustret när ni installerar. Om ert konto inte kan läsa kubernetes-Endpoints i namnrymden default, anger ni dem själva i networkPolicy.apiServerCIDRs, som /32-intervall. proxy.trustedCIDRs namnger det poddnätverk som er ingress-controller ligger på, så att nexus-auth vet vems X-Forwarded-For-huvud det ska lita på. Standardvärdet, 10.42.0.0/16, är poddnätverket i k3s.

Dimensionering

Chartets standardbegäranden uppgår till cirka 2.05 kärnor för centralprocessor (CPU) och 6.7 GiB minne. Det är vad schemaläggaren reserverar; gränsvärdena (limits) är högre, och datalagren växer in i dem allt eftersom ni lägger till användare och filer.

Del Begärd CPU Begärt minne
Nio plattformstjänster (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 kärnor 2.6 GiB
Nyckeltjänsten, nexus-keys 0.05 kärnor 64 MiB
PostgreSQL 0.25 kärnor 1 GiB
Neo4j 0.25 kärnor 2 GiB
Valkey, Qdrant och objektlagret tillsammans 0.25 kärnor 640 MiB
De två OpenBao-servrarna i nyckellagret 0.15 kärnor 384 MiB

Standardvolymerna uppgår till 142 GiB:

Datalager Values-nyckel Standardstorlek
PostgreSQL 16 med PostGIS 3 och pgvector 0.8 dataTier.postgres.size 50Gi
Objektlager (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
Nyckellagret och dess upplåsare (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi och 1Gi
Kvitton för nyckeltjänsten keys.receiptsStorage 1Gi

För en enskild nod bör ni planera för 8 vCPU, 32 GiB arbetsminne (RAM) och en solid-state drive (SSD) på 250 GB. För en utvärdering räcker 4 vCPU, 16 GiB och 200 GB. Installationsprogrammets diskavbildning avvisar en maskin med mindre än 16 GiB minne (se kapitel 2.9, Installationsprogrammets diskavbildning), och jag skulle betrakta det som den lägsta nivån överallt.

Grafiknoder är valfria. Utan en nod som erbjuder en grafikprocessor (GPU) svarar assistenten via en värdbaserad modell med organisationens egen nyckel. Förkontrollen rapporterar detta som en varning, aldrig som ett fel. Kapitel 2.14, AI-leverantörer och modeller, behandlar båda alternativen.

Varje lager kan också köras utanför klustret: sätt dataTier.<store>.mode till external och ange dess värd och en Secret. En extern PostgreSQL kräver ett superanvändarkonto för installationens bootstrap samt ett certifikat som Nexus kan verifiera. Kapitel 2.11, Variationer: externa lager, TLS och ingress, behandlar detta. Om ni behåller dem i klustret, placera dem på en lagringsklass med riktiga diskar bakom. Databasen är den del ni kommer att sakna mest om en nods lokala disk går sönder.

Installationsnamnet är permanent

keys.installationName är vad operatörer kallar den här installationen. Det måste matcha ^[a-z][a-z0-9-]{0,62}$: en gemen bokstav, följt av upp till 62 gemena bokstäver, siffror eller bindestreck.

Första gången nyckellagret startar skapar det installationens identitet under det här namnet, och den identiteten är låst för alltid. En licens från Adverant utfärdas för den identiteten, så en licens som skapats för en installation avvisas på en annan med LICENCE_OTHER_INSTALLATION. Att byta namn skulle innebära en ny installation, en ny identitet och nya licenser.

Chartet har inget standardvärde för namnet. Det avvisar en installation utan namn (INSTALLATION_NAME_MISSING) och avvisar exempelnamnet från sina egna exempel-values-filer (INSTALLATION_NAME_EXAMPLE). Förkontrollen rapporterar båda innan ni kommer så långt.

På Harrow lade vi mer tid på detta än jag vill erkänna. Vi fastnade för harrow-port-authority: det namnger organisationen, säger ingenting om vilket kluster det körs på, och kommer fortfarande att stämma när hårdvaran byts ut. Undvik namn som prod-k3s-2 som beskriver dagens maskiner.

Nyckelförvaltning

Nexus förvarar varje organisations nycklar i sitt eget nyckellager, inuti klustret. Ni hanterar det inte i det dagliga arbetet, men ni bestämmer före installationen vem som kan återställa det efter en omstart. Det här är det beslut som kostar mest om ni gör fel.

Nyckellagret består av två OpenBao-servrar. Den primära, openbao, håller nycklarna och låser upp sig själv (unseal) via en andra, mindre server, openbao-unsealer. Upplåsaren (unsealer) är förseglad med Shamirs schema: fem andelar, där vilka tre som helst öppnar den. När ni installerar initierar ett förvaltnings-Job båda servrarna inuti klustret. I detta Jobs minne krypterar det upplåsarens andelar och nyckellagrets återställningsnycklar till varje förvaltare (custodian) ni anger, lagrar endast chiffertexten (i Secrets openbao-unseal-shares-encrypted och openbao-recovery-keys-encrypted), och återkallar båda rot-tokens innan det avslutas. Ingen andel i klartext når någonsin en disk eller en logg.

Efter varje omstart av upplåsarens nod startar upplåsaren i förseglat läge. Nyckellagret väntar på den, och ingenting som behöver en nyckel fungerar förrän en förvaltare låser upp den. Det kräver en dekryptering med förvaltarens egen privata nyckel. Proceduren finns i kapitel 2.15, Dag två: drift av Nexus.

Skapa en förvaltarnyckel

En förvaltare anges med den publika halvan av en age-nyckel, kallad dess mottagare (recipient). Varje förvaltare skapar sin egen nyckel på sin egen maskin och ger er endast mottagaren:

age-keygen -o custodian.key

Filens # public key:-rad är mottagaren, som börjar med age1. En förvaltare med en Mac kan i stället förvara nyckeln i Mac-datorns Secure Enclave, så att den privata halvan aldrig lämnar chippet och varje användning kräver ett fingeravtryck:

age-plugin-se keygen --access-control=any-biometry -o custodian.key

Den mottagaren börjar med age1se1. Förvaltnings-Jobet krypterar till fem former av mottagare: age1 (X25519), age1tag1 och age1tagpq1 (tag), age1pq1 (hybrid post-kvant) samt age1se1 (Secure Enclave). Det avvisar alla andra insticksformsformat, såsom age1yubikey1; ange i stället den nyckeln i en av de accepterade formerna.

Chartet kontrollerar varje mottagare när det renderas. En felstavad mottagare underkänns i sin bech32-kontrollsumma och avvisas, så ingenting förseglas någonsin till en nyckel som ingen innehar. Om någon av misstag klistrar in en privat nyckel i listan avvisar chartet den utan att skriva ut den igen. Exempelmottagaren i chartets egna values-filer avvisas också (KEYS_CUSTODIAN_EXAMPLE); ingen innehar dess privata halva.

Hur många förvaltare

Varje andel krypteras till varje förvaltare, så vilken enskild förvaltare som helst kan låsa upp på egen hand. Fler förvaltare innebär fler sätt att återställa och fler personer som var och en kan agera på egen hand. Vi valde tre på Harrow: Aoife, jag och en Secure Enclave-nyckel på en reservdator som förvaras i hamnens kassaskåp. Två är det minsta jag skulle acceptera. En är en enskild felpunkt (single point of failure) som förr eller senare kommer att vara på semester när en nod startar om.

Välja utgåva

edition är community eller enterprise, och enterprise.enabled måste stämma överens med det. Chartet avvisar en avvikelse, och det avvisar varje utgåva som inte är en av de två.

Utgåvan avgör också vilka avbildningar ni installerar. Varje chart-paket innehåller ett avbildningslås (images lock), listan över varje avbildning per kontrollsumma (digest), för en utgåva. En Community-installation hämtar endast Community-avbildningar. En Enterprise-installation använder Enterprise-låset, som består av Community-avbildningarna plus Enterprise-byggena, och hämtar dem med en pull-token från ert Adverant-konto. Kapitel 2.4, Hämta och verifiera en utgåva, förklarar låset, och kapitel 2.2, Utgåvorna under huven, förklarar vad varje utgåva innehåller.

Ni behöver inte bestämma er för gott. En Community-installation kan uppgraderas till Enterprise på plats, med bibehållna användare, filer och historik; kapitel 2.7, Installera Enterprise och tillämpa en licens, visar hur. Vi körde Community under piloten på Harrow och bytte sex veckor senare.

Licensen är aldrig en del av den här planen. Den är inte ett chart-värde eller en monterad fil: ni importerar den efter installationen, via konsolen, nexusctl eller API:et.

Välja leveransform

Form När den passar Kapitel
Helm-chart från registry.adverant.ai Ert eget Kubernetes-kluster, med en väg till registret 2.6 och 2.7
nexusctl install Samma kluster, där förkontrollen och signaturkontrollen körs åt er 2.6
nexusctl install --single-node En maskin, där nexusctl även sätter upp klustret 2.8
Installationsprogrammets skivavbildning En ren server eller virtuell maskin (VM) som ni helst inte förbereder för hand 2.9
Offline-paketet Ingen väg ut alls; avbildningar och chart levereras på en disk 2.10

Chartet är detsamma i varje form. Det som skiljer sig åt är vem som skapar klustret och varifrån avbildningarna kommer.

Hämta utgåvan
Hämta utgåvan
Det här är utgåvosidan på Adverant-kontot. Lägg märke till den tydliga beskrivningen av vad en alfautgåva utlovar, storleken och signaturen bredvid varje fil, samt offline-kommandona för att kontrollera en nedladdning.

Planeringsbladet

Det här är Harrows, så som Aoife godkände det. Kopiera de två vänstra kolumnerna och fyll i den högra för er egen installation.

Beslut Values-nyckel eller kommando Harrow Port Authority
Kubernetes och version (förkontrollen läser av det) k3s v1.33.6+k3s1, tre noder
Kube-kontext för installationen --context harrow-prod
Namnrymd --namespace nexus
Utgåva edition, enterprise.enabled community för piloten, därefter enterprise
Avbildningsregister global.imageRegistry registry.adverant.ai
Domän global.domain harrow.example
Konsoladress hosts.console console.harrow.example
API-adress hosts.api api.harrow.example
Inloggningsadress hosts.auth auth.harrow.example
TLS vid kanten tls.mode, tls.existingSecret existing, Secret harrow-public-tls från Harrows interna CA
Ingress-klass ingress.className traefik
Ingress-namnrymd networkPolicy.ingressNamespace kube-system
Lagringsklass storage.className local-path
Datalager dataTier.<store>.mode Alla in-cluster, standardstorlekar
Utgående intervall networkPolicy.externalEgressCIDRs Endast e-postreläets intervall
Installationsnamn (permanent) keys.installationName harrow-port-authority
Förvaltare (i praktiken permanent) keys.custody.recipients Tre: Aoife Brennan, Tomás Reilly, den bärbara datorn i kassaskåpet (age1se1)
Grafiknoder (förkontrollen läser av det) Inga för den anslutna piloten; värdbaserad modell med Harrows egen nyckel
Första administratör nexusctl claim-code --administrator aoife.brennan@harrow.example

Två rader på det bladet kan inte ångras: installationsnamnet, och förvaltarna i den meningen att om alla förloras så förloras nyckellagret. Se till att få dessa två godkända av någon med befogenhet att säga ja. Allt annat är en ändring i values.

När arbetsbladet är klart, gå till kapitel 2.4, Hämta och verifiera en utgåva, och hämta utgåvan.