Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

Rótulos e anotações

As entidades do Aggrega carregam dois mecanismos de metadados estruturalmente semelhantes — metadata.labels e metadata.annotations — além de campos portadores de anotações espalhados pelas superfícies de cascata por fronteira e de vinculação de funcionalidades. Seis superfícies distintas escrevem ou carregam conteúdo de anotações/rótulos, cada uma com regras de cascata diferentes, consumidores diferentes e convenções de prefixo diferentes. Esta página documenta as superfícies em um só lugar, define os três contêineres semânticos que o contexto de template em tempo de execução expõe, nomeia a disciplina de prefixos que os autores devem seguir e documenta lado a lado as cinco superfícies de vinculação de Feature, para que fiquem visíveis junto ao vocabulário mais amplo de rótulos/anotações.

As seis superfícies portadoras de anotações e de rótulos

Os autores encontram rótulos e anotações em seis superfícies distintas. Cada uma tem um escopo diferente, uma regra de cascata diferente e um consumidor diferente.

#SuperfícieEscopoRegra de cascataConsumidor principal
1metadata.labels da entidade de catálogoIdentidade por entidade (Component, Feature, Aggregate)Não se propaga em cascata para as instâncias; carregado na própria entidade de catálogoaggrega search -l para Components e Features; os rótulos de um Aggregate são carregados no seu documento e nenhum comando os lê
2metadata.labels do Component (intrínsecos)Propriedades por instância de Component (component.aggrega.ai/type etc.)Propaga em cascata para o .context.labels por nó do IR após as mutações de label-transformCorrespondência de seletores (declarações selector: de usesSchema, carregadas como x-aggrega-selector: no JSON Schema sintetizado), lógica de template da Recipe
3metadata.annotations do ComponentTraços por instância de Component escritos pelo arquitetoPropaga em cascata para o contêiner .context.annotations.catalog por nó do IRpapéis de veredito da governança (políticas de traços intrínsecos), lógica de template da Recipe
4annotations: de Aggregate / subsistemaMetadados cognitivos do lado do AggregatePropaga em cascata para o contêiner .context.annotations.aggregate por nó do IRvaluesMapping: da Recipe para o roteamento cognitivo
5Fronteira da Release annotations:Metadados físicos do lado de Ops, incluindo as anotações conhecidas aggrega.ai/*Propaga em cascata para o contêiner .context.annotations.release por nó do IRProviders (o helm lê aggrega.ai/namespace; o compose deriva o nome da rede da mesma chave); injectMapping: da FeatureRecipe para o roteamento entre fronteiras
6Associações features.annotations do ManifestAssociação chave de anotação → tipo de Feature com roteamento de subchaves agrupado por pilar (maps.infra / maps.values) para a vinculação de Feature orientada por anotaçõesA subfase de expansão de anotações da resolução percorre as fronteiras da Release (de fora para dentro) e os subsistemas do Aggregate (de fora para dentro); aplicam-se a sobrescrita por componente e a exclusão com null do valor inteiro / por subchave; a aplicação de lado versus pilar determina qual pilar dispara para cada lado de autoriaExpansão de Feature orientada por anotações (vinculações de Feature sintéticas, registradas no grafo IR com origin: annotation)

As superfícies 4 e 5 compartilham uma forma YAML (um mapa annotations: na fronteira em cascata), mas se propagam para contêineres distintos do IR — a distinção entre contêineres é a regra essencial que o tempo de execução expõe. A superfície 6 é estruturalmente separada: ela fica na entidade Manifest em vez de no conteúdo de Aggregate / Release, e o seu consumo é condicionado à passagem de expansão orientada por anotações.

A semântica de três contêineres de .context.annotations.*

Quando o renderizador avalia um template de Recipe, o campo por nó .context.annotations carrega três contêineres nomeados. Cada contêiner é um mapa plano string → string indexado pelo nome da anotação; o contêiner determina quem escreveu a anotação e qual é a sua intenção.

  • .context.annotations.release — anotações da fronteira da Release (Superfície 5). Servem para governar as realidades físicas; os renderizadores as roteiam para campos infra: quando apropriado. As anotações conhecidas aggrega.ai/* ficam neste contêiner.
  • .context.annotations.catalog — anotações dos metadados do Component (Superfície 3). Traços intrínsecos imutáveis escritos pelo arquiteto; consumidos principalmente por plugins de política Wasm.
  • .context.annotations.aggregate — anotações dos subsistemas do Aggregate (Superfície 4). Metadados cognitivos; os renderizadores as roteiam para payloads values: quando apropriado.

A separação em três contêineres é um contrato social

O compilador não impõe as fronteiras entre os contêineres. Os três contêineres compartilham uma forma plana string → string; o template de uma Recipe pode ler os três, e nada impede que uma anotação da fronteira da Release seja interpretada como um campo de metadados cognitivos ou que uma anotação do catálogo seja roteada para infra:. A separação é disciplina de autoria, não uma garantia do compilador.

O objetivo da disciplina — o que os contêineres pretendem expressar:

  • release = “onde este componente é executado, governado por Ops”
  • catalog = “o que este componente é, escrito pelo arquiteto”
  • aggregate = “o que este componente faz, escrito pelo desenvolvedor”

Quando os autores respeitam a separação, as ferramentas a jusante podem ler o contêiner certo para a questão certa. Quando os autores a violam (por exemplo, colocando metadados cognitivos em anotações release porque o arquivo da Release é conveniente), o tempo de execução continua funcionando, mas a intenção do contêiner fica confusa.

Socket de linter — sinalizar leituras entre contêineres

Um plugin de linter (aviso fora de banda; consulte plugins/plugin-contract.md para o critério de posicionamento) pode sinalizar leituras entre contêineres em que o template de uma Recipe busca dados de um contêiner cuja intenção não corresponde ao campo sendo roteado. O critério:

  • Ler .context.annotations.release para preencher um campo values: — sinalizar (metadados cognitivos deveriam vir do contêiner aggregate).
  • Ler .context.annotations.aggregate para preencher um campo infra: — sinalizar (metadados físicos deveriam vir do contêiner release).
  • Ler .context.annotations.catalog para preencher values: ou infra: — normalmente apenas um aviso (as anotações do catálogo são traços intrínsecos; roteá-las para pilares é incomum, mas nem sempre errado).

O linter de publicação não tem nenhuma regra para esse critério, e o build não o verifica; um plugin de linter seu pode fazê-lo, por meio do socket de linter que aggrega lint executa. A disciplina é mantida pelos revisores e autores que seguem a convenção sobre a intenção dos contêineres.

Disciplina de prefixos

As chaves de anotação e de rótulo seguem uma forma uniforme <namespace>/<name>. As famílias de prefixos abaixo indicam quem escreve chaves sob cada uma e como cada uma é mantida — um prefixo é reservado, e um build é interrompido onde uma associação do Manifest ou um rótulo de saída de uma Recipe reivindica uma nova chave dentro dele; os demais são convenção do catálogo, sem nada que recuse uma chave. A diferença entre os dois é se um build é interrompido, então leia a coluna do meio antes das outras.

PrefixoQuem escreve chaves aquiComo é mantidoFinalidadeExemplos
aggrega.ai/Somente a plataforma AggregaReservado e imposto. A plataforma define as chaves aqui, e você escreve as que ela define — aggrega.ai/namespace em uma fronteira da Release, por exemplo. Reivindicar uma chave nova dentro do prefixo provoca uma interrupção: uma associação features.annotations do Manifest sob o prefixo puro, e igualmente uma chave de rótulo de saída de uma Recipe sob ele em outputLabels: ou outputComponentLabels:. Uma anotação escrita sob ele que a plataforma não define não é recusada: o build a carrega, e onde ela está em uma Release, um destino que não age sobre ela informa isso com um alerta. Consulte errors/fatal-halts.md “A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Uma associação de anotação do Manifest reivindica o prefixo reservado)” e “An output-label key uses a reserved namespace (Uma chave de rótulo de saída usa um namespace reservado)”.Anotações nativas da plataforma consumidas diretamente pelo provedoraggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/Biblioteca padrão oficialConvenção. Nada recusa uma chave aqui; o vocabulário pertence à biblioteca padrão por acordo, e não por uma verificação.Atalhos de anotação de Feature associados em features.annotations do Manifestfeature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/Biblioteca padrão oficialConvenção. Nada recusa uma chave aqui.Rótulos de traços intrínsecos do Component (a chave de seletor component.aggrega.ai/type fica aqui)component.aggrega.ai/type
aggregate.aggrega.ai/Biblioteca padrão oficialConvenção. Nada recusa uma chave aqui.Rótulos de identidade em nível de módulo do Aggregateaggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/Biblioteca padrão oficial, e as empresas em seus próprios catálogosConvenção. Nada recusa uma chave aqui.Rótulos de capacidade — as dimensões comportamentais pelas quais um seletor usesSchema ou o appliesTo de uma Feature discrimina. O <role> nomeia a questão à qual a dimensão pertence: ou um papel de componente, ou uma questão transversal que vários papéis compartilham.model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/Empresa / comunidadeAberto. Escreva sob um domínio que você controla.Anotações e rótulos personalizadosacme.com/billing-tier, corp/cost-center

Os autores que escrevem anotações personalizadas usam um domínio que controlam (normalmente no estilo DNS reverso). Escrever diretamente sob aggrega.ai/ (sem um subprefixo) é reservado à plataforma; as associações features.annotations do Manifest também não podem associar chaves diretamente sob aggrega.ai/ — consulte entities/manifest.md “aggrega.ai/ Prefix Reservation (Reserva do prefixo aggrega.ai/)”.

Nomear um prefixo de capacidade

Uma chave de capacidade é <role>.aggrega.ai/<dimension>, e o <role> é a parte que exige julgamento. Três regras o regem, e a primeira é a que mais vezes é aplicada ao contrário.

  • Nomeie a questão, não o tipo de componente que por acaso a carrega primeiro. Onde uma dimensão descreve algo que vários tipos de componente compartilham, o prefixo nomeia a questão compartilhada para que o próximo tipo a adquiri-la reutilize o vocabulário em vez de inventar um paralelo. component.aggrega.ai/hosting é uma questão — quem opera o recurso subjacente — e descreve um banco de dados e uma API de modelo com as mesmas palavras; dataplane.aggrega.ai/* nomeia uma posição no caminho do tráfego, de modo que um proxy, um gateway de entrada e uma service mesh se descrevem da mesma forma. Uma dimensão realmente específica de um papel recebe o nome desse papel, como faz model.aggrega.ai/capability.
  • Uma única palavra em minúsculas, sem hífen, no prefixo. O hífen pertence à metade <dimension>, onde um composto é lido com naturalidade (request-mirroring, data-class, upstream-licensing).
  • Uma dimensão é adicionada quando um seletor precisa dela, e cada valor que ela declara tem um componente que o carrega. Cada palavra aqui é uma que um autor de catálogo precisa aprender e que um autor de Feature pode encontrar, então uma dimensão conquista seu lugar discriminando algo que um usesSchema ou um appliesTo de fato pergunta. Um valor que nenhum componente carrega é pior do que um ausente: um seletor que o nomeia é analisado, não corresponde a nada e não informa nada — por isso um valor que o catálogo não consegue demonstrar fica fora do vocabulário até que um componente o carregue. Uma chave cujo valor é uma declaração de uma organização sobre como ela usa seus próprios componentes, em vez de uma propriedade do produto, é a exceção, e compliance.aggrega.ai/data-class é esse caso: a classe dos dados de um componente depende de como uma organização usa o componente, então nenhum Component da biblioteca padrão carrega qualquer um de seus valores e nenhum socket ou Feature da biblioteca padrão seleciona por eles. A chave e seus valores são declarados para que os Components da própria organização e as políticas que ela vincula compartilhem uma única grafia; um seletor ou uma política que nomeia um valor só corresponde em um catálogo cujos Components o carregam. policy-data-class-route mostra um desses Component e a política que o lê.

Uma reserva e uma chave definida pela plataforma não são a mesma coisa

A reserva incide sobre a raiz aggrega.ai/ pura. Cada namespace <scope>.aggrega.ai/ abaixo dela é um espaço de chaves próprio que a plataforma não possui, e é isso que mantém extensível o vocabulário do catálogo: um catálogo empresarial pode escrever acme.aggrega.ai/team sem disputar nada do que o build carimba.

Algumas chaves dentro desses namespaces abertos são, no entanto, definidas pela plataforma e lidas pelo build, e isso não torna o seu namespace reservado:

  • component.aggrega.ai/type é obrigatória nos metadata.labels de todo Component e assume um de um conjunto fixo de valores. Os seletores fazem correspondência com ela; o compilador não se ramifica conforme o valor que ela contém.
  • features.aggrega.ai/requiredType.<label>, escrita nos metadata.annotations de um Component, declara que uma Feature do tipo indicado deve estar vinculada. O build verifica essa exigência contra o conjunto final de vinculações de cada nó e é interrompido onde nada a satisfaz — consulte errors/fatal-halts.md “Required feature not attached (Funcionalidade obrigatória não vinculada)”. Observe o plural: features.aggrega.ai/ é um namespace próprio, distinto do singular feature.aggrega.ai/ na tabela acima, que carrega os atalhos de associação do Manifest.

Leia a diferença assim: um prefixo reservado recusa uma chave que você tenta definir dentro dele, enquanto uma chave definida pela plataforma é uma única chave nomeada que o build conhece, situada em um namespace em que, de resto, você é livre para escrever. Qualquer outra chave sob component.aggrega.ai/, features.aggrega.ai/ e os demais são metadados que o build carrega sem interpretar.

Uma dessas chaves nos metadata.annotations de um Component é lida pelo linter de publicação padrão, e não pelo build: observability.aggrega.ai/metrics-credential indica como as métricas do produto se autenticam — none, são servidas sem credencial; target-key, exigem a chave que o Component exige de todo chamador; separate-token, exigem um token próprio. O build a carrega como qualquer outra anotação. O linter a lê para decidir se a credencial de uma conexão de scrape é comparada com a chave de chamador do destino, e exige que ela concorde com a chave provides metrics_credential_required que o Component declara — consulte “The discipline rules (As regras de disciplina)” em cli/aggrega-lint.md.

Labels de proveniência emitidos na saída renderizada

Além das anotações de entrada que os provedores consomem, o Aggrega também emite rótulos de proveniência em cada manifesto Kubernetes que o provedor helm renderiza e em cada serviço compose emitido, e o provedor helm-chart escreve o mesmo conjunto, tal como o provedor helm o escreve, em cada artefato que carrega com $import:. O conjunto de rótulos permite que as ferramentas a jusante (painéis de custos, stacks de observabilidade, controladores GitOps) atribuam os recursos em tempo de execução ao conteúdo do catálogo que os produziu. Os templates próprios de um subchart helm-chart são copiados como o autor os escreveu, então carregam os rótulos que esse autor tiver escrito.

O conjunto que os provedores helm e compose emitem — no helm, três das chaves são escritas como anotações em vez de rótulos, como a tabela indica:

RótuloOrigemSempre emitido?
app.kubernetes.io/nameIdentidade do Component — o nome que você escreveu ou, para um componente que um Aggregate importado contribui, seu nome qualificado com o separador de módulo escrito por extenso (veja abaixo); ou, para um recurso que uma FeatureRecipe emite, o identificador derivado para essa vinculaçãoSim nos manifestos Kubernetes; não emitido nos serviços compose (o rótulo padrão é específico do K8s)
aggrega.ai/component-idIdentidade do Component — o nome que você escreveu ou, para um componente que um Aggregate importado contribui, seu nome qualificado com o separador de módulo escrito por extenso (veja abaixo); ou, para um recurso que uma FeatureRecipe emite, o identificador derivado para essa vinculaçãoSim
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> da Recipe produtora (ou da FeatureRecipe produtora para recursos emitidos por uma FR)Quando a entidade produtora tem nome e versão definidos; uma anotação no helm
aggrega.ai/boundary-pathCaminho da fronteira para o qual o componente foi roteadoQuando o caminho da fronteira não está vazio; uma anotação no helm
aggrega.ai/aggregate-namemetadata.name do AggregateQuando definido
aggrega.ai/compiler-versionVersão do compilador carimbada no momento do buildQuando definido
aggrega.ai/providerO provedor que renderizou o recurso (helm, helm-chart, compose)Sim
aggrega.ai/provider-versionA versão desse provedorSim
aggrega.ai/environmentmetadata.environment da ReleaseSim — toda Release o declara
aggrega.ai/sync-waveInteiro syncWave por fronteira, a ordem em que uma ferramenta GitOps aplica os recursosQuando diferente de zero; uma anotação no helm, ao lado de argocd.argoproj.io/sync-wave

O nome do agregado, o ambiente, a versão do compilador e o nome e a versão do provedor são strings que você ou o build escolheram, e nenhuma delas está sujeita às regras de valores de rótulo do Kubernetes no lugar onde é escrita. No helm, cada um desses rótulos carrega o valor como foi escrito quando ele já é um valor de rótulo válido — letras, dígitos, -, _ e ., uma letra ou um dígito nas duas extremidades, no máximo 63 caracteres — e, caso contrário, o valor reescrito em um válido, com o valor literal adicionado como anotação sob a mesma chave: um Aggregate chamado imported/flow recebe o rótulo aggrega.ai/aggregate-name: imported-flow e a anotação aggrega.ai/aggregate-name: imported/flow. Um valor que já se encaixa não adiciona nenhuma anotação. O Compose carrega o valor literal como rótulo. A regra de reescrita está descrita em providers/well-known-annotations.md “Rótulos de proveniência emitidos pelos provedores”.

Para recursos que uma FeatureRecipe emite, o valor aggrega.ai/component-id é construído a partir da vinculação, e não do nome do componente hospedeiro — para cada forma pela qual uma FeatureRecipe pode entregar esses recursos, seja sintetizando uma carga de trabalho, emitindo um conjunto de artefatos independente ou renderizando um chart ou um fragmento fornecido por seu autor. Assim, uma consulta que seleciona por identidade os recursos de uma vinculação retorna todos eles, e nenhum deles é indistinguível de um recurso que o próprio componente hospedeiro emitiu. Como o valor é construído depende de onde a Feature está vinculada; em ambos os casos o resultado é uma string de rótulo Kubernetes válida.

Para um componente que um Aggregate importado contribui, a identidade é o nome qualificado desse componente com o separador que une o módulo ao componente escrito por extenso — data-layer.main-db é carimbado como data-layer-zdmain-db — porque um ponto não é um caractere que um nome de recurso ou um endereço do cluster possa carregar com segurança. Um nome que você escreveu sem nenhum separador é carimbado byte a byte.

A identidade diz a que um recurso pertence. Essa é uma pergunta diferente de como um recurso se chama, e para uma das entregas as duas têm respostas diferentes:

  • Onde uma FeatureRecipe sintetiza uma carga de trabalho, o Aggrega constrói esses recursos por conta própria, então também os nomeia segundo a identidade: a identidade chega ao seu metadata.name, aos seus rótulos de seletor e aos seus nomes de arquivo emitidos, além dos seus rótulos. É um nome dentro do cluster, e não apenas um rótulo.
  • Onde uma FeatureRecipe entrega um chart ou um fragmento que seu autor escreveu, os nomes pertencem a quem o escreveu. O nome de release do Helm com o qual esses templates são renderizados — e o prefixo nos arquivos que essa renderização emite — continuam sendo os do componente hospedeiro. Os charts costumam nomear seus recursos segundo o nome de release, então alterá-lo renomearia recursos que o próprio chart declara, em um cluster onde eles já estão implantados, por um motivo que nada tem a ver com o chart. Os rótulos continuam carregando a identidade própria da vinculação, que é o que mantém os recursos da vinculação localizáveis.
  • Onde a Feature está vinculada a uma fronteira, não há componente hospedeiro cujo nome possa servir em seu lugar, então ali a identidade composta é a base da nomeação, além do rótulo.

Em ambos os casos o valor é composto a partir das partes que você escreveu, unidas por --, atrás de um início fixo que diz de qual dos dois se trata. Há dois inícios em uso, e uma identidade de componente que você escreve não pode começar com nenhum deles — é isso que impede que um nome que você escreveu e um nome que o Aggrega compôs sejam algum dia confundidos um com o outro.

Onde a Feature está vinculada a um componente, as partes são um início fixo cfr, a identidade do componente ao qual a Feature está vinculada e a chave sob a qual ela está vinculada. Uma Feature vinculada ao componente api sob mon resulta em cfr--api--mon. O componente hospedeiro faz parte do valor porque um mesmo nome de Feature vinculado a vários componentes emite um conjunto de recursos separado em cada um, e cada conjunto precisa de uma identidade própria: vincular mon tanto a api quanto a worker resulta em cfr--api--mon e cfr--worker--mon em vez de um único valor para ambos. Uma vinculação nomeada exatamente como o componente que a hospeda resulta em um valor distinto do próprio valor desse componente pelo mesmo motivo — mon vinculada a mon resulta em cfr--mon--mon.

Onde a Feature está vinculada a uma fronteira — o serviço de gateway compose-bridge é o exemplo canônico —, as partes são um início fixo bfr, depois cada segmento do caminho da fronteira, do mais externo para o mais interno, depois o nome sob o qual a Feature está vinculada. Uma Feature chamada gateway em uma fronteira em bridge resulta em bfr--bridge--gateway; a mesma Feature em uma fronteira em prod/eu resulta em bfr--prod--eu--gateway.

Um caractere que o valor não pode carregar é escrito por extenso em vez de substituído, e como o valor é um nome dentro do cluster além de um rótulo, ele fica restrito aos caracteres que todo tipo de nome de recurso Kubernetes admite: letras minúsculas, dígitos e o hífen. Assim, um hífen que você escreveu continua sendo um hífen, uma letra minúscula ou um dígito permanece como está, e qualquer outra coisa — inclusive uma letra maiúscula, que um valor de rótulo admite e um nome de recurso recusa — vira um escape curto: uma vinculação chamada my_zone contribui my-zuzone, e um componente myApi com uma vinculação worker resulta em cfr--my-zx000041pi--worker. Esse valor com escape é aquele pelo qual os recursos da vinculação são rotulados e selecionados em todo destino, aquele segundo o qual são nomeados uma carga de trabalho que a vinculação sintetiza e seus arquivos, e aquele do qual é derivado o nome de release de uma vinculação a uma fronteira. Uma maiúscula é o único caractere que a regra de nomes de recurso acrescenta ao que um rótulo sozinho teria escrito por extenso, então um valor composto cujas partes não contêm nenhuma — cfr--api--mon, bfr--prod--eu--gateway — é o valor que um rótulo sozinho carregaria. Duas vinculações que você consegue distinguir resultam, portanto, em dois valores — qualquer que seja o nome que você lhes deu e por mais profunda que esteja a fronteira — porque -- é uma sequência que nenhuma parte escrita pode conter, de modo que mover a divisão entre as partes altera o valor em vez de colidir com ele.

O comprimento que um valor composto pode ter é uma resposta do destino, e não um número que o Aggrega mantém: o destino para o qual os recursos são renderizados é consultado, e o valor é encurtado até que esse destino o aceite. Um valor de rótulo Kubernetes carrega no máximo 63 caracteres, e um nome de release do Helm derivado da mesma identidade é limitado de forma ainda mais estrita, então a mesma vinculação pode ficar mais curta sob um destino do que sob outro. Um valor que cabe é emitido exatamente como composto, que é o caso comum e o caso de toda vinculação no catálogo da biblioteca padrão. Um que não cabe é encurtado: cada parte mantém o seu começo, e um digest de dez caracteres da identidade inteira é acrescentado atrás de um marcador que nenhum nome que você possa escrever produz — assim um valor encurtado é reconhecível como tal e nunca pode ser lido como um valor que coube. Uma vinculação gateway profundamente aninhada pode, portanto, ser renderizada como bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. É muito improvável que dois valores encurtados coincidam e, se isso acontecer, um build é interrompido em vez de deixar que dois deles compartilhem um nome.

Consulte errors/fatal-halts.md “The same name is derived more than once inside the output (O mesmo nome é derivado mais de uma vez dentro da saída)” para saber quais pares provocam uma interrupção e como separá-los.

O valor aggrega.ai/recipe-uri de um recurso emitido por uma FR corresponde ao name:version próprio da FeatureRecipe, e não à identidade da Recipe consumidora — assim, as ferramentas a jusante que leem recipe-uri para identificar a entidade produtora obtêm a proveniência correta tanto para a saída emitida por componentes quanto para a emitida por FRs.

Para os detalhes de emissão por provedor (onde os rótulos ficam na saída renderizada e como cada provedor os serializa), consulte providers/well-known-annotations.md “Provenance labels emitted by providers (Rótulos de proveniência emitidos pelos provedores)”.

Rótulos de saída declarados pela Recipe

Ao lado do conjunto de proveniência que pertence ao compilador, o autor de uma Recipe pode declarar seus próprios rótulos para carimbar na saída renderizada da Recipe, por meio de Recipe.spec.outputLabels:. Eles seguem pelo mesmo trilho de emissão que os rótulos de proveniência — são mesclados no mesmo conjunto de rótulos e vão parar onde quer que a proveniência vá parar —, mas pertencem ao autor, e não ao compilador. O uso pretendido é um traço de realização: uma propriedade de como uma Recipe específica realiza um componente (por exemplo, hosting: managed versus hosting: self-hosted para uma Recipe de serviço gerenciado versus uma Recipe de chart auto-hospedado do mesmo tipo de componente), exposta na saída para que as ferramentas de custo, de política e de inventário possam consultá-la.

Os namespaces aggrega.ai/ e app.kubernetes.io/ são reservados ao conjunto de proveniência; uma chave sob qualquer um dos dois prefixos é recusada no carregamento — em outputLabels: e em outputComponentLabels:, o bloco complementar que nomeia uma chave de rótulo do componente e carimba o valor que o próprio componente declara. Um conjunto de rótulos de saída validado é, portanto, sempre disjunto das chaves de proveniência, de modo que os dois nunca colidem na saída mesclada. O critério é a raiz pura: uma chave com escopo como component.aggrega.ai/hosting fica em um namespace próprio e pode ser escrita literalmente ou promovida. A exposição por provedor (objeto do helm e pod-template na síntese; objeto na renderização a partir de fonte e nos artefatos; rótulos de serviço do compose; tags por recurso do terraform nos corpos de artefato .tf.json) corresponde ao posicionamento da proveniência, e está documentada por completo na página da entidade Recipe em “The outputLabels: field (O campo outputLabels:)” e “The outputComponentLabels: field (O campo outputComponentLabels:)”.

Vinculação de Feature — cinco superfícies

As Features se vinculam aos Components por meio de cinco superfícies de autoria distintas, cada uma com escopo, usuário pretendido e precedência de ordenação diferentes dentro do modelo de cebola de 5 níveis. A ordenação completa das vinculações e o próprio modelo de cebola estão documentados em architecture/10-compilation-pipeline.md; a tabela abaixo enumera as cinco superfícies lado a lado.

NívelSuperfícieEscrito porEscopoRegra de cascata
1Bloco features: de um componente do AggregateDesenvolvedorPor instância de componente (granular)Nenhuma — direta do autor
2Bloco features: de um subsistema do AggregateDesenvolvedorEscopo do subsistema (transversal dentro do Aggregate)Propaga-se em cascata para cada componente do subsistema
3components.<id>.features da fronteira da ReleaseOpsPor instância de componente (granular, lado de Ops)Nenhuma — direta do autor
4Bloco features: da fronteira da ReleaseOpsEscopo da fronteira (transversal dentro da fronteira)Propaga-se em cascata para cada componente da fronteira
5Expansão de features.annotations do ManifestOperador da plataformaOrientada por anotações (vinculação sintética)Propaga-se em cascata pela árvore de fronteiras (lado da Release) ou pela árvore de subsistemas (lado do Aggregate); aplicam-se a sobrescrita por componente e a exclusão por subchave via null

As cinco superfícies se acumulam; uma vinculação presente em qualquer superfície contribui para o conjunto de funcionalidades resolvido do Component. Quando o mesmo nome de instância de Feature aparece em mais de uma superfície, as contribuições se mesclam em uma única vinculação em vez de substituírem umas às outras, e uma divergência de tipo entre elas interrompe o build com um erro feature-merge-conflict.

As cinco superfícies são deliberadas segundo a separação de responsabilidades da arquitetura — desenvolvedor (níveis 1-2), Ops (níveis 3-4), operador da plataforma (nível 5) — e não redundantes. Os autores escolhem a superfície que corresponde a quem é dono da vinculação e em qual escopo.

Quais rótulos decidem se uma Feature se aplica

Uma Feature declara onde pode ser vinculada com spec.appliesTo e spec.appliesToAnyOf, e o build julga essa declaração em relação aos rótulos finalizados do nó em que a vinculação recai. Vincular uma Feature a um nó que esses rótulos não satisfazem interrompe o build; uma Feature que não declara nenhuma das duas superfícies não estabelece nenhum requisito e se aplica em qualquer lugar.

O conjunto de rótulos finalizado é montado em duas etapas, e nenhuma delas é a que os autores supõem com mais frequência.

  1. Um nó obtém seus rótulos da entidade de catálogo Component que seu type: nomeia. Eles são uma propriedade do tipo de componente, não da instância: o Aggregate não pode rotular uma instância de componente, e a Release também não. Os metadata.labels próprios de um Aggregate descrevem o Aggregate como um módulo reutilizável e não se propagam em cascada para os componentes dentro dele. Assim, duas instâncias de um mesmo tipo carregam rótulos idênticos, e mudar quais são os rótulos de um nó significa mudar o tipo para o qual ele aponta — ou mudar a entidade desse tipo.
  2. Uma vinculação label-transform pode então reescrevê-los. Onde a configuração do workspace vincula um plugin de governança no papel label-transform, ele é executado na construção da topologia e pode adicionar, alterar ou remover rótulos de nó antes que qualquer coisa seja julgada em relação a eles. Ele não pode tocar em mais nada, então os rótulos são a única parte de um nó que ele pode mover — e são exatamente a parte da qual a aplicabilidade depende.

Uma proposta feita com base nos rótulos que um único documento declara é, portanto, uma aproximação, não uma previsão. Ler os metadata.labels de uma entidade Component diz a você com o que um nó desse tipo começa, o que é a resposta certa com frequência suficiente para ser útil e errada de duas maneiras específicas: um documento que apenas compartilha o nome de um nó é um assunto diferente com rótulos diferentes, e uma vinculação label-transform pode mover o conjunto por baixo de qualquer documento. As ferramentas que oferecem sugestões de vinculação apenas a partir do código-fonte trabalham com essa aproximação; o julgamento que um build faz é sobre o conjunto finalizado.

Precedência de anexos

Quando duas contribuições fornecem o mesmo campo da mesma vinculação, quatro regras decidem qual delas a saída renderizada carrega. Elas são aplicadas nesta ordem, e é a ordem que torna o resultado previsível:

  1. Origem. Uma contribuição escrita explicitamente prevalece sobre uma orientada por anotações, qualquer que seja o escopo em que cada uma foi declarada. Escrever um campo em um bloco features: é a forma como um autor sobrescreve o que uma anotação teria contribuído, e uma anotação nunca desloca silenciosamente algo escrito à mão. O compilador registra a anotação suprimida ao lado do valor vencedor e a reporta como um aviso, de modo que a sobrescrita fica visível em vez de misteriosa.
  2. Propriedade dos pilares. Cada domínio preenche o seu próprio pilar: as superfícies do Aggregate contribuem values, as superfícies da Release contribuem infra. Como os dois lados nunca escrevem o mesmo pilar, uma contribuição do desenvolvedor e uma contribuição do operador não podem disputar o mesmo campo — não há nenhuma questão de precedência entre desenvolvedor e operador a responder.
  3. Autoridade da composição. Uma declaração no Aggregate que você está implantando prevalece sobre uma declaração dentro de um Aggregate que ele compõe, mesmo quando o Aggregate composto declarou no escopo mais estreito. A composição continua determinante: um módulo não pode se impor ao Aggregate que o consome simplesmente escolhendo um escopo mais estreito.
  4. Especificidade. Dentro de um mesmo nível de autoria e de um mesmo pilar, o escopo mais estreito refina o mais amplo, campo a campo. Uma vinculação com escopo de componente sobrescreve uma vinculação no nível de subsistema ou de fronteira com o mesmo nome de instância — mas apenas para os campos que ela de fato menciona. Os campos que o escopo mais estreito omite mantêm os valores do escopo mais amplo, de modo que uma vinculação compartilhada pode fornecer a configuração comum enquanto um único componente ajusta um de seus campos. Duas contribuições no mesmo escopo são resolvidas pela ordem do autor, com a posterior prevalecendo, que é o que permite que um subsistema interno refine um externo e que uma fronteira mais profunda refine uma menos profunda.

A precedência governa os valores dos campos. Ela não reordena a avaliação: a sequência em que o compilador combina as superfícies, e em que executa o injectMapping pré-renderização de cada vinculação, é a sequência fixa de cinco níveis documentada em architecture/10-compilation-pipeline.md. O bloco inject escrito de uma vinculação segue essa sequência de avaliação em vez da classificação de escopos acima, de modo que uma vinculação nunca carrega duas ordenações concorrentes.

Quais tipos carregam metadata.labels e metadata.annotations

metadata.labels fica em Component, Feature, Aggregate e nos quatro tipos de biblioteca; metadata.annotations nos mesmos tipos, exceto Aggregate. Manifest, Release, Recipe, FeatureRecipe e Plugin não carregam nenhum dos dois.

Resumo da cascata

As regras de cascata nas seis superfícies, conforme o compilador as avalia:

  1. Os rótulos das entidades de catálogo (Superfície 1) permanecem na entidade de catálogo. Eles não fluem para as instâncias; os consumidores os leem inspecionando diretamente o conteúdo do catálogo.
  2. Os metadata.labels do Component (Superfície 2) fluem para o .context.labels por nó após a passagem opcional label-transform na construção da topologia.
  3. Os metadata.annotations do Component (Superfície 3) fluem para o contêiner por nó .context.annotations.catalog.
  4. As annotations: do Aggregate / do subsistema (Superfície 4) se propagam em cascata pela hierarquia de subsistemas, acumulando-se dos subsistemas externos para dentro, no contêiner por nó .context.annotations.aggregate.
  5. As annotations: da fronteira da Release (Superfície 5) se propagam em cascata pela hierarquia de fronteiras, das fronteiras externas para dentro, no contêiner por nó .context.annotations.release.
  6. As features.annotations do Manifest (Superfície 6) não se propagam em cascata diretamente para os dados de IR por nó; a subfase de expansão orientada por anotações da resolução consome as associações para sintetizar vinculações de Feature por nó, que o grafo de IR (--ir-graph) registra com origin: annotation. As vinculações sintéticas são estruturalmente indistinguíveis das explícitas a jusante da resolução, exceto por essa proveniência — consulte providers/well-known-annotations.md para a explicação completa da expansão e architecture/13-catalog-and-registry.md §“Annotation-driven Feature expansion (expansão de Feature orientada por anotações)” para a mecânica no carregamento do catálogo e no momento da inspeção.

Para o design canônico das anotações em cascata, consulte architecture/06-data-taxonomy-and-composition.md §2 (Fluxo 5).

Referências cruzadas