Versiune 1.0.0-alpha.1cea mai recentă
Capitolul 2.3
Planificarea unei instalări
Ce necesită o instalare Nexus pe Kubernetes înainte de a tasta o comandă, cât de mare este și cele două decizii ireversibile: numele instalării și custozii cheilor. Se încheie cu fișa de planificare completată pentru Harrow Port Authority.
Această pagină a fost tradusă cu ajutorul IA din originalul în limba engleză. Dacă există neclarități, pagina în limba engleză rămâne cea de referință. Citiți această pagină în limba engleză

Când am instalat Nexus la Harrow Port Authority, rularea comenzilor a durat o după-amiază. Planificarea a durat o săptămână, iar cea mai mare parte din acea săptămână s-a dus pe două întrebări care nu au nicio legătură cu Kubernetes: cum urma să numim instalarea și ce persoane aveau să dețină cheile sale de recuperare. Ambele răspunsuri sunt permanente. Orice altceva din acest capitol poate fi modificat ulterior cu un fișier de valori și o comandă helm upgrade.
Sunt Tomás Reilly, inginerul de platformă de la Harrow. Harrow rulează două instalări. Acest capitol o planifică pe cea conectată din rețeaua noastră corporativă, unde am testat mai întâi ediția Community într-un proiect pilot. Rețeaua de operațiuni a portului, care nu are rută către internet, a primit propria instalare mai târziu; capitolul 2.10, Instalarea izolată de rețea (air-gapped), acoperă acest subiect. Acest capitol reprezintă ceea ce mi-aș fi dorit să am în prima dimineață: clusterul pe care îl așteaptă Nexus, numele la care răspunde, cât de mult solicită nodurile dumneavoastră și deciziile pe care trebuie să le stabiliți cu directorul IT înainte de instalare. Se încheie cu fișa de lucru pe care Aoife Brennan, directoarea noastră IT, a aprobat-o înainte să începem. Capitolul 2.4, Obținerea și verificarea unei versiuni, acoperă descărcarea și verificarea versiunii, iar capitolul 2.5, Verificarea prealabilă cu nexusctl, vă verifică clusterul în raport cu tot ce este prezentat aici.
Ce trebuie să aibă clusterul
Nexus se instalează ca un singur chart Helm, nexus, versiunea 1.0.0-alpha.1. Chart-ul conține serviciile platformei și nivelul lor de date și refuză instalarea pe un cluster căruia îi lipsesc elementele de mai jos.
| Cerință | Ce așteaptă Nexus | De ce |
|---|---|---|
| Kubernetes | 1.33 sau o versiune ulterioară. Testat pe k3s v1.33.6+k3s1 |
Proprietatea kubeVersion a chart-ului este >=1.33.0-0, iar helm install o impune |
| cert-manager | v1.21.3, instalat înainte de Nexus |
Chart-ul își creează propria autoritate de certificare (CA) locală și certificatele pe care serviciile sale le folosesc pentru a comunica între ele |
| Helm | v4 (noi am folosit v4.3.1) | Helm 4 așteaptă în mod implicit finalizarea Job-urilor de tip hook ale chart-ului, de care depinde instalarea |
| O clasă de stocare | Una marcată ca implicită sau una pe care o numiți în storage.className |
Fiecare depozit de date revendică un volum persistent |
| O clasă de ingress | Una marcată ca implicită sau una pe care o numiți în ingress.className |
Cele trei adrese publice sunt resurse Ingress networking.k8s.io/v1 standard |
| Porturile 80 și 443 | Deschise pe controllerul de ingress, ca un Service de tip LoadBalancer sau NodePort | Utilizatorii accesează Nexus prin intermediul controllerului de ingress |
| Arhitectură | Noduri linux/amd64 sau linux/arm64 |
Fiecare imagine este construită pentru ambele arhitecturi |
Două lucruri lipsesc din acel tabel în mod intenționat. Nexus nu are nevoie de service mesh: criptarea TLS reciprocă (mTLS, Transport Layer Security în ambele direcții) între servicii provine de la autoritatea de certificare (CA) locală a chart-ului, prin intermediul cert-manager. Chart-ul are o cheie istio.enabled a cărei valoare implicită este false, iar dumneavoastră ar trebui să o lăsați așa. De asemenea, Nexus nu are nevoie de un motor propriu de politici de admisie.
Pe stația dumneavoastră de lucru veți avea nevoie de kubectl, Helm v4, cosign v3 pentru verificarea semnăturilor, age pentru crearea cheilor de custode și nexusctl, interfața în linie de comandă (CLI) a operatorului Nexus. Capitolul 2.4, Obținerea și verificarea unei versiuni, indică unde se află fiecare descărcare Nexus.
Trei adrese
Fiecare instalare răspunde la trei nume de gazdă (host). Chart-ul le numește identitatea instalării, iar fiecare serviciu refuză să pornească fără ele.
| Cheie în fișierul de valori | Numele folosit la Harrow | Ce răspunde acolo |
|---|---|---|
hosts.console |
console.harrow.example |
Consola, aplicația web în care se autentifică utilizatorii |
hosts.api |
api.harrow.example |
Gateway-ul, care deservește interfața de programare a aplicațiilor (API) și rutează fiecare cerere de inteligență artificială (IA) |
hosts.auth |
auth.harrow.example |
Serviciul de autentificare, nexus-auth |
global.domain reține domeniul sub care se află cele trei, harrow.example în cazul nostru. Fiecare gazdă este un nume complet în sine și se poate afla sub orice domeniu pe care îl controlați. Noi le-am păstrat pe toate trei sub un singur domeniu, deoarece un singur certificat le putea acoperi astfel pe toate.
Creați o înregistrare în sistemul de nume de domenii (DNS) pentru fiecare dintre cele trei, care să indice adresa controllerului dumneavoastră de ingress. Faceți acest lucru înainte de verificarea prealabilă (preflight). nexusctl preflight caută fiecare nume de pe stația dumneavoastră de lucru și oprește instalarea dacă vreunul dintre ele nu are înregistrare, deoarece o persoană nu poate accesa un nume care nu se rezolvă.
Alegerea modului de terminare TLS
Cheia tls.mode a chart-ului decide cine deține certificatele pentru cele trei adrese publice. Există trei opțiuni și puteți schimba între ele ulterior printr-un upgrade.
tls.mode |
Ce furnizați dumneavoastră | Ce face chart-ul |
|---|---|---|
existing (valoarea implicită) |
Un Secret TLS Kubernetes în namespace-ul nexus, numit în tls.existingSecret |
Toate cele trei resurse Ingress folosesc acel unic Secret |
cert-manager |
Un ClusterIssuer pe care îl rulați, numit în tls.clusterIssuer |
Adaugă adnotări fiecărui Ingress astfel încât cert-manager să emită nexus-console-tls, nexus-api-tls și nexus-auth-tls |
none |
Un element în fața clusterului care termină conexiunea TLS, cum ar fi propriul dumneavoastră load balancer | Generează resursele Ingress fără nicio secțiune TLS |
Cu existing, un singur certificat deservește toate cele trei gazde, deci trebuie să le numească pe toate trei, fie ca trei nume alternative ale subiectului (SAN), fie ca un certificat wildcard pentru domeniul dumneavoastră. Noi am folosit un certificat de la autoritatea de certificare (CA) internă a Harrow. Verificarea prealabilă citește Secretul înainte de instalare și emite un avertisment atunci când certificatul său expiră în mai puțin de 30 de zile.
Cu cert-manager și un emițător Automatic Certificate Management Environment (ACME), chart-ul nu adaugă nicio redirecționare proprie, astfel încât o cerere /.well-known/acme-challenge/ pe portul 80 ajunge la rezolvitor neatinsă. Nu adăugați o redirecționare de la HTTP la HTTPS la nivelul controllerului de ingress care să se execute înaintea căii de validare (challenge path); un certificat care nu se poate reînnoi eșuează în tăcere, săptămâni mai târziu.
Orice ați alege pentru marginea publică a rețelei (public edge), serviciile din interiorul namespace-ului comunică întotdeauna prin TLS emis de autoritatea de certificare (CA) locală a chart-ului. Această parte nu este opțională și acesta este motivul pentru care cert-manager este o cerință prealabilă chiar și atunci când tls.mode este existing sau none.
Ce părăsește clusterul și ce nu
Chart-ul generează o politică de rețea de refuz implicit (default-deny) pentru namespace-ul nexus. După aceea, sunt permise doar următoarele fluxuri:
- traficul între pod-urile Nexus din interiorul namespace-ului;
- interogările DNS către serviciul DNS al clusterului;
- serverul API Kubernetes, pentru puținele servicii care verifică token-urile sarcinilor de lucru (workload tokens);
- namespace-ul controllerului de ingress, către cele trei resurse Service publice;
- orice intervale Classless Inter-Domain Routing (CIDR) pe care le enumerați în
networkPolicy.externalEgressCIDRs.
Această ultimă listă este goală în mod implicit. Dacă veți folosi un releu de e-mail (mail relay) sau un server de modele în afara clusterului, intervalul acestuia trebuie trecut acolo. Telemetria este dezactivată și rămâne dezactivată: schema acceptă doar telemetry.enabled: false, iar raportarea proprie a utilizării din depozitele de date este, de asemenea, dezactivată.
Chart-ul citește adresele serverului API din cluster atunci când instalați. Dacă contul dumneavoastră nu poate citi resursele Endpoints kubernetes din namespace-ul default, furnizați-le chiar dumneavoastră în networkPolicy.apiServerCIDRs, ca intervale /32. proxy.trustedCIDRs numește rețeaua de pod-uri pe care se află controllerul dumneavoastră de ingress, astfel încât nexus-auth să știe în al cui antet X-Forwarded-For să aibă încredere. Valoarea implicită, 10.42.0.0/16, este rețeaua de pod-uri a k3s.
Dimensionare
Cererile implicite ale chart-ului însumează aproximativ 2.05 nuclee de unitate centrală de procesare (CPU) și 6.7 GiB de memorie. Aceasta este capacitatea pe care o rezervă planificatorul (scheduler); limitele sunt mai mari, iar depozitele de date cresc până la acestea pe măsură ce adăugați utilizatori și fișiere.
| Componentă | CPU solicitat | Memorie solicitată |
|---|---|---|
| Nouă servicii de platformă (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) | 1.1 nuclee | 2.6 GiB |
Serviciul de chei, nexus-keys |
0.05 nuclee | 64 MiB |
| PostgreSQL | 0.25 nuclee | 1 GiB |
| Neo4j | 0.25 nuclee | 2 GiB |
| Valkey, Qdrant și depozitul de obiecte împreună | 0.25 nuclee | 640 MiB |
| Cele două servere OpenBao ale depozitului de chei | 0.15 nuclee | 384 MiB |
Volumele implicite însumează 142 GiB:
| Depozit de date | Cheie în fișierul de valori | Dimensiune implicită |
|---|---|---|
| PostgreSQL 16 cu PostGIS 3 și pgvector 0.8 | dataTier.postgres.size |
50Gi |
| Depozit de obiecte (SeaweedFS) | dataTier.objectStore.size |
50Gi |
| Neo4j 5.26 Community Edition | dataTier.neo4j.size |
20Gi |
| Qdrant | dataTier.qdrant.size |
10Gi |
| Valkey | dataTier.valkey.size |
5Gi |
| Depozitul de chei și deblocatorul său (unsealer) | keys.openbao.storage.keystore, keys.openbao.storage.unsealer |
5Gi și 1Gi |
| Chitanțe ale serviciului de chei | keys.receiptsStorage |
1Gi |
Pentru un singur nod, planificați 8 vCPU, 32 GiB de memorie cu acces aleatoriu (RAM) și o unitate solid-state (SSD) de 250 GB. Pentru o evaluare, 4 vCPU, 16 GiB și 200 GB vor fi suficiente. Imaginea de disc a instalatorului refuză o mașină cu mai puțin de 16 GiB de memorie (consultați capitolul 2.9, Imaginea de disc a instalatorului), și aș trata această valoare drept pragul minim peste tot.
Nodurile grafice sunt opționale. Fără un nod care să ofere o unitate de procesare grafică (GPU), asistentul răspunde printr-un model găzduit, folosind propria cheie a organizației. Verificarea prealabilă raportează acest lucru ca pe un avertisment, niciodată ca pe o eroare. Capitolul 2.14, Furnizori și modele de IA, acoperă ambele variante.
Fiecare depozit poate rula și în afara clusterului: setați dataTier.<store>.mode la external și numiți gazda acestuia și un Secret. Un PostgreSQL extern are nevoie de un cont de superutilizator pentru inițializarea (bootstrap) instalării și de un certificat pe care Nexus să îl poată verifica. Capitolul 2.11, Variații: depozite externe, TLS și ingress, acoperă acest aspect. Dacă le păstrați în cluster, plasați-le pe o clasă de stocare care are discuri reale în spate. Baza de date este componenta căreia îi veți simți cel mai mult lipsa dacă discul local al unui nod cedează.
Numele instalării este permanent
keys.installationName este numele pe care operatorii îl dau acestei instalări. Trebuie să respecte expresia ^[a-z][a-z0-9-]{0,62}$: o literă mică, urmată de până la 62 de litere mici, cifre sau cratime.
Prima dată când pornește depozitul de chei, acesta creează identitatea instalării sub acest nume, iar acea identitate este fixată definitiv. O licență de la Adverant este emisă pentru acea identitate, astfel încât o licență creată pentru o instalare este refuzată pe o alta cu eroarea LICENCE_OTHER_INSTALLATION. Redenumirea ar însemna o instalare nouă, o identitate nouă și licențe noi.
Chart-ul nu are o valoare implicită pentru nume. Refuză o instalare fără nume (INSTALLATION_NAME_MISSING) și refuză numele de exemplu din propriile sale fișiere cu valori de exemplu (INSTALLATION_NAME_EXAMPLE). Verificarea prealabilă le raportează pe amândouă înainte să ajungeți atât de departe.
La Harrow am petrecut mai mult timp pe acest subiect decât mi-ar plăcea să recunosc. Ne-am oprit asupra harrow-port-authority: numește organizația, nu spune nimic despre clusterul pe care rulează și va rămâne valabil și atunci când hardware-ul va fi înlocuit. Evitați nume precum prod-k3s-2, care descriu mașinile de astăzi.
Custodia cheilor
Nexus păstrează cheile fiecărei organizații în propriul său depozit de chei, în interiorul clusterului. Nu îl operați zi de zi, dar decideți, înainte de instalare, cine îl poate repune în funcțiune după o repornire. Aceasta este decizia care costă cel mai mult dacă o greșiți.
Depozitul de chei este format din două servere OpenBao. Cel principal, openbao, deține cheile și se deblochează (unseals) singur prin intermediul unui al doilea server, mai mic, openbao-unsealer. Deblocatorul (unsealer) este sigilat cu schema lui Shamir: cinci fragmente (shares), dintre care oricare trei îl deschid. Când instalați, un Job de custodie inițializează ambele servere în interiorul clusterului. În memoria acelui Job, acesta criptează fragmentele deblocatorului și cheile de recuperare ale depozitului de chei pentru fiecare custode pe care îl numiți, stochează doar textul cifrat (în resursele Secret openbao-unseal-shares-encrypted și openbao-recovery-keys-encrypted) și revocă ambele token-uri root înainte de a se încheia. Niciun fragment în text clar nu ajunge vreodată pe un disc sau într-un jurnal (log).
După orice repornire a nodului pe care rulează deblocatorul, acesta pornește sigilat. Depozitul de chei îl așteaptă, iar nimic din ceea ce are nevoie de o cheie nu funcționează până când un custode nu îl deblochează. Acest lucru necesită o singură decriptare cu propria cheie privată a custodelui. Procedura se află în capitolul 2.15, A doua zi: operarea Nexus.
Crearea unei chei de custode
Un custode este desemnat prin jumătatea publică a unei chei age, numită destinatarul său (recipient). Fiecare custode își creează propria cheie pe propria mașină și vă oferă doar destinatarul:
age-keygen -o custodian.keyLinia # public key: a fișierului este destinatarul, începând cu age1. Un custode cu un Mac poate păstra cheia în Secure Enclave al Mac-ului în schimb, astfel încât jumătatea privată nu părăsește niciodată cipul și fiecare utilizare solicită o amprentă:
age-plugin-se keygen --access-control=any-biometry -o custodian.keyAcel destinatar începe cu age1se1. Job-ul de custodie criptează către cinci forme de destinatar: age1 (X25519), age1tag1 și age1tagpq1 (tag), age1pq1 (hibrid post-cuantic) și age1se1 (Secure Enclave). Refuză orice altă formă de plugin, cum ar fi age1yubikey1; numiți acea cheie într-una dintre formele acceptate în schimb.
Chart-ul verifică fiecare destinatar atunci când generează șabloanele. Unul scris greșit eșuează la suma de control bech32 și este refuzat, astfel încât nimic nu este vreodată sigilat către o cheie pe care nu o deține nimeni. Dacă cineva lipește din greșeală o cheie privată în listă, chart-ul o refuză fără a o afișa în răspuns. Destinatarul de exemplu din propriile fișiere de valori ale chart-ului este, de asemenea, refuzat (KEYS_CUSTODIAN_EXAMPLE); nimeni nu deține jumătatea sa privată.
Câți custozi
Fiecare fragment este criptat pentru fiecare custode, astfel încât oricare custode poate debloca singur. Mai mulți custozi înseamnă mai multe modalități de recuperare și mai multe persoane care pot acționa fiecare pe cont propriu. Noi am ales trei la Harrow: Aoife, eu și o cheie Secure Enclave pe un laptop de rezervă care stă în seiful portului. Doi este minimul pe care l-aș accepta. Unul singur reprezintă un punct unic de eșec care, mai devreme sau mai târziu, va fi în concediu atunci când repornește un nod.
Alegerea ediției
edition este community sau enterprise, iar enterprise.enabled trebuie să corespundă cu aceasta. Chart-ul refuză o nepotrivire și refuză orice ediție care nu este una dintre cele două.
Ediția decide, de asemenea, ce imagini instalați. Fiecare pachet chart conține un fișier de blocare a imaginilor (images lock), lista fiecărei imagini după amprenta sa (digest), pentru o singură ediție. O instalare Community preia doar imagini Community. O instalare Enterprise preia fișierul de blocare Enterprise, care conține imaginile Community plus versiunile Enterprise, și le descarcă folosind un token de descărcare (pull token) din contul dumneavoastră Adverant. Capitolul 2.4, Obținerea și verificarea unei versiuni, explică fișierul de blocare, iar capitolul 2.2, Edițiile sub capotă, explică ce conține fiecare ediție.
Nu trebuie să decideți definitiv. O instalare Community trece la Enterprise pe loc, păstrându-și utilizatorii, fișierele și istoricul; capitolul 2.7, Instalarea ediției Enterprise și aplicarea unei licențe, arată cum. Noi am rulat Community pentru proiectul pilot de la Harrow și am făcut trecerea șase săptămâni mai târziu.
Licența nu face niciodată parte din acest plan. Nu este o valoare în chart sau un fișier montat: o importați după instalare, prin intermediul consolei, al nexusctl sau al API-ului.
Alegerea formei de livrare
| Formă | Când se potrivește | Capitol |
|---|---|---|
Chart Helm din registry.adverant.ai |
Propriul dumneavoastră cluster Kubernetes, cu o rută către registru | 2.6 și 2.7 |
nexusctl install |
Același cluster, cu verificarea prealabilă și verificarea semnăturii rulate pentru dumneavoastră | 2.6 |
nexusctl install --single-node |
O singură mașină, unde nexusctl configurează și clusterul |
2.8 |
| Imaginea de disc a programului de instalare | Un server fizic (bare metal) sau o mașină virtuală (VM) pe care ați prefera să nu o pregătiți manual | 2.9 |
| Pachetul offline | Nicio rută către exterior; imaginile și chart-ul vin pe un disc | 2.10 |
Chart-ul este același în fiecare formă. Ceea ce se schimbă este cine creează clusterul și de unde provin imaginile.
Fișa de planificare
Aceasta este fișa de la Harrow, așa cum a aprobat-o Aoife. Copiați cele două coloane din stânga și completați-o pe cea din dreapta pentru propria dumneavoastră instalare.
| Decizie | Cheie în fișierul de valori sau comandă | Harrow Port Authority |
|---|---|---|
| Kubernetes și versiunea | (verificarea prealabilă o citește) | k3s v1.33.6+k3s1, trei noduri |
| Contextul Kube pentru instalare | --context |
harrow-prod |
| Namespace | --namespace |
nexus |
| Ediție | edition, enterprise.enabled |
community pentru proiectul pilot, apoi enterprise |
| Registrul de imagini | global.imageRegistry |
registry.adverant.ai |
| Domeniu | global.domain |
harrow.example |
| Adresa consolei | hosts.console |
console.harrow.example |
| Adresa API | hosts.api |
api.harrow.example |
| Adresa de autentificare | hosts.auth |
auth.harrow.example |
| TLS la marginea rețelei (edge) | tls.mode, tls.existingSecret |
existing, Secretul harrow-public-tls de la autoritatea de certificare (CA) internă a Harrow |
| Clasa de ingress | ingress.className |
traefik |
| Namespace-ul de ingress | networkPolicy.ingressNamespace |
kube-system |
| Clasa de stocare | storage.className |
local-path |
| Depozite de date | dataTier.<store>.mode |
Toate in-cluster, dimensiuni implicite |
| Intervale de ieșire (outbound) | networkPolicy.externalEgressCIDRs |
Doar intervalul releului de e-mail |
| Numele instalării (permanent) | keys.installationName |
harrow-port-authority |
| Custozi (în practică, permanenți) | keys.custody.recipients |
Trei: Aoife Brennan, Tomás Reilly, laptopul din seif (age1se1) |
| Noduri grafice | (verificarea prealabilă o citește) | Niciunul pentru proiectul pilot conectat; model găzduit cu propria cheie a Harrow |
| Primul administrator | nexusctl claim-code --administrator |
aoife.brennan@harrow.example |
Două rânduri din acea fișă sunt ireversibile: numele instalării și custozii, în sensul că pierderea tuturor duce la pierderea depozitului de chei. Obțineți aprobarea pentru aceste două rânduri de la cineva care are autoritatea de a spune da. Orice altceva este o modificare în fișierul de valori.
Odată finalizată fișa de lucru, treceți la capitolul 2.4, Obținerea și verificarea unei versiuni, și descărcați versiunea.
