aggrega pin
aggrega pin <entity-path> registra, nell’entity.lock accanto a una Recipe o a una FeatureRecipe, il pin del contenuto di ogni input che l’entità legge al di fuori del proprio documento. È il passaggio dell’autore dell’entità: eseguilo prima che l’entità venga consumata o pubblicata, ed esegui il commit del lock che scrive.
aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yamlCosa registra
Un’entità può dipendere da byte al di fuori del proprio documento, e il lock contiene un pin per ciascuno:
- Un
source:remoto le cui coordinate hai scritto per esteso — nessun template inkind,url,chart,module_subdir,versionoref. Il passaggio lo scarica e registra la versione in cui si è risolto — per una sorgente git, il commit indicato dal suoref— e il digest del contenuto di ciò che è stato scaricato. - Un file che una voce di
artifactsimporta con$import. Il passaggio calcola il digest del file così com’è nel tuo workspace. - Ogni file di un
source:che indica una directory o un file accanto all’entità. Non viene scaricato nulla: il passaggio calcola il digest di ogni file che la sorgente contribuisce a ciò che una pubblicazione dell’entità porta con sé — ogni file sotto la directory indicata che le regole di esclusione dell’entità mantengono, oppure l’unico file — e lo registra con il suo percorso accanto all’entità. Un file accanto alla Recipe che la sorgente non contribuisce, come un README, non riceve un pin. Una sorgente scritta come template, come./charts/{{ .values.flavour }}, indica la sua directory solo quando una Release la compila, quindi contribuisce ogni file della directory dell’entità che le regole mantengono, e ognuno di essi riceve un pin. Una build confronta la sorgente con questi pin prima che il suo provider la legga, quindi un file aggiunto, modificato o rimosso dopo il pin arresta la build — A local source no longer matches the pins recorded beside its Recipe (Una sorgente locale non corrisponde più ai pin registrati accanto alla sua Recipe). - Le regole di esclusione stesse, per un
source:che è una directory. Il passaggio registra quale plugin ha servito la capability dell’entità e le regole esatte che ha composto, come descrive la sezione successiva.
Cosa non registra: una sorgente remota le cui coordinate sono compilate da un template, che indica un artefatto solo quando una Release lo compila e riceve un pin nel lockfile di ciascuna Release tramite aggrega pull; e una voce di artifacts inline o una presa da una ArtifactLibrary. Il file stesso è descritto campo per campo nello schema del lock dell’entità.
Non serve alcuna Release. Una sorgente scritta per esteso indica lo stesso artefatto per ogni Release che userà mai l’entità, quindi risolverla non richiede nulla che una Release fornisca. È ciò che permette a un autore di eseguire il pin di un’entità in un workspace che non ha alcuna Release.
Il file dell’entità non viene mai scritto. Ciò che il passaggio ricava va accanto all’entità; ciò che hai digitato resta esattamente come l’hai digitato. Rieseguirlo su input invariati lascia il lock identico byte per byte, e un’entità che smette di leggere qualsiasi cosa registrata da un lock vede il suo lock rimosso. Un Component, una Feature o qualsiasi altro tipo che non legge un input di questo genere viene segnalato come privo di elementi di cui eseguire il pin, e nulla accanto a esso viene toccato.
Quali file vengono distribuiti con un’entità
Una Recipe o una FeatureRecipe il cui source: indica una directory accanto a essa — un chart collocato insieme, un modulo — porta con sé i file di quella directory quando viene pubblicata. Non tutti i file al suo interno vi appartengono: una directory di controllo di versione, una cache di dipendenze, i residui di un editor. Quali file vi appartengono lo decidono le regole di esclusione, nella sintassi usata da .gitignore, e sei tu a controllarle. Provengono da due fonti:
- Il plugin che esegue il rendering della capability dell’entità dichiara ciò che il proprio ecosistema non distribuisce mai. I plugin per i chart escludono le directory di controllo di versione (
.git/,.hg/,.svn/,.bzr/) e i file nascosti sottotemplates/di un chart, e rispettano il.helmignoredel chart stesso: ovunque la visita della sorgente ne incontri uno, le sue righe vengono lette come regole aggiuntive per la directory che lo contiene. Il plugin Terraform esclude le directory di controllo di versione e la directory di lavoro.terraform/— non il file di lock delle dipendenze, che è pensato per viaggiare con il modulo — e rispetta.terraformignoreallo stesso modo. Un plugin che non dichiara nulla include tutto. - Il tuo
.aggregaignore, un file accanto al documento dell’entità, nella stessa sintassi. Le sue righe si applicano dopo quelle del plugin e dopo ogni file di esclusione indicato dal plugin, quindi l’ultima parola su qualsiasi percorso che indichi spetta a te: una riga come.venv/esclude una directory di cui il plugin non sa nulla, e una riga come!.git/reinclude una directory che il plugin aveva escluso. Il file stesso non viaggia mai; le sue regole sì, all’interno del lock.
.venv/*.bak!notes.bakOgni regola viene letta in relazione alla directory a cui appartiene. Una regola dichiarata dal plugin viene letta dalla radice della directory sorgente; una riga di un .helmignore dalla directory che contiene quel file; una riga del tuo .aggregaignore dalla directory dell’entità stessa. Una regola senza barra, o con la sola barra finale, corrisponde a un nome a qualsiasi profondità; una barra finale corrisponde solo a una directory; un ! iniziale reinclude ciò che una regola precedente aveva escluso. In una directory esclusa da una regola non si entra, quindi un file al suo interno viene reincluso solo quando lo è la directory stessa — !.git/HEAD da solo non reinclude il file finché .git/ è escluso, mentre !.git/ sì.
Il plugin le cui regole vengono lette è quello che serve la capability nel tuo workspace al momento del pin: il binding del provider del tuo workspace per quella capability, oppure il plugin integrato in aggrega. Il passaggio registra nell’entity.lock quel plugin per nome, ad esempio provider/terraform, senza versione, e le regole esatte che ha composto; eseguire di nuovo il pin con un aggrega più recente il cui plugin dichiara le stesse regole lascia il lock invariato. Da quel momento ogni lettura della directory applica le regole registrate e nessun’altra: una pubblicazione dell’entità, il confronto con il lock eseguito da un pull o da un push, la riga dell’entità in un lockfile, il confronto di una build, il rendering che passa la directory a un provider e aggrega pull --verify. Così ciò che pubblichi è esattamente ciò che la tua build esegue nel rendering, e un binding cambiato, un .aggregaignore modificato o un aggrega più recente non cambiano nulla finché non esegui di nuovo il pin — e a quel punto il diff del lock mostra cosa si è spostato. Un file che un plugin indica come file di esclusione, come un .helmignore, è a sua volta uno dei file della sorgente e riceve un pin come qualsiasi altro, a meno che una regola non lo escluda, quindi modificarlo senza eseguire di nuovo il pin viene rilevato dal pull o dalla build successivi. Un lock che non registra regole mantiene ogni file sotto la directory.
Un consumatore esegue il rendering dei file che le tue regole hanno mantenuto. Un plugin può eseguire il rendering di una Recipe pubblicata per la sua capability quando parla la stessa versione di ABI, il suo contratto corrisponde a quanto dichiarato dalla sua entità e non ha bisogno di alcun file al di fuori dell’insieme pubblicato. Un plugin che ha bisogno di un file escluso dall’insieme deve far fallire la propria build in modo esplicito e indicare il file; il compito dell’host è rifiutare qualsiasi impacchettamento o lettura di un file che l’insieme non contiene, indicandolo. Quando il plugin che il workspace di un consumatore associa alla capability dichiara regole diverse da quelle registrate dal tuo lock, l’aggrega pull del consumatore lo segnala con un avviso che indica entrambi i plugin e la differenza, e prosegue.
Un link simbolico tra i file di un’entità viene rifiutato, ovunque punti e che si risolva o meno — vedi A symbolic link sits among the files an entity carries (Un link simbolico si trova tra i file che un’entità porta con sé). Un link che le tue regole escludono viene ignorato come qualsiasi altro file escluso. Anche un percorso indicato dall’entità che passa attraverso una directory che è un link verso l’esterno della directory dell’entità viene rifiutato, prima che venga eseguito qualsiasi pin — vedi A path names content outside the entity’s own directory (Un percorso indica contenuto al di fuori della directory dell’entità).
Dove va il lock
Il lock viene scritto accanto al documento che indichi, nella stessa directory, quindi l’entità ha bisogno di una posizione scrivibile: un documento in una tua directory. Un’entità che un pull ha risolto dalla cache dei contenuti non ha una posizione del genere e non riceve mai un pin da nulla.
Una directory, un’entità. Una directory contiene un solo entity.lock, quindi il passaggio rifiuta una Recipe o una FeatureRecipe che condivide la directory con qualsiasi altra entità, che l’una o l’altra abbia o meno qualcosa di cui eseguire il pin, indicando ogni entità d’intralcio — il rifiuto è An entity shares its directory with another entity (Un’entità condivide la propria directory con un’altra entità). Ogni tipo ha una directory propria tranne Aggregate, Release e Manifest, che possono stare fianco a fianco; un push applica la stessa regola all’entità che pubblica, come spiega Un’entità per directory. Il passaggio giudica solo ciò per cui scrive un lock, quindi un Component o qualsiasi altro tipo per cui non ha nulla di cui eseguire il pin viene segnalato come privo di elementi di cui eseguire il pin, e il rifiuto raggiunge quell’entità quando viene pubblicata. Un file accanto all’entità che non è un documento di entità — un file di chart, il file importato stesso — non è d’intralcio. Ogni documento accanto all’entità viene letto solo dall’interno del workspace o, per un documento che indichi al di fuori di esso, dall’interno della sua directory — dove si trova anche il lock — quindi uno che è un link verso l’esterno arresta il passaggio indicando il link, senza leggerlo, come spiega il confine del workspace.
Chi esegue il pin, e quando
Il pin è un dovere di authoring. Un’entità i cui input non hanno un pin non è ancora pronta per essere consumata, quindi per impostazione predefinita un pull non registra alcun pin: su una Recipe o una FeatureRecipe in una delle tue directory di catalogo che la Release compila, confronta ciò che questo passaggio registrerebbe con ciò che contiene il lock, e si arresta quando un pin manca o non corrisponde più al suo input. L’arresto indica l’entità, ciascun input e se si tratta di una sorgente remota, di un file importato o di un file di una sorgente locale, e questo comando. È 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). Un push applica lo stesso confronto all’entità che pubblica e rifiuta con lo stesso arresto, quindi un’entità non può raggiungere un registry tramite aggrega push con un pin non registrato — lo spiega Eseguire il pin prima di pubblicare. Una sorgente locale è trattata come un unico insieme di file: un lock che non ne registra nessuno arresta un pull o un push, e lo stesso fa un file aggiunto, modificato o rimosso dopo il pin, come qualsiasi altro pin mancante o non aggiornato.
Un arresto al primo pull spetta a chi pubblica correggerlo, mai a chi consuma. Quando consumi un catalogo scritto da qualcun altro — per esempio un suo checkout in una tua directory — e un’entità lì non ha un pin, l’autore non ha mai eseguito questo passaggio. Il rimedio non è modificare a mano la sua directory: imposta la chiave del workspace descritta sotto, così i tuoi pull registrano i pin da soli.
Due comandi eseguono questo stesso passaggio per conto tuo e scrivono gli stessi byte:
aggrega pull --pin-sourceslo esegue sulle entità che la Release compila, invece di arrestarsi.aggrega push --pin-sourceslo esegue sull’entità prima di crearne il bundle, così il lock che scrive fa parte di ciò che viene pubblicato, invece di rifiutare.
Ciascuno ha una chiave del workspace che rende il pin il suo comportamento predefinito, pin_sources_at_pull e pin_sources_at_push, entrambe disattivate per impostazione predefinita e ognuna valida solo per il proprio comando. Il flag prevale sulla sua chiave in entrambe le direzioni: --pin-sources esegue il pin per un’esecuzione qualunque cosa dica la chiave, e --pin-sources=false no. Così un workspace configurato per eseguire il pin può comunque riavere l’arresto per un pull. Una build che compila il proprio lockfile è un pull, quindi segue pin_sources_at_pull. Le chiavi sono descritte nel riferimento della configurazione.
Modificare un’entità pubblicata
Best practice: una modifica a un’entità che hai già pubblicato va in una nuova versione, seguita da un pin — mai un nuovo pin della versione già distribuita. Copia l’entità in una nuova directory di versione, apporta lì la modifica ed esegui aggrega pin sulla nuova versione. La versione pubblicata continua a descrivere esattamente i byte con cui è stata pubblicata, e un consumatore che passa alla nuova lo fa di proposito.
Il prodotto impone metà di questo: pubblicare contenuto modificato in una versione già pubblicata viene rifiutato, quindi una versione pubblicata non può essere sostituita di nascosto. Non impone l’altra metà nel tuo workspace. Rieseguire il pin di una versione esistente dopo una modifica a volte è esattamente la cosa giusta — per esempio un’entità che consumi all’interno di un’applicazione e che non hai pubblicato — quindi nulla te lo impedisce, e mantenere questa disciplina spetta a te.
Lo stesso passaggio sulle altre superfici
Il daemon offre questo passaggio come aggrega/pin (aggrega serve), e il protocollo degli strumenti come strumento pin (aggrega mcp); entrambi scrivono gli stessi byte che scrive questo comando. Su un listener HTTP, lo strumento scrive all’interno del workspace e raggiunge gli host indicati dalle sorgenti di un’entità, quindi un chiamante ha bisogno dello scope di scrittura del workspace per chiamarlo — la stessa autorizzazione di cui ha bisogno un pull.
Vedi anche
- aggrega-pull.md — il lock dell’entità, cosa una build confronta con esso e l’arresto.
- aggrega-push.md — pubblicare un’entità, e pubblicare una versione una sola volta.
- configuration.md —
pin_sources_at_pullepin_sources_at_push.
Sinossi
aggrega pin <entity-path> [flags]Descrizione
Record, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every inputthe entity reads from outside its own document: a remote source: whose coordinates you wrote outin full, a file an artifacts entry imports with $import, and each file of a local source:.
Pinning is the entity author's step. Run it on an entity before it is consumed — before youpublish it, and after every change to one of its inputs — and commit the entity.lock it writesbeside the entity. A pull over an entity whose lock does not record these pins halts and namesthis command, and so does a push of it; so does one whose local source has had a file added,changed or removed since it was pinned.
No Release is needed. A source whose coordinates carry no template names one artifact for everyRelease that uses the entity, so it is resolved and pinned here, with nothing supplied. A remotesource whose coordinates are filled in from a template is not pinned here: which artifact it names isdecided by each Release, and each identity it resolves to is pinned in that Release's lockfile.A source that names a directory beside the entity is not fetched: each file it contributes to whata publication of the entity carries is digested as it stands and pinned by its path, so a buildrefuses a file added, changed or removed after the pin. A local source written as a templatecontributes every file in the entity's directory, so each of those is pinned.
Which files a source directory contributes is decided here, once, and recorded. The step reads theignore rules the plugin serving the entity's capability declares — this workspace's provider bindingfor that capability, or else the plugin built into aggrega — together with the ignore files thatplugin names inside the source, such as a chart's .helmignore, and the .aggregaignore beside theentity, in gitignore syntax, whose lines come last and so have the final say. It records the pluginand the composed rules in the entity.lock, and every publication, pull, build and render of theentity applies the recorded rules and no others, so a changed binding or a newer binary movesnothing until you pin again. A symbolic link among the files is refused rather than followed.
The step writes beside the entity, so the entity needs a writable home: the document you name isread from its own directory and the lock lands next to it. The entity file itself is neverwritten to. Re-running over unchanged inputs leaves the lock byte-identical; an entity that readsnothing a lock records has its lock removed. A Component, a Feature or any other kind that readsno such input is reported as having nothing to pin, and nothing beside it is touched.
A directory holds one entity.lock, so the step refuses a Recipe or FeatureRecipe that shares itsdirectory with any other entity, naming the entity in the way, whether or not either has anythingto pin. Every kind has a directory of its own except Aggregate, Release and Manifest, which may sitside by side; a push holds the entity it publishes to the same rule.
aggrega pull --pin-sources and aggrega push --pin-sources run this same step on your behalf, andwrite the same bytes.Flag
| Flag | Predefinito | Descrizione |
|---|---|---|
--dry-run | false | Risolve gli input dell’entità e stampa l’entity.lock che il passaggio scriverebbe invece di scriverlo: il suo percorso e il contenuto che avrebbe vanno su stdout, e nulla su disco cambia. Un lock che il passaggio lascerebbe identico byte per byte non viene stampato. La risoluzione si svolge esattamente come altrimenti, quindi la cache dei contenuti viene comunque popolata |