aggrega pin
aggrega pin <entity-path> registra, en el entity.lock junto a una Recipe o FeatureRecipe, el pin de contenido de cada entrada que la entidad lee fuera de su propio documento. Es el paso del autor de la entidad: ejecútalo antes de que la entidad se consuma o se publique, y haz commit del lock que escribe.
aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yamlQué registra
Una entidad puede depender de bytes fuera de su propio documento, y el lock contiene un pin para cada uno:
- Un
source:remoto cuyas coordenadas escribiste completas, sin ninguna plantilla enkind,url,chart,module_subdir,versionniref. El paso lo descarga y registra la versión a la que se resolvió —para una fuente git, el commit que nombraba suref— y el digest del contenido descargado. - Un archivo que una entrada de
artifactsimporta con$import. El paso calcula el digest del archivo tal como está en tu workspace. - Cada archivo de un
source:que nombra un directorio o un archivo junto a la entidad. No se descarga nada: el paso calcula el digest de cada archivo que la fuente aporta a lo que lleva una publicación de la entidad —cada archivo bajo el directorio que nombra que conservan las reglas de exclusión de la entidad, o el único archivo— y lo registra por su ruta junto a la entidad. Un archivo junto a la Recipe que la fuente no aporta, como un README, no se fija. Una fuente escrita como plantilla, como./charts/{{ .values.flavour }}, solo nombra su directorio cuando una Release la rellena, así que aporta cada archivo del directorio de la entidad que conservan las reglas, y cada uno de ellos se fija. Una build compara la fuente con estos pins antes de que su provider la lea, de modo que un archivo añadido, modificado o eliminado desde el pin detiene la build: A local source no longer matches the pins recorded beside its Recipe (Una fuente local ya no coincide con los pins registrados junto a su Recipe). - Las propias reglas de exclusión, para un
source:que es un directorio. El paso registra qué plugin sirvió la capability de la entidad y las reglas exactas que compuso, como describe la sección siguiente.
Lo que no registra: una fuente remota cuyas coordenadas se rellenan a partir de una plantilla, que solo nombra un artefacto cuando una Release la rellena y que aggrega pull fija en el lockfile de cada Release; y una entrada de artifacts en línea o una tomada de una ArtifactLibrary. El archivo en sí se describe campo por campo en el esquema del lock de entidad.
No se necesita ninguna Release. Una fuente escrita completa nombra el mismo artefacto para cada Release que vaya a usar la entidad, de modo que resolverla no necesita nada que aporte una Release. Eso es lo que permite a un autor fijar una entidad en un workspace que no tiene ninguna Release.
El archivo de la entidad nunca se escribe. Lo que el paso deriva va junto a la entidad; lo que escribiste queda exactamente como lo escribiste. Volver a ejecutarlo sobre entradas sin cambios deja el lock idéntico byte a byte, y a una entidad que deja de leer cualquier cosa que registre un lock se le elimina el lock. Un Component, una Feature o cualquier otro tipo que no lee ninguna entrada así se notifica como sin nada que fijar, y no se toca nada a su lado.
Qué archivos se distribuyen con una entidad
Una Recipe o FeatureRecipe cuyo source: nombra un directorio junto a ella —un chart ubicado junto a ella, un módulo— lleva los archivos de ese directorio cuando se publica. No todos los archivos que contiene pertenecen ahí: un directorio de control de versiones, una caché de dependencias, restos de un editor. Qué archivos pertenecen lo deciden las reglas de exclusión, en la sintaxis que usa .gitignore, y tú las controlas. Provienen de dos lugares:
- El plugin que renderiza la capability de la entidad declara lo que su propio ecosistema nunca distribuye. Los plugins de charts excluyen los directorios de control de versiones (
.git/,.hg/,.svn/,.bzr/) y los archivos ocultos bajotemplates/de un chart, y respetan el.helmignoredel propio chart: dondequiera que el recorrido de la fuente encuentre uno, sus líneas se leen como reglas adicionales para el directorio que lo contiene. El plugin de Terraform excluye los directorios de control de versiones y el directorio de trabajo.terraform/—no el archivo de bloqueo de dependencias, que está pensado para viajar con el módulo— y respeta.terraformignorede la misma manera. Un plugin que no declara nada lo incluye todo. - Tu propio
.aggregaignore, un archivo junto al documento de la entidad, en la misma sintaxis. Sus líneas se aplican después de las del plugin y de cada archivo de exclusión que nombra el plugin, de modo que tienes la última palabra sobre cualquier ruta que nombres: una línea como.venv/excluye un directorio del que el plugin no sabe nada, y una línea como!.git/vuelve a incluir uno que el plugin había excluido. El archivo en sí nunca viaja; sus reglas sí, dentro del lock.
.venv/*.bak!notes.bakCada regla se lee en relación con el directorio al que pertenece. Una regla que declara el plugin se lee desde la raíz del directorio fuente; una línea de un .helmignore, desde el directorio que contiene ese archivo; una línea de tu .aggregaignore, desde el propio directorio de la entidad. Una regla sin barra, o solo con una barra final, coincide con un nombre a cualquier profundidad; una barra final solo coincide con un directorio; un ! inicial vuelve a incluir lo que una regla anterior había excluido. En un directorio que una regla excluye no se entra, así que un archivo dentro de él solo vuelve cuando vuelve el propio directorio: !.git/HEAD por sí solo no vuelve a incluir el archivo mientras .git/ esté excluido, y !.git/ sí.
El plugin cuyas reglas se leen es el que sirve la capability en tu workspace cuando fijas: el binding de provider de tu workspace para esa capability o, si no, el plugin integrado en aggrega. El paso registra en el entity.lock ese plugin solo por su nombre, como provider/terraform, sin versión, y las reglas exactas que compuso; volver a fijar con un aggrega más reciente cuyo plugin declara las mismas reglas deja el lock sin cambios. A partir de entonces, cada lectura del directorio aplica las reglas registradas y ninguna otra: una publicación de la entidad, la comparación con la que un pull o un push contrasta el lock, la fila de la entidad en un lockfile, la comparación de una build, el renderizado que entrega el directorio a un provider y aggrega pull --verify. Así, lo que publicas es exactamente lo que renderiza tu propia build, y un binding cambiado, un .aggregaignore editado o un aggrega más reciente no cambian nada hasta que vuelvas a fijar, momento en el que el diff del lock muestra qué se ha movido. Un archivo que un plugin nombra como archivo de exclusión, como un .helmignore, es en sí uno de los archivos de la fuente y se fija como cualquier otro salvo que una regla lo excluya, así que editarlo sin volver a fijar lo detecta el siguiente pull o build. Un lock que no registra reglas conserva cada archivo bajo el directorio.
Un consumidor renderiza los archivos que conservaron tus reglas. Un plugin puede renderizar una Recipe publicada para su capability cuando habla la misma versión de ABI, su contrato coincide con lo que declara su entidad y no necesita ningún archivo fuera del conjunto publicado. Un plugin que necesita un archivo que el conjunto excluyó debe hacer fallar su build de forma explícita y nombrar el archivo; la parte del host es rechazar cualquier empaquetado o lectura de un archivo que el conjunto no lleva, nombrándolo. Cuando el plugin que el workspace de un consumidor vincula a la capability declara reglas distintas de las que registra tu lock, el aggrega pull del consumidor lo indica en una advertencia que nombra ambos plugins y la diferencia, y continúa.
Se rechaza un enlace simbólico entre los archivos de una entidad, apunte adonde apunte y se resuelva o no; consulta A symbolic link sits among the files an entity carries (Hay un enlace simbólico entre los archivos que lleva una entidad). Un enlace que tus reglas excluyen se omite como cualquier otro archivo que excluyan. También se rechaza, antes de fijar nada, una ruta que nombra la entidad y que pasa por un directorio que es un enlace que sale del directorio de la entidad; consulta A path names content outside the entity’s own directory (Una ruta nombra contenido fuera del propio directorio de la entidad).
Dónde va el lock
El lock se escribe junto al documento que nombras, en el mismo directorio, así que la entidad necesita una ubicación con permiso de escritura: un documento en un directorio tuyo. Una entidad que un pull resolvió desde la caché de contenido no tiene esa ubicación y nada la fija nunca.
Un directorio, una entidad. Un directorio contiene un solo entity.lock, así que el paso rechaza una Recipe o FeatureRecipe que comparte su directorio con cualquier otra entidad, tenga o no alguna de ellas algo que fijar, nombrando cada entidad que estorba; el rechazo es An entity shares its directory with another entity (Una entidad comparte su directorio con otra entidad). Cada tipo tiene un directorio propio excepto Aggregate, Release y Manifest, que pueden estar uno al lado del otro; un push somete la entidad que publica a la misma regla, como explica Una entidad por directorio. El paso solo juzga aquello para lo que escribe un lock, de modo que un Component o cualquier otro tipo para el que no tiene nada que fijar se notifica como sin nada que fijar, y el rechazo alcanza a esa entidad cuando se publica. Un archivo junto a la entidad que no es un documento de entidad —un archivo de chart, el propio archivo importado— no estorba. Cada documento junto a la entidad se lee solo desde dentro del workspace o, para un documento que nombras fuera de él, desde dentro de su propio directorio —donde también está el lock—, de modo que uno que es un enlace que sale detiene el paso nombrando el enlace, sin leerlo, como explica el límite del workspace.
Quién fija, y cuándo
Fijar es una obligación de autoría. Una entidad cuyas entradas no están fijadas aún no está lista para consumirse, así que de forma predeterminada un pull no registra ningún pin: sobre una Recipe o FeatureRecipe de uno de tus directorios de catálogo que construye la Release, compara lo que registraría este paso con lo que contiene el lock, y se detiene cuando falta un pin o ya no coincide con su entrada. La detención nombra la entidad, cada entrada y si es una fuente remota, un archivo importado o un archivo de una fuente local, y este comando. Es An entity reads an input the lock beside it records no pin for (Una entidad lee una entrada para la que el lock a su lado no registra ningún pin). Un push somete la entidad que publica a la misma comparación y rechaza con la misma detención, de modo que una entidad no puede llegar a un registry mediante aggrega push con un pin sin registrar; lo explica Fijar antes de publicar. Una fuente local se trata como un único conjunto de archivos: un lock que no registra ninguno de ellos detiene un pull o un push, y lo mismo hace un archivo añadido, modificado o eliminado desde el pin, como cualquier otro pin que falte o esté desactualizado.
Una detención en un primer pull la debe corregir quien publica, nunca quien consume. Cuando consumes un catálogo que escribe otra persona —por ejemplo, un checkout suyo en un directorio tuyo— y una entidad de ahí no está fijada, el autor nunca ejecutó este paso. Tu solución no es editar su directorio a mano: establece la clave del workspace que se describe abajo, para que tus pulls registren los pins por sí mismos.
Dos comandos ejecutan este mismo paso por ti y escriben los mismos bytes:
aggrega pull --pin-sourceslo ejecuta sobre las entidades que construye la Release, en lugar de detenerse.aggrega push --pin-sourceslo ejecuta sobre la entidad antes de empaquetarla, de modo que el lock que escribe forma parte de lo que se publica, en lugar de rechazar.
Cada uno tiene una clave del workspace que hace que fijar sea su comportamiento predeterminado, pin_sources_at_pull y pin_sources_at_push, ambas desactivadas de forma predeterminada y cada una aplicable solo a su propio comando. El flag prevalece sobre su clave en ambos sentidos: --pin-sources fija en una ejecución diga lo que diga la clave, y --pin-sources=false no. Así, un workspace configurado para fijar puede recuperar la detención para un pull. Una build que rellena su propio lockfile es un pull, así que sigue pin_sources_at_pull. Las claves se describen en la referencia de configuración.
Cambiar una entidad publicada
Buena práctica: una modificación de una entidad que ya has publicado va en una versión nueva, y después un pin; nunca un nuevo pin de la versión que ya está publicada. Copia la entidad en un nuevo directorio de versión, haz el cambio allí y ejecuta aggrega pin sobre la nueva versión. La versión publicada sigue describiendo exactamente los bytes con los que se publicó, y un consumidor que pasa a la nueva lo hace a propósito.
El producto impone una mitad de esto: publicar contenido modificado en una versión que ya está publicada se rechaza, de modo que una versión publicada no se puede sustituir discretamente. No impone la otra mitad en tu propio workspace. Volver a fijar una versión existente después de una edición es a veces exactamente lo correcto —por ejemplo, una entidad que consumes dentro de una aplicación y que no has publicado—, así que nada te lo impide, y mantener la disciplina te corresponde a ti.
El mismo paso en las otras superficies
El daemon ofrece este paso como aggrega/pin (aggrega serve), y el protocolo de herramientas como la herramienta pin (aggrega mcp); ambos escriben los mismos bytes que escribe este comando. A través de un listener HTTP, la herramienta escribe dentro del workspace y llega a los hosts que nombran las fuentes de una entidad, así que quien llama necesita el scope de escritura del workspace para invocarla, el mismo permiso que necesita un pull.
Véase también
- aggrega-pull.md — el lock de entidad, lo que una build compara con él y la detención.
- aggrega-push.md — publicar una entidad, y publicar una versión una sola vez.
- configuration.md —
pin_sources_at_pullypin_sources_at_push.
Sinopsis
aggrega pin <entity-path> [flags]Descripción
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.Flags
| Flag | Predeterminado | Descripción |
|---|---|---|
--dry-run | false | Resolver las entradas de la entidad e imprimir el entity.lock que escribiría el paso en lugar de escribirlo: su ruta y el contenido que tendría van a stdout, y no cambia nada en el disco. No se imprime un lock que el paso dejaría idéntico byte a byte. La resolución se ejecuta exactamente igual que en otro caso, así que la caché de contenido se llena igualmente |