Versjon 1.0.0-alpha.1nyeste
Kapittel 2.10
Luftgap-installasjon
Ta med en signert frakoblet pakke inn til et anlegg uten internett, bekreft den mot en nøkkel du har tatt med separat, last den inn i ditt eget register og installer. Lisenser, oppdateringer og tilbakekallingslister krysser også gapet manuelt.
Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

Driftsnettverket til Harrow Port Authority har ingen rute til internett, verken etter loven eller i sin utforming. Fartøystrafikk, kaiplaner og tolltilbakehold ligger der alt sammen, og ingenting på nettverket har lov til å kalle ut. Da Tomás Reilly installerte Nexus der, ankom hver eneste byte på en disk som et bud brakte til portvakten, og hver eneste byte ble kontrollert inne på anlegget før noe tok den i bruk.
Dette kapittelet handler om den installasjonen. Du henter en signert frakoblet pakke, kontrollerer den med en nøkkel som kom frem til deg via en annen rute, kopierer avbildningene i den inn i ditt eget register, kontrollerer dem på nytt der, og installerer chartet med navnet på ditt eget register i verdiene. Deretter følger det et luftgap-isolert anlegg må gjøre manuelt, men som et tilkoblet anlegg får gratis: k3s og cert-manager uten nedlasting, oppdateringer på fysiske medier, lisenser gjennom en frakoblet utveksling og tilbakekallingslister du importerer selv.
Hva den frakoblede pakken inneholder
En pakke er én utgave av én utgivelse, som en ukomprimert tar-fil med en kontrollsumfil ved siden av: nexus-alpha-1.0.0-alpha.1-enterprise.tar og nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256. Community-pakker ligger offentlig ute på downloads.adverant.ai. Enterprise-pakker kommer fra Adverant-kontoen din på https://account.adverant.ai, ved siden av lisensen din, og aldri anonymt.
Utpakket ser den slik ut:
nexus-alpha-1.0.0-alpha.1-enterprise/
release/facts.json the release facts: version, edition, architectures, key fingerprint
release/facts-gaps.json the release facts the build couldn't record, each with its reason
release/images.lock.json every image by digest: index, per platform, its SBOMs
release/source-offer.json the sources of every copyleft data-tier image
release/source-offer.sha256 a checksum for each of those source files
images/<svc>/ one cosign save layout per image
charts/nexus-1.0.0-alpha.1.tgz the Helm chart
sbom/<edition>/<svc>-<arch>.spdx.json
source-offer/ the source files themselves
docs/INSTALL-AIRGAP.md
docs/example-values.yaml
docs/RELEASE-NOTES.md
SHA256SUMS a checksum for every file above
SHA256SUMS.sigstore.json the signature over SHA256SUMS, made with the release key
Hver images/<svc>/-katalog er det cosign save skriver. Den inneholder avbildningsindeksen og begge plattformavbildningene, linux/amd64 og linux/arm64, med cosign-signaturen, en SPDX SBOM-attestasjon (software bill of materials) for hver plattform og en opphavsattestasjon, alt laget med utgivelsesnøkkelen fra Adverant. De samme SBOM-ene ligger i sbom/ som vanlige filer, slik at et sikkerhetsteam kan lese dem uten cosign.
Datalaget inneholder copyleft-programvare: blant annet PostgreSQL med PostGIS og Neo4j Community Edition. Pakken inneholder kildekoden til hver avbildning i datalaget den leverer, og release/source-offer.json oppgir dette for hver avbildning. En pakke som ville ha levert en copyleft-binærfil uten kildekoden, blir ikke bygget.
release/facts.json navngir utgivelsen, utgaven, arkitekturene og fingeravtrykket til utgivelsesnøkkelen som pakken ble signert med, som sha256:<hex>.
Den offentlige nøkkelen fraktes separat
Pakken inneholder aldri nøkkelen som kontrollerer den. En pakke som hadde med seg sin egen nøkkel, kunne ha blitt byttet ut, med nøkkel og det hele, av hvem som helst, og enhver kontroll ville fortsatt ha blitt godkjent. Verifiseringsskriptet avviser en nøkkel som ligger inne i pakkekatalogen.
Hent den offentlige utgivelsesnøkkelen én gang, på en tilkoblet maskin, fra https://downloads.adverant.ai/nexus/1.0.0-alpha.1/. Lagre den som release.pub. Fingeravtrykket er SHA-256-verdien til filen:
sha256sum release.pubSammenlign dette med fingeravtrykket Adverant publiserer, og med det i utgivelsesnotatene du mottok via en separat kanal. Kapittel 2.4, Hente og verifisere en utgivelse, inneholder detaljene. Ta deretter med release.pub inn på anlegget, via en annen rute enn pakken hvis du kan, og oppbevar den der. Teamet til Tomás oppbevarer den på fildelingen til driftsnettverket med et notat om datoen den kom inn. Hver senere utgivelse kontrolleres mot den installerte nøkkelen, aldri mot noe en disk bringer med seg.
Bekreft pakken
verify-bundle.sh er skriptet som kontrollerer en pakke, og publiseres med hver utgivelse. Diskavbildningen for installasjonsprogrammet kjører det samme skriptet ved første oppstart. Det krever cosign v3, helm v4 og sha256sum eller shasum. Det leser ingenting fra noe nettverk og trenger ikke Python, så det kjører like godt på en ren installasjonsnode som på en arbeidsstasjon.
- Kontroller tar-filen mot kontrollsummen, og pakk den deretter ut:
sha256sum -c nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256
tar -xf nexus-alpha-1.0.0-alpha.1-enterprise.tar- Kjør verifiseringen med nøkkelen du tok med inn:
./verify-bundle.sh nexus-alpha-1.0.0-alpha.1-enterprise release.pubEt tredje argument angir en verdifil for chart-kontrollene. Uten det bruker skriptet pakkens docs/example-values.yaml.
- Les den siste linjen, som må være
VERIFY-BUNDLE PASSfør du går videre.
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>
Skriptet stopper ved den første kontrollen som feiler. Her er hva hver enkelt gjør.
| Trinn | Hva det kontrollerer |
|---|---|
| 1 | Hver fil som er oppført i SHA256SUMS, samsvarer med kontrollsummen sin, og ingen fil er til stede som ikke står på listen. En ekstra fil som er plassert der, fører like sikkert til feil som en endret fil. |
| 2 | SHA256SUMS.sigstore.json er en gyldig signatur over SHA256SUMS med nøkkelen du oppga. Med trinn 1 og 2 sammen er hver byte i pakken den byten Adverant signerte. |
| 3 | For hver avbildningskatalog: avbildningens indeks-digest finnes i release/images.lock.json; det finnes en cosign-signatur der emnet er nøyaktig denne digest-verdien, og den verifiseres mot nøkkelen din; både cosign verify og cosign verify-attestation --type spdxjson blir godkjent på den lagrede strukturen. |
| 4 | helm lint --strict blir godkjent på chartet med eksempelverdiene, eller med dine egne. |
| 5 | Hver avbildning i låsefilen er lagret i images/, og hver avbildning som chartet genererer, er en digest-verdi i låsefilen. Ingenting som chartet installerer, kommer fra noe annet sted. |
| 6 | Når låsefilen inneholder avbildninger for datalaget, er release/source-offer.json fullstendig, navngir hver eneste en av dem, og hver kildefil den lister opp, er til stede med riktig kontrollsum. |
Trinn 3 kontrollerer selve signaturen, via digest, i tillegg til å kjøre cosign verify. Årsaken er cosigns egen oppførsel: cosign verify på en lagret struktur avslutter også med 0 når strukturen kun inneholder en attestasjon med nøkkelen og ingen signatur. Skriptet godtar ikke det.
Hvis dette feiler
En feil slutter med VERIFY-BUNDLE FAIL step=<k> <why>.
| Siste linje | Hva det betyr | Hva du skal gjøre |
|---|---|---|
step=0 the public key must come from outside the bundle |
Nøkkelen du oppga, ligger inne i pakkekatalogen. | Bruk nøkkelen du tok med inn separat. |
step=1 checksum mismatch |
En fil ble endret etter at listen ble laget, eller ble skadet under overføring. | Kopier pakken på nytt fra det opprinnelige mediet og kontroller på nytt. |
step=1 files not covered by SHA256SUMS |
En fil ble lagt til i pakken. | Behandle mediet som upålitelig. Ikke installer fra det. |
step=2 SHA256SUMS signature does not verify |
Kontrollsumlisten er ikke signert med utgivelsesnøkkelen du har. | Stopp. Rapporter det til sikkerhetsteamet ditt og be Adverant om nye medier. |
step=3 image <svc>: ... |
Signaturen eller SBOM-attestasjonen til en avbildning mangler eller lar seg ikke verifisere. | Stopp, som for trinn 2. |
step=4, step=5 |
Chartet eller avbildningslisten henger ikke sammen. | Be Adverant om en ny pakke. |
step=6 ... |
Kildekodetilbudet er ufullstendig. | Be Adverant om en ny pakke. |
At trinn 2 og 3 feiler, er akkurat det tilfellet hele denne utformingen er laget for. Det betyr at filene ikke er dem Adverant signerte. Ta vare på mediet for sikkerhetsteamet ditt.
Last avbildningene inn i ditt eget register
Nodene dine henter avbildninger fra et register inne på anlegget. Harrows er registry.harrow.example. Hver Nexus-avbildning legges under stien nexus/ i det registeret, fordi chartet refererer til hver avbildning som <global.imageRegistry>/nexus/<svc>@<digest>.
- Logg inn i registeret ditt med verktøyet du vanligvis bruker, slik at
cosignkan pushe til det. - Fra innsiden av pakkekatalogen laster du inn hver avbildning og verifiserer den på nytt på det nye stedet:
REG=registry.harrow.example
jq -r '.images[] | "\(.svc) \(.index)"' release/images.lock.json | while read -r svc digest; do
cosign load --dir "images/$svc" "$REG/nexus/$svc"
cosign verify --key release.pub --insecure-ignore-tlog=true "$REG/nexus/$svc@$digest" > /dev/null \
&& cosign verify-attestation --key release.pub --insecure-ignore-tlog=true --type spdxjson "$REG/nexus/$svc@$digest" > /dev/null \
&& echo "verified $svc"
donecosign load tar med seg signaturen og hver attestasjon sammen med avbildningen, slik at kopien i registeret kan verifiseres mot den samme nøkkelen. Verifiseringen her er den som teller for klyngen din: den beviser at det nodene dine vil hente, er det Adverant signerte.
verified nexus-alpha
verified nexus-auth
verified nexus-postgres
...
Hver avbildning i låsefilen skal skrive ut én verified-linje. En manglende linje betyr at innlastingen eller kontrollen av den avbildningen feilet, og feilmeldingen skrives ut rett over.
Det finnes ingen transparenslogg for Nexus-utgivelser, så --insecure-ignore-tlog=true er nødvendig ved hver kontroll. Utgivelsesnøkkelen er hele tillitsroten. Uten dette flagget avviser cosign med not enough verified log entries from transparency log: 0 < 1.
Installer fra registeret ditt
Verdifilen for en luftgap-isolert installasjon skiller seg fra en tilkoblet installasjon på én linje: global.imageRegistry oppgir registeret ditt.
# harrow-prod-values.yaml (Helm values)
global:
imageRegistry: registry.harrow.example
domain: harrow.example
hosts:
console: console.harrow.example
api: api.harrow.example
auth: auth.harrow.example
edition: enterprise
enterprise:
enabled: true
tls:
mode: existing
existingSecret: harrow-public-tls
storage:
className: harrow-ssd
keys:
installationName: harrow-port
custody:
recipients:
- "<custodian-one-age-recipient>"
- "<custodian-two-age-recipient>"Oppføringene i <custodian-...-age-recipient> er de offentlige age1...-linjene til personene som sitter på gjenopprettingsnøklene til nøkkellageret. Kapittel 2.8, Enkeltmaskininstallasjoner, forklarer hvordan hver enkelt lager en slik. harrow-ssd er Harrows egen lagringsklasse: sett inn din egen, eller utelat storage.className for å bruke klyngens standard.
- Kjør forhåndskontroll (preflight) mot klyngen med denne filen, slik kapittel 2.5, Forhåndskontroll med nexusctl, beskriver.
- Installer fra pakkens chart, og utelat
--wait.
helm install nexus charts/nexus-1.0.0-alpha.1.tgz -n nexus --create-namespace \
-f harrow-prod-values.yaml --timeout 45m
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900shelm install --wait går i vranglås med dette chartet: en post-install-hook gir hver tjeneste sitt databasepassord, og --wait holder tilbake hooks til tjenestene er oppe. Kapittel 2.8, Enkeltmaskininstallasjoner, har løkken som også venter på StatefulSets.
Med nexusctl er den samme installasjonen nexusctl install --context <kube-context> --values harrow-prod-values.yaml.
Ingenting i chartet kontakter noe utenfor navnerommet bortsett fra DNS (Domain Name System), Kubernetes API (application programming interface) for gjennomgang av tokener og eventuelle adresser du lister opp i networkPolicy.externalEgressCIDRs, som er tom som standard. Ingen telemetri forlater installasjonen, og telemetry.enabled kan ikke settes til noe annet enn false. For KI (kunstig intelligens) på et anlegg uten internett kobler organisasjonen til sin egen OpenAI-kompatible modellserver inne på anlegget, oppgitt i ai.localProvider.baseUrl; kapittel 2.14, KI-leverandører og -modeller, dekker dette.
Lisensen er ikke en chart-verdi. Du importerer den etter installasjonen, som beskrevet nedenfor.
k3s og cert-manager uten nedlasting
Hvis Nexus skal inn på en k3s-klynge du bygger selv, må k3s også installeres uten nettverk. Diskavbildningen for installasjonsprogrammet gjør dette for deg (kapittel 2.9, Diskavbildningen for installasjonsprogrammet). Manuelt, på hver node:
- Ta med over utgivelsesfilene for k3s v1.33.6+k3s1 for arkitekturen din: binærfilen
k3s(k3s-arm64på arm64),install.sh,k3s-airgap-images-<arch>.tar.zstogsha256sum-<arch>.txt. k3s publiserer kontrollsummer for disse filene og ingen signatur. Kontroller hver fil motsha256sum-<arch>.txt, og vær tydelig overfor sikkerhetsteamet ditt på at dette er en kontrollsum fra samme kilde, ikke en signatur. - Plasser binærfilen og systemavbildningene der k3s ser etter dem, og installer med nedlastinger slått av:
sudo install -m 0755 k3s /usr/local/bin/k3s
sudo mkdir -p /var/lib/rancher/k3s/agent/images
sudo cp k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/
sudo INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC="--write-kubeconfig-mode=0600" sh install.sh
sudo k3s kubectl wait --for=condition=Ready node --all --timeout=600scert-manager v1.21.3 er en forutsetning: chartets egen CA (certificate authority) er en cert-manager-utsteder. Ta med over chartet til cert-manager, cert-manager-v1.21.3.tgz, og tilhørende avbildninger. På den tilkoblede siden kontrollerer du avbildningene med cert-manager-prosjektets egen nøkkel før de krysser over:
cosign verify --signature-digest-algorithm sha512 --insecure-ignore-tlog=true \
--key cert-manager-pubkey-2021-09-20.pem quay.io/jetstack/<image>@<digest>Inne på anlegget importerer du avbildningene til containerlageret på hver node under de navnene cert-manager-chartet ber om, quay.io/jetstack/cert-manager-<name>:v1.21.3, før du kontrollerer dem og installerer:
sudo k3s ctr -n k8s.io images import --all-platforms cert-manager-images.tar
sudo k3s ctr -n k8s.io images ls -q | grep cert-manager
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
--create-namespace --set crds.enabled=true --wait --timeout 10m--wait er riktig for cert-manager. Det er bare Nexus som ikke må ha det.
Oppdateringer og nye deler leveres på signerte medier
Et luftgap-isolert anlegg oppgraderer også fra en disk. I konsollen laster Importer fra medier på sidene for Denne installasjonen inn en utgivelse fra en disk som er brakt inn på anlegget. Den kontrollerer kontrollsummen for hver fil, deretter signaturen mot utgivelsesnøkkelen som allerede er installert på anlegget, aldri en nøkkel disken har med seg, og deretter at utgivelsen er nyere enn den som kjører. Importering bare kopierer og kontrollerer. Folk fortsetter å jobbe på den kjørende utgivelsen, og ingenting endres før du velger å oppgradere.
Fra kommandolinjen legges den samme utgivelsen inn med nexusctl:
nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar
nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tarplan viser hva som vil endres, og endrer ingenting. apply tar en sikkerhetskopi først og oppgraderer deretter. Kapittel 2.15, Dag to: drift av Nexus, dekker oppgraderinger i sin helhet.
Når signaturen på en disk ikke stemmer, avvises importen med MEDIA_SIGNATURE_INVALID. Ingenting lastes eller kopieres inn, og den kjørende utgivelsen fortsetter å kjøre. Siden oppgir hvilke kontroller som ble godkjent, hvor den stoppet, og hvilken nøkkel den forventet ved siden av nøkkelen den fant. Ta vare på disken for sikkerhetsteamet ditt, og be Adverant om en ny.
Enterprise-delene som en lisens slår på, kommer på samme måte på et luftgap-isolert anlegg: på utgivelsesdisken, gjennom Importer fra medier, før du slår dem på. Hver del kontrolleres mot utgivelsesnøkkelen fra Adverant før den slås på, slik at du aldri kopierer en binærfil inn i klyngen manuelt.
Lisenser uten internett
En tilkoblet installasjon mottar lisensen sin av seg selv. En luftgap-isolert installasjon utveksler filer med Adverant manuelt, gjennom den frakoblede utvekslingen.
- Lisenssidene i konsollen lager en liten fil med en lisensforespørsel. Installasjonen signerer den med sin egen nøkkel, slik at Adverant kan se hvilken installasjon som ba om den.
- Noen tar med filen ut på en USB-minnepinne til en datamaskin som er på nett, logger inn på Adverant-kontoen på
https://account.adverant.aiog laster den opp på siden Frakoblet utveksling. - De tar med lisensfilen tilbake på samme måte.
- Importer den. I konsollen åpner du Lisens og hva den låser opp og trykker på Importer en ny lisens. Fra kommandolinjen:
nexusctl licence import harrow-port-licence.jsonLisensen kontrolleres frakoblet, inne på anlegget, mot Adverants nøkler. Adverant signerer hver lisens med to uavhengige nøkler, og begge signaturene må kunne verifiseres.
Den samme utvekslingen frakter den årlige bruksoppgaven ut. Den inneholder kun tellere (seter, enheter, funksjonsgrupper), og administratoren leser den linje for linje på Bruksoppgave for Adverant før den sendes ut.
| Kode | Status | Hva det betyr |
|---|---|---|
LICENCE_SIGNATURE_INVALID |
422 | Filen er ikke en lisens Adverant har signert, eller så har en byte blitt endret etter signering. Ingenting endres. |
LICENCE_OTHER_INSTALLATION |
409 | Lisensen er ekte, men ble utstedt for en annen installasjon. Be om en som er utstedt for denne installasjonens ID. |
LICENCE_CLOCK_BEHIND_FLOOR |
409 | Klokken viser et tidligere tidspunkt enn det seneste tidspunktet denne installasjonen har registrert. Å stille klokken tilbake gjenoppliver ikke en utløpt lisens. |
LICENCE_REVOKED |
403 | Adverant trakk tilbake lisensen med en signert tilbakekalling. Enterprise-deler slutter å bli tilbudt; Community og eksport forblir tilgjengelige. |
Kapittel 2.13, Lisenser, dekker tilstander, respittperiode og fornyelse.
Tilbakekallingslister importeres manuelt
Når Adverant trekker tilbake en lisens, publiseres det en signert tilbakekallingsliste. Listen er kumulativ: hver liste inneholder alle lisenser som er trukket tilbake før den. En tilkoblet installasjon får vite om det automatisk. En luftgap-isolert installasjon får bare vite om det når noen importerer listen, så ta med den nyeste listen inn sammen med hver utgivelsesdisk og importer den gjennom installasjonens importfunksjon for tilbakekallinger på lisenssidene, eller via /api/v1/installation/licence/revocations-adressen på innloggingsverten.
Dette slår begge veier. En luftgap-isolert installasjon som aldri importerer en liste, får aldri vite at en lisens ble tilbakekalt, inkludert en lisens signert med en nøkkel som senere viste seg å være kompromittert. Å importere listen er den eneste måten den informasjonen krysser gapet på.
Den suverene forseglede pakken: nexus-airgap
Noen suverene anlegg ønsker en utgivelse som én forseglet, signert fil der selve manifestet forbyr nettverkstilgang. For dem finnes det et annet format, den forseglede pakken, og det tilhørende verktøyet, nexus-airgap, fra pakken @adverant/nexus-sovereign. Installer verktøyet fra Adverants pakkeregister, separat fra enhver pakke det skal kontrollere. En pakke kan ikke gå god for seg selv.
Den forseglede pakken er en enkelt signert tarball. Manifestet er signert med Ed25519 og lister opp en SHA-256 for hver fil. Verktøyet har fire kommandoord.
| Kommandoord | Hva den gjør |
|---|---|
nexus-airgap bundle |
Bygger en forseglet pakke fra en klargjort katalog og signerer manifestet. |
nexus-airgap verify --bundle <file> --trusted-key <pem> --profile <profile> |
Kontrollerer signaturen mot den klarerte nøkkelen, beregner hash for hver fil på nytt, avviser enhver fil som manifestet ikke lister opp, og avviser en pakke der nettverksregelen ikke er den tomme tillatelseslisten med kun lokal agenttrafikk. Endrer ingenting. |
nexus-airgap install |
Verifiserer, og utfører deretter installasjonsplanen i rekkefølge: last inn avbildningene, ta i bruk manifestene, kjør migreringene, legg inn ferdighetene (skills), klargjør nøklene. |
nexus-airgap open |
Åpner pakkens valgfrie krypterte eksport med anleggets egen nøkkelforvalter, som på et luftgap-isolert anlegg er maskinens TPM-brikke (Trusted Platform Module). |
Verifiser før alt annet:
nexus-airgap verify --bundle nexus-alpha-1.0.0-alpha.1.tar.gz \
--trusted-key release.pub --profile airgap --keep-staging > verify.json
jq '{ok, bundleId, profile, artifactsVerified}' verify.json--keep-staging beholder den verifiserte, utpakkede kopien og navngir den som stagingDir i utdataene, slik at du arbeider ut fra det som ble kontrollert.
Hvis verifiseringen feiler med BUNDLE_INTEGRITY_VIOLATION, ble en fil inne i pakken endret etter at den ble signert. Stopp der. Verktøyet har et --no-strict-flagg som hopper over kontrollen av filer som ikke er oppført. Ikke bruk det på en utgivelse.
Dagen den neste disken kommer
Tomás har en kort sjekkliste teipet fast på innsiden av skapet i portvakten, og den er verdt å kopiere. Kontroller tar-filens .sha256. Kjør verify-bundle.sh med den installerte nøkkelen og les den siste linjen. Importer den nyeste tilbakekallingslisten. Først da, og kun da, importerer du utgivelsen fra mediet og planlegger oppgraderingen. En disk som feiler på et av disse trinnene, legges tilbake i konvolutten sin, merket, til sikkerhetsteamet, og ingenting på nettverket har blitt endret.


