aggrega pin
aggrega pin <entity-path> enregistre, dans l’entity.lock à côté d’une Recipe ou d’une FeatureRecipe, le pin de contenu de chaque entrée que l’entité lit en dehors de son propre document. C’est l’étape de l’auteur de l’entité : exécutez-la avant que l’entité soit consommée ou publiée, et committez le lock qu’elle écrit.
aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yamlCe qu’elle enregistre
Une entité peut dépendre d’octets situés en dehors de son propre document, et le lock contient un pin pour chacun :
- Une
source:distante dont vous avez écrit les coordonnées en entier — aucun template danskind,url,chart,module_subdir,versionouref. L’étape la récupère et enregistre la version vers laquelle elle s’est résolue — pour une source git, le commit que nommait sonref— ainsi que le digest du contenu récupéré. - Un fichier qu’une entrée
artifactsimporte avec$import. L’étape calcule le digest du fichier tel qu’il se trouve dans votre workspace. - Chaque fichier d’une
source:qui nomme un répertoire ou un fichier à côté de l’entité. Rien n’est récupéré : l’étape calcule le digest de chaque fichier que la source apporte à ce que transporte une publication de l’entité — chaque fichier sous le répertoire nommé que conservent les règles d’exclusion de l’entité, ou l’unique fichier — et l’enregistre par son chemin à côté de l’entité. Un fichier à côté de la Recipe que la source n’apporte pas, comme un README, ne reçoit pas de pin. Une source écrite sous forme de template, comme./charts/{{ .values.flavour }}, ne nomme son répertoire qu’une fois qu’une Release la remplit, elle apporte donc chaque fichier du répertoire de l’entité que les règles conservent, et chacun d’eux reçoit un pin. Une build compare la source à ces pins avant que son provider ne la lise, de sorte qu’un fichier ajouté, modifié ou supprimé depuis le pin arrête la build — A local source no longer matches the pins recorded beside its Recipe (Une source locale ne correspond plus aux pins enregistrés à côté de sa Recipe). - Les règles d’exclusion elles-mêmes, pour une
source:qui est un répertoire. L’étape enregistre quel plugin a servi la capability de l’entité et les règles exactes qu’il a composées, comme le décrit la section suivante.
Ce qu’elle n’enregistre pas : une source distante dont les coordonnées sont remplies à partir d’un template, qui ne nomme un artefact qu’une fois qu’une Release la remplit et reçoit un pin dans le lockfile de chaque Release par aggrega pull ; et une entrée artifacts inline ou une entrée tirée d’une ArtifactLibrary. Le fichier lui-même est décrit champ par champ dans le schéma du lock d’entité.
Aucune Release n’est nécessaire. Une source écrite en entier nomme le même artefact pour chaque Release qui utilisera un jour l’entité, sa résolution ne requiert donc rien que fournisse une Release. C’est ce qui permet à un auteur de pinner une entité dans un workspace qui n’a aucune Release.
Le fichier de l’entité n’est jamais écrit. Ce que l’étape dérive va à côté de l’entité ; ce que vous avez saisi reste exactement tel que vous l’avez saisi. Une nouvelle exécution sur des entrées inchangées laisse le lock identique octet pour octet, et une entité qui cesse de lire tout ce qu’un lock enregistre voit son lock supprimé. Un Component, une Feature ou tout autre type qui ne lit aucune entrée de ce genre est signalé comme n’ayant rien à pinner, et rien à côté de lui n’est modifié.
Quels fichiers sont livrés avec une entité
Une Recipe ou une FeatureRecipe dont la source: nomme un répertoire à côté d’elle — un chart colocalisé, un module — transporte les fichiers de ce répertoire lorsqu’elle est publiée. Tous les fichiers qu’il contient n’y ont pas leur place : un répertoire de gestion de versions, un cache de dépendances, les restes d’un éditeur. Les fichiers qui y ont leur place sont déterminés par des règles d’exclusion, dans la syntaxe qu’utilise .gitignore, et c’est vous qui les contrôlez. Elles proviennent de deux endroits :
- Le plugin qui effectue le rendu de la capability de l’entité déclare ce que son propre écosystème ne livre jamais. Les plugins de charts excluent les répertoires de gestion de versions (
.git/,.hg/,.svn/,.bzr/) et les fichiers cachés soustemplates/d’un chart, et respectent le.helmignoredu chart lui-même : partout où le parcours de la source en rencontre un, ses lignes sont lues comme des règles supplémentaires pour le répertoire qui le contient. Le plugin Terraform exclut les répertoires de gestion de versions et le répertoire de travail.terraform/— mais pas le fichier de verrouillage des dépendances, destiné à voyager avec le module — et respecte.terraformignorede la même manière. Un plugin qui ne déclare rien conserve tout. - Votre propre
.aggregaignore, un fichier à côté du document de l’entité, dans la même syntaxe. Ses lignes s’appliquent après celles du plugin et après chaque fichier d’exclusion que nomme le plugin, de sorte que vous avez le dernier mot sur tout chemin que vous nommez : une ligne telle que.venv/exclut un répertoire dont le plugin ne sait rien, et une ligne telle que!.git/réintègre un répertoire que le plugin avait exclu. Le fichier lui-même ne voyage jamais ; ses règles, si, à l’intérieur du lock.
.venv/*.bak!notes.bakChaque règle est lue par rapport au répertoire auquel elle appartient. Une règle que déclare le plugin est lue depuis la racine du répertoire source ; une ligne d’un .helmignore depuis le répertoire qui contient ce fichier ; une ligne de votre .aggregaignore depuis le répertoire propre de l’entité. Une règle sans barre oblique, ou avec seulement une barre finale, correspond à un nom à n’importe quelle profondeur ; une barre oblique finale ne correspond qu’à un répertoire ; un ! initial réintègre ce qu’une règle précédente avait exclu. Un répertoire qu’une règle exclut n’est pas parcouru, de sorte qu’un fichier qu’il contient ne revient qu’une fois que le répertoire lui-même revient — !.git/HEAD seul ne réintègre pas le fichier tant que .git/ est exclu, alors que !.git/ le fait.
Le plugin dont les règles sont lues est celui qui sert la capability dans votre workspace au moment du pin : la liaison de provider de votre workspace pour cette capability, ou à défaut le plugin intégré à aggrega. L’étape enregistre dans l’entity.lock ce plugin par son seul nom, par exemple provider/terraform, sans version, ainsi que les règles exactes qu’il a composées ; refaire le pin avec un aggrega plus récent dont le plugin déclare les mêmes règles laisse le lock inchangé. Dès lors, chaque lecture du répertoire applique les règles enregistrées et aucune autre : une publication de l’entité, la comparaison à laquelle un pull ou un push soumet le lock, la ligne de l’entité dans un lockfile, la comparaison d’une build, le rendu qui transmet le répertoire à un provider, et aggrega pull --verify. Ce que vous publiez est donc exactement ce que votre propre build rend, et une liaison modifiée, un .aggregaignore modifié ou un aggrega plus récent ne changent rien tant que vous ne refaites pas le pin — moment où le diff du lock montre ce qui a bougé. Un fichier qu’un plugin nomme comme fichier d’exclusion, tel qu’un .helmignore, est lui-même l’un des fichiers de la source et reçoit un pin comme n’importe quel autre, sauf si une règle l’exclut ; le modifier sans refaire le pin est donc détecté par le pull ou la build suivant. Un lock qui n’enregistre aucune règle conserve chaque fichier sous le répertoire.
Un consommateur effectue le rendu des fichiers que vos règles ont conservés. Un plugin peut effectuer le rendu d’une Recipe publiée pour sa capability lorsqu’il parle la même version d’ABI, que son contrat correspond à ce que revendique son entité et qu’il n’a besoin d’aucun fichier en dehors de l’ensemble publié. Un plugin qui a besoin d’un fichier que l’ensemble a exclu doit faire échouer sa build de manière explicite et nommer le fichier ; le rôle de l’hôte est de refuser tout empaquetage ou toute lecture d’un fichier que l’ensemble ne contient pas, en le nommant. Lorsque le plugin que le workspace d’un consommateur lie à la capability déclare des règles différentes de celles qu’enregistre votre lock, l’aggrega pull du consommateur le signale par un avertissement nommant les deux plugins et la différence, et poursuit.
Un lien symbolique parmi les fichiers d’une entité est refusé, où qu’il pointe et qu’il se résolve ou non — voir A symbolic link sits among the files an entity carries (Un lien symbolique se trouve parmi les fichiers que transporte une entité). Un lien que vos règles excluent est ignoré comme tout autre fichier qu’elles excluent. Un chemin nommé par l’entité qui passe par un répertoire qui est un lien menant hors du répertoire de l’entité est également refusé, avant que quoi que ce soit ne reçoive de pin — voir A path names content outside the entity’s own directory (Un chemin nomme un contenu situé hors du répertoire propre de l’entité).
Où va le lock
Le lock est écrit à côté du document que vous nommez, dans le même répertoire, l’entité a donc besoin d’un emplacement accessible en écriture : un document dans l’un de vos répertoires. Une entité qu’un pull a résolue depuis le cache de contenu n’a pas d’emplacement de ce genre et ne reçoit jamais de pin de quoi que ce soit.
Un répertoire, une entité. Un répertoire contient un seul entity.lock, l’étape refuse donc une Recipe ou une FeatureRecipe qui partage son répertoire avec toute autre entité, que l’une ou l’autre ait ou non quelque chose à pinner, en nommant chaque entité gênante — le refus est An entity shares its directory with another entity (Une entité partage son répertoire avec une autre entité). Chaque type a son propre répertoire, sauf Aggregate, Release et Manifest, qui peuvent cohabiter ; un push soumet l’entité qu’il publie à la même règle, comme l’explique Une entité par répertoire. L’étape ne juge que ce pour quoi elle écrit un lock, de sorte qu’un Component ou tout autre type pour lequel elle n’a rien à pinner est signalé comme n’ayant rien à pinner, et le refus atteint cette entité lorsqu’elle est publiée. Un fichier à côté de l’entité qui n’est pas un document d’entité — un fichier de chart, le fichier importé lui-même — ne gêne pas. Chaque document à côté de l’entité n’est lu que depuis l’intérieur du workspace ou, pour un document que vous nommez en dehors de celui-ci, depuis l’intérieur de son propre répertoire — où se trouve aussi le lock — de sorte qu’un document qui est un lien menant vers l’extérieur arrête l’étape en nommant le lien, sans le lire, comme l’explique la frontière du workspace.
Qui pinne, et quand
Le pin est un devoir de rédaction. Une entité dont les entrées n’ont pas de pin n’est pas encore prête à être consommée, c’est pourquoi, par défaut, un pull n’enregistre aucun pin : sur une Recipe ou une FeatureRecipe dans l’un de vos répertoires de catalogue que la Release construit, il compare ce que cette étape enregistrerait avec ce que contient le lock, et s’arrête lorsqu’un pin manque ou ne correspond plus à son entrée. L’arrêt nomme l’entité, chaque entrée et s’il s’agit d’une source distante, d’un fichier importé ou d’un fichier d’une source locale, ainsi que cette commande. Il s’agit de An entity reads an input the lock beside it records no pin for (Une entité lit une entrée pour laquelle le lock à côté d’elle n’enregistre aucun pin). Un push soumet l’entité qu’il publie à la même comparaison et refuse avec le même arrêt, de sorte qu’une entité ne peut pas atteindre un registry via aggrega push avec un pin non enregistré — Pinner avant de publier l’explique. Une source locale est traitée comme un seul ensemble de fichiers : un lock qui n’en enregistre aucun arrête un pull ou un push, tout comme un fichier ajouté, modifié ou supprimé depuis le pin, comme tout autre pin manquant ou périmé.
Un arrêt lors d’un premier pull est à corriger par l’éditeur, jamais par le consommateur. Lorsque vous consommez un catalogue rédigé par quelqu’un d’autre — un checkout de celui-ci dans l’un de vos répertoires, par exemple — et qu’une entité y est dépourvue de pin, l’auteur n’a jamais exécuté cette étape. Votre remède n’est pas de modifier son répertoire à la main : définissez la clé de workspace ci-dessous, afin que vos pulls enregistrent eux-mêmes les pins.
Deux commandes exécutent cette même étape pour vous, et écrivent les mêmes octets :
aggrega pull --pin-sourcesl’exécute sur les entités que la Release construit, au lieu de s’arrêter.aggrega push --pin-sourcesl’exécute sur l’entité avant sa mise en bundle, de sorte que le lock qu’elle écrit fait partie de ce qui est publié, au lieu de refuser.
Chacune a une clé de workspace qui fait du pin son comportement par défaut, pin_sources_at_pull et pin_sources_at_push, toutes deux désactivées par défaut et chacune ne régissant que sa propre commande. Le flag prévaut sur sa clé dans les deux sens : --pin-sources pinne pour une exécution quoi que dise la clé, et --pin-sources=false ne le fait pas. Un workspace configuré pour pinner peut donc retrouver l’arrêt pour un pull. Une build qui remplit son propre lockfile est un pull, elle suit donc pin_sources_at_pull. Les clés sont décrites dans la référence de configuration.
Modifier une entité publiée
Bonne pratique : une modification d’une entité que vous avez déjà publiée va dans une nouvelle version, suivie d’un pin — jamais d’un nouveau pin de la version déjà diffusée. Copiez l’entité dans un nouveau répertoire de version, effectuez-y la modification et exécutez aggrega pin sur la nouvelle version. La version publiée continue de décrire exactement les octets avec lesquels elle a été publiée, et un consommateur qui passe à la nouvelle le fait délibérément.
Le produit impose une moitié de cela : publier un contenu modifié sous une version déjà publiée est refusé, de sorte qu’une version publiée ne peut pas être remplacée discrètement. Il n’impose pas l’autre moitié dans votre propre workspace. Refaire le pin d’une version existante après une modification est parfois exactement ce qu’il faut — une entité que vous consommez au sein d’une application et que vous n’avez pas publiée, par exemple — donc rien ne vous en empêche, et c’est à vous de maintenir cette discipline.
La même étape sur les autres surfaces
Le daemon propose cette étape sous la forme aggrega/pin (aggrega serve), et le protocole d’outils sous la forme de l’outil pin (aggrega mcp) ; tous deux écrivent les mêmes octets que cette commande. Sur un listener HTTP, l’outil écrit dans le workspace et atteint les hôtes que nomment les sources d’une entité, un appelant a donc besoin du scope d’écriture du workspace pour l’appeler — la même autorisation que celle dont a besoin un pull.
Voir aussi
- aggrega-pull.md — le lock d’entité, ce qu’une build compare avec lui, et l’arrêt.
- aggrega-push.md — publier une entité, et publier une version une seule fois.
- configuration.md —
pin_sources_at_pulletpin_sources_at_push.
Synopsis
aggrega pin <entity-path> [flags]Description
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.Options
| Option | Par défaut | Description |
|---|---|---|
--dry-run | false | Résoudre les entrées de l’entité et afficher l’entity.lock que l’étape écrirait au lieu de l’écrire : son chemin et le contenu qu’il contiendrait vont sur stdout, et rien ne change sur le disque. Un lock que l’étape laisserait identique octet pour octet n’est pas affiché. La résolution s’exécute exactement comme dans le cas contraire, le cache de contenu est donc tout de même rempli |