InloggenBriefing plannen

Hoofdstuk 2.4

Een release ophalen en verifiëren

Waar elk onderdeel van een Nexus-release staat, hoe Enterprise-images worden opgehaald met een pull-token, en hoe u offline bewijst dat elke image, chart en download ongewijzigd van Adverant afkomstig is, voordat u iets installeert.

Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

15 minuten leestijd

Elke image in een Nexus-release is ondertekend met de releasesleutel van Adverant, en elke image wordt aangeduid met zijn digest, nooit met een tag. De chart rendert uitsluitend images die op basis van hun digest zijn opgenomen in het eigen images-lockbestand. Samen betekent dit dat u op uw eigen werkstation en zonder verbinding met wie dan ook kunt bewijzen dat wat u op het punt staat uit te voeren, exact is wat Adverant heeft gebouwd.

Bij Harrow Port Authority hebben we vóór de eerste installatie alles gecontroleerd. Het duurde ongeveer twintig minuten, waarvan het grootste deel bestond uit de lus over de images. Dit hoofdstuk volgt hetzelfde pad: waar elk onderdeel van de release zich bevindt, het pull-token voor Enterprise-images, het images-lockbestand, de controles met cosign inclusief de exacte opdrachten, en wat u moet doen als een controle mislukt.

Waar de release staat

Adres Wat u daar ophaalt
registry.adverant.ai De platform-images, op registry.adverant.ai/nexus/<service>@sha256:<digest>, en de Helm-chart, op oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ De openbare releasesleutel en de bijbehorende vingerafdruk, de binaire bestanden van nexusctl en de offline bundels
https://account.adverant.ai Uw Adverant-account: Downloads, Pull-tokens en installatieopdrachten, Implementaties en de licentiepagina's

Community-images en de Community-chart zijn openbaar; u kunt ze ophalen zonder in te loggen. Enterprise-images worden opgehaald met een pull-token uit uw account, en de Enterprise-chart en -bundel staan op de pagina Downloads van het account, die uw licentie volgt.

Downloads
Downloads
Downloads in het Adverant-account, per versie en kanaal. Naast elk bestand staan de bijbehorende controlesom en handtekening, en onderdelen die buiten de licentie vallen blijven zichtbaar in het grijs, met opgave van de reden.

Lees eerst de releasenotes

De releasenotes worden in elke bundel meegeleverd als docs/RELEASE-NOTES.md, vermeld in de bijbehorende SHA256SUMS, en dezelfde opmerkingen staan op de releasepagina in uw account. Lees ze voordat u installeert of upgradet. Voor 1.0.0-alpha.1 zijn ze kort. Het is de eerste release, dus een schone installatie heeft geen van de daarin beschreven upgradepunten, en de lijst met bekende problemen vermeldt dat niets daarin van invloed is op een schone installatie die de gedocumenteerde stappen volgt. Latere releases vermelden elk bekend probleem met de versie waarin het wordt opgelost.

De releasepagina vermeldt ook, in drie regels, wat een alfarelease belooft: functies kunnen nog veranderen vóór de eerste stabiele versie, een upgrade behoudt uw gegevens en maakt eerst een back-up, en beveiligingsfixes verschijnen binnen 7 dagen. We hebben die pagina afgedrukt en in het wijzigingsdossier bij Harrow gevoegd, omdat dit het dichtst in de buurt komt van een ondersteuningsverklaring waar de wijzigingscommissie om zou vragen.

Stap 1: haal de releasesleutel op en controleer deze via een tweede route

Alles hieronder steunt op één bestand: de openbare releasesleutel van Adverant. Een sleutel die afkomstig is van dezelfde plek als hetgeen waarvoor hij instaat, bewijst heel weinig; controleer de vingerafdruk daarom aan de hand van een kopie die u via een andere weg heeft bereikt.

  1. Download de sleutel uit de map van de release onder Downloads.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Bepaal de vingerafdruk ervan. De vingerafdruk is de SHA-256 (Secure Hash Algorithm 256) van het sleutelbestand zelf.

    sha256sum release.pub

    Op macOS geeft shasum -a 256 release.pub hetzelfde antwoord.

  3. Vergelijk deze, teken voor teken, met de vingerafdruk die is afgedrukt in uw contract met Adverant en in de releasenotes. Downloads publiceert de vingerafdruk ook, maar dat exemplaar kwam via dezelfde weg binnen als de sleutel en geldt dus niet als controle.

