Etiquetas e anotações
As entidades do Aggrega contêm 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 anexo de funcionalidades. Seis superfícies distintas escrevem ou contêm conteúdo de anotações/etiquetas, cada uma com regras de cascata diferentes, consumidores diferentes e convenções de prefixo diferentes. Esta página documenta as superfícies num só lugar, define os três contentores semânticos que o contexto de template em tempo de execução expõe, indica a disciplina de prefixos que os autores devem seguir e documenta lado a lado as cinco superfícies de anexo de Feature, para que fiquem visíveis junto ao vocabulário mais amplo de etiquetas/anotações.
As seis superfícies portadoras de anotações e de etiquetas
Os autores encontram etiquetas e anotações em seis superfícies distintas. Cada uma tem um âmbito diferente, uma regra de cascata diferente e um consumidor diferente.
| # | Superfície | Âmbito | Regra de cascata | Consumidor principal |
|---|---|---|---|---|
| 1 | metadata.labels da entidade de catálogo | Identidade por entidade (Component, Feature, Aggregate) | Não se propaga em cascata para as instâncias; está contido na própria entidade de catálogo | aggrega search -l para Components e Features; as etiquetas de um Aggregate estão contidas no seu documento e nenhum comando as lê |
| 2 | metadata.labels do Component (intrínsecas) | Propriedades por instância de Component (component.aggrega.ai/type, etc.) | Propaga-se em cascata para o .context.labels por nó do IR após as mutações de label-transform | Correspondência de seletores (declarações selector: de usesSchema, transportadas como x-aggrega-selector: no JSON Schema sintetizado), lógica de template da Recipe |
| 3 | metadata.annotations do Component | Características por instância de Component escritas pelo arquiteto | Propaga-se em cascata para o contentor .context.annotations.catalog por nó do IR | papéis de veredicto da governação (políticas de características intrínsecas), lógica de template da Recipe |
| 4 | annotations: de Aggregate / subsistema | Metadados cognitivos do lado do Aggregate | Propaga-se em cascata para o contentor .context.annotations.aggregate por nó do IR | valuesMapping: da Recipe para o encaminhamento cognitivo |
| 5 | Fronteira da Release annotations: | Metadados físicos do lado de Ops, incluindo as anotações conhecidas aggrega.ai/* | Propaga-se em cascata para o contentor .context.annotations.release por nó do IR | Providers (o helm lê aggrega.ai/namespace; o compose deriva o nome da rede da mesma chave); injectMapping: da FeatureRecipe para o encaminhamento entre fronteiras |
| 6 | Associações features.annotations do Manifest | Associação chave de anotação → tipo de Feature com encaminhamento de subchaves agrupado por pilar (maps.infra / maps.values) para o anexo de Feature orientado por anotações | A 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 substituição por componente e a exclusão com null do valor inteiro / por subchave; a aplicação de lado face a pilar determina que pilar é acionado para cada lado de criação | Expansão de Feature orientada por anotações (anexos de Feature sintéticos, registados no grafo IR com origin: annotation) |
As superfícies 4 e 5 partilham uma forma YAML (um mapa annotations: na fronteira em cascata), mas propagam-se para contentores distintos do IR — a distinção entre contentores é a regra essencial que o tempo de execução expõe. A superfície 6 está estruturalmente separada: fica na entidade Manifest em vez de no conteúdo de Aggregate / Release, e o seu consumo está condicionado pela passagem de expansão orientada por anotações.
A semântica de três contentores de .context.annotations.*
Quando o renderizador avalia um template de Recipe, o campo por nó .context.annotations transporta três contentores com nome. Cada contentor é um mapa plano string → string indexado pelo nome da anotação; o contentor 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 encaminham-nas para camposinfra:quando apropriado. As anotações conhecidasaggrega.ai/*residem neste contentor..context.annotations.catalog— anotações dos metadados do Component (Superfície 3). Características intrínsecas imutáveis escritas 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 encaminham-nas para payloadsvalues:quando apropriado.
A separação em três contentores é um contrato social
O compilador não impõe as fronteiras entre os contentores. Os três contentores partilham 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 encaminhada para infra:. A separação é disciplina de criação, não uma garantia do compilador.
O objetivo da disciplina — o que os contentores pretendem exprimir:
- release = «onde este componente é executado, governado por Ops»
- catalog = «o que este componente é, escrito pelo arquiteto»
- aggregate = «o que este componente faz, escrito pelo programador»
Quando os autores respeitam a separação, as ferramentas a jusante podem ler o contentor certo para a questão certa. Quando os autores a violam (por exemplo, colocando metadados cognitivos em anotações release porque o ficheiro da Release é conveniente), o tempo de execução continua a funcionar, mas a intenção do contentor fica confusa.
Socket de linter — assinalar leituras entre contentores
Um plugin de linter (aviso fora de banda; ver plugins/plugin-contract.md para o critério de colocação) pode assinalar leituras entre contentores em que o template de uma Recipe vai buscar dados a um contentor cuja intenção não corresponde ao campo a ser encaminhado. O critério:
- Ler
.context.annotations.releasepara preencher um campovalues:— assinalar (os metadados cognitivos deveriam vir do contentoraggregate). - Ler
.context.annotations.aggregatepara preencher um campoinfra:— assinalar (os metadados físicos deveriam vir do contentorrelease). - Ler
.context.annotations.catalogpara preenchervalues:ouinfra:— normalmente apenas um aviso (as anotações do catálogo são características intrínsecas; encaminhá-las para pilares é invulgar, mas nem sempre errado).
O linter de publicação não tem nenhuma regra para este critério, e a compilação não o verifica; um plugin de linter próprio pode fazê-lo, através 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 contentores.
Disciplina de prefixos
As chaves de anotação e de etiqueta 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 está reservado, e uma compilação é interrompida onde uma associação do Manifest ou uma etiqueta de saída de uma Recipe reivindica uma nova chave dentro dele; os restantes são convenção do catálogo, sem nada que recuse uma chave. A diferença entre os dois é se uma compilação é interrompida, por isso convém ler a coluna do meio antes das outras.
| Prefixo | Quem escreve chaves aqui | Como é mantido | Finalidade | Exemplos |
|---|---|---|---|---|
aggrega.ai/ | Apenas a plataforma Aggrega | Reservado e imposto. A plataforma define as chaves aqui, e o autor escreve as que ela define — aggrega.ai/namespace numa 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 simples, e igualmente uma chave de etiqueta 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: a compilação transporta-a, e onde ela está numa Release, um destino que não atua sobre ela indica-o com uma advertência. Ver 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 etiqueta de saída usa um espaço de nomes reservado)». | Anotações nativas da plataforma consumidas diretamente pelo fornecedor | aggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment |
feature.aggrega.ai/ | Biblioteca padrão oficial | Convençã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 Manifest | feature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking |
component.aggrega.ai/ | Biblioteca padrão oficial | Convenção. Nada recusa uma chave aqui. | Etiquetas de características intrínsecas do Component (a chave de seletor component.aggrega.ai/type reside aqui) | component.aggrega.ai/type |
aggregate.aggrega.ai/ | Biblioteca padrão oficial | Convenção. Nada recusa uma chave aqui. | Etiquetas de identidade ao nível do módulo do Aggregate | aggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance |
<role>.aggrega.ai/ | Biblioteca padrão oficial, e as empresas nos seus próprios catálogos | Convenção. Nada recusa uma chave aqui. | Etiquetas de capacidade — as dimensões comportamentais pelas quais um seletor usesSchema ou o appliesTo de uma Feature discrimina. O <role> nomeia a questão a que a dimensão pertence: ou um papel de componente, ou uma questão transversal partilhada por vários papéis. | model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring |
<any-other-domain>/ | Empresa / comunidade | Aberto. Escrever sob um domínio que se controla. | Anotações e etiquetas personalizadas | acme.com/billing-tier, corp/cost-center |
Os autores que escrevem anotações personalizadas usam um domínio que controlam (normalmente no estilo DNS invertido). Escrever diretamente sob aggrega.ai/ (sem um subprefixo) está reservado à plataforma; as associações features.annotations do Manifest também não podem associar chaves diretamente sob aggrega.ai/ — ver 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 discernimento. Três regras regem-no, e a primeira é a que mais vezes é aplicada ao contrário.
- Nomear a questão, não o tipo de componente que por acaso a transporta primeiro. Onde uma dimensão descreve algo que vários tipos de componente partilham, o prefixo nomeia a questão partilhada 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 uma base 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 verdadeiramente específica de um papel recebe o nome desse papel, como fazmodel.aggrega.ai/capability. - Uma única palavra em minúsculas, sem hífen, no prefixo. O hífen pertence à metade
<dimension>, onde um composto se lê com naturalidade (request-mirroring,data-class,upstream-licensing). - Uma dimensão é acrescentada quando um seletor precisa dela, e cada valor que declara tem um componente que o transporta. Cada palavra aqui é uma que um autor de catálogo tem de aprender e que um autor de Feature pode encontrar, por isso uma dimensão conquista o seu lugar ao discriminar algo sobre que um
usesSchemaou umappliesToefetivamente pergunta. Um valor que nenhum componente transporta é pior do que um ausente: um seletor que o nomeia é analisado, não corresponde a nada e não reporta nada — por isso um valor que o catálogo não consegue demonstrar fica fora do vocabulário até que um componente o transporte. Uma chave cujo valor é uma declaração de uma organização sobre a forma como usa os seus próprios componentes, em vez de uma propriedade do produto, é a exceção, ecompliance.aggrega.ai/data-classé esse caso: a classe dos dados de um componente depende da forma como uma organização usa o componente, por isso nenhum Component da biblioteca padrão transporta qualquer um dos seus valores e nenhum socket ou Feature da biblioteca padrão seleciona por eles. A chave e os seus valores estão declarados para que os Components da própria organização e as políticas que ela anexa partilhem uma única grafia; um seletor ou uma política que nomeia um valor só corresponde num catálogo cujos Components o transportam. 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/ simples. Cada espaço de nomes <scope>.aggrega.ai/ abaixo dela é um espaço de chaves próprio que a plataforma não detém, 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 a compilação carimba.
Algumas chaves dentro desses espaços de nomes abertos são, no entanto, definidas pela plataforma e lidas pela compilação, e isso não torna o seu espaço de nomes reservado:
component.aggrega.ai/typeé obrigatória nosmetadata.labelsde todo o Component e assume um de um conjunto fixo de valores. Os seletores fazem correspondência com ela; o compilador não se ramifica consoante o valor que ela contém.features.aggrega.ai/requiredType.<label>, escrita nosmetadata.annotationsde um Component, declara que uma Feature do tipo indicado tem de estar anexada. A compilação verifica essa exigência face ao conjunto final de anexos de cada nó e é interrompida onde nada a satisfaz — vererrors/fatal-halts.md«Required feature not attached (Funcionalidade obrigatória não anexada)». Repare-se no plural:features.aggrega.ai/é um espaço de nomes próprio, distinto do singularfeature.aggrega.ai/na tabela acima, que transporta os atalhos de associação do Manifest.
A diferença lê-se assim: um prefixo reservado recusa uma chave que se tente definir dentro dele, enquanto uma chave definida pela plataforma é uma única chave com nome que a compilação conhece, situada num espaço de nomes em que, de resto, se é livre de escrever. Qualquer outra chave sob component.aggrega.ai/, features.aggrega.ai/ e os restantes são metadados que a compilação transporta sem os interpretar.
Uma dessas chaves nos metadata.annotations de um Component é lida pelo linter de publicação padrão, e não pela compilação: 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 a todos os chamadores; separate-token, exigem um token próprio. A compilação transporta-a como qualquer outra anotação. O linter lê-a para decidir se a credencial de uma ligaçã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 — ver «The discipline rules (As regras de disciplina)» em cli/aggrega-lint.md.
Etiquetas de proveniência emitidas na saída renderizada
Além das anotações de entrada que os fornecedores consomem, o Aggrega também emite etiquetas de proveniência em cada manifesto Kubernetes que o fornecedor helm renderiza e em cada serviço compose emitido, e o fornecedor helm-chart escreve o mesmo conjunto, tal como o fornecedor helm o escreve, em cada artefacto que carrega com $import:. O conjunto de etiquetas 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 tal como o seu autor os escreveu, por isso transportam as etiquetas que esse autor tiver escrito.
O conjunto que os fornecedores helm e compose emitem — no helm, três das chaves são escritas como anotações em vez de etiquetas, como a tabela indica:
| Etiqueta | Origem | Sempre emitida? |
|---|---|---|
app.kubernetes.io/name | Identidade do Component — o nome escrito pelo autor ou, para um componente que um Aggregate importado contribui, o seu nome qualificado com o separador de módulo escrito por extenso (ver abaixo); ou, para um recurso que uma FeatureRecipe emite, o identificador derivado para esse anexo | Sim nos manifestos Kubernetes; não emitida nos serviços compose (a etiqueta padrão é específica do K8s) |
aggrega.ai/component-id | Identidade do Component — o nome escrito pelo autor ou, para um componente que um Aggregate importado contribui, o seu nome qualificado com o separador de módulo escrito por extenso (ver abaixo); ou, para um recurso que uma FeatureRecipe emite, o identificador derivado para esse anexo | Sim |
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-path | Caminho da fronteira para o qual o componente foi encaminhado | Quando o caminho da fronteira não está vazio; uma anotação no helm |
aggrega.ai/aggregate-name | metadata.name do Aggregate | Quando definido |
aggrega.ai/compiler-version | Versão do compilador carimbada no momento da compilação | Quando definido |
aggrega.ai/provider | O fornecedor que renderizou o recurso (helm, helm-chart, compose) | Sim |
aggrega.ai/provider-version | A versão desse fornecedor | Sim |
aggrega.ai/environment | metadata.environment da Release | Sim — cada Release declara-o |
aggrega.ai/sync-wave | Inteiro syncWave por fronteira, a ordem pela qual uma ferramenta GitOps aplica os recursos | Quando 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 fornecedor são cadeias de caracteres escolhidas pelo utilizador ou pela compilação, e nenhuma delas está sujeita às regras de valores de etiqueta do Kubernetes no local onde é escrita. No helm, cada uma dessas etiquetas contém o valor tal como foi escrito quando já é um valor de etiqueta válido — letras, dígitos, -, _ e ., uma letra ou um dígito em ambas as extremidades, no máximo 63 caracteres — e, caso contrário, o valor reescrito num valor válido, com o valor literal adicionado como anotação sob a mesma chave: um Aggregate chamado imported/flow recebe a etiqueta aggrega.ai/aggregate-name: imported-flow e a anotação aggrega.ai/aggregate-name: imported/flow. Um valor que já cumpre as regras não adiciona nenhuma anotação. O Compose contém o valor literal como etiqueta. A regra de reescrita é indicada em providers/well-known-annotations.md «Etiquetas de proveniência emitidas pelos fornecedores».
Para recursos que uma FeatureRecipe emite, o valor aggrega.ai/component-id é construído a partir do anexo, e não do nome do componente anfitrião — para cada forma pela qual uma FeatureRecipe pode entregar esses recursos, quer sintetize uma carga de trabalho, emita um conjunto de artefactos autónomo ou renderize um chart ou um fragmento fornecido pelo seu autor. Assim, uma consulta que seleciona por identidade os recursos de um anexo devolve-os todos, e nenhum deles é indistinguível de um recurso que o próprio componente anfitrião emitiu. A forma como o valor é construído depende de onde a Feature está anexada; em ambos os casos, o resultado é uma cadeia de etiqueta 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 carácter que um nome de recurso ou um endereço do cluster possa transportar em segurança. Um nome escrito pelo autor sem qualquer 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 si próprio, por isso também os nomeia segundo a identidade: a identidade chega ao seu
metadata.name, às suas etiquetas de seletor e aos seus nomes de ficheiro emitidos, além das suas etiquetas. É um nome dentro do cluster, e não apenas uma etiqueta. - Onde uma FeatureRecipe entrega um chart ou um fragmento escrito pelo seu autor, 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 ficheiros que essa renderização emite — continuam a ser os do componente anfitrião. Os charts nomeiam habitualmente os seus recursos segundo o nome de release, por isso alterá-lo mudaria o nome de recursos que o próprio chart declara, num cluster onde já estão implementados, por um motivo que nada tem a ver com o chart. As etiquetas continuam a transportar a identidade própria do anexo, que é o que mantém os recursos do anexo localizáveis.
- Onde a Feature está anexada a uma fronteira, não existe componente anfitrião cujo nome possa servir em seu lugar, por isso aí a identidade composta é a base da nomeação, além da etiqueta.
Em ambos os casos, o valor é composto a partir das partes escritas pelo autor, unidas por --, atrás de um início fixo que indica de qual dos dois se trata. Há dois inícios em uso, e uma identidade de componente escrita pelo autor não pode começar por nenhum deles — é isso que impede que um nome escrito pelo autor e um nome composto pelo Aggrega sejam alguma vez confundidos um com o outro.
Onde a Feature está anexada a um componente, as partes são um início fixo cfr, a identidade do componente ao qual a Feature está anexada e a chave sob a qual está anexada. Uma Feature anexada ao componente api sob mon resulta em cfr--api--mon. O componente anfitrião faz parte do valor porque um mesmo nome de Feature anexado a vários componentes emite um conjunto de recursos separado em cada um, e cada conjunto precisa de uma identidade própria: anexar mon tanto a api como a worker resulta em cfr--api--mon e cfr--worker--mon em vez de um único valor para ambos. Um anexo com exatamente o mesmo nome do componente que o aloja resulta num valor distinto do próprio valor desse componente pelo mesmo motivo — mon anexado a mon resulta em cfr--mon--mon.
Onde a Feature está anexada 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á anexada. Uma Feature chamada gateway numa fronteira em bridge resulta em bfr--bridge--gateway; a mesma Feature numa fronteira em prod/eu resulta em bfr--prod--eu--gateway.
Um carácter que o valor não pode transportar é escrito por extenso em vez de substituído, e como o valor é um nome dentro do cluster além de uma etiqueta, fica restrito aos caracteres que todo o tipo de nome de recurso Kubernetes admite: letras minúsculas, dígitos e o hífen. Assim, um hífen escrito pelo autor continua a ser um hífen, uma letra minúscula ou um dígito fica como está, e qualquer outra coisa — incluindo uma letra maiúscula, que um valor de etiqueta admite e um nome de recurso recusa — torna-se um escape curto: um anexo chamado my_zone contribui my-zuzone, e um componente myApi com um anexo worker resulta em cfr--my-zx000041pi--worker. Esse valor com escape é aquele pelo qual os recursos do anexo são etiquetados e selecionados em todos os destinos, aquele segundo o qual são nomeados uma carga de trabalho que o anexo sintetiza e os seus ficheiros, e aquele do qual é derivado o nome de release de um anexo a uma fronteira. Uma maiúscula é o único carácter que a regra dos nomes de recurso acrescenta ao que uma etiqueta sozinha teria escrito por extenso, por isso um valor composto cujas partes não contêm nenhuma — cfr--api--mon, bfr--prod--eu--gateway — é o valor que uma etiqueta sozinha transportaria. Dois anexos que se conseguem distinguir resultam, portanto, em dois valores — seja qual for o nome que lhes foi dado 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 detenha: o destino para o qual os recursos são renderizados é consultado, e o valor é encurtado até que esse destino o aceite. Um valor de etiqueta Kubernetes tem no máximo 63 caracteres, e um nome de release do Helm derivado da mesma identidade tem um limite ainda mais estreito, por isso o mesmo anexo pode ficar mais curto sob um destino do que sob outro. Um valor que cabe é emitido exatamente como foi composto, que é o caso comum e o caso de todos os anexos do 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 se possa escrever produz — assim um valor encurtado é reconhecível como tal e nunca pode ser lido como um valor que coube. Um anexo gateway profundamente aninhado pode, portanto, ser renderizado como bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. É muito improvável que dois valores encurtados coincidam e, se isso acontecer, uma compilação é interrompida em vez de deixar que dois deles partilhem um nome.
Ver 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 que 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 como para a emitida por FR.
Para os pormenores de emissão por fornecedor (onde as etiquetas ficam na saída renderizada e como cada fornecedor as serializa), ver providers/well-known-annotations.md «Provenance labels emitted by providers (Etiquetas de proveniência emitidas pelos fornecedores)».
Etiquetas de saída declaradas pela Recipe
Ao lado do conjunto de proveniência que pertence ao compilador, o autor de uma Recipe pode declarar as suas próprias etiquetas para carimbar na saída renderizada da Recipe, através de Recipe.spec.outputLabels:. Estas seguem pelo mesmo trilho de emissão que as etiquetas de proveniência — são fundidas no mesmo conjunto de etiquetas e vão parar onde quer que a proveniência vá parar —, mas pertencem ao autor, e não ao compilador. A utilização prevista é uma característica de realização: uma propriedade da forma como uma Recipe específica realiza um componente (por exemplo, hosting: managed versus hosting: self-hosted para uma Recipe de serviço gerido versus uma Recipe de chart auto-alojado do mesmo tipo de componente), exposta na saída para que as ferramentas de custos, de políticas e de inventário a possam consultar.
Os espaços de nomes aggrega.ai/ e app.kubernetes.io/ estã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 etiqueta do componente e carimba o valor que o próprio componente declara. Um conjunto de etiquetas de saída validado é, portanto, sempre disjunto das chaves de proveniência, pelo que os dois nunca colidem na saída fundida. O critério é a raiz simples: uma chave com âmbito como component.aggrega.ai/hosting está num espaço de nomes próprio e pode ser escrita literalmente ou promovida. A exposição por fornecedor (objeto do helm e pod-template na síntese; objeto na renderização a partir de fonte e nos artefactos; etiquetas de serviço do compose; tags por recurso do terraform nos corpos de artefacto .tf.json) corresponde à colocação da proveniência, e está documentada na íntegra na página da entidade Recipe em «The outputLabels: field (O campo outputLabels:)» e «The outputComponentLabels: field (O campo outputComponentLabels:)».
Anexo de Feature — cinco superfícies
As Features anexam-se aos Components através de cinco superfícies de criação distintas, cada uma com âmbito, utilizador previsto e precedência de ordenação diferentes dentro do modelo de cebola de 5 níveis. A ordenação completa dos anexos 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ível | Superfície | Escrito por | Âmbito | Regra de cascata |
|---|---|---|---|---|
| 1 | Bloco features: de um componente do Aggregate | Programador | Por instância de componente (granular) | Nenhuma — direta do autor |
| 2 | Bloco features: de um subsistema do Aggregate | Programador | Âmbito do subsistema (transversal dentro do Aggregate) | Propaga-se em cascata a cada componente do subsistema |
| 3 | components.<id>.features da fronteira da Release | Ops | Por instância de componente (granular, lado de Ops) | Nenhuma — direta do autor |
| 4 | Bloco features: da fronteira da Release | Ops | Âmbito da fronteira (transversal dentro da fronteira) | Propaga-se em cascata a cada componente da fronteira |
| 5 | Expansão de features.annotations do Manifest | Operador da plataforma | Orientado por anotações (anexo sintético) | Propaga-se em cascata pela árvore de fronteiras (lado da Release) ou pela árvore de subsistemas (lado do Aggregate); aplicam-se a substituição por componente e a exclusão por subchave através de null |
As cinco superfícies acumulam-se; um anexo 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 fundem-se num único anexo em vez de se substituírem umas às outras, e uma divergência de tipo entre elas interrompe a compilação com um erro feature-merge-conflict.
As cinco superfícies são deliberadas segundo a separação de responsabilidades da arquitetura — programador (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 detém o anexo e em que âmbito.
Que etiquetas decidem se uma Feature se aplica
Uma Feature declara onde pode ser anexada com spec.appliesTo e spec.appliesToAnyOf, e a compilação julga essa declaração face às etiquetas finalizadas do nó em que o anexo recai. Anexar uma Feature a um nó que essas etiquetas não satisfazem interrompe a compilação; uma Feature que não declara nenhuma das duas superfícies não estabelece qualquer requisito e aplica-se em qualquer lugar.
O conjunto de etiquetas finalizado é montado em dois passos, e nenhum deles é aquele que os autores supõem com mais frequência.
- Um nó obtém as suas etiquetas da entidade de catálogo Component que o seu
type:nomeia. São uma propriedade do tipo de componente, não da instância: o Aggregate não pode etiquetar uma instância de componente, e a Release também não. Osmetadata.labelspróprios de um Aggregate descrevem o Aggregate como um módulo reutilizável e não se propagam em cascata aos componentes dentro dele. Assim, duas instâncias de um mesmo tipo transportam etiquetas idênticas, e mudar quais são as etiquetas de um nó significa mudar o tipo para o qual aponta — ou mudar a entidade desse tipo. - Um anexo
label-transformpode depois reescrevê-las. Onde a configuração do workspace anexa um plugin de governação no papellabel-transform, este é executado na construção da topologia e pode acrescentar, alterar ou remover etiquetas de nó antes de qualquer coisa ser julgada face a elas. Não pode tocar em mais nada, pelo que as etiquetas são a única parte de um nó que pode mover — e são exatamente a parte de que depende a aplicabilidade.
Uma proposta feita com base nas etiquetas que um único documento declara é, portanto, uma aproximação, não uma previsão. Ler os metadata.labels de uma entidade Component indica com o que começa um nó desse tipo, o que é a resposta certa com frequência suficiente para ser útil e errada de duas formas específicas: um documento que apenas partilha o nome de um nó é um assunto diferente com etiquetas diferentes, e um anexo label-transform pode mover o conjunto por baixo de qualquer documento. As ferramentas que oferecem sugestões de anexo apenas a partir do código-fonte trabalham com essa aproximação; o juízo que uma compilação faz incide sobre o conjunto finalizado.
Precedência das anexações
Quando duas contribuições fornecem o mesmo campo do mesmo anexo, quatro regras decidem qual delas a saída renderizada transporta. São aplicadas por esta ordem, e é a ordem que torna o resultado previsível:
- Origem. Uma contribuição escrita explicitamente prevalece sobre uma orientada por anotações, seja qual for o âmbito em que cada uma foi declarada. Escrever um campo num bloco
features:é a forma como um autor substitui o que uma anotação teria contribuído, e uma anotação nunca desloca silenciosamente algo escrito à mão. O compilador regista a anotação suprimida ao lado do valor vencedor e reporta-a como um aviso, de modo que a substituição fica visível em vez de misteriosa. - Propriedade dos pilares. Cada domínio preenche o seu próprio pilar: as superfícies do Aggregate contribuem
values, as superfícies da Release contribueminfra. Como os dois lados nunca escrevem o mesmo pilar, uma contribuição do programador e uma contribuição do operador não podem disputar o mesmo campo — não há qualquer questão de precedência entre programador e operador a responder. - Autoridade da composição. Uma declaração no Aggregate que está a ser implementado prevalece sobre uma declaração dentro de um Aggregate que este compõe, mesmo quando o Aggregate composto declarou no âmbito mais estreito. A composição continua determinante: um módulo não pode sobrepor-se ao Aggregate que o consome simplesmente escolhendo um âmbito mais estreito.
- Especificidade. Dentro de um mesmo nível de criação e de um mesmo pilar, o âmbito mais estreito refina o mais amplo, campo a campo. Um anexo com âmbito de componente substitui um anexo ao nível de subsistema ou de fronteira com o mesmo nome de instância — mas apenas para os campos que efetivamente menciona. Os campos que o âmbito mais estreito omite mantêm os valores do âmbito mais amplo, pelo que um anexo partilhado pode fornecer a configuração comum enquanto um único componente ajusta um dos seus campos. Duas contribuições no mesmo âmbito são resolvidas pela ordem do autor, prevalecendo a posterior, e é isso que permite que um subsistema interior refine um exterior e que uma fronteira mais profunda refine uma menos profunda.
A precedência rege os valores dos campos. Não reordena a avaliação: a sequência pela qual o compilador combina as superfícies, e pela qual executa o injectMapping pré-renderização de cada anexo, é a sequência fixa de cinco níveis documentada em architecture/10-compilation-pipeline.md. O bloco inject escrito de um anexo segue essa sequência de avaliação em vez da classificação de âmbitos acima, pelo que um anexo nunca transporta duas ordenações concorrentes.
Que tipos transportam metadata.labels e metadata.annotations
metadata.labels encontra-se 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 transportam nenhum dos dois.
Resumo da cascata
As regras de cascata nas seis superfícies, tal como o compilador as avalia:
- As etiquetas das entidades de catálogo (Superfície 1) permanecem na entidade de catálogo. Não fluem para as instâncias; os consumidores leem-nas inspecionando diretamente o conteúdo do catálogo.
- Os
metadata.labelsdo Component (Superfície 2) fluem para o.context.labelspor nó após a passagem opcionallabel-transformna construção da topologia. - Os
metadata.annotationsdo Component (Superfície 3) fluem para o contentor por nó.context.annotations.catalog. - As
annotations:do Aggregate / do subsistema (Superfície 4) propagam-se em cascata pela hierarquia de subsistemas, acumulando-se dos subsistemas exteriores para dentro, no contentor por nó.context.annotations.aggregate. - As
annotations:da fronteira da Release (Superfície 5) propagam-se em cascata pela hierarquia de fronteiras, das fronteiras exteriores para dentro, no contentor por nó.context.annotations.release. - As
features.annotationsdo 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 anexos de Feature por nó, que o grafo de IR (--ir-graph) regista comorigin: annotation. Os anexos sintéticos são estruturalmente indistinguíveis dos explícitos a jusante da resolução, exceto por essa proveniência — verproviders/well-known-annotations.mdpara a explicação completa da expansão earchitecture/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, ver architecture/06-data-taxonomy-and-composition.md §2 (Fluxo 5).
Referências cruzadas
templates/template-context-contract.md— vista em tempo de execução de.context.labelse dos três contentores.context.annotations.*.providers/well-known-annotations.md— matriz de anotações da fronteira por fornecedor e assimetria na emissão de etiquetas de proveniência.entities/manifest.md— a superfície de associaçãofeatures.annotationsdo Manifest (Superfície 6).vocabulary/publishing-surface.md— vocabulário de metadados uniforme que complementa etiquetas/anotações no lado da publicação.plugins/plugin-contract.md— o critério de colocação do socket de linter para verificações de aviso sobre leituras entre contentores.architecture/06-data-taxonomy-and-composition.md— design canónico das anotações em cascata.architecture/10-compilation-pipeline.md— modelo de cebola de 5 níveis que ordena o anexo de Feature.