aggrega pin
aggrega pin <entity-path> regista, no entity.lock junto a uma Recipe ou FeatureRecipe, a fixação de conteúdo de cada entrada que a entidade lê de fora do seu próprio documento. É o passo do autor da entidade: execute-se antes de a entidade ser consumida ou publicada, e faça-se commit do lock que escreve.
aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yamlO que regista
Uma entidade pode depender de bytes fora do seu próprio documento, e o lock guarda uma fixação para cada um:
- Um
source:remoto cujas coordenadas foram escritas por extenso — sem template no seukind,url,chart,module_subdir,versionouref. O passo obtém-no e regista a versão para que resolveu — para uma origem git, o commit que o seurefindicou — e o digest de conteúdo do que foi obtido. - Um ficheiro que uma entrada de
artifactsimporta com$import. O passo calcula o digest do ficheiro tal como está no espaço de trabalho. - Cada ficheiro de um
source:que indica um diretório ou um ficheiro junto à entidade. Nada é obtido: o passo calcula o digest de cada ficheiro com que a origem contribui para o que uma publicação da entidade traz — cada ficheiro sob o diretório que indica que as regras de exclusão da entidade mantêm, ou o único ficheiro — e regista-o pelo seu caminho junto à entidade. Um ficheiro ao lado da Recipe com que a origem não contribui, como um README, não é fixado. Uma origem escrita como template, como./charts/{{ .values.flavour }}, só indica o seu diretório quando uma Release a preenche, pelo que contribui com todos os ficheiros do diretório da entidade que as regras mantêm, e cada um deles é fixado. Uma build compara a origem com estas fixações antes de o seu provider a ler, pelo que um ficheiro acrescentado, alterado ou removido desde a fixação interrompe a build — A local source no longer matches the pins recorded beside its Recipe (Uma origem local já não corresponde às fixações registadas junto à sua Recipe). - As próprias regras de exclusão, para um
source:que é um diretório. O passo regista que plugin serviu a capacidade da entidade e as regras exatas que compôs, como a secção seguinte descreve.
O que não regista: uma origem remota cujas coordenadas são preenchidas a partir de um template, que só indica um artefacto quando uma Release a preenche e é fixada no lockfile de cada Release por aggrega pull; e uma entrada de artifacts inline ou uma obtida de uma ArtifactLibrary. O próprio ficheiro é descrito campo a campo no esquema do lock de entidade.
Não é necessária nenhuma Release. Uma origem escrita por extenso indica o mesmo artefacto para todas as Releases que alguma vez usarão a entidade, pelo que resolvê-la não precisa de nada que uma Release forneça. É isso que permite a um autor fixar uma entidade num espaço de trabalho que não tem Release nenhuma.
O ficheiro da entidade nunca é escrito. O que o passo deriva vai para junto da entidade; o que se escreveu fica exatamente como foi escrito. Executar de novo sobre entradas inalteradas deixa o lock idêntico byte a byte, e uma entidade que deixa de ler o que quer que um lock registe vê o seu lock removido. Um Component, uma Feature ou qualquer outro tipo que não leia tal entrada é reportado como não tendo nada a fixar, e nada junto a ele é tocado.
Que ficheiros acompanham uma entidade
Uma Recipe ou FeatureRecipe cujo source: indica um diretório junto a ela — um chart colocado ao lado, um módulo — traz os ficheiros desse diretório quando é publicada. Nem todos os ficheiros dele pertencem aí: um diretório de controlo de versões, uma cache de dependências, restos de um editor. Que ficheiros pertencem é decidido por regras de exclusão, na sintaxe que .gitignore usa, e são controladas pelo utilizador. Vêm de dois sítios:
- O plugin que renderiza a capacidade da entidade declara o que o seu próprio ecossistema nunca distribui. Os plugins de charts deixam de fora os diretórios de controlo de versões (
.git/,.hg/,.svn/,.bzr/) e os ficheiros ocultos sob otemplates/de um chart, e respeitam o próprio.helmignoredo chart: onde quer que a travessia da origem encontre um, as suas linhas são lidas como regras adicionais para o diretório que o contém. O plugin Terraform deixa de fora os diretórios de controlo de versões e o diretório de trabalho.terraform/— não o ficheiro de lock de dependências, que se destina a acompanhar o módulo — e respeita.terraformignoreda mesma forma. Um plugin que não declara nada deixa tudo dentro. - O próprio
.aggregaignoredo utilizador, um ficheiro junto ao documento da entidade, na mesma sintaxe. As suas linhas aplicam-se depois das do plugin e depois de todos os ficheiros de exclusão que o plugin indica, pelo que se tem a palavra final sobre qualquer caminho que se indique: uma linha como.venv/deixa de fora um diretório que o plugin não conhece, e uma linha como!.git/traz de volta um que o plugin deixou de fora. O próprio ficheiro nunca viaja; as suas regras sim, dentro do lock.
.venv/*.bak!notes.bakCada regra é lida em relação ao diretório a que pertence. Uma regra que o plugin declara é lida a partir da raiz do diretório de origem; uma linha de um .helmignore a partir do diretório que contém esse ficheiro; uma linha do .aggregaignore a partir do próprio diretório da entidade. Uma regra sem barra, ou apenas com uma barra final, corresponde a um nome a 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, pelo que um ficheiro dentro dele só volta quando o próprio diretório volta — !.git/HEAD sozinho não traz o ficheiro de volta enquanto .git/ estiver de fora, e !.git/ traz.
O plugin cujas regras são lidas é o que serve a capacidade no espaço de trabalho no momento da fixação: a associação de provider do espaço de trabalho para essa capacidade, ou, caso contrário, o plugin incorporado no aggrega. O passo regista no entity.lock esse plugin apenas pelo seu nome, como provider/terraform, sem versão, e as regras exatas que compôs; fixar de novo com um aggrega mais recente cujo plugin declare as mesmas regras deixa o lock inalterado. A partir daí, cada leitura do diretório aplica as regras registadas e nenhumas outras: uma publicação da entidade, a comparação a que um pull ou um push sujeita o lock, a linha da entidade num 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 se publica é exatamente o que a própria build renderiza, e uma associação alterada, um .aggregaignore editado ou um aggrega mais recente não alteram nada até se fixar de novo — momento em que a diferença do lock mostra o que mudou. Um ficheiro que um plugin indica como ficheiro de exclusão, como um .helmignore, é ele próprio um dos ficheiros da origem e é fixado como qualquer outro, a menos que uma regra o deixe de fora, pelo que editá-lo sem fixar de novo é detetado pelo pull ou pela build seguinte. Um lock que não regista regras mantém todos os ficheiros sob o diretório.
Um consumidor renderiza os ficheiros que as regras mantiveram. Um plugin pode renderizar uma Recipe publicada para a sua capacidade quando fala a mesma versão de ABI, o seu contrato corresponde ao que a sua entidade afirma e não precisa de nenhum ficheiro fora do conjunto publicado. Um plugin que precise de um ficheiro que o conjunto deixou de fora tem de falhar a sua build de forma explícita e indicar o ficheiro; a parte do anfitrião é recusar qualquer empacotamento ou leitura de um ficheiro que o conjunto não traz, indicando-o. Quando o plugin que o espaço de trabalho de um consumidor associa à capacidade declara regras diferentes das que o lock regista, o aggrega pull do consumidor di-lo num aviso que indica ambos os plugins e a diferença, e prossegue.
Uma ligação simbólica entre os ficheiros de uma entidade é recusada, para onde quer que aponte e quer resolva quer não — ver A symbolic link sits among the files an entity carries (Uma ligação simbólica está entre os ficheiros que uma entidade traz). Uma ligação que as regras deixam de fora é ignorada como qualquer outro ficheiro que deixam de fora. Um caminho que a entidade indica e que passa por um diretório que é uma ligação que sai do diretório da entidade é também recusado, antes de se fixar o que quer que seja — ver A path names content outside the entity’s own directory (Um caminho indica conteúdo fora do próprio diretório da entidade).
Onde fica o lock
O lock é escrito junto ao documento indicado, no mesmo diretório, pelo que a entidade precisa de um sítio gravável: um documento num diretório do utilizador. Uma entidade que um pull resolveu a partir da cache de conteúdo não tem tal sítio e nunca é fixada por nada.
Um diretório, uma entidade. Um diretório contém um único entity.lock, pelo que o passo recusa uma Recipe ou FeatureRecipe que partilhe o seu diretório com qualquer outra entidade, quer alguma delas tenha algo a fixar quer não, indicando cada entidade que está no caminho — a recusa é An entity shares its directory with another entity (Uma entidade partilha o seu diretório com outra entidade). Todos os tipos têm um diretório próprio exceto Aggregate, Release e Manifest, que podem ficar lado a lado; um push sujeita a entidade que publica à mesma regra, como Uma entidade por diretório expõe. O passo só avalia aquilo para que escreve um lock, pelo que um Component ou qualquer outro tipo para o qual não tem nada a fixar é reportado como não tendo nada a fixar, e a recusa chega a essa entidade quando é publicada. Um ficheiro junto à entidade que não é um documento de entidade — um ficheiro de chart, o próprio ficheiro importado — não está no caminho. Cada documento junto à entidade só é lido de dentro do espaço de trabalho, ou, para um documento indicado fora dele, de dentro do seu próprio diretório — onde o lock também fica contido — pelo que um que seja uma ligação que sai interrompe o passo indicando a ligação, sem a ler, como o limite do espaço de trabalho expõe.
Quem fixa, e quando
Fixar é um dever de autoria. Uma entidade cujas entradas não estão fixadas ainda não está pronta para ser consumida, pelo que, por predefinição, um pull não regista nenhuma fixação: sobre uma Recipe ou FeatureRecipe num dos diretórios de catálogo que a Release compila, compara o que este passo registaria com o que o lock contém, e interrompe quando uma fixação falta ou já não corresponde à sua entrada. A interrupção indica a entidade, cada entrada e se é uma origem remota, um ficheiro importado ou um ficheiro de uma origem 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 junto a ela não regista fixação). Um push sujeita a entidade que publica à mesma comparação e recusa com a mesma interrupção, pelo que uma entidade não pode chegar a um registo através de aggrega push com uma fixação por registar — Fixar antes de publicar expõe-o. Uma origem local é tratada como um conjunto de ficheiros: um lock que não regista nenhum deles para um pull ou um push, tal como um ficheiro acrescentado, alterado ou removido desde a fixação, como qualquer outra fixação em falta ou desatualizada.
Uma interrupção num primeiro pull cabe ao publicador corrigir, nunca ao consumidor. Quando se consome um catálogo que outra pessoa escreve — uma cópia dele num diretório próprio, por exemplo — e uma entidade aí não está fixada, o autor nunca executou este passo. A solução não é editar o diretório dele à mão: defina-se a chave do espaço de trabalho abaixo, para que os próprios pulls registem as fixações.
Dois comandos executam este mesmo passo em nome do utilizador, e escrevem os mesmos bytes:
aggrega pull --pin-sourcesexecuta-o sobre as entidades que a Release compila, em vez de interromper.aggrega push --pin-sourcesexecuta-o sobre a entidade antes de a empacotar, para que o lock que escreve faça parte do que é publicado, em vez de recusar.
Cada um tem uma chave de espaço de trabalho que torna a fixação a sua predefinição, pin_sources_at_pull e pin_sources_at_push, ambas desligadas por predefinição e cada uma a governar apenas o seu próprio comando. A flag sobrepõe-se à sua chave em ambos os sentidos: --pin-sources fixa numa execução diga a chave o que disser, e --pin-sources=false não fixa. Assim, um espaço de trabalho configurado para fixar pode ainda recuperar a interrupção num pull. Uma build que preenche o seu próprio lockfile é um pull, pelo que segue pin_sources_at_pull. As chaves estão descritas na referência de configuração.
Alterar uma entidade publicada
Boa prática: uma edição a uma entidade já publicada pertence a uma nova versão, seguida de uma fixação — nunca uma nova fixação da versão que já está publicada. Copie-se a entidade para um novo diretório de versão, faça-se a alteração aí e execute-se aggrega pin sobre a nova versão. A versão publicada continua a descrever exatamente os bytes com que foi publicada, e um consumidor que passe para a nova passa de propósito.
O produto impõe metade disto: publicar conteúdo alterado numa versão que já está publicada é recusado, pelo que uma versão publicada não pode ser substituída discretamente. Não impõe a outra metade no espaço de trabalho do utilizador. Voltar a fixar uma versão existente depois de uma edição é por vezes exatamente o certo — uma entidade que se consome dentro de uma aplicação e não se publicou, por exemplo — pelo que nada o impede, e a disciplina cabe ao utilizador.
O mesmo passo nas outras superfícies
O daemon oferece este passo como aggrega/pin (aggrega serve), e o protocolo de ferramentas como a ferramenta pin (aggrega mcp); ambos escrevem os mesmos bytes que este comando escreve. Através de um listener HTTP, a ferramenta escreve dentro do espaço de trabalho e alcança os anfitriões que as origens de uma entidade indicam, pelo que um chamador precisa do âmbito de escrita no espaço de trabalho para a chamar — a mesma concessão de que um pull precisa.
Ver 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 | Predefinição | Descrição |
|---|---|---|
--dry-run | false | Resolve as entradas da entidade e imprime o entity.lock que o passo escreveria em vez de o escrever: o seu caminho e o conteúdo que teria vão para o stdout, e nada em disco muda. Um lock que o passo deixaria idêntico byte a byte não é impresso. A resolução corre exatamente como correria de outro modo, pelo que a cache de conteúdo continua a ser preenchida |