Als er ook maar één teken afwijkt, stop dan. Installeer niet en ga niet op internet op zoek naar een ander exemplaar van de sleutel. Dien een ondersteuningsverzoek in vanuit uw account en vermeld wat u heeft gezien.

Stap 2: haal nexusctl op

nexusctl is de opdrachtregelinterface (CLI) voor de Nexus-beheerder. Deze draait op uw werkstation en leest uw cluster uit via uw kubeconfig. Downloads biedt vier builds:

Bestand Platform
nexusctl-linux-amd64 Linux op Intel of AMD
nexusctl-darwin-arm64 macOS op Apple silicon
nexusctl-darwin-amd64 macOS op Intel
nexusctl-windows-amd64.exe Windows

Naast elk bestand staat de bijbehorende handtekeningbundel, met dezelfde naam en .sigstore.json aan het einde. Controleer het binaire bestand voordat u het uitvoert:

curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64.sigstore.json
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle nexusctl-linux-amd64.sigstore.json nexusctl-linux-amd64
Verified OK

Zet het vervolgens in uw PATH en vraag de versie op:

install -m 0755 nexusctl-linux-amd64 /usr/local/bin/nexusctl
nexusctl version

Vanaf dit punt kan nexusctl verify de bestandscontroles voor u uitvoeren. Hoofdstuk 2.5, Preflight met nexusctl, behandelt de hoofdtaak ervan: de preflight.

Waarom de vlag "insecure" heet

Elke cosign-opdracht in dit hoofdstuk bevat --insecure-ignore-tlog=true. Nexus-releases worden ondertekend met de sleutel van Adverant en niet vastgelegd in een openbaar transparantielogboek, zodat er voor het controleren van een release nooit een verbinding met wie dan ook nodig is, ook niet met Sigstore. Standaard eist cosign een logboekvermelding; de vlag geeft de opdracht om uitsluitend op de sleutel te vertrouwen. Zonder deze vlag mislukt de controle als volgt:

Error: not enough verified log entries from transparency log: 0 < 1

Wanneer de vlag is ingesteld, drukt cosign nog steeds de zin "Existence of the claims in the transparency log was verified offline" af. Dat is een vaste formulering in cosign; er zit geen logboekvermelding achter. De handtekeningcontrole tegen de sleutel is echt, en dat is het deel waar het om gaat.

Stap 3: een pull-token, voor Enterprise

Enterprise-images bevinden zich achter een pull-token. U maakt er een aan in uw account, onder Pull-tokens en installatieopdrachten:

  1. Druk op Een token toevoegen.
  2. Geef aan voor welk cluster het bestemd is, wat het mag ophalen en wanneer het verloopt.
  3. Druk op Het token kopiëren en plak het direct op de plek waar u inloggegevens bewaart, want de pagina toont het slechts deze ene keer.

Elk token is beperkt tot wat het mag ophalen en heeft een einddatum. Het intrekken van een token stopt nieuwe pulls onmiddellijk; images die een cluster al heeft opgehaald, blijven gewoon draaien. Bij Harrow hebben we één token per cluster aangemaakt, zodat het intrekken van het token van het testcluster de productieomgeving nooit raakt. Een Community-installatie heeft helemaal geen token nodig; u maakt er pas een aan wanneer u overstapt naar Enterprise, en dat kunt u op dezelfde dag nog doen.

Pull-tokens en installatieopdrachten
Pull-tokens en installatieopdrachten
Pull-tokens in het Adverant-account. Elk token toont wat het mag ophalen, wie het heeft aangemaakt en wanneer het verloopt; een nieuw token wordt één keer getoond, en het intrekken ervan stopt nieuwe pulls zonder te stoppen wat al draait.

De chart heeft geen waarde voor een pull-secret. Uw nodes halen de images op, dus het token hoort thuis bij de containerruntime van de nodes. Voeg op k3s het register toe aan /etc/rancher/k3s/registries.yaml op elke node en herstart k3s daar:

# /etc/rancher/k3s/registries.yaml (on every node)
configs:
  "registry.adverant.ai":
    auth: {username: "<registry-user>", password: "<pull-token>"}

<registry-user> is de gebruikersnaam voor het register uit uw Adverant-uitnodiging, en <pull-token> is het token dat u heeft gekopieerd. Het bestand bevat inloggegevens, dus zorg dat het alleen leesbaar is voor root.

Op een beheerd cluster waarvan de nodes dat bestand niet lezen, kopieert u de images naar een register dat uw nodes al vertrouwen en stelt u global.imageRegistry daarop in; elke node moet het Transport Layer Security (TLS)-certificaat van dat register vertrouwen. Hoofdstuk 2.11, Variaties: externe opslag, TLS en ingress, behandelt dat, en hoofdstuk 2.10, Air-gapped installatie, behandelt dezelfde kopieerslag voor een locatie zonder uitgaande verbinding.

Stap 4: lees het images-lockbestand

Een Nexus-chart verwijst nooit naar een image met een tag. Hij verwijst naar elke image met de digest van de bijbehorende multi-platformindex, afkomstig uit het images-lockbestand, een bestand dat de chart meelevert als files/images.lock.json. De offline bundel bevat hetzelfde lockbestand als release/images.lock.json.

Haal de chart op en pak deze uit om het lockbestand te lezen:

helm pull oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1
tar -xzf nexus-1.0.0-alpha.1.tgz
jq -r '.version, .edition' nexus/files/images.lock.json
1.0.0-alpha.1
community

Het hoogste niveau van het lockbestand vermeldt bij welke release en welke editie het hoort. Elk item onder images beschrijft één image:

Veld Wat het bevat
svc De service, zoals nexus-auth of nexus-postgres
index De sha256:-digest van de index van de image, die zowel linux/amd64 als linux/arm64 dekt
edition community, enterprise of all voor de datalaag
kind service, migrations of data-tier voor de vijf gegevensopslagplaatsen en OpenBao
verified Wanneer de release-build de bijbehorende handtekening en attestaties heeft geverifieerd

De chart rendert elke image als <global.imageRegistry>/nexus/<svc>@<index>. Met global.imageRegistry: registry.adverant.ai is de aanmeldservice dus registry.adverant.ai/nexus/nexus-auth@sha256: gevolgd door 64 hexadecimale tekens, en niets in het cluster kan deze verwisselen voor iets anders met dezelfde naam.

Het lockbestand is per editie. Een Community-lockbestand vermeldt alleen images waarvan de editie community of all is. Een Enterprise-lockbestand vermeldt die images plus de Enterprise-builds. De chart controleert dit elke keer bij het renderen en weigert bij twijfel in plaats van te gokken:

Wat de chart meldt Waarom
edition=enterprise but enterprise.enabled=false: they must agree De twee editiewaarden in uw values-bestand spreken elkaar tegen
files/images.lock.json is the community lock; this install is edition enterprise U installeert Enterprise vanuit de Community-chart, of andersom
image nexus-auth is not in files/images.lock.json De chart en het lockbestand horen niet bij elkaar; haal de chart opnieuw op
image ... is in the lock but was never verified by build-all Het item in het lockbestand heeft geen verificatietijdstip; installeer hier niet vanuit
NEXUS_EDITION_INVALID edition is leeg of is niet een van community en enterprise
RELEASE_VERSION_MISSING Het lockbestand vermeldt geen versie

Zet elke image en digest in één keer op een rij:

jq -r '.images[] | "\(.svc) \(.index)"' nexus/files/images.lock.json

Stap 5: verifieer de handtekening van elke image

Elke image-index is ondertekend, net als elk platformmanifest daarbinnen. Verifieer op basis van de digest, rechtstreeks vanuit het lockbestand, zodat u exact controleert wat de chart zal uitvoeren:

jq -r '.images[] | "\(.svc)@\(.index)"' nexus/files/images.lock.json |
while read -r ref; do
  cosign verify --key release.pub --insecure-ignore-tlog=true \
    "registry.adverant.ai/nexus/$ref" > /dev/null && echo "OK $ref" || echo "FAILED $ref"
done

Elke regel moet beginnen met OK. Op onze verbinding duurde de lus enkele minuten, waarvan het grootste deel bestond uit wachten op het register. De lus leest alleen de handtekeningen en haalt geen imagelagen op, waardoor het weinig kost om dit na elke upgrade te herhalen. Een regel met FAILED betekent stoppen: de volgende paragraaf legt uit wat elke melding betekent.

Voor één losse image laat u de omleiding weg en leest u wat cosign heeft gecontroleerd:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
The following checks were performed on each of these signatures:
  - Existence of the claims in the transparency log was verified offline
  - The signatures were verified against the specified public key

<digest> bestaat uit de 64 hexadecimale tekens uit index van het lockbestand voor die image. Enterprise-images hebben voor deze controle uw pull-token nodig, net als voor elke andere pull uit het register.

Een verticale keten van vijf kaders verbonden door neerwaartse pijlen. Boven: "Openbare releasesleutel, vingerafdruk gecontroleerd aan de hand van uw contract". Tweede: "Chartpakket nexus-1.0.0-alpha.1, ondertekend". Derde: "Images-lockbestand in de chart: elke image op index-digest, één editie". Vierde: "Elke image-index, ondertekend, met Software Bill of Materials (SBOM) en herkomstattestaties". Onder: "Pods in namespace nexus, opgehaald op digest". Een zijpijl vanuit het bovenste kader wijst naar het tweede en vierde kader, met het label "cosign verify, offline".
Wat waarvoor instaat, van de sleutel die u heeft gecontroleerd tot de pods die draaien.

Beide platformen, en wat u moet bewaren

Elke image-index bevat twee platformmanifesten, linux/amd64 en linux/arm64, en elk daarvan is ook ondertekend. cosign verify slaagt op de index-digest en op elk van beide platform-digests, zodat een cluster met gemengde nodes door dezelfde controle wordt gedekt. Om de twee platformen achter een index te zien, vraagt u bij het register de ruwe index op:

docker buildx imagetools inspect registry.adverant.ai/nexus/nexus-auth@sha256:<digest> --raw

De bijbehorende lijst manifests noemt één amd64-item en één arm64-item.

Bewaar de uitvoer van de bovenstaande lus bij uw wijzigingsdossier, naast de vingerafdruk die u heeft gecontroleerd. Wanneer iemand maanden later vraagt hoe u weet dat het cluster draait wat Adverant heeft geleverd, geven dat bestand en de digests van het lockbestand het antwoord. Onze auditor bij Harrow stelde precies die vraag, en het antwoord kostte één minuut.

Stap 6: lees de attestaties

Elke image bevat ook twee ondertekende attestaties, die tijdens het bouwen vanuit de image zijn aangemaakt: een Software Bill of Materials (SBOM) en een herkomstverklaring (provenance statement).

De SBOM heeft de vorm van Software Package Data Exchange (SPDX), één per platform, zodat een index er twee bevat. Deze vermeldt elk pakket in de image met de bijbehorende licentie. Vóór de release worden die licenties gecontroleerd aan de hand van een weigerlijst; geen enkele Community-image bevat code onder de GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) of Business Source License (BUSL). De herkomstverklaring is volgens Supply-chain Levels for Software Artifacts (SLSA) v1. Deze vermeldt de bron-commit waaruit de image is gebouwd, de digests van de basis-images en de bouwtools met hun versies, zodat een image terug te herleiden is tot de gecontroleerde broncode zonder Adverant te hoeven vragen.

Beide worden gecontroleerd met de releasesleutel die u al in bezit heeft:

cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type spdxjson registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type slsaprovenance1 registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

De spdxjson-controle drukt twee resultaten af, één voor de SBOM van elk platform. Om alles te zien wat aan een image is gekoppeld zonder het te verifiëren, gebruikt u cosign tree:

cosign tree registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

Deze toont één handtekeningbundel, twee spdx.dev/Document-attestaties en één slsa.dev/provenance/v1-attestatie. Vragen om een type dat de image niet bevat, zoals --type cyclonedx, mislukt met none of the attestations matched the predicate type: cyclonedx. Die foutmelding klopt; de release voegt SPDX bij, geen CycloneDX.

Stap 7: verifieer de chart en de downloads

De chart in het register is ondertekend op de bijbehorende OCI-digest (OCI staat voor Open Container Initiative, de indeling voor images en artefacten die registers gebruiken). helm pull drukt de opgehaalde digest af; controleer die digest op dezelfde manier als een image:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/charts/nexus@sha256:<chart-digest>

Voor een gedownload chartbestand, of voor de offline bundel, controleert nexusctl verify het bestand aan de hand van de releasesleutel van Adverant:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Een goed resultaat eindigt met het noemen van de releasesleutel van Adverant en het begin van de bijbehorende vingerafdruk. Vergelijk die groepen met de vingerafdruk die u in stap 1 heeft gecontroleerd.

De offline bundel bestaat uit één ongecomprimeerd tar-bestand per editie, nexus-alpha-1.0.0-alpha.1-community.tar of nexus-alpha-1.0.0-alpha.1-enterprise.tar, met daarnaast een .sha256-bestand. Binnenin bevat deze:

Pad Wat het is
release/images.lock.json Het images-lockbestand voor die editie
release/facts.json De releasegegevens: versie, editie, architecturen en de vingerafdruk van de releasesleutel
images/<service>/ Elke image met beide platformen, de bijbehorende handtekening en de attestaties
charts/nexus-1.0.0-alpha.1.tgz De chart
sbom/ De SPDX-SBOM van elke image, per platform
docs/ De releasenotes, de handleiding voor air-gapped installatie en voorbeeldwaarden
SHA256SUMS en SHA256SUMS.sigstore.json De controlesom van elk bestand en de bijbehorende handtekening

De openbare releasesleutel zit nooit in de bundel zelf; een sleutel die wordt meegeleverd met hetgeen hij ondertekent, bewijst niets. Controleer de volledige bundel met twee opdrachten, vanuit de bijbehorende map:

sha256sum -c SHA256SUMS
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS

Elke regel van de eerste opdracht moet eindigen op OK, en de tweede moet Verified OK afdrukken. Hoofdstuk 2.10, Air-gapped installatie, pakt de bundel vanaf daar verder op: het laden van de images in uw eigen register, het daar opnieuw verifiëren van elke image en de eigen end-to-end-controle van de bundel.

Een download controleren
Een download controleren
Een download controleren, in het Adverant-account. Twee offline controles, een voorbeeld van een goed en een fout resultaat, en de vingerafdruk van de releasesleutel in groepjes van vier om op het oog te vergelijken.

Wanneer een handtekening niet kan worden geverifieerd

Stop. Installeer niet en pas de opdracht niet aan totdat deze wel slaagt. Een mislukte handtekeningcontrole betekent dat het systeem werkt: het houdt in dat het bestand dat u heeft niet het bestand is dat Adverant heeft ondertekend, of dat de sleutel die u heeft niet van Adverant is.

Wat u ziet Wat het betekent Wat te doen
accepted signatures do not match threshold, Found: 0, Expected 1 (exit 1) De image is ondertekend, maar niet met de sleutel die u heeft opgegeven Controleer of u de releasesleutel heeft gebruikt waarvan u de vingerafdruk in stap 1 heeft gecontroleerd
no signatures found (exit 10) Er is niets ondertekend op die digest Controleer of de digest uit het lockbestand komt; verifieer nooit een tag
not enough verified log entries from transparency log: 0 < 1 --insecure-ignore-tlog=true ontbreekt Voeg de vlag toe; er is niets mis met de image
none of the attestations matched the predicate type U heeft gevraagd om een attestatietype dat de image niet bevat Gebruik spdxjson of slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature Een gedownload bestand is gewijzigd nadat het was ondertekend Download het opnieuw
FAILED van sha256sum -c Een bestand is niet het bestand waarvoor de controlesom is berekend Download het opnieuw

Als een download twee keer mislukt, dien dan vanuit uw account een ondersteuningsverzoek in en vermeld de bestandsnaam en de melding. Bewaar het falende bestand; uw beveiligingsteam wil het mogelijk onderzoeken.

Op een installatie die releases vanaf schijf laadt, voert de console dezelfde controles uit en weigert deze een release waarvan de handtekening niet overeenkomt met de geïnstalleerde sleutel, met MEDIA_SIGNATURE_INVALID. De console vermeldt wat er is gecontroleerd, in welke volgorde, waar het proces is gestopt en dat er niets is gewijzigd: er is geen image geladen en de draaiende versie is onaangeroerd gebleven.

Importeren vanaf media mislukt
Importeren vanaf media mislukt
Een release op schijf die niet door de handtekeningcontrole kwam. Let op de controles op volgorde met degene waarbij het proces stopte, de verwachte en aangetroffen vingerafdrukken van de sleutel, en de duidelijke melding dat er niets is geladen of gewijzigd.

Zodra de sleutel, de images en de chart allemaal zijn goedgekeurd, is de volgende stap de preflight op uw cluster, in hoofdstuk 2.5, Preflight met nexusctl.