Log indBook en briefing

Kapitel 2.25

Byg til hver udgave

Hvad der ændrer sig, når én udvidelse skal fungere i hver udgave, på et air-gapped anlæg, på en Nexus Edge-payload eller bag en kundes eget brand. Dækker licensgrænsen for Enterprise-moduler og signeret offline-levering med en oversigt over, hvad man skal gøre forskelligt for hvert mål.

Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

17 minutters læsetid

Hos Corrán Orbital leverer vi til flere steder end de fleste teams. Vores egne ingeniører kører Enterprise på jorden. En satellit, CORR-3, kører en missionspakke på Nexus Edge. To kunder kører Community på en enkelt server, én kører en air-gapped Enterprise-installation, der aldrig er på internettet, og vi har bygget en pakke til et forsikringsselskab på deres egen installation. Koden nedenunder er stort set den samme, og forskellene handler mest om, hvor den må komme hen, og hvordan den kommer derhen.

Dette kapitel gennemgår hvert mål for sig: hvad De bygger op imod, hvad De ikke må røre, og hvordan resultatet når frem til kunden. En matrix til sidst samler det på én side. Kapitel 2.18, Udvidelsesmodellen, forklarer, hvordan skills, plugins, pakker og moduler adskiller sig. Kapitel 2.2, Udgaverne under motorhjelmen, beskriver selve udgaverne.

Community og open core

Community er den åbne kerne under Apache License, Version 2.0. De kan forke den og levere ændringer til den. NOTICE-filen, der følger med, siger én ting, som er værd at kende, før De sætter Deres brand på noget: licensen giver ikke ret til at bruge Adverants navne eller varemærker ud over at angive, hvor værket stammer fra.

De udvider Community på samme måde, som De udvider Enterprise. Plugin SDK (software development kit) er den samme pakke i begge udgaver, og hverken den fulde serviceskabelon eller de 22 overholdelsesporte ændrer sig; kapitel 2.21, Plugin SDK, beskriver det. Skills virker også. Community får hele Skills Engines editor og bibliotek med versioner og tests, mens canary-udgivelser og godkendelse af to personer forbliver i Enterprise.

Udvikling på Community
Udvikling på Community
Opbygning af et booking-plugin på en enkelt Community-server. Bemærk adgangskortet, som når Propose via GitHub og ikke tilbyder Elevate, og teaseren til højre, der viser, hvad Enterprise tilføjer.

Udviklersiderne i Community tilbyder de samme golden paths med tre forskelle, som De vil mærke med det samme:

  1. Deres kode ligger i GitHub i stedet for i installationens egne repositories. Plugin-golden path'en opretter et GitHub-repository og et udviklingsrum ud fra den samme fastlåste skabelon, som Enterprise bruger; skærm DV18 viser den oprette room-bookings.
  2. Golden paths for domænepakker og platform hører til Enterprise. I Community bygger De plugins og skills samt lenses og workflows på det, De kører.
  3. Community-adgangskort stopper under Elevate-niveauet. På én server er der ingen produktion at nå fra en IDE (integrated development environment), og De administrerer serveren direkte. Et forsøg fra IDE'en afvises med PASS_TIER_REQUIRED.

Et Community-udviklingsrum på en lille server er beskedent. Vores havde 2 kerner og 8 GiB hukommelse, var lukket bortset fra det, manifestet erklærer, og blev afsluttet efter 7 dages inaktivitet.

Bidrag tilbage

Skills Engine er også Apache-2.0 og modtager bidrag på den sædvanlige måde. Fork repository'et, opret en gren fra main, foretag ændringen med dens tests, og kør kontrollerne, før De åbner en pull request:

git checkout -b feature/skill-synthesis-validation
npm test
npm run lint
npm run typecheck

Et bidrag, der ændrer adfærd, kræver en test, der fejler uden det. Det er ikke husstil: SDK'ens egne testregler siger, at enhver ny test skal påvises at fejle på træet før ændringen, og reviewerne beder om dokumentationen.

Enterprise-moduler og licensgrænsen

Enterprise er Community plus licenserede moduler. Et licenseret modul er en separat artefakt, som en Community-tjeneste indlæser ved opstart, og det er sådan Enterprise-funktioner, og ethvert lukket modul De bygger til Enterprise-kunder, kobles på den åbne kerne.

Reglen, der får dette til at fungere, er licenslinjen. Et lukket modul må kun nå Community-udgaven gennem én pakke, @adverant/nexus-spi, serviceudbyder-grænsefladen. Den er Apache-2.0 og indeholder grænseflader samt de typevagter, som en vært og et modul bruger til at kontrollere hinanden, uden anden runtime-logik. Kobling på tværs af linjen sker via en grænseflade eller en netværksprotokol, aldrig via kildekode.

Eksport Hvad det er
RouteModule Et licenseret rutemodul: id, featureGroup, bodies og register(app, ctx), som monterer sine routere på værtens app
SpiApp Den del af værtens HTTP-app, et modul berører: use
SpiContext Hvad værten giver et modul: produktporten og scope-vagten, licenslæseren, puljen til scope-afgrænsede forespørgsler, tjenestens skema, upstream-adresserne og platformsklienterne
SpiRuntime De plugin SDK-værdier, en vært giver et modul, så modulet aldrig selv importerer SDK'ens runtime
SpiPlane Hvad et licenseret plan tilføjer ud over ruter, såsom de skærmlæsninger, det leverer
ScreenModule En konsols licenserede skærmgruppe: group, featureGroup, routes, screens og menu
GrantCheck (featureGroup) => Promise<{ entitled, code?: 'LICENCE_LOCKED' }>

HTTP-frameworket og konsollens skærmtype er typeparametre, så grænsefladen binder ingen af dem. Her er skelettet til et rutemodul med en Express-handlertype:

import type { GrantCheck, RouteModule, SpiApp, SpiContext } from "@adverant/nexus-spi";
import { Router, type RequestHandler } from "express";

export function auditTrail(checkGrant: GrantCheck): RouteModule<RequestHandler> {
  return {
    id: "audit-trail",
    featureGroup: "<feature-group>",
    bodies: [],
    register(app: SpiApp<RequestHandler>, ctx: SpiContext<RequestHandler>) {
      const router = Router();
      router.get("/api/audit-trail", ...ctx.requireScope, async (_req, res) => {
        const verdict = await checkGrant("<feature-group>");
        if (!verdict.entitled) {
          res.status(403).json({
            error: true,
            code: verdict.code,
            message: "This organisation's licence does not carry the audit trail.",
            troubleshooting: ["An owner or administrator can turn it on with a licence from Adverant."],
          });
          return;
        }
        res.json({ entries: [] });
      });
      app.use(router);
    },
  };
}

<feature-group> er den funktionsgruppe i udgavematrixen, som modulet betjener. Enhver licenseret rute kører bag ctx.requireScope, værtens produktport og scope-vagt, og modulet kontrollerer også sin egen tildeling, før det svarer. Et modul uden berettigelse afviser med LICENCE_LOCKED og viser funktionens teaser, aldrig dens data. Deres modul importerer heller aldrig plugin SDK'ens runtime, fordi SDK'en er en Community-pakke, som linjen ikke tillader. Værten giver det de SDK-værdier, det kalder. Før værten indlæser noget modul, installerer den en SpiHost på globalThis under Symbol.for(SPI_HOST_KEY), som indeholder SDK-runtimen og appens eget rutekit. Det skal ske først: et modul, der er kompileret til ét bundle, evalueres som en helhed, og et register-kald ville komme for sent for kode, der læser SDK-værdierne under indlæsningen. Til typer re-eksporterer @adverant/nexus-spi/sdk/<module> SDK'ens deklarationer, vendored uændret fra én SDK-udgivelse og fastlåst med checksum, så Deres modul typetjekkes mod de samme afvisningsindhold og klienter, som et plugin bruger.

Et skærmmodul følger én regel mere: ét modul pr. funktionsgruppe, så en gruppe, hvis skærme hører til to funktionsgrupper, leveres som to moduler, og kun ét af dem indeholder menulinjen.

Hvad licenslinje-porten afviser

Adverants licenslinje-port holder ethvert Enterprise-modul til linjen, og det er værd at holde Deres egne lukkede moduler til samme regel. Dens konfiguration er én fil:

{
  "communityScopes": ["@adverant/", "@adverant-nexus/"],
  "allowedCommunityPackages": ["@adverant/nexus-spi"],
  "enterprisePrefixes": ["@adverant/enterprise-", "@adverant-enterprise/"],
  "communityRepos": ["nexus-community", "nexus-core", "Adverant-Nexus-Open-Core"],
  "allowedCommunityGoModules": []
}

Hvert af disse er et fund med fil og linje:

  • enhver import af en pakke under et Community-scope, som ikke er den tilladte grænseflade eller en Enterprise-pakke, inklusive dynamiske importer;
  • enhver specifier, Go-importsti eller afhængigheds-URL, der navngiver et Community-repository, medmindre det er et Go-modul, der er anført i allowedCommunityGoModules;
  • en relativ import, der kravler ud af repository'et;
  • en package.json-afhængighed, der er en file:-, link:-, portal:- eller workspace:-sti uden for repository'et, eller en Git-URL til et Community-repository;
  • en go.mod replace, der peger uden for repository'et.

Den afslutter med 0, når alt er rent, og 1 ved fund. Exit 2 betyder, at den afviste, fordi dens konfiguration var forkert, eller den ikke scannede noget. Grænsefladepakken publiceres ikke i et registry. De medbringer en byte-fastlåst kopi af den byggede pakke i Deres repository som en lokal file:-pakke med en SHA256SUMS-fastlåsning og en kontrol i Deres pipeline, der afviser en kopi, som afviger. Fordi kopien ligger i repository'et, accepterer porten den.

To store bokse side om side. Den venstre boks er mærket "Community (Apache-2.0)" og indeholder mindre bokse for "Services", "Plugin SDK" og "@adverant/nexus-spi". Den højre boks er mærket "Enterprise module (closed)" og indeholder "RouteModule", "ScreenModule" og "GrantCheck". Én fuldt optrukket pil krydser linjen, fra den højre boks kun til "@adverant/nexus-spi", mærket "compile against". To stiplede pile fra den højre boks til "Services" og "Plugin SDK" er overstreget og mærket "licence-line gate: finding".
Licenslinjen mellem Community og et Enterprise-modul.

Udgavespecifikke builds

Hvis Deres udvidelse leveres til kunder i begge udgaver, bygger De den én gang pr. udgave, og hvert build sker i sit eget sammensatte træ. At sammensætte et træ betyder kun at tage de filer, der hører til den udgave. Adverants egen eksport gør dette ud fra en grænseliste, hvor hver sporet fil tildeles efter regler, hvor første match vinder: en regel navngiver en kapabilitet, og filens udgave følger af den kapabilitets niveau i udgavematrixen, eller den navngiver en filklasse, der ikke leveres i nogen af udgaverne, med en begrundelse. Filer, der kun bruges til build, leveres i Enterprise-træet og, når de er markeret, også i Community-træet. Et moduls migreringskæde er installationsdata og leveres i alle udgavers træer.

Kør derefter hele buildet fra rent i hvert sammensat træ. Det betyder alle tre kommandoer, hver gang:

npm ci
npm test
npm run build

Det lærte vi på den dyre måde: et Enterprise-træ bestod sine tests, mens Community-træet fejlede i sit produktionsbuild, fordi en type, det havde brug for, kun fandtes i en Enterprise-fil. At tests består i ét træ, siger intet om det andet. En udgaves tests må kun importere det, som den udgaves træ indeholder, og eksporten afviser en test, der rækker uden for det.

Eksporten skriver også hver udgaves licens. Community-filer bærer SPDX-identifikatoren (Software Package Data Exchange) Apache-2.0; Enterprise-filer bærer LicenseRef-Adverant-Enterprise, og deres package.json angiver UNLICENSED. Redigér ikke disse felter manuelt: eksporten omskriver dem, og en kopi, der ikke længere matcher sin fastlåste licenstekst, afvises.

Team: kun i skyen

Team er Community plus Team-sættet, og det kører kun på Adverant cloud. Der findes ingen selvhostet Team. Team-sættet tilføjer seks kapabiliteter oven på Community, heriblandt det samlede arbejdspanel, delte notesbøger, administration af skills-biblioteket og workflow-drift med promovering mellem miljøer.

For en udvikler betyder kun-cloud én ting: en Team-kunde får Deres plugin som en signeret udgivelse via kataloget, aldrig fra Deres egne servere. De bygger det, som en ekstern udgiver bygger, på en udgiverklynge.

Udgiverklynge
Udgiverklynge
En udgivers egen virtuelle klynge på Adverant cloud, kun med eksempeldata. Følg det aktive flow langs toppen: IDE'en når udgiverens klynge og eksempeldata, en signeret udgivelse går gennem gennemgang til kataloget, og der er ingen vej til nogen kunde.

En udgiverklynge er en virtuel klynge på Adverant cloud med en kvote fastsat af Adverant. Den indeholder kun eksempeldata og har ingen rute til nogen kunde. En anmodning om en maskeret kopi af en kundes data dér afvises med TENANT_BOUNDARY; en kunde kan dele testresultater med Dem, aldrig sine data. Deres adgangskort til den rækker aldrig ind hos en kunde. Når udgivelsen er klar, signeres og gennemgås den af Adverant, før den optages i kataloget. Hver kunde vælger derefter, om den vil installere den, og tildeler den kun det, dens manifest erklærer, enhed for enhed. Et kald til noget, manifestet ikke erklærede, afvises hos kunden med CONNECTION_SCOPE_EXCEEDED, og den eneste måde at tilføje det på er en ny udgivelse, som kunden gennemgår.

Air-gapped kunder

En af vores kunder kører Nexus, hvor intet går ind eller ud over et netværk. Deres installation er beskrevet i kapitel 2.10, Air-gapped installation. For os betød det, at vi skulle levere vores plugin på signerede medier, og værktøjet til det er nexus-airgap fra det suveræne leveringskit @adverant/nexus-sovereign.

Et forseglet bundle er én signeret, selvstændig tarball. Det kan indeholde images og migreringer, forudsignerede skills og modelvægte samt en SBOM (software bill of materials) med licenserne for alt indholdet. Dets manifest angiver hver fil med dens SHA-256 og er signeret med Ed25519. At bygge et ud fra kode ser sådan ud:

import { SealedBundleExporter } from "@adverant/nexus-sovereign";

const { bundleDigest } = await new SealedBundleExporter().export(source, {
  outPath: "./cold-chain-0.4.0.tar.gz",
  profile: "airgap",
  signerPrivateKeyPem,
});

signerPrivateKeyPem er Deres signeringsnøgle til udgivelser. Kommandoen nexus-airgap bundle gør det samme fra kommandolinjen. Kundens operatør kontrollerer det derefter før alt andet:

nexus-airgap verify --bundle cold-chain-0.4.0.tar.gz --trusted-key corran-release.pub.pem --profile airgap

Verifikationen genberegner hashen for hver fil mod manifestet, afviser enhver fil, som manifestet ikke angiver, kræver en betroet Ed25519-signatar og afviser ethvert bundle, hvis netværks-allow-list ikke er tom. En fil, der er ændret efter signering, fejler med BUNDLE_INTEGRITY_VIOLATION. Bed operatøren om at stoppe dér og ringe til Dem; der findes en ikke-streng indstilling, og den bør de aldrig bruge.

Tre regler bar vores levering:

  1. Den betroede nøgle sendes adskilt fra bundlet. Vi sender den offentlige nøgle og bundlets SHA-256 ad en anden vej end medierne, så et bundle ikke kan stå inde for sig selv.
  2. Intet i bundlet må kræve netværk ved installation. Ingen pakkehentning, ingen modeldownload, intet licenskald. Hvis pluginnet har brug for en model, leverer kundens egen modelserver den via AI (kunstig intelligens) Provider Router.
  3. Efter verifikationen bringer operatøren udgivelsen ind via installationens egne udgivelseskanaler, præcis som en forbundet kunde ville. Bundlet er måden, bytene ankommer på, ikke en vej uden om promoveringsportene.

Air-gapped arbejde er langsommere, og det kan vi ikke ændre fra vores side. En forkert byte koster et nyt sæt medier og endnu en tur, så vi verificerer selv bundlet på en ren maskine med den samme kommando, før det forlader bygningen.

Nexus Edge-missionspakker

Nexus Edge er en mindre udgave af Nexus, der kører på satellitter og droner, på missionscomputere, som holdes adskilt fra flycomputeren. Det er et tilvalg med en licens pr. platform eller flåde. Det, der ændrer sig fra den ene mission til den næste, er missionspakken, og at bygge dem udgør en god del af mit arbejde.

En missionspakke indeholder det, som nyttelasten skal bruge til én mission. Ud over sine modeller og adaptere indeholder den ontologien med en startgraf, agenttrin, alarmregler, prioriteterne for, hvad der sendes ned først, en placeringstabel, der angiver, hvilken computer der kører hvad, de reducerede trin, som platformen kan falde tilbage til, når en computer svigter, og de testcases, den skal bestå om bord.

Byg en missionspakke
Byg en missionspakke
Maritime watch 1.5 bygges ud fra 1.4. Bemærk testcasene om bord (48, som alle skal bestås) og placeringstabellen, der angiver, hvad der kører på hvert af de to GPU-kort (grafikprocessor) og CPU-kortet (centralprocessor) ved hvert reduceret trin.

Pakker bygges og signeres på jorden. Nogle praktiske regler fra vores builds:

  • Hold de store dele stabile. Maritime watch 1.5 tilføjede en skibsfinder-adapter og to alarmregler; sprogmodellen og ontologien blev ikke ændret, så pakken var på 412 MB i stedet for 9.8 GB. Uplinket er smalt, og basismodeller indlæses før opsendelse.
  • Brug én embedding-model for hele missionsfamilien, både på jorden og i nyttelasten, så de grafændringer, der sendes ned, kan flettes med grafen på jorden.
  • Nyttelasten sender aldrig en kommando til flysystemerne. Den sender typede anmodninger via supervisoren til flycomputeren, som besvarer hver af dem med en begrundelse.
  • Hver hardwaretype kræver sin egen kontrol af pakken. Installation af en pakke, der ikke er kontrolleret for en enheds hardware, afvises med PACK_NOT_CHECKED_FOR_HARDWARE.
Signér og send en pakke
Signér og send en pakke
Maritime watch 1.5 frigives til CORR-3. Der kræves to ud af tre signaturer, så én stjålet nøgle ikke kan frigive en pakke, og planen viser, at pakken først aktiveres, når dens 48 tests er bestået om bord.

Frigivelse kræver to ud af tre signaturer. Vores og Adverants er det sædvanlige par, og den tredje er en offlinenøgle, som vi opbevarer i et pengeskab, til når en af de to andre går tabt. Pakken sendes op i den ledige plads, verificeres, kører sine testcases på de rigtige kort og aktiveres kun, hvis de alle bestås, med en tæller, der forhindrer, at en ældre pakke geninstalleres. Hvis en test fejler, forbliver platformen på den tidligere pakke, og fejlen sendes ned ved næste passage. Vi udruller én platform ad gangen, hver efter en uge uden fejl. Pakker forbliver gyldige, mens en platform er uden forbindelse, så en satellit uden link fortsætter med at arbejde på den pakke, den har.

På køretøjer og fartøjer kan Edge køre på k3s. Et rumfartøj kører en supervisor med signerede images eller statiske binærfiler og en fast placeringstabel i stedet for Kubernetes, og det er derfor, placeringstabellen følger med i pakken.

White-label-butiksfacader

Tilvalget Storefront / white-label giver en kunde mulighed for at sætte sit eget brand og domæne på det, brugerne ser, med egne login-skærme, og at modtage betalinger via egne gateways. Kortoplysninger berører aldrig Nexus.

Et plugin, der er bygget til en white-label-kunde, må aldrig vise Adverant. Manifestet indeholder alt brandspecifikt, og platformen henter resten fra organisationens eget brand i stedet for fra noget, der er hardkodet i Deres kode:

{
  "domains": [
    { "primary": "<app-domain>", "aliases": ["www.<app-domain>"] }
  ],
  "branding": {
    "appName": "<app name>",
    "tagline": "<one line>",
    "primaryColor": "<hex>",
    "accentColor": "<hex>",
    "passkeyRpId": "<app-domain>",
    "oauthClientRef": "brand:<plugin name>:google"
  }
}

<app-domain> er kundens eget domæne, og passkeyRpId skal matche det, fordi passkeys er bundet til det domæne, en person logger ind på. En webapp på sin egen origin logger brugere ind via SDK'ets login-hjælpere, hvis to offentlige ruter er de eneste ubeskyttede /api-ruter, som scope-kontrollen accepterer, og kun når manifestet erklærer dem auth: public med allowAnonymous: true. Frontend-kald går via backend for frontend-proxyen med tilladelsesliste, aldrig direkte til en serviceadresse. Kundens administrator konfigurerer betalingsdelen, fra gateways til den brandede checkout. Det gør Deres plugin ikke.

Oversigten

Byggemål Byg mod Hvad De gør anderledes Hvordan det når kunden
Community Plugin SDK, Skills Engine Kode i GitHub; ingen domænepakke eller platformstier; ingen Elevate Kunden installerer det; ingen kataloggennemgang nødvendig
Enterprise (Deres egen installation) Plugin SDK, Skills Engine, pakkeskabeloner Udviklingsmiljøer, datagrene, maskerede kopier med dataejeren; pakker og linser Promovering fra staging til en pilotenhed og derefter overalt
Enterprise-modul (lukket) Kun @adverant/nexus-spi Licenslinjeregel; tildelingskontrol på sin egen funktionsgruppe; LICENCE_LOCKED ved manglende rettighed Indlæses af en Community-tjeneste ved start på licenserede installationer
Begge udgaver Plugin SDK Sammensæt hver udgaves træ; npm ci, tests og produktionsbuild i hver Én release pr. udgave
Team Plugin SDK på en udgiverklynge Kun eksempeldata; kun cloud Signeret release, Adverant-gennemgang, katalog
Air-gapped Plugin SDK, @adverant/nexus-sovereign Forseglet bundt; nøgle og kontrolsum sendes separat; intet hentes ved installation Signerede medier, verificeret, derefter installationens releasekanaler
Nexus Edge Missionspakkens indhold Placeringstabel, reducerede trin, tests om bord, hardwarekontroller To ud af tre signaturer, ledig plads, aktiveres når tests er bestået
White-label Plugin SDK domains og branding i manifestet; intet Adverant-navn nogen steder Som for Enterprise, på kundens eget domæne

Uanset målet sker udrulning kun via installationens releasekanaler. Kapitel 2.28, Frigivelse af Deres udvidelse, beskriver disse kanaler. Kapitel 2.27, Byggescenarier, har en opskrift for hver række ovenfor.