AutentificareProgramați o prezentare

Capitolul 2.9

Imaginea de disc a programului de instalare

Porniți un server fizic sau o mașină virtuală de pe imaginea de instalare Nexus, iar aceasta instalează sistemul de operare, k3s, cert-manager și Nexus fără rețea, verificând fiecare fișier înainte de a fi utilizat.

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ă

17 minute de lectură

Biroul căpitanului portului de pe cheiul de est din Harrow are un singur server, nu are conexiune la internet și nu există nimeni la fața locului care să administreze Kubernetes. Cu toate acestea, Tomás Reilly avea nevoie de Nexus pe acel server. A scris imaginea pe un stick USB (Universal Serial Bus), a conectat lângă acesta un al doilea stick mic cu patru rânduri de setări și a pornit serverul. O oră mai târziu, ecranul afișa adresa consolei și cele trei rânduri care trebuiau adăugate în fișierul hosts. Nu a introdus nicio comandă Kubernetes.

Acesta este rolul imaginii de disc a programului de instalare. Aceasta scrie un sistem de operare minimal pe discul serverului, apoi, la prima pornire, verifică fiecare fișier pe care îl conține folosind cheia de lansare Adverant, instalează k3s fără conexiune la rețea, importă toate imaginile, instalează cert-manager și Nexus și verifică dacă toate podurile rulează. Fiecare pas se oprește cu un motiv explicit în momentul în care apare o problemă. Nu există un mod de funcționare degradat și nicio parolă implicită nicăieri.

Cele două imagini

Fiecare versiune este disponibilă sub forma a două tipuri de imagini, pentru două arhitecturi de procesor: amd64 și arm64.

Fișier Ce conține Cine o poate descărca
nexus-alpha-installer-1.0.0-alpha.1-<arch>.iso Doar programul de instalare: sistemul de operare, k3s v1.33.6+k3s1, cert-manager v1.21.3 și programul de instalare la prima pornire. Funcționează pentru oricare dintre ediții și nu conține imagini Nexus. Oricine, de la downloads.adverant.ai
nexus-alpha-<edition>-1.0.0-alpha.1-<arch>.iso Același program de instalare, având pachetul offline al ediției respective adăugat ca o a doua partiție etichetată NEXUS-BUNDLE. Un singur mediu de stocare instalează totul. Community: oricine. Enterprise: doar din contul dumneavoastră Adverant

<arch> este amd64 sau arm64, iar <edition> este community sau enterprise.

Programul de instalare caută exclusiv un sistem de fișiere etichetat NEXUS-BUNDLE. În imaginea completă (all-in-one), aceasta este partiția aflată pe imaginea însăși. În cazul imaginii care conține doar programul de instalare, aduceți pachetul pe un al doilea disc sau stick cu acea etichetă, ceea ce este util atunci când instalați mai multe locații de pe un singur stick de instalare și schimbați doar pachetul. Capitolul 2.10, Instalarea fără conexiune la rețea (air-gapped), descrie acest pachet.

Imaginile Enterprise și pachetele Enterprise nu sunt niciodată anonime. Le puteți descărca din contul dumneavoastră Adverant la https://account.adverant.ai, de pe pagina Downloads, alături de licența dumneavoastră. Imaginile și pachetele Community sunt publice.

Două schițe de discuri sunt așezate una lângă alta. Cea din stânga, „imagine doar cu programul de instalare”, are o partiție etichetată „program de instalare a sistemului de operare, k3s, cert-manager, program de instalare la prima pornire” și, lângă aceasta, un stick USB separat etichetat „NEXUS-BUNDLE: pachetul offline al ediției”. Cea din dreapta, „imagine completă (all-in-one)”, are aceeași primă partiție și o a doua partiție pe același disc etichetată „NEXUS-BUNDLE”. Sub ambele, un stick USB mic este etichetat „NEXUS-SEED: seed.yaml și licence.json pentru Enterprise”, cu o notă „opțional pentru Community”. Săgeți de la toate cele trei etichete indică în jos către o singură casetă, „prima pornire găsește fiecare componentă după eticheta sa”.
Imaginea doar cu programul de instalare și imaginea completă (all-in-one), precum și locul în care prima pornire găsește fiecare componentă.

Din ce este construită imaginea

Sistemul de operare este bazat pe Debian 13 și nu este o imagine Debian oficială. Acesta conține sistemul de bază Debian și nimic altceva: fără pachete suplimentare, fără interfață grafică (desktop) și fără server oglindă (mirror). k3s vine cu propriul mediu de execuție pentru containere și propria rețelistică. Lanțul de pornire (shim, GRUB, nucleul și ramdisk-ul inițial) este identic, octet cu octet, cu cel distribuit de Debian, astfel încât o mașină cu Secure Boot activat îl pornește ca pe orice program de instalare Debian.

Două compilări ale aceleiași versiuni generează imagini identice, octet cu octet, iar versiunea nu este publicată până când acest lucru nu se confirmă. Pachetele sursă Debian pentru fiecare fișier binar de pe imagine sunt publicate alături de aceasta ca nexus-alpha-installer-1.0.0-alpha.1-debian-source.tar, în aceeași listă de sume de control.

Verificați descărcarea înainte de a o scrie

Directorul de imagini de pe downloads.adverant.ai conține imaginile, un fișier SHA256SUMS care acoperă fiecare fișier publicat și SHA256SUMS.sigstore.json, semnătura aplicată peste acea listă, realizată cu cheia de lansare Adverant. Obțineți separat cheia publică de lansare, salvați-o ca release.pub și verificați amprenta acesteia așa cum este descris în capitolul 2.4, Obținerea și verificarea unei versiuni.

  1. Verificați semnătura de pe lista de sume de control. Nu există un jurnal de transparență pentru versiunile Nexus, prin urmare parametrul care omite căutarea în jurnal este obligatoriu.
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS
Verified OK
  1. Verificați imaginea pe care ați descărcat-o în raport cu lista:
grep nexus-alpha-community-1.0.0-alpha.1-amd64.iso SHA256SUMS | sha256sum -c -
nexus-alpha-community-1.0.0-alpha.1-amd64.iso: OK

Pe un Mac, utilizați shasum -a 256 -c - în loc de sha256sum -c -.

  1. Scrieți imaginea pe un stick USB cu instrumentul pe care îl utilizați în mod normal sau atașați-o la mașina virtuală ca disc optic.

k3s publică sume de control pentru fișierele versiunilor sale, dar nu și o semnătură, astfel încât fișierele k3s din interiorul imaginii sunt verificate în raport cu sumele de control publicate de k3s, din aceeași sursă ca și fișierele. Tot ceea ce este construit de Adverant este semnat.

Pachete împărțite în fragmente

Un pachet pe care îl transportați pe un stick separat are câțiva gigaocteți. Unele sisteme de fișiere, printre care FAT (File Allocation Table), nu pot stoca un fișier de 4 GiB sau mai mare, motiv pentru care fișierele de pachet sunt publicate în fragmente de 2047 MiB care încap pe orice stick. Îmbinați fragmentele la loc în ordine și verificați fișierul îmbinat în raport cu .sha256 înainte de a-l utiliza.

Hardware-ul necesar

Prima pornire verifică mașina înainte de a modifica ceva și refuză să continue atunci când mașina are resurse insuficiente.

Verificare Baza minimă Când se verifică
Arhitectură Proprie imaginii: o imagine amd64 pe amd64, arm64 pe arm64 Prima pornire
Memorie 16 GiB Prima pornire
Disc țintă Exact un disc gol de cel puțin 64 GB sau discul indicat în seed Înainte de scrierea sistemului de operare
Spațiu liber pe / 50 GB după ce sistemul de operare a fost instalat Prima pornire
Ceas Nu mai vechi decât data la care a fost construită imaginea Prima pornire

Acestea sunt praguri minime, nu o recomandare. Cu valorile implicite ale diagramei (chart), doar volumele Nexus însumează 142 GiB, astfel încât un disc de 64 GB trece de programul de instalare, dar se umple în câteva zile. Utilizați resursele pe care ar trebui să le aibă un singur nod: 8 vCPU (virtual central processing units), 32 GiB de memorie și un SSD (solid-state drive) de 250 GB. Patru vCPU, 16 GiB și 200 GB sunt suficiente pentru o evaluare.

Verificarea ceasului este prezentă deoarece serverul nu are conexiune la rețea și, prin urmare, nici serviciu de timp la momentul instalării. Certificatele și semnăturile sunt verificate în raport cu ceasul. Dacă ceasul hardware al mașinii este în urma datei de construire a imaginii, prima pornire se oprește și vă solicită să îl setați. Setați-l în configurarea firmware-ului și porniți din nou.

Servere fizice (bare metal) și mașini virtuale

Imaginea pornește pe firmware UEFI (Unified Extensible Firmware Interface), atât pe servere fizice, cât și pe mașini virtuale. Aceasta instalează încărcătorul de sistem (boot loader) pe calea pentru medii amovibile, precum și pe cea obișnuită, astfel încât o VM (mașină virtuală) fără intrări de pornire salvate îl găsește totuși după prima repornire. Alocați unei VM memoria și discul din tabelul de mai sus, un disc virtual gol și imaginea ca CD.

Programul de instalare alege discul țintă după o regulă strictă și nu alege niciodată „primul disc”.

  • Omite mediul de pe care a pornit.
  • Omite discurile amovibile, cu excepția cazului în care volumul seed indică unul.
  • Omite orice disc care are deja o tabelă de partiții, de orice tip.
  • Omite discurile sub 64 GB și afișează acest lucru pe consolă.
  • Instalează doar atunci când rămâne exact un singur disc.

Pe un server cu două discuri goale, se oprește și vă cere să alegeți. Alegerea se face indicând discul în volumul seed, cu wipe: true, aceasta fiind singura modalitate prin care va scrie vreodată pe un disc care are deja partiții.

Volumul NEXUS-SEED

Volumul seed este un volum mic, de obicei un stick USB, cu un sistem de fișiere etichetat NEXUS-SEED și un fișier seed.yaml la nivelul său superior (rădăcină). Programul de instalare îl montează doar pentru citire (read-only), citește setările și îl remontează cu drept de scriere doar la final, pentru a vă lăsa parola sistemului de operare.

# seed.yaml on the NEXUS-SEED volume
domain: harrow.example
adminEmail: aoife.brennan@harrow.example
edition: enterprise
timeout: 45m
Cheie Ce setează Când lipsește
domain Domeniul instalării. Programul de instalare derivă cele trei gazde (hosts) din acesta: console.<domain>, api.<domain> și auth.<domain>. Solicitat pe consola serverului
adminEmail Adresa de e-mail a persoanei care va fi primul administrator Solicitat pe consola serverului
edition community sau enterprise. Când este setat, trebuie să corespundă cu ediția pachetului. Preluat din pachet
timeout Cât timp pot dura instalarea cert-manager și a Nexus, sub forma unei durate precum 30m sau 1h 30m
time Ora curentă în UTC, în formatul afișat de mesajul ceasului (2026-11-14T09:00:00Z), pentru o mașină al cărei ceas hardware nu poate fi setat sau nu își păstrează setarea. O mașină offline nu are niciun server de timp pe care să îl interogheze. Se utilizează ceasul hardware
disk Discul țintă, sub forma /dev/<name>, utilizat doar împreună cu wipe: true Regula discului gol de mai sus
wipe true permite programului de instalare să șteargă discul indicat de disk Niciun disc nu este șters vreodată

Pentru Enterprise, puneți fișierul de licență pe același volum ca licence.json. Fără acesta, prima pornire se oprește la pasul seed și indică faptul că licența lipsește. Ediția Community nu necesită licență, iar pentru Community întregul volum seed este opțional: programul de instalare solicită domeniul și adresa de e-mail pe consolă și continuă.

Programul de instalare citește fiecare rând ca key: value la începutul rândului. Scrieți câte o cheie pe rând, la nivelul superior, fără ghilimele și fără indentare. O valoare între ghilimele este citită împreună cu ghilimelele sale.

La prima pornire, programul de instalare solicită pe consolă și custodele depozitului de chei (key store): jumătatea publică a unei chei age, age1..., generată pe propria mașină a custodelui cu age-keygen -o custodian.key. Depozitul de chei își sigilează cheile de recuperare cu aceasta. Capitolul 2.8, Instalări pe o singură mașină, explică rolul custozilor. Custodele păstrează jumătatea privată offline și în siguranță: fără aceasta, nimeni nu poate desigila depozitul de chei după o repornire.

Ce se întâmplă, de la pornire până la adresa consolei

Etapa întâi: sistemul de operare

Imaginea pornește într-un program de instalare Debian neasistat. Acesta nu configurează o rețea, nu utilizează un server oglindă și nu instalează niciun pachet în afara sistemului de bază. Setează fusul orar la UTC (Coordinated Universal Time), dezactivează autentificarea ca root și creează un singur utilizator, nexus, a cărui parolă este blocată. Alege discul țintă conform regulii de mai sus și scrie un disc GPT (globally unique identifier partition table) cu o partiție de sistem EFI (Extensible Firmware Interface) și un sistem de fișiere rădăcină ext4, fără partiție swap.

La final, copiază programul de instalare Nexus pe noul sistem, verifică fiecare fișier copiat în raport cu lista de sume de control a imaginii și activează un serviciu de primă pornire. Dacă vreun fișier copiat nu corespunde, se oprește în acel punct. Apoi ejectează mediul de stocare și repornește.

Etapa a doua: prima pornire

La prima pornire, serviciul nexus-install rulează o singură dată. Fiecare pas este afișat pe consola serverului și în jurnal, și se înregistrează ca finalizat, astfel încât o reîncercare pornește de la primul pas nefinalizat. Serviciul în ansamblu poate rula timp de până la patru ore înainte ca systemd să îl oprească, ceea ce lasă timp suficient pentru un disc lent și o așteptare de o oră pentru conectarea stick-ului cu pachetul.

  1. Preflight. Arhitectura, ceasul, memoria și spațiul liber pe disc, conform tabelului de mai sus.
  2. Payload. Fișierele proprii ale programului de instalare: semnătura de pe lista sa de sume de control folosind cheia de lansare pe care o conține, apoi fiecare fișier în raport cu acea listă.
  3. Seed. Citește seed.yaml și solicită pe consolă orice informație care lipsește.
  4. Bundle. Găsește volumul etichetat NEXUS-BUNDLE și îl montează doar pentru citire. Dacă nu există niciunul, afișează waiting-for-bundle și așteaptă până la o oră să îl atașați. Apoi rulează verificarea completă a pachetului, care se încheie cu VERIFY-BUNDLE PASS, folosind cheia de lansare pe care o conține, înainte ca orice să fie importat. Un pachet Enterprise necesită licence.json pe volumul seed, iar ediția din seed trebuie să corespundă cu cea a pachetului.
  5. k3s. Instalează k3s v1.33.6+k3s1 din fișierele proprii ale imaginii, cu descărcările dezactivate, și așteaptă până la zece minute ca nodul să devină Ready. Apoi elimină arhiva de imagini air-gap a k3s, astfel încât imaginile să nu fie importate din nou la fiecare pornire.
  6. Import. Importă fiecare imagine verificată din pachet, precum și imaginile cert-manager, în depozitul de containere al nodului. Nimic nu este descărcat vreodată dintr-un registru.
  7. cert-manager, apoi Nexus. Instalează cert-manager v1.21.3, apoi diagrama (chart) Nexus din pachet, ambele încadrându-se în timeout specificat în seed.
  8. Acceptance. Verifică dacă fiecare pod este în starea Running și fiecare Job de tip hook s-a finalizat.
  9. Credential. Atribuie utilizatorului de sistem de operare nexus o parolă aleatorie nouă, o afișează o singură dată pe consolă și o scrie în nexus-os-password.txt pe volumul seed atunci când volumul permite scrierea.

Verificarea pachetului de la pasul 4 este același script pe care îl rulați manual în capitolul 2.10, Instalarea fără conexiune la rețea (air-gapped), și afișează aceleași rânduri:

  1 SHA256SUMS OK files=<n>
  2 SHA256SUMS signature OK
  3 images signed + SBOM-attested: <n>
  4 helm lint --strict OK nexus-1.0.0-alpha.1.tgz
  5 coverage OK rendered=<n> lock=<n>
  6 source offer OK images=5 files=<n>
VERIFY-BUNDLE PASS files=<n> images=<n>

Rândul 3 numără imaginile care poartă o semnătură validă și un SBOM (software bill of materials) semnat, adică lista cu ceea ce conține fiecare imagine. Numărul acestora (<n>) depinde de ediție. Ceea ce contează este ultimul rând.

Instalarea scrie valorile în forma curentă a diagramei: global.domain și cele trei nume hosts.* derivate din domeniul volumului seed, precum și keys.custody.recipients de la custodele pe care l-ați furnizat pe consolă. Instalează din diagrama și imaginile proprii ale pachetului, astfel încât versiunea de pe disc este exact versiunea care a fost verificată.

Un lanț orizontal de nouă casete: Preflight, Payload, Seed, Bundle, k3s, Import, cert-manager și Nexus, Acceptance, Credential. Sub fiecare casetă, o etichetă roșie scurtă arată ce anume o oprește: „memorie, disc, ceas, arhitectură”, „semnătură sau sumă de control”, „fără domeniu sau e-mail; fără licență pentru Enterprise”, „fără NEXUS-BUNDLE în 1 h; VERIFY-BUNDLE FAIL”, „nodul nu este Ready în 10 min”, „o imagine nu se poate importa”, „instalarea helm eșuează în timpul alocat”, „un pod nu rulează, un Job nu este finalizat” și nimic sub Credential. O săgeată de întoarcere de la fiecare casetă către începutul lanțului este etichetată „reîncercarea nexus-install reia de la primul pas nefinalizat”.
Prima pornire a imaginii de instalare, pas cu pas, fiecare pas putând opri instalarea.

Ultimele rânduri de pe consolă

Când toți pașii au fost parcurși cu succes, consola afișează o singură dată parola sistemului de operare și adresa care trebuie deschisă:

nexus-install: OS login: user nexus, password <shown-once>  (shown once; change it with passwd)
nexus-install: DONE: https://console.harrow.example  (add to /etc/hosts: 10.20.4.15 console.harrow.example api.harrow.example auth.harrow.example)

Notați parola sau preluați-o de pe stick-ul seed, apoi autentificați-vă ca nexus și schimbați-o cu passwd. Nimeni, inclusiv Adverant, nu cunoaște o parolă implicită pentru această mașină, deoarece nu există una.

Adresa din rândul hosts este propria adresă a serverului. Neavând DNS (Domain Name System) pe chei, Tomás a adăugat acel unic rând în fișierul hosts al fiecărui laptop care urma să utilizeze consola. Într-o locație cu DNS, adăugați în schimb înregistrări pentru cele trei nume.

Pregătit sau nu încă
Pregătit sau nu încă
După instalare, lista de verificare a disponibilității (readiness) include un test de trafic de ieșire, astfel încât un operator poate demonstra că nimic nu a încercat să părăsească serverul în ultima oră.

După instalare

Instalarea este nerevendicată. Nimeni nu se poate conecta până când cineva nu o revendică într-un browser, comparând amprenta instalării cu cea afișată de server. Capitolul 2.12, Prima rulare, acoperă revendicarea, primul administrator și cheia de acces (passkey). Primul administrator ar trebui să fie persoana a cărei adresă de e-mail se află în volumul seed.

Fișierul kubeconfig propriu al nodului se află la /etc/rancher/k3s/k3s.yaml, putând fi citit doar de root. Pentru a lucra pe cluster de pe o stație de lucru, nexusctl kubeconfig îl afișează, așa cum descrie capitolul 2.8, Instalări pe o singură mașină.

Actualizările sosesc în același mod în care s-a făcut și instalarea: o versiune pe un mediu semnat, verificată în raport cu cheia deja instalată pe server și niciodată în raport cu o cheie adusă de disc. Capitolul 2.10, Instalarea fără conexiune la rețea (air-gapped), descrie această verificare.

Revendică această instalare
Revendică această instalare
Pagina de revendicare care urmează instalării. Amprenta este afișată în opt grupuri de câte patru caractere, pentru a fi comparată rând cu rând cu consola serverului.

Dacă acest lucru eșuează

Fiecare eroare afișează nexus-install: FAILED <step>: <what is missing> pe consolă și scrie același lucru în /var/lib/nexus/install.state. Remediați cauza și rulați din nou instalarea de la primul pas care nu a fost finalizat:

sudo nexus-install retry
Mesaj Ce înseamnă Ce trebuie să faceți
FAILED preflight: payload is for arm64, this machine is amd64 Ați pornit imaginea destinată celeilalte arhitecturi. Utilizați imaginea corespunzătoare arhitecturii acestei mașini.
FAILED preflight: memory 11 GiB, need >= 16 GiB Mașina are resurse sub pragul minim. Adăugați memorie sau alocați mai multă mașinii virtuale (VM).
FAILED preflight: free disk 38 GB on /, need >= 50 GB Sistemul de fișiere rădăcină este prea mic. Instalați pe un disc mai mare.
FAILED preflight: the clock (...) is older than the build (...); set the RTC or give time: in the seed Ceasul hardware este în urma datei la care a fost construit programul de instalare. Setați ceasul în firmware sau furnizați time în seed.yaml și reîncercați.
FAILED payload: SHA256SUMS signature does not verify Fișierele proprii ale programului de instalare nu corespund cu ceea ce a semnat Adverant. Opriți-vă. Descărcați din nou imaginea și verificați-o înainte de a o scrie.
FAILED seed: the installation domain and the first administrator e-mail are required Nici volumul seed, nici consola nu le-au furnizat. Adăugați-le în seed.yaml sau răspundeți la solicitările din consolă.
FAILED seed: Enterprise bundle: licence file missing on NEXUS-SEED (licence.json) Pachetul este Enterprise, iar volumul seed nu are licență. Puneți licence.json pe volumul seed.
FAILED bundle: no volume labelled NEXUS-BUNDLE within 1 h Nu a fost atașat niciun pachet în timp util. Atașați stick-ul cu pachetul și reîncercați.
FAILED bundle: the bundle does not verify with this installer's release key Verificarea pachetului nu s-a încheiat cu VERIFY-BUNDLE PASS. Propriul său rezultat, afișat deasupra mesajului, indică pasul respectiv. Opriți-vă. Nu utilizați acel pachet. Obțineți unul nou.
FAILED bundle: the seed asks for enterprise, the bundle is community Volumul seed și pachetul nu concordă. Corectați edition în volumul seed sau aduceți pachetul potrivit.
FAILED k3s: node not Ready within 10 min k3s nu a pornit. Verificați jurnalul pentru k3s, apoi reîncercați.
FAILED nexus: helm install nexus Diagrama nu s-a instalat în timpul alocat (timeout). Verificați kubectl -n nexus get pods,jobs, măriți valoarea timeout în volumul seed dacă mașina este lentă și reîncercați.
FAILED acceptance: pods not ready Unele poduri nu rulează după instalare. Mesajul indică până la cinci dintre ele. Citiți evenimentele acestora, remediați problema și reîncercați.
FAILED acceptance: jobs not complete: <jobs> Un Job de tip hook nu s-a finalizat. Citiți jurnalul Jobului indicat cu kubectl -n nexus logs job/<name>, remediați ceea ce raportează și reîncercați.

Înainte ca sistemul de operare să fie scris, alegerea discului poate opri și ea instalarea. Mesajul aferent începe cu nexus select-disk: REFUSED:. Cel mai frecvent este found 2 empty disks of >= 64 GB; need exactly one, or a NEXUS-SEED seed.yaml naming the disk with wipe: true. Indicați discul în volumul seed și porniți din nou.

Eșecul verificării pachetului este situația care trebuie tratată cu maximă seriozitate. Înseamnă că fișierele de pe disc nu sunt fișierele semnate de Adverant sau că a fost adăugat un fișier. Programul de instalare nu a importat nimic în acel moment, deci serverul este nemodificat. Păstrați discul pentru echipa dumneavoastră de securitate.