Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

aggrega push

aggrega push pubblica un’entità di catalogo in un registry OCI, dove altri workspace possono risolverla con aggrega pull.

Cosa fa

aggrega push legge un singolo YAML di entità, lo impacchetta per il trasporto e lo invia a <registry>/<kind>/<metadata.name>:<metadata.version>, con il percorso del repository in minuscolo; una Recipe o una FeatureRecipe porta il proprio spec.capability, e un Plugin il proprio metadata.pluginType, come segmento tra il tipo e il nome. Esegui aggrega push --list-kinds per ottenere i tipi di entità che il binario installato pubblica — un tipo per riga, in ordine, e nient’altro, così uno script può leggerlo direttamente. L’insieme comprende i tipi di authoring del catalogo insieme all’Aggregate, un modulo riutilizzabile, e al Plugin, un riferimento indirizzato per contenuto a un artefatto WebAssembly che il compilatore instrada e il runtime esegue. Il Plugin è un artefatto pubblicabile strutturale anziché un tipo di authoring del catalogo. La pubblicabilità è una proprietà dell’entità, non di come viene usata: un Aggregate è pubblicabile sia che venga poi referenziato come spec.aggregate di primo livello di una Release sia che venga annidato nel blocco aggregates: di un altro Aggregate. Release e Manifest sono input del lato deployment, non artefatti di catalogo, e vengono rifiutati.

Impacchettamento

Un push pubblica il documento dell’entità e i file che l’entità stessa nomina accanto a esso — e nient’altro nella sua directory. I file che un’entità nomina sono:

  • per una Recipe o una FeatureRecipe, il suo source: locale — una directory viaggia con ogni file al suo interno mantenuto dalle regole di esclusione registrate nel suo entity.lock, come descrive Quali file vengono distribuiti con un’entità; ogni file che le sue voci valuesMapping:, workload: e artifacts: importano con $import:; e l’entity.lock accanto a essa;
  • per un Component o una Feature, ogni file di schema che il suo spec.schema, un pilastro o un socket usesSchema importa con $import:, incluso ogni file che un file importato importa a sua volta.

Un Aggregate, un Plugin e i tipi di libreria non nominano alcun file accanto al proprio documento. Una nota, un README, i file di un’altra entità o l’output di una build presenti nella directory non vengono pubblicati, comunque si chiamino. Un link simbolico tra i file che un’entità nomina viene rifiutato anziché seguito — A symbolic link sits among the files an entity carries (Un link simbolico si trova tra i file che un’entità porta con sé) — e lo stesso vale per un percorso che un’entità nomina attraverso una directory che è un link che conduce fuori dalla directory dell’entità, prima che venga impacchettato qualcosa — A path names content outside the entity’s own directory (Un percorso nomina contenuto esterno alla directory dell’entità).

La forma ne consegue. Un’entità che non nomina nulla viene pubblicata come il proprio documento, invariato, con il media type +yaml del suo tipo. Una che nomina un file viene pubblicata come un .tar.gz che contiene il documento e quei file nelle rispettive posizioni nella directory, con il media type +tar+gz del suo tipo. Quindi una Recipe il cui contenuto è tutto inline viene pubblicata come il proprio documento, e un Component il cui schema è importato da un file viene pubblicato come archivio. Catalogo e registry §6 elenca entrambi i media type per ogni tipo.

Ogni file in un archivio ha modalità 0644 e nessun timestamp, qualunque siano i suoi bit di permesso su disco. Un checkout scrive i file con i propri bit di permesso, e un sistema che non registra alcun bit di esecuzione estrae come file ordinario ciò che un altro sistema estrae come eseguibile, quindi l’archivio non porta alcuna modalità letta dal disco: due checkout di uno stesso commit pubblicano gli stessi file qualunque sia la loro umask e su qualunque sistema siano stati fatti, e invertire il bit di esecuzione di uno script non cambia nulla di ciò che viene pubblicato.

Un push avvisa per ogni voce di un archivio che Windows non può contenere così come è scritta — un percorso con una parte che porta il nome di un dispositivo, come CON, AUX o NUL, in qualsiasi combinazione di maiuscole e minuscole e qualunque estensione segua, come aux/x.yaml, oppure una parte che termina con un punto o uno spazio, come report.. Su Windows, aggrega rifiuta di estrarre una voce del genere, quindi un workspace Windows non può usare la versione. L’avviso viene scritto sullo standard error su ogni piattaforma, una riga per voce, prima del resoconto della pubblicazione stessa; il nome del file del documento dell’entità viene valutato insieme ai file che nomina, e un’entità che non nomina nulla viene pubblicata come il solo proprio documento e non riceve mai avvisi. Non rifiuta nulla: il push procede o viene rifiutato esattamente come avverrebbe senza l’avviso, e --dry-run avvisa allo stesso modo. A published archive carries an entry Windows cannot use (Un archivio pubblicato contiene una voce che Windows non può usare) mostra la riga e cosa fare.

Un source: locale scritto come template porta con sé l’intera directory. Un template come ./charts/{{ .values.flavour }} nomina una directory solo dopo che una Release lo compila, quindi nessuna pubblicazione può sapere quale sarà. Un’entità del genere porta con sé ogni file della propria directory mantenuto dalle sue regole di esclusione registrate — mai il suo .aggregaignore, le cui regole viaggiano all’interno del lock — e il push lo indica sotto gli altri suoi dati:

carries: every file in the entity's directory, because its source "./charts/{{ .values.flavour }}" is a template and the directory it names is decided by each Release that uses it

Ciò che non è nominato non viaggia, e chi se ne accorge è un consumatore. Un file su cui l’entità fa affidamento senza nominarlo tramite uno dei campi precedenti non è nella pubblicazione, e la build di un consumatore fallisce indicando il percorso mancante all’interno del suo slot di cache — non il tuo push. Nomina ogni file di cui l’entità ha bisogno tramite uno di quei campi.

Ogni file pubblicato è nominato nel manifest dell’artefatto, quindi un client OCI generico come oras lo scrive in un file con quel nome: entity.yaml per un’entità pubblicata come il proprio documento, entity.tar.gz per una pubblicata con i propri file, e per un Plugin entity.yaml per l’entità accanto a entity.wasm per il suo eseguibile. Il nome dipende dal media type, non dal file da cui pubblichi, quindi lo stesso contenuto pubblicato da un file rinominato pubblica lo stesso artefatto. Catalogo e registry §6 elenca ogni forma pubblicata e il file in cui ciascuna arriva.

Un URL source: remoto su una Recipe (un riferimento a un chart OCI, un URL di chart o di frammento HTTPS, un modulo Git) viene conservato alla lettera nello YAML pubblicato; non viene recuperato e incorporato nell’artefatto. I consumatori risolvono e fissano le sorgenti remote in modo indipendente al momento del proprio pull. Questo mantiene la distribuzione delle entità di catalogo e la risoluzione degli artefatti sorgente come aspetti separati.

Un Aggregate viene pubblicato come un unico documento a sé: un sotto-aggregate che referenzia in aggregates: non viene incluso nell’artefatto. Ogni sotto-aggregate è un Aggregate pubblicato separatamente che i consumatori risolvono e fissano in modo indipendente al momento del pull, per identità — lo stesso principio di separazione della distribuzione che si applica alle sorgenti remote.

Un’entità per directory

Un archivio contiene il file dell’entità tra i file che nomina, quindi l’entità deve essere ritrovata all’uscita. Un consumatore la trova dal preambolo che porta: il documento in cima al bundle il cui kind: è un tipo di entità pubblicabile è l’entità. Il file in cui è scritta può chiamarsi in qualsiasi modo — recipe.yaml è la convenzione del catalogo, non un requisito — e un frammento compose, un template di chart o un manifest Kubernetes accanto all’entità non viene scambiato per essa, perché questi dichiarano qualcos’altro o nessun tipo. I documenti di entità più in basso, all’interno di un albero source/, sono contenuto che l’entità distribuisce anziché l’entità stessa e non vengono mai considerati.

Un push rifiuta un’entità che condivide la propria directory con un’altra entità. Ogni tipo ha una directory propria tranne Aggregate, Release e Manifest, che la radice di un workspace contiene uno accanto all’altro. Per qualsiasi altro tipo, un push controlla prima di fare qualsiasi altra cosa con l’entità — prima del passaggio di pin, della policy di firma e del bundle — che nessun altro documento di entità si trovi nella stessa directory, e altrimenti rifiuta, indicando ogni entità d’intralcio, indipendentemente dal fatto che al push sia stato chiesto di fissare i pin. aggrega pin rifiuta la stessa directory con le stesse parole; l’arresto è An entity shares its directory with another entity (Un’entità condivide la propria directory con un’altra entità). Un documento di nessun tipo di entità accanto all’entità — un file di chart, un frammento compose, un README — non è d’intralcio, e neppure qualsiasi cosa in una sottodirectory. Ogni documento accanto all’entità viene letto solo dall’interno del workspace o, per un’entità che nomini al di fuori di esso, dall’interno della directory dell’entità stessa, quindi uno che è un link che conduce all’esterno arresta il push indicando il link, senza leggerlo, come stabilisce il confine del workspace.

La regola è ciò che fa sì che un entity.lock appartenga a una sola entità: il nome del file del lock è lo stesso per ogni entità, quindi due entità scritte in una sola directory condividerebbero l’unico lock per cui c’è posto. Viene valutata solo quando qualcosa viene prodotto dalla directory, quindi una directory che contiene più entità continua a essere caricata, a superare il lint e a essere compilata.

Il nome della directory non viene valutato. Un’entità da sola nella propria directory viene pubblicata al suo metadata.version ovunque si trovi quella directory; <name>/<version>/, la struttura seguita dal catalogo della libreria standard, è una convenzione. Un artefatto che un altro client ha pubblicato da una directory contenente due entità viene comunque letto in sicurezza: un pull di esso si arresta indicando entrambi i documenti anziché rispondere con uno dei due, come catalogato in errors/fatal-halts.md.

Leggere l’entità prima che venga impacchettata

Un push legge un Component, una Feature, una Recipe o una FeatureRecipe come li legge una build, e rifiuta ciò che quella lettura rifiuta — per lo stesso motivo, con lo stesso codice breve, prima che il bundle venga costruito e prima che venga contattato il registry di destinazione. Quindi un documento che non supera lo schema del suo tipo, un percorso che nomina contenuto esterno alla directory dell’entità e uno schema che un Component o una Feature importa con $import: mancante o inutilizzabile vengono rifiutati alla pubblicazione anziché pubblicati. Ciascuno di essi è un’entità che la prima build dei suoi consumatori rifiuterebbe; un percorso che esce dalla directory nomina anche un file che non viaggerebbe con l’entità, perché ogni file che una pubblicazione porta è preso dalla directory dell’entità stessa — vedi A path names content outside the entity’s own directory (Un percorso nomina contenuto esterno alla directory dell’entità).

Una Recipe o una FeatureRecipe viene letta in questo modo mentre vengono confrontati i suoi pin, come descrive la sezione successiva, quindi la lettura avviene indipendentemente dal fatto che al push sia chiesto di fissare i pin e dal fatto che l’entità abbia qualcosa da fissare. Ognuno dei quattro tipi viene letto in questo modo anche immediatamente prima che venga costruito il suo bundle, perché è quella lettura a dire quali file nomina. Un Aggregate e una libreria non nominano alcun file e non vengono letti in questo modo. Neanche un Plugin nomina alcun file, e viene letto rispetto allo schema del suo tipo prima del suo .wasm, come descrive Pubblicare un Plugin.

Pubblicare un Plugin

Un Plugin viene pubblicato insieme al suo .wasm, indicato da --plugin, e un push valuta i due prima che venga pubblicato alcun byte o venga contattato il registry. --dry-run li valuta esattamente come una pubblicazione.

L’entità viene letta prima rispetto allo schema del suo tipo, come la legge un caricamento del catalogo, prima che venga letto il .wasm. Quindi un metadata.version che non è una versione semantica — un semplice commit come 415148e — viene rifiutato in base alla condizione propria dello schema, indicando il campo, e così qualsiasi altro scostamento dallo schema, come un spec.abiVersion mancante. Ciò che conta come versione semantica qui è il pattern proprio dello schema per metadata.version; il push non aggiunge alcuna regola propria.

Poi il .wasm viene caricato e confrontato con l’entità. Ciò che dichiara di offrire deve concordare con ciò che l’entità afferma, l’insieme di comandi e le funzioni host che l’entità registra devono corrispondervi, e la versione che dichiara della propria build deve essere uguale a metadata.version — vedi A Plugin entity’s recorded version does not match the plugin (La versione registrata da un’entità Plugin non corrisponde al plugin).

Un .wasm compilato da un working tree con modifiche non committate viene rifiutato. Una build del genere porta il marcatore -dirty alla fine della versione che dichiara — 1.0.0-dirty, 1.0.0-3-g1a2b3c4-dirty. Si tratta di una versione semantica valida, ma nomina un commit che non contiene ciò che è stato compilato, quindi nessuno potrebbe ricompilare ciò che è stato pubblicato a partire dalla versione con cui è stato pubblicato. Il push lo rifiuta, indicando la versione e la soluzione: compila il plugin da un checkout pulito del commit indicato dal tag della release, così che dichiari la versione stessa della release — e, per rilasciare la modifica, committala con il metadata.version dell’entità impostato sulla nuova release e applica prima il tag a quel commit — anziché copiare nell’entità la versione dichiarata da una ricompilazione. Una versione di sviluppo compilata da un commit, come 1.0.0-3-g1a2b3c4, e una prerelease come 1.0.0-rc.1 vengono entrambe pubblicate. Il rifiuto è A plugin was built from a working tree with uncommitted changes (Un plugin è stato compilato da un working tree con modifiche non committate).

Eseguire il pin prima di pubblicare

Una Recipe o FeatureRecipe porta i pin degli input che legge — un source: remoto scritto per intero, un file che una voce artifacts importa, i file di un source: accanto a essa — nell’entity.lock accanto a sé, e un push pubblica quel file insieme all’entità. Il pin è un passaggio che esegui prima di pubblicare, aggrega pin, e di cui poi esegui il commit del lock che scrive.

Un push rifiuta un’entità il cui lock non registra quei pin. Prima di costruire il bundle, un push determina cosa registrerebbe il passaggio di pin per l’entità e lo confronta con l’entity.lock accanto a essa. Dove manca un pin, o il lock ne contiene uno a cui un input non corrisponde più, il push si ferma prima che venga costruito qualsiasi archivio o contattato qualsiasi registry. Il rifiuto nomina l’entità e ognuno di tali input — ciascuno un remote source, un imported file o un local source file — e cosa eseguire: aggrega pin sull’entità, --pin-sources sul push appena eseguito, oppure pin_sources_at_push per ogni push del workspace. È lo stesso rifiuto che un pull solleva sullo stesso lock, An entity reads an input the lock beside it records no pin for (Un’entità legge un input per cui il lock accanto a essa non registra alcun pin), con i rimedi propri di un push. Così una Recipe o FeatureRecipe pubblicata da un push porta, dentro il suo bundle, un lock che registra ogni pin che il passaggio avrebbe registrato nel momento in cui è stata pubblicata.

Due tipi di entità non hanno nulla di cui eseguire il pin e vengono pubblicati senza modifiche: un’entità che non legge alcuna sorgente remota, non importa alcun file e non nomina alcuna sorgente locale, e una Recipe le cui coordinate della sorgente remota sono compilate da un template. Quella sorgente nomina un artefatto solo quando una Release compila il template, quindi il suo pin appartiene al lockfile di ciascuna Release, e un push non ne chiede uno accanto all’entità. Un Component, una Feature, una libreria, un Aggregate o un Plugin non legge nulla di ciò che il lock registra e qui non viene mai rifiutato.

Confrontare il pin di una sorgente remota significa scaricare la sorgente, come fa aggrega pin, perché un pin che non corrisponde più è visibile solo rispetto a ciò che la sorgente serve ora. Un push su un’entità con una tale sorgente raggiunge quindi l’host della sorgente prima di raggiungere il registry. Il confronto legge una Recipe o FeatureRecipe come fa il passaggio di pin, attraverso il catalogo, quindi una che il catalogo si rifiuta di leggere — per esempio un documento che non supera lo schema del suo tipo — viene rifiutata qui con il motivo indicato dal catalogo stesso.

Dove non è stato trovato alcun workspace e nessuno è stato indicato, un push che scaricherebbe una sorgente remota per il confronto viene rifiutato prima di scaricarla, come avviene per aggrega pin. Il confronto scarica ogni sorgente remota che l’entità scrive per intero nella cache degli artefatti, esattamente come fa il passaggio di pin, e una cache scritta in una cartella da cui non è stato trovato alcun workspace renderebbe quella cartella un workspace. Quindi, quando nulla indica una radice e nulla ne ancora una — dalla cartella in cui esegui il push o, per un’entità indicata con un percorso assoluto, dalla cartella dell’entità stessa — un push di una Recipe o FeatureRecipe con una tale sorgente si ferma prima che la sorgente venga scaricata, inclusi un dry run e --pin-sources, e nomina la sorgente, la cartella e le due soluzioni: indica il tuo workspace con --workspace-root o AGGREGA_WORKSPACE_ROOT, oppure dai a quella cartella un .aggrega-config.yaml che contenga un blocco workspace:. Il confronto non scarica nulla per i due tipi di entità descritti sopra, né per una la cui sorgente è locale, quindi ognuna di queste viene confrontata con il suo lock e pubblicata lì come altrove; e ogni altro tipo non è vincolato a un lock e non viene rifiutato per questo. Configurazione elenca gli altri comandi per cui vale.

aggrega push --pin-sources esegue per te lo stesso passaggio, per primo. Il passaggio viene eseguito prima che il bundle sia costruito, quindi il lock che scrive si trova nell’artefatto pubblicato e il digest pubblicato lo copre; e viene eseguito prima di ogni altro rifiuto che valuta l’entità, quindi ciò che viene valutato è l’entità dopo il pin. Viene prima solo la regola sulla directory descritta sopra, perché il passaggio scrive l’unico lock che la directory contiene. Scrive gli stessi byte che scrive aggrega pin, quindi il rifiuto descritto sopra non scatta mai in quell’esecuzione: il lock appena scritto dal passaggio registra esattamente ciò con cui il rifiuto confronterebbe. La chiave del workspace pin_sources_at_push rende questo il comportamento predefinito di ogni push, e --pin-sources=false salta il passaggio per un’esecuzione, il che riporta il rifiuto. Il passaggio scrive accanto all’entità, il che richiede una collocazione scrivibile — e un push ne ha sempre una, poiché pubblica il documento che indichi.

--dry-run risponde come risponderebbe la pubblicazione. Senza --pin-sources rifiuta un’entità senza pin esattamente come fa la pubblicazione, quindi un dry run che riporta un bundle è uno che questo rifiuto lascerebbe passare. Con --pin-sources il passaggio esegue il pin come dry run: stampa il lock che scriverebbe e non scrive nulla, e i dati del bundle che seguono descrivono la directory così com’è, senza quel lock — quindi il digest è quello di una pubblicazione senza di esso e, dove il lock sarebbe nuovo, lo sono anche la dimensione e, per un’entità che non nomina nient’altro, il media type. Il rifiuto non scatta, perché la pubblicazione avrebbe eseguito prima il pin.

Best practice: una modifica a una versione già pubblicata va in una nuova versione, e poi in un pin. Copia l’entità in una nuova directory di versione, apporta lì la modifica, esegui il pin e pubblica quella. La metà che il prodotto fa rispettare è descritta nella sezione successiva: pubblicare contenuto diverso a una versione già pubblicata viene rifiutato. L’altra metà — non rieseguire il pin di una versione già pubblicata dopo averla modificata nel tuo workspace — spetta a te; nulla lo rifiuta in locale, perché rieseguire il pin è legittimo per un’entità che non hai pubblicato.

Registry, tag e indirizzamento per contenuto

Il registry di destinazione è --registry <ref> se fornito, altrimenti il default_registry del workspace (hub.aggrega.ai per impostazione predefinita). Il tag è il metadata.version dell’entità, e il percorso del repository deriva dal suo tipo e dal suo nome, quindi la posizione in cui finisce una versione pubblicata non dipende dalla directory da cui è stata pubblicata.

Un default_registry può contenere un percorso di repository, e una pubblicazione attraverso di esso finisce sotto quel percorso. Con default_registry: ghcr.io/acme, il Component core/api-server alla versione 1.0.0 viene pubblicato in ghcr.io/acme/component/core/api-server:1.0.0 — il luogo da cui lo scarica un pull attraverso lo stesso default, quindi la firma allegata qui è quella che quel pull trova. --registry indica un host, e una pubblicazione che esso dirige finisce su quell’host senza percorso. In qualunque modo venga indicata la destinazione, il requisito di firma e la configurazione di firma applicati sono quelli mantenuti per il suo host: un percorso non seleziona mai una policy diversa. La forma di scrittura di un percorso è descritta in come si scrive un host di registry.

Il manifest nomina il digest dei byte pubblicati, e il lockfile registra il digest di ciò che contengono. Il manifest OCI che un push scrive nomina il digest del documento o dell’archivio pubblicato, e aggrega pull rifiuta un download che non vi corrisponde, quindi i byte alterati tra pubblicazione e pull vengono individuati. Il lockfile che un pull scrive registra l’entità con un digest diverso: il digest del suo contenuto — il percorso e i byte di ogni file, e nulla su come l’archivio è stato compresso o su quali bit di permesso avessero i suoi file. È il digest che un pull nel workspace dell’autore registra per la stessa entità nella sua directory di catalogo, quindi un autore e ogni consumatore di una pubblicazione registrano lo stesso valore, e una build da entrambe le parti rifiuta contenuto che non vi corrisponde più. I due digest rispondono a domande diverse: quello del manifest verifica il download, e quello del lockfile è l’identità dell’entità.

Pubblicare su una versione esistente

Prima di caricare qualsiasi byte, aggrega push determina cosa il registry di destinazione contiene già al riferimento che sta per scrivere e lo confronta con il contenuto che ha davanti. Tre esiti:

  • Lì non è ancora pubblicato nulla — il push procede e pubblica normalmente.
  • Lo stesso contenuto — non viene caricato nulla, e il comando riporta la versione come già pubblicata, quindi un push ripetuto o ritentato non è un errore. Ciò che un push precedente ha lasciato non allegato — la firma o la data di pubblicazione — viene allegato ora, come descritto in Completare una pubblicazione lasciata parziale da un push precedente.
  • Contenuto diverso — il push si arresta, nominando il digest già pubblicato e quello che avrebbe scritto. Nessun flag lo forza.

Una versione già pubblicata continua quindi a denotare i byte pubblicati sotto di essa. Il contenuto modificato viene pubblicato sotto un nuovo metadata.version; aggrega lint --pre-publish risponde alla domanda successiva — di quanto deve avanzare quella versione — classificando la modifica rispetto alla versione pubblicata in precedenza.

--dry-run stampa il digest che un push scriverebbe, accanto al riferimento a cui lo scriverebbe:

aggrega push (dry-run): <reference>:<tag> (<digest>)

È il digest che il push stesso confronta con ciò che è già pubblicato, calcolato allo stesso modo dal solo contenuto, e stamparlo non contatta alcun registry. Così il contenuto che hai davanti può essere confrontato con il digest con cui una versione è stata pubblicata prima che venga eseguito qualsiasi push: dove differiscono in una versione pubblicata, il push verrebbe rifiutato. Con --pin-sources, è il digest della directory così com’è, come descritto in Eseguire il pin prima di pubblicare.

Completare una pubblicazione lasciata parziale da un push precedente

Un push scrive prima il contenuto e allega la firma e la data di pubblicazione in seguito, quindi un push che fallisce in uno di questi allegati — dopo i suoi tentativi ripetuti — lascia il contenuto pubblicato senza di esso, ed esce con un codice diverso da zero nominando ciò che non è riuscito ad allegare. Eseguire di nuovo lo stesso push completa quella pubblicazione. Trova il contenuto già pubblicato, stampa la riga Already published:, non carica nulla e allega ciò che ancora manca alla versione, ciascuno sulla riga che una prima pubblicazione stampa per esso:

  • La firma, dove questo push firma. Viene allegata quando la versione non porta alcuna firma che valga come firma di questa pubblicazione. Dove la tua configurazione fissa una policy di fiducia per l’host della destinazione — una public_key o trusted_identities, oppure per hub.aggrega.ai la baseline integrata — una firma vale quando si verifica secondo quella policy, quindi una firma che la policy non ammette non viene mai presa per quella propria della pubblicazione. Dove la policy non fissa nessuna delle due, nessuna firma può essere verificata rispetto a essa, quindi vale qualsiasi firma portata dalla versione e il push firma solo una versione che non ne porta alcuna; giudicare in base alla verifica in quel caso allegherebbe un’altra firma a ogni esecuzione.
  • La data di pubblicazione, dove la regola per le date ne richiede una — letta dalla firma appena allegata, o da quella già considerata valida — e la versione non porta alcun referrer published-at. Un push che non firma deve una data come una pubblicazione non firmata, qualunque firma sia stata allegata alla versione in seguito. La data che indica è l’orologio di questo push: il momento in cui la pubblicazione è stata completata, che è successivo al momento in cui il contenuto è arrivato per la prima volta, poiché nulla di ciò che il registry serve registra quel momento.

A una pubblicazione già completa non viene allegato nulla, per quante volte il push venga ripetuto. Prima di allegare qualcosa, il push legge quali firme e date porta la versione e crea qualsiasi firma dovuta. Una domanda a cui non sa rispondere — un elenco o una firma che non riesce a leggere, o una firma che non riesce a giudicare perché la radice di fiducia non può essere ottenuta — e una firma che non riesce a creare escono ciascuna con codice diverso da zero senza allegare nulla, anziché essere intese come se la versione non ne portasse alcuna.

Quando il registry fa fallire una scrittura

Un push scrive nel registry per passaggi: il contenuto — per un Plugin, l’entità e il suo .wasm — poi il manifest che lo nomina, poi il tag di versione, poi la firma e la data di pubblicazione accanto. Ogni passaggio che scrive viene ritentato quando fallisce in un modo in cui un tentativo successivo può riuscire: il registry risponde con un errore del server (qualsiasi stato 5xx, diverso da un 503 che riporta Retry-After) o 408 Request Timeout, oppure la connessione va in timeout, viene reimpostata o si interrompe a metà di una risposta. Un passaggio viene tentato al massimo tre volte, attendendo mezzo secondo prima del secondo tentativo e un secondo prima del terzo.

Si aspetta un registry che chiede di rallentare, e l’attesa non consuma nessuno di quei tentativi. Con un 429 Too Many Requests, o un 503 che riporta Retry-After, ogni richiesta rivolta a quel registry — una lettura quanto una scrittura — attende quanto il registry ha chiesto e poi riparte, e un passaggio il cui contenuto è stato rifiutato ricomincia come un nuovo caricamento, senza un numero fisso di tentativi, finché il registry non ha risposto altro che «rallenta» per cinque minuti. Un registry che chiede di rallentare descrive l’attesa e il rifiuto che la conclude.

Ogni tentativo è un nuovo caricamento degli stessi byte, mai un nuovo invio della richiesta fallita. Un registry che ha già ricevuto il corpo di un caricamento può rifiutare la stessa richiesta una seconda volta, e ciò che accetta è un nuovo caricamento. Il contenuto che il registry contiene già vale come caricato, e un passaggio ritentato scrive ciò che avrebbe scritto il primo tentativo, quindi un tentativo andato a buon fine ma la cui risposta è andata persa non scrive nulla due volte: il manifest mantiene il suo digest, e la versione porta una sola firma e una sola data di pubblicazione.

Ogni altro errore termina subito il passaggio: una credenziale rifiutata (401, 403, o nessuna credenziale memorizzata per il registry), qualsiasi altra risposta del registry, un registry del tutto irraggiungibile, o un push che interrompi. Un passaggio che fallisce ancora dopo l’ultimo tentativo fa fallire il comando, e l’errore nomina il passaggio — il contenuto, il manifest, il tag, la firma o la data di pubblicazione. Ciò che i passaggi precedenti hanno pubblicato resta pubblicato; Firma e La data di pubblicazione spiegano cosa significa per la versione.

Per questi errori vengono ritentate solo le scritture. La lettura di ciò che il registry contiene già alla versione, prima che venga caricato qualsiasi cosa, no, anche se, come ogni richiesta, attende il tempo indicato da un registry che chiede di rallentare.

Firma

aggrega push può firmare l’artefatto mentre lo pubblica e allegare la firma come referrer OCI — un bundle Sigstore (compatibile con cosign) sul digest immutabile del manifest dell’artefatto. La firma è un manifest fratello, quindi firmare non ripubblica né modifica mai i byte pubblicati. Il referrer chiama il suo bundle signature.json, quindi un client OCI generico che scarica il referrer tramite il suo digest scrive il bundle in quel file.

La firma è sign-before-push: il digest del manifest è noto prima della pubblicazione, quindi aggrega push costruisce il firmatario e firma il digest prima che qualsiasi byte raggiunga il registry. Se il firmatario non può essere costruito o la firma fallisce, il push viene rifiutato prima che venga caricato qualsiasi cosa — non viene pubblicato nulla, quindi una firma fallita non lascia mai contenuto non firmato sul registry. Prima di rifiutare, una chiamata di firma fallita in modo transitorio — qualsiasi errore per cui una scrittura nel registry viene ritentata, o l’autorità di certificazione keyless che segnala di non aver potuto elaborare il token di identità — viene ritentata, fino a tre tentativi con le stesse attese. All’interno di una chiamata di firma keyless, una richiesta a cui l’autorità di certificazione, il log di trasparenza o l’autorità di marcatura temporale risponde con 429 Too Many Requests o con un errore del server viene prima inviata di nuovo a quel servizio, come descrive aggrega sign.

La firma viene allegata dopo che il contenuto è arrivato, quindi un allegato fallito lascia effettivamente il contenuto pubblicato senza di essa. L’allegato è una scrittura, ritentata come descritto in Quando il registry fallisce una scrittura. Se fallisce ancora, il comando esce con codice diverso da zero nominando la firma che non ha potuto allegare, e un consumatore il cui registry richiede firme rifiuta la versione finché non viene allegata una firma. Eseguire di nuovo lo stesso push la allega, come descritto in Completare una pubblicazione lasciata parziale da un push precedente; aggrega sign ne allega una alla versione pubblicata tramite riferimento.

Una pubblicazione richiede una firma quando il blocco signing proprio del registry di destinazione imposta required: true, oppure quando lo fa il blocco signing di primo livello per ogni registry — ciascuno limitato ai tipi elencati nel suo kinds, dove ne elenca. Una tale pubblicazione firma per impostazione predefinita, e --sign richiede la firma esplicitamente. Non esiste alcun flag per eseguire il push di contenuto non firmato dove è richiesta una firma — quel push si arresta sempre.

Due modalità di firma:

  • Keyless (predefinita) — una chiave effimera legata a un’identità OIDC da un certificato Fulcio di breve durata, registrata nel log di trasparenza Rekor. Fulcio e Rekor usano per impostazione predefinita le istanze Sigstore pubbliche (https://fulcio.sigstore.dev, https://rekor.sigstore.dev). Il timestamp attendibile keyless deriva dall’inclusione nel log di trasparenza di Rekor; un’autorità di timestamp RFC3161 separata è facoltativa — fornisci --timestamp-url con un endpoint completo per abilitarne una. In un terminale interattivo la firma keyless non richiede flag: la CLI apre un browser per ottenere un token di identità OIDC di breve durata. Su GitHub Actions non ne richiede nemmeno: la CLI genera automaticamente il token OIDC del workflow dall’endpoint ambientale del runner. Per altri usi non interattivi / CI, esporta AGGREGA_IDENTITY_TOKEN (o SIGSTORE_ID_TOKEN), oppure passa --identity-token; senza un token fornito, senza endpoint ambientale e senza terminale il push viene rifiutato. Vedi environment-variables.md per il modello dei token in CI.
  • Keyed (--key) — una chiave ECDSA P-256 conservata offline (PEM compatibile con cosign), la via d’uscita per gli ambienti senza un provider di identità OIDC. Non viene contattato alcun provider di identità, alcuna autorità di certificazione né alcun log di trasparenza.

Gli URL dei servizi keyless e il percorso della chiave keyed possono essere impostati anche in .aggrega-config.yaml sotto un blocco signing: (globale e per registry); un flag sovrascrive la configurazione, e la configurazione sovrascrive il default pubblico. Il token di identità OIDC non è mai un campo di configurazione (è un segreto di breve durata), e la chiave privata non è mai inline nella configurazione — solo un percorso verso di essa.

La data di pubblicazione

L’ora di creazione del manifest è fissata, quindi il digest di un manifest dipende solo da ciò che viene pubblicato e mai da quando. La data in cui una versione è stata pubblicata viaggia invece accanto a essa, e la sua provenienza dipende dalla firma:

  • Una firma keyless la porta già. La sua voce nel log di trasparenza registra quando il log ha integrato la firma, e la promessa firmata del log attesta quell’ora. aggrega push non scrive nient’altro.
  • Una firma keyed, o l’assenza di firma, non porta alcuna ora. Quindi, dopo che l’entità e l’eventuale firma sono arrivate, aggrega push allega al manifest un piccolo referrer published-at — chiamato published-at.json per un client OCI generico — che contiene un timestamp RFC 3339 in UTC al secondo, letto dall’orologio della macchina che pubblica. Non è firmato: è la dichiarazione dell’editore, e un lettore la registra come tale. La riga Publication date attached: lo riporta.

Come una firma, il referrer published-at è un manifest fratello che punta al manifest pubblicato, quindi non sposta alcun digest e non cambia alcun tag, e il controllo sulla pubblicazione su una versione esistente non ne è influenzato. Un push ripetuto dello stesso contenuto allega una data solo a una versione che non ne porta alcuna, indicando il proprio orologio — vedi Completare una pubblicazione lasciata parziale da un push precedente. La data viene letta dall’orologio una sola volta, prima del primo tentativo di allegato, quindi un allegato ritentato — vedi Quando il registry fallisce una scrittura — indica la stessa data. Un push che ha pubblicato il contenuto ma non è riuscito ad allegare la data dopo quei tentativi esce con codice diverso da zero e nomina ciò che non è stato allegato. aggrega registry update registra la data di ogni versione insieme a quale delle due fonti l’ha fornita.

Offline

La pubblicazione è un round trip di rete e non ha alcuna forma che non lo sia, quindi in modalità offline — la chiave di primo livello offline in un file di configurazione, AGGREGA_OFFLINE o --offline — aggrega push rifiuta prima di leggere la tua entità. Il rifiuto indica quale dei tre ha impostato la modalità, ed è ciò di cui un lettore ha bisogno quando è stata la configurazione committata di un progetto ad attivarla anziché qualcosa che ha digitato.

--dry-run è l’eccezione, ed è un’eccezione per ciò che fa: calcola il bundle, stampa il riferimento che pubblicherebbe e il digest che quella pubblicazione produrrebbe, e non contatta mai il registry. Questo lo rende la forma di pubblicazione sicura offline anziché un conflitto con la modalità, e continua a funzionare in essa — con una precisazione. Per una Recipe o FeatureRecipe il cui source: remoto è scritto per intero, quella sorgente viene scaricata per confrontarne il pin, e in modalità offline quel download viene rifiutato con un messaggio proprio, quindi un dry run su una tale entità si ferma lì anziché riportare un bundle di cui non può garantire.

Per pubblicare per un’esecuzione da un workspace la cui configurazione è offline, passa --offline=false.

Variabili d’ambiente

Gli input di firma e il registry di destinazione possono essere forniti tramite l’ambiente, sovrascrivendo .aggrega-config.yaml mentre un flag ha comunque la precedenza:

  • AGGREGA_IDENTITY_TOKEN — il token di identità OIDC keyless (la controparte d’ambiente di --identity-token). SIGSTORE_ID_TOKEN è accettato come alias di interoperabilità con l’ecosistema sigstore, con priorità inferiore a AGGREGA_IDENTITY_TOKEN e all’endpoint ambientale di GitHub Actions. Il token non è mai un campo di configurazione.
  • AGGREGA_SIGNING_FULCIO_URL, AGGREGA_SIGNING_REKOR_URL, AGGREGA_SIGNING_TIMESTAMP_URL — gli URL dei servizi keyless.
  • AGGREGA_SIGNING_KEY_PATH — un puntatore al percorso di un PEM con chiave keyed (mai il materiale della chiave).
  • AGGREGA_DEFAULT_REGISTRY — il registry di destinazione quando --registry è omesso.

La precedenza è flag > ambiente > configurazione > default. Vedi environment-variables.md per l’elenco completo e il modello di precedenza.

Autenticazione

aggrega push legge le credenziali dei registry come fa aggrega pull — dalla configurazione delle credenziali di Docker e dai credential helper che essa nomina. Esegui aggrega login <registry>, che non richiede alcun altro strumento, oppure docker login <registry> prima di eseguire il push verso un registry privato. Vedi aggrega-pull.md per sapere dove viene letta quella configurazione.

Vedi anche

  • ./aggrega-sign.md — firma a posteriori un artefatto già pubblicato (la controparte post-pubblicazione di --sign).
  • ./aggrega-lint.md — il controllo di pubblicazione (--pre-publish) che dovrebbe precedere un push.
  • ./aggrega-pull.md — il lato del consumo, che risolve ed esegue il pin di ciò che push pubblica.
  • ./aggrega-serve.md — il daemon offre questa stessa pubblicazione in aggrega/publishEntity, così un editor può eseguirla senza lasciare la sessione; viene eseguita solo quando una richiesta la nomina, e risponde con il riferimento, il digest pubblicato — in un dry run, il digest che --dry-run stampa — fin dove è arrivata la chiamata, e le voci per cui questo comando avvisa come windowsUnusableEntries.
  • ./aggrega-mcp.md — la stessa funzionalità come strumento publish-entity, che un assistente può chiamare e che risponde con quelle voci come windows_unusable_entries. Leggi cosa dice quella pagina sul consentirlo prima di farlo.
  • ../../architecture/13-catalog-and-registry.md — il modello di catalogo, registry e mediatype OCI.

Sinossi

aggrega push <entity-path> [flags]

Descrizione

Publish a single catalog entity to an OCI registry, where other workspaces
resolve it with "aggrega pull".
The entity is read from the path given, bundled for transport, and pushed to
<registry>/<kind>/<metadata.name>:<metadata.version>, the repository path
lowercased; a Recipe or FeatureRecipe carries its spec.capability, and a Plugin
its metadata.pluginType, as a segment between <kind> and <metadata.name>. The
tag is the entity's own metadata.version. Run "aggrega push --list-kinds" for
the kinds this binary publishes, one per line and nothing else, so a script can
read it directly. Release and Manifest are deployment-side inputs rather than
catalog artifacts and are refused.
Every kind has a directory of its own except Aggregate, Release and Manifest: an
entity of any other kind is refused when another entity sits in its directory,
before anything is pinned or bundled, and the refusal names the entity in the way.
The directory's name is not judged.
A Component, Feature, Recipe or FeatureRecipe is read the way a build reads it
before it is bundled, and one that read refuses is refused here for the same
reason: a document that fails its kind's schema, a path naming content outside
the entity's own directory, which would not travel with the entity, or a schema
a Component or Feature imports that cannot be read or used.
A Plugin is read against its kind's schema too, before its .wasm is read, so a
metadata.version that is not a semantic version is refused. Its .wasm must then
agree with the entity on what the plugin offers and on its version, and a .wasm
whose version says it was built from a working tree with uncommitted changes —
the -dirty mark a build adds — is refused. A version disagreement and a build
from uncommitted changes are both cleared by building the plugin from a clean
checkout of the commit its release tag names, never by copying the version it
reports into the entity. A development version such as 1.0.0-3-g1a2b3c4, built
from a commit, and a prerelease such as 1.0.0-rc.1 publish.
What is published is the entity document and the files the entity itself names
beside it — a Recipe's or FeatureRecipe's local source, each file an $import:
names, the entity.lock beside it, and each schema file a Component or Feature
imports — and nothing else in its directory. An entity that names nothing
publishes as its document, unchanged; one that names a file publishes as a
gzipped archive of the document and those files. A directory it names travels
with every file under it that the ignore rules recorded in its entity.lock keep:
the rules the plugin serving its capability declared, and the author's own
.aggregaignore beside it, composed when the entity was pinned. A symbolic link
among those files is refused rather than followed. A local source written as a
template names no one directory until a Release fills it in, so an entity with
one carries every such file in its own directory, and push says so.
Push warns about each file an archive carries whose path holds a part Windows
cannot hold as written: a name Windows reserves for a device — CON, PRN, AUX,
NUL, COM1 or LPT1, say, in any letter case and whatever extension follows — or a
part ending in a full stop or a space. On Windows, aggrega refuses to unpack
such a file, so a Windows workspace cannot use the version. The warning is
written to standard error on every platform, one line per file, the entity
document's own file name judged with the rest, and it refuses nothing: the push,
or its dry run, goes ahead or stops exactly as it would without it. An entity
that names nothing publishes as its document alone and is never warned about.
Each file travels with mode 0644, whatever its permission bits — the execute
bit included — in the checkout it is published from. The OCI manifest names the
digest of the published bytes, so "aggrega pull" refuses a download that does
not match it. The lockfile a pull writes records the entity by the digest of its
content — each file's path and its bytes — which is the digest a pull in the
author's own workspace records for the same entity in its catalog directory, so
a build on either side refuses content that no longer matches.
Push signs before it publishes: where signing applies, the signature is made
over the manifest digest before any bytes reach the registry, so a failed
signing refuses the push rather than leaving unsigned content published.
The manifest's creation time is pinned, so the digest depends only on what is
published and never on when. Push states when it published beside the manifest
instead, as a small published-at attachment carrying this machine's clock, in
UTC to the second — unless the signature it attached already carries a time a
transparency log attests, as a keyless signature does. So a keyed or unsigned
publication writes one, and a keyless one does not. The attachment moves no
digest and changes no tag. "aggrega registry update" records the date, with
which of the two it came from.
Push refuses to replace content already published at the same version:
publish changed content under a new version instead.
A Recipe or FeatureRecipe carries the pins for its own inputs in the entity.lock
beside it, and pinning them is a step you run before publishing: aggrega pin.
A push that does not run that step refuses an entity whose entity.lock is
missing a pin, or holds one an input no longer matches, and names the step.
Pass --pin-sources, or set pin_sources_at_push in the workspace configuration, to
have push run that same step first, so the lock it writes is part of what is
published; --pin-sources=false skips it for one run.

Flag

FlagPredefinitoDescrizione
--dry-runfalseCalcola il bundle e stampa il : proposto con il digest che una pubblicazione produrrebbe, senza contattare il registry. Un’entità che la pubblicazione rifiuterebbe per un pin mancante viene rifiutata anche qui
--entity—Percorso dello YAML dell’entità da pubblicare (in alternativa, passalo come argomento posizionale)
--fulcio-url—URL dell’autorità di certificazione Fulcio per la firma keyless. Se omesso, viene usata l’istanza pubblica di Fulcio.
--identity-token—Token di identità OIDC per la firma keyless. Facoltativo in un terminale interattivo (un flusso nel browser ne acquisisce uno) e su GitHub Actions (il token OIDC del workflow viene generato automaticamente); obbligatorio per altri usi non interattivi/CI, dove può invece essere esportato come AGGREGA_IDENTITY_TOKEN o SIGSTORE_ID_TOKEN.
--key—Percorso di un PEM di chiave privata ECDSA P-256 posseduta, per la firma con chiave offline. Se omesso, viene usata la firma keyless.
--list-kindsfalseElenca ogni tipo di entità che può essere pubblicato, poi esce senza pubblicare nulla. L’output è leggibile da una macchina e la sua forma è stabile: un tipo per riga, in ordine, senza nient’altro.
--pin-sourcesfalseEsegue il passaggio di pin dell’autore dell’entità sull’entità prima di creare il bundle, così l’entity.lock che il passaggio scrive accanto a essa fa parte di ciò che viene pubblicato, anziché rifiutare un’entità il cui lock non registra i suoi pin. È lo stesso passaggio di aggrega pin e scrive gli stessi byte. Scrive accanto all’entità, quindi viene eseguito solo dove l’entità ha una collocazione scrivibile: un documento in una directory da cui è stato letto — che un push ha sempre, poiché pubblica il documento dell’entità che indichi. Sovrascrive pin_sources_at_push del workspace in entrambe le direzioni: —pin-sources esegue il pin per questa esecuzione e —pin-sources=false no, qualunque cosa dica l’impostazione
--plugin—Percorso dell’artefatto .wasm locale per un’entità Plugin. Obbligatorio quando si pubblica un Plugin: la pubblicazione carica l’artefatto .wasm, ne calcola il digest del contenuto ed esegue il push dell’entità.
--registry—Host del registry di destinazione (sovrascrive il default_registry del workspace)
--rekor-url—URL del transparency log Rekor per la firma keyless. Se omesso, viene usata l’istanza pubblica di Rekor.
--signfalseFirma l’artefatto pubblicato e allega la firma come referrer OCI. Se omesso, la firma segue la policy del registry di destinazione.
--timestamp-url—URL facoltativo della timestamp authority RFC3161 per la firma keyless.