aggrega pin
aggrega pin <entity-path> registra, no entity.lock ao lado de uma Recipe ou FeatureRecipe, o pin de conteúdo de cada entrada que a entidade lê de fora do seu próprio documento. É a etapa do autor da entidade: execute-a antes que a entidade seja consumida ou publicada, e faça commit do lock que ela grava.
aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yamlO que ela registra
Uma entidade pode depender de bytes fora do seu próprio documento, e o lock contém um pin para cada um:
- Um
source:remoto cujas coordenadas você escreveu por completo — nenhum template emkind,url,chart,module_subdir,versionouref. A etapa o baixa e registra a versão para a qual ele foi resolvido — para uma fonte git, o commit que seurefnomeou — e o digest do conteúdo baixado. - Um arquivo que uma entrada de
artifactsimporta com$import. A etapa calcula o digest do arquivo como ele está no seu workspace. - Cada arquivo de um
source:que nomeia um diretório ou um arquivo ao lado da entidade. Nada é baixado: a etapa calcula o digest de cada arquivo que a fonte contribui para o que uma publicação da entidade carrega — cada arquivo sob o diretório nomeado que as regras de exclusão da entidade mantêm, ou o único arquivo — e o registra pelo seu caminho ao lado da entidade. Um arquivo ao lado da Recipe que a fonte não contribui, como um README, não é fixado. Uma fonte escrita como template, como./charts/{{ .values.flavour }}, só nomeia seu diretório quando uma Release a preenche, então ela contribui cada arquivo do diretório da entidade que as regras mantêm, e cada um deles é fixado. Uma build compara a fonte com esses pins antes que seu provider a leia, de modo que um arquivo adicionado, alterado ou removido desde o pin interrompe a build — A local source no longer matches the pins recorded beside its Recipe (Uma fonte local não corresponde mais aos pins registrados ao lado da sua Recipe). - As próprias regras de exclusão, para um
source:que é um diretório. A etapa registra qual plugin atendeu a capability da entidade e as regras exatas que ele compôs, como descreve a próxima seção.
O que ela não registra: uma fonte remota cujas coordenadas são preenchidas a partir de um template, que só nomeia um artefato quando uma Release a preenche e é fixada no lockfile de cada Release por aggrega pull; e uma entrada de artifacts inline ou uma tirada de uma ArtifactLibrary. O próprio arquivo é descrito campo a campo no schema do lock de entidade.
Nenhuma Release é necessária. Uma fonte escrita por completo nomeia o mesmo artefato para toda Release que algum dia usar a entidade, então resolvê-la não precisa de nada que uma Release forneça. É isso que permite a um autor fixar uma entidade em um workspace que não tem nenhuma Release.
O arquivo da entidade nunca é gravado. O que a etapa deriva vai ao lado da entidade; o que você digitou fica exatamente como você digitou. Executá-la de novo sobre entradas inalteradas deixa o lock idêntico byte a byte, e uma entidade que deixa de ler qualquer coisa que um lock registra tem seu lock removido. Um Component, uma Feature ou qualquer outro tipo que não lê nenhuma entrada desse tipo é informado como sem nada a fixar, e nada ao lado dele é tocado.
Quais arquivos são distribuídos com uma entidade
Uma Recipe ou FeatureRecipe cujo source: nomeia um diretório ao lado dela — um chart colocalizado, um módulo — carrega os arquivos desse diretório quando é publicada. Nem todo arquivo nele pertence ali: um diretório de controle de versão, um cache de dependências, sobras de um editor. Quais arquivos pertencem é decidido por regras de exclusão, na sintaxe que .gitignore usa, e você as controla. Elas vêm de dois lugares:
- O plugin que renderiza a capability da entidade declara o que seu próprio ecossistema nunca distribui. Os plugins de chart deixam de fora os diretórios de controle de versão (
.git/,.hg/,.svn/,.bzr/) e os arquivos ocultos sobtemplates/de um chart, e respeitam o.helmignoredo próprio chart: onde quer que a varredura da fonte encontre um, suas linhas são lidas como regras adicionais para o diretório que o contém. O plugin do Terraform deixa de fora os diretórios de controle de versão e o diretório de trabalho.terraform/— não o arquivo de lock de dependências, que deve viajar com o módulo — e respeita.terraformignoreda mesma forma. Um plugin que não declara nada mantém tudo. - Seu próprio
.aggregaignore, um arquivo ao lado do documento da entidade, na mesma sintaxe. Suas linhas se aplicam depois das do plugin e depois de cada arquivo de exclusão que o plugin nomeia, então você tem a palavra final sobre qualquer caminho que nomear: uma linha como.venv/deixa de fora um diretório do qual o plugin não sabe nada, e uma linha como!.git/traz de volta um que o plugin deixou de fora. O próprio arquivo nunca viaja; suas regras sim, dentro do lock.
.venv/*.bak!notes.bakCada regra é lida em relação ao diretório ao qual pertence. Uma regra que o plugin declara é lida a partir da raiz do diretório da fonte; uma linha de um .helmignore, a partir do diretório que contém esse arquivo; uma linha do seu .aggregaignore, a partir do próprio diretório da entidade. Uma regra sem barra, ou só com uma barra final, corresponde a um nome em qualquer profundidade; uma barra final corresponde apenas a um diretório; um ! inicial traz de volta o que uma regra anterior deixou de fora. Um diretório que uma regra deixa de fora não é percorrido, então um arquivo dentro dele só volta quando o próprio diretório volta — !.git/HEAD sozinho não traz o arquivo de volta enquanto .git/ estiver de fora, e !.git/ traz.
O plugin cujas regras são lidas é o que atende a capability no seu workspace quando você fixa: o binding de provider do seu workspace para essa capability ou, caso contrário, o plugin embutido no aggrega. A etapa registra no entity.lock esse plugin apenas pelo nome, como provider/terraform, sem versão, e as regras exatas que ele compôs; fixar de novo com um aggrega mais recente cujo plugin declara as mesmas regras deixa o lock inalterado. A partir daí, toda leitura do diretório aplica as regras registradas e nenhuma outra: uma publicação da entidade, a comparação a que um pull ou um push submete o lock, a linha da entidade em um lockfile, a comparação de uma build, a renderização que entrega o diretório a um provider e aggrega pull --verify. Assim, o que você publica é exatamente o que sua própria build renderiza, e um binding alterado, um .aggregaignore editado ou um aggrega mais recente não mudam nada até que você fixe de novo — momento em que o diff do lock mostra o que mudou. Um arquivo que um plugin nomeia como arquivo de exclusão, como um .helmignore, é ele mesmo um dos arquivos da fonte e é fixado como qualquer outro, a menos que uma regra o deixe de fora, então editá-lo sem fixar de novo é detectado pelo próximo pull ou build. Um lock que não registra regras mantém todo arquivo sob o diretório.
Um consumidor renderiza os arquivos que suas regras mantiveram. Um plugin pode renderizar uma Recipe publicada para sua capability quando fala a mesma versão de ABI, seu contrato corresponde ao que sua entidade declara e ele não precisa de nenhum arquivo fora do conjunto publicado. Um plugin que precisa de um arquivo que o conjunto deixou de fora deve fazer sua build falhar de forma explícita e nomear o arquivo; o papel do host é recusar qualquer empacotamento ou leitura de um arquivo que o conjunto não carrega, nomeando-o. Quando o plugin que o workspace de um consumidor vincula à capability declara regras diferentes das que seu lock registra, o aggrega pull do consumidor informa isso em um aviso que nomeia os dois plugins e a diferença, e continua.
Um link simbólico entre os arquivos de uma entidade é recusado, para onde quer que aponte e seja resolvido ou não — consulte A symbolic link sits among the files an entity carries (Há um link simbólico entre os arquivos que uma entidade carrega). Um link que suas regras deixam de fora é ignorado como qualquer outro arquivo que elas deixam de fora. Um caminho nomeado pela entidade que passa por um diretório que é um link levando para fora do diretório da entidade também é recusado, antes que qualquer coisa seja fixada — consulte A path names content outside the entity’s own directory (Um caminho nomeia conteúdo fora do próprio diretório da entidade).
Onde o lock fica
O lock é gravado ao lado do documento que você nomeia, no mesmo diretório, então a entidade precisa de um local gravável: um documento em um diretório seu. Uma entidade que um pull resolveu a partir do cache de conteúdo não tem esse local e nunca é fixada por nada.
Um diretório, uma entidade. Um diretório contém um único entity.lock, então a etapa recusa uma Recipe ou FeatureRecipe que compartilha seu diretório com qualquer outra entidade, tenha qualquer uma delas algo a fixar ou não, nomeando cada entidade no caminho — a recusa é An entity shares its directory with another entity (Uma entidade compartilha seu diretório com outra entidade). Todo tipo tem um diretório próprio, exceto Aggregate, Release e Manifest, que podem ficar lado a lado; um push submete a entidade que publica à mesma regra, como explica Uma entidade por diretório. A etapa avalia apenas aquilo para o qual grava um lock, então um Component ou qualquer outro tipo para o qual ela não tem nada a fixar é informado como sem nada a fixar, e a recusa alcança essa entidade quando ela é publicada. Um arquivo ao lado da entidade que não é um documento de entidade — um arquivo de chart, o próprio arquivo importado — não está no caminho. Cada documento ao lado da entidade é lido apenas de dentro do workspace ou, para um documento que você nomeia fora dele, de dentro do seu próprio diretório — onde o lock também fica —, então um que seja um link levando para fora interrompe a etapa nomeando o link, sem lê-lo, como explica o limite do workspace.
Quem fixa, e quando
Fixar é um dever de criação. Uma entidade cujas entradas não estão fixadas ainda não está pronta para ser consumida, então, por padrão, um pull não registra nenhum pin: sobre uma Recipe ou FeatureRecipe em um dos seus diretórios de catálogo que a Release compila, ele compara o que esta etapa registraria com o que o lock contém, e é interrompido quando um pin está faltando ou não corresponde mais à sua entrada. A interrupção nomeia a entidade, cada entrada e se é uma fonte remota, um arquivo importado ou um arquivo de uma fonte local, e este comando. É An entity reads an input the lock beside it records no pin for (Uma entidade lê uma entrada para a qual o lock ao lado dela não registra nenhum pin). Um push submete a entidade que publica à mesma comparação e recusa com a mesma interrupção, de modo que uma entidade não pode chegar a um registry por meio de aggrega push com um pin não registrado — Fixar antes de publicar explica isso. Uma fonte local é tratada como um único conjunto de arquivos: um lock que não registra nenhum deles interrompe um pull ou um push, assim como um arquivo adicionado, alterado ou removido desde o pin, como qualquer outro pin ausente ou desatualizado.
Uma interrupção em um primeiro pull cabe a quem publica corrigir, nunca a quem consome. Quando você consome um catálogo criado por outra pessoa — um checkout dele em um diretório seu, por exemplo — e uma entidade ali não está fixada, o autor nunca executou esta etapa. A solução não é editar o diretório dele à mão: defina a chave de workspace abaixo, para que seus pulls registrem os pins por conta própria.
Dois comandos executam esta mesma etapa por você e gravam os mesmos bytes:
aggrega pull --pin-sourcesa executa sobre as entidades que a Release compila, em vez de ser interrompido.aggrega push --pin-sourcesa executa na entidade antes de empacotá-la, de modo que o lock que ela grava faz parte do que é publicado, em vez de recusar.
Cada um tem uma chave de workspace que torna a fixação seu comportamento padrão, pin_sources_at_pull e pin_sources_at_push, ambas desativadas por padrão e cada uma valendo apenas para seu próprio comando. O flag prevalece sobre sua chave nas duas direções: --pin-sources fixa em uma execução, não importa o que a chave diga, e --pin-sources=false não fixa. Assim, um workspace configurado para fixar ainda pode ter a interrupção de volta em um pull. Uma build que preenche seu próprio lockfile é um pull, então segue pin_sources_at_pull. As chaves são descritas na referência de configuração.
Alterar uma entidade publicada
Boa prática: uma edição em uma entidade que você já publicou vai em uma nova versão, seguida de um pin — nunca uma nova fixação da versão que já está publicada. Copie a entidade para um novo diretório de versão, faça a alteração ali e execute aggrega pin na nova versão. A versão publicada continua descrevendo exatamente os bytes com que foi publicada, e um consumidor que passa para a nova o faz de propósito.
O produto impõe metade disso: publicar conteúdo alterado em uma versão que já está publicada é recusado, de modo que uma versão publicada não pode ser substituída silenciosamente. Ele não impõe a outra metade no seu próprio workspace. Fixar de novo uma versão existente depois de uma edição às vezes é exatamente o certo — uma entidade que você consome dentro de uma aplicação e não publicou, por exemplo —, então nada impede você, e manter a disciplina cabe a você.
A mesma etapa nas outras superfícies
O daemon oferece esta etapa como aggrega/pin (aggrega serve), e o protocolo de ferramentas como a ferramenta pin (aggrega mcp); ambos gravam os mesmos bytes que este comando grava. Por um listener HTTP, a ferramenta grava dentro do workspace e alcança os hosts que as fontes de uma entidade nomeiam, então quem chama precisa do scope de escrita do workspace para chamá-la — a mesma permissão de que um pull precisa.
Veja também
- aggrega-pull.md — o lock de entidade, o que uma build compara com ele e a interrupção.
- aggrega-push.md — publicar uma entidade, e publicar uma versão uma única vez.
- configuration.md —
pin_sources_at_pullepin_sources_at_push.
Sinopse
aggrega pin <entity-path> [flags]Descrição
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 | Padrão | Descrição |
|---|---|---|
--dry-run | false | Resolver as entradas da entidade e imprimir o entity.lock que a etapa gravaria em vez de gravá-lo: seu caminho e o conteúdo que ele teria vão para stdout, e nada no disco muda. Um lock que a etapa deixaria idêntico byte a byte não é impresso. A resolução é executada exatamente como seria de outra forma, então o cache de conteúdo ainda é preenchido |