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

Anotações bem conhecidas

Os Providers leem anotações específicas para configurar um contexto específico da plataforma — definidas na fronteira de uma Release ou na entrada de um componente numa Release, ou declaradas no Aggregate num subsistema ou numa instância de componente. O próprio compilador é agnóstico em relação aos valores destas anotações — fá-los passar como cadeias de caracteres opacas. Cada fornecedor declara que anotações lê, em que âmbito e que valor predefinido se aplica quando a anotação está ausente. Essa declaração encontra-se em spec.provider.wellKnownAnnotations de um Plugin de renderização de fornecedor, e é deliberadamente estreita: um fornecedor só lista uma chave onde a lê. Um fornecedor que não lê nenhuma delas declara, em vez disso, spec.provider.readsNoWellKnownAnnotations: true.

A matriz de suporte deste capítulo é gerada a partir dessas declarações, na granularidade que a declaração tem — por fornecedor por tipo de entrada, porque um fornecedor pode ler uma chave quando sintetiza uma unidade de implementação e não ter forma de a ler quando renderiza um artefacto copiado localmente. Convém escrever com base na matriz daqui: uma célula diz o que esse fornecedor lê nesse caminho, porque uma célula não pode dizer nada que o fornecedor não tenha declarado. Uma declaração que nomeie um tipo de entrada que o próprio contrato de comportamento de renderização do fornecedor não renderiza é recusada quando a entidade Plugin é lida, pelo que as duas afirmações não podem divergir.

O vocabulário reservado é o conjunto mais amplo, e encontra-se antes em dois lugares — este capítulo, que nomeia cada chave reservada, incluindo as que nenhum fornecedor lê, e o conjunto de prefixos reservados que o lint de publicação verifica.

Os invariantes

  1. O compilador nunca interpreta nem valida o valor de uma anotação bem conhecida de fornecedor: transporta a chave e o seu valor através da cascata e avisa onde um destino não atua sobre a chave.
  2. Cada fornecedor documenta que anotações lê e que valores predefinidos aplica.
  3. As anotações aplicam-se de forma uniforme dentro de uma fronteira. Se um valor variar por componente, pertence às anotações ao nível do componente (que substituem as anotações da fronteira) ou a infra do componente.
  4. As anotações bem conhecidas dos Provider nunca duplicam as etiquetas dos componentes. As etiquetas de Component descrevem o que um componente é. As anotações de fronteira descrevem onde um componente é implementado.
  5. As Recipes não tratam as anotações bem conhecidas do fornecedor. O fornecedor aplica automaticamente o contexto de posicionamento (namespace, prefixo de registo, service account) depois de a Recipe produzir o seu conteúdo.
  6. O prefixo aggrega.ai/ está reservado à biblioteca padrão. As anotações empresariais personalizadas usam o seu próprio prefixo.
  7. As anotações ao nível de Component na Release substituem as anotações ao nível da fronteira (fusão profunda, prevalece o componente). Onde um fornecedor monta a saída de várias fronteiras num único artefacto, pode exigir que uma anotação se resolva de forma uniforme entre elas — o fornecedor helm-chart obtém o nome do chart guarda-chuva a partir de aggrega.ai/chart-name e, quando mais do que uma fronteira contribui para o mesmo chart e resolvem essa anotação para valores diferentes, a compilação é interrompida nomeando as fronteiras em desacordo, porque um chart não pode ter dois nomes.
  8. As anotações que o Aggregate declara alcançam as mesmas chaves abaixo das da Release. Uma chave declarada num subsistema ou numa instância de componente — no próprio Aggregate, ou num módulo que este importa, onde alcança os componentes próprios do módulo — aplica-se ao componente sempre que a Release não define nenhum valor para essa chave; onde a Release define um, na fronteira ou na entrada do componente, o valor aplicado é o da Release. As anotações próprias de uma entidade do catálogo nunca definem nenhum. aggrega.ai/chart-name é a exceção ao alcance do Aggregate: nomeia uma montagem em vez de um componente, e é lida a partir das fronteiras da Release que contribuem para ela.

A matriz completa de anotações

Como ler esta matriz

As seis tabelas por categoria abaixo nomeiam cada anotação do vocabulário reservado aggrega.ai/, o que controla e o que o fornecedor faz quando está ausente. Saber se um dado fornecedor aplica uma dada chave é uma questão mais fina, porque um fornecedor renderiza mais do que um tipo de entrada — um artefacto copiado localmente (sourced), um Workload que o próprio fornecedor sintetiza (synthesized) ou os artifacts: de uma Recipe como a saída inteira de um nó (artifacts-only) — e uma chave pode ser lida num desses caminhos sendo inalcançável noutro. Que fornecedor renderiza que tipo de entrada está em ../../architecture/16-recipe-input-composition.md; o que cada um aplica é Suporte por fornecedor e tipo de entrada abaixo, que é a declaração de referência desta página.

Cada célula dessa grelha tem um de três níveis:

  • Aplicada — o fornecedor aplica a chave neste tipo de entrada, e a saída renderizada muda de forma determinística em resultado disso.
  • Aplicada condicionalmente — o compilador emite uma substituição aditiva ao lado do artefacto de destino em vez de editar o artefacto, pelo que o valor produzir efeito depende de esse artefacto expor uma chave correspondente própria. Eficaz na prática, nunca uma garantia. Nenhum fornecedor implementa uma célula condicional, e a superfície de declaração não oferece forma de exprimir uma, pelo que a grelha gerada abaixo emite apenas os outros dois níveis. O nível é nomeado porque a via existe de facto para um artefacto copiado localmente, e um vocabulário de dois níveis obrigaria a matriz a reivindicar uma garantia que não pode dar ou a negar que a via sequer exista.
  • Não aplicada — nenhum fornecedor aplica a chave neste caminho: o destino não tem aí nenhum slot de renderização para ela, pelo que o mecanismo de posicionamento não contribui em nada para o que é renderizado, e a coluna Predefinição da tabela da categoria indica o que se obtém em alternativa. O valor continua a passar pela compilação como uma cadeia de caracteres opaca, intacto. O nível tem o nome do mecanismo e não do que acontece ao valor, porque são perguntas diferentes e só a primeira é uma a que uma célula consegue responder: o que um fornecedor aplica é uma propriedade dos slots de renderização desse destino, que é exatamente o que a declaração por detrás de cada célula afirma.

Dois âmbitos, e só um deles faz do tipo de entrada um eixo significativo:

  • Com âmbito de nó — aggrega.ai/namespace, aggrega.ai/image-registry, aggrega.ai/image-pull-secret, aggrega.ai/service-account e aggrega.ai/kubernetes-version moldam a saída renderizada própria de um componente, produzida pelo caminho que o seu tipo de entrada seleciona. Estas são as colunas da grelha.
  • Com âmbito de montagem e de referência — aggrega.ai/chart-name é resolvida uma única vez quando um chart guarda-chuva é montado, e as três chaves aggrega.ai/aws-* são resolvidas quando uma referência atravessa uma fronteira. O tipo de entrada não é um eixo para nenhuma das duas: o valor é lido na montagem ou na referência, independentemente de como cada nó contribuinte foi renderizado. Têm uma tabela própria em Chaves resolvidas por montagem e por referência.

Categoria 1 — Posicionamento

AnotaçãoAplicada porFinalidadePredefinição
aggrega.ai/namespacehelm (com fonte, sintetizado); compose (com fonte, sintetizado)Namespace do Kubernetes (helm); nome da rede do Docker (compose)Não é injetado se estiver ausente (helm); uma rede com o nome do caminho do ficheiro compose, partilhada por todos os nós desse ficheiro sem a anotação (compose)
aggrega.ai/project-namereservada; nenhum fornecedor a lêReservada a um nome de projeto do Docker Compose—
aggrega.ai/regionreservada; nenhum fornecedor a lêReservada a uma região de nuvem no âmbito do posicionamento—
aggrega.ai/account-idreservada; nenhum fornecedor a lêReservada a um identificador de conta de nuvem no âmbito do posicionamento—
aggrega.ai/kubernetes-versionhelm (com fonte)Versão do Kubernetes do cluster em que o componente é implementado, que um chart renderizado a partir da fonte lê como .Capabilities.KubeVersionA versão para a qual renderiza o helm template padrão da mesma release do helm: a da biblioteca cliente do Kubernetes com que o fornecedor é construído

aggrega.ai/namespace tem duplo propósito por conceção. Exprime a mesma intenção de isolamento lógico — «os recursos desta fronteira vivem no seu próprio âmbito endereçável» — na forma nativa de cada destino: um metadata.namespace do Kubernetes para o helm, um nome de rede do Docker para o compose. Os autores de Recipe definem uma única anotação; cada fornecedor materializa-a de forma adequada ao destino. No caso do compose, o nome da rede é resolvido por nó a partir da anotação desse nó, recorrendo ao caminho do ficheiro compose onde o nó não tem nenhuma anotação — de modo que fronteiras sem anotação que partilham um ficheiro compose partilham uma rede, e é aggrega.ai/namespace que as separa. Seja qual for dos dois a fornecer a identidade, esta é depois escrita nos caracteres que um nome de rede do compose aceita — qualquer outro carácter é escrito como sequência de escape em vez de ser substituído, pelo que duas identidades que difiram em alguma coisa ficam em duas redes, e as maiúsculas e minúsculas da identidade são mantidas tal como foram escritas. A referência do fornecedor compose documenta a derivação por inteiro, incluindo como ler um nome codificado e quanto custa uma mudança de nome.

aggrega.ai/kubernetes-version indica uma propriedade do cluster em que um componente é implementado, e não onde dentro dele o componente vai parar: os templates de chart escolhem uma versão de API, um campo ou um mecanismo inteiro pela versão para a qual são renderizados, e a compilação não tem nenhum cluster a quem perguntar. O fornecedor helm lê o valor da mesma forma que helm template --kube-version lê a sua flag e interrompe a compilação perante um valor que não seja uma versão; onde nenhuma é indicada, um chart é renderizado para a versão para a qual renderiza helm template da mesma release do helm. A referência do fornecedor helm documenta as formas aceites e o valor predefinido.

Categoria 2 — Registo

AnotaçãoAplicada porFinalidadePredefinição
aggrega.ai/image-registryhelm, compose — apenas sintetizadoPrefixo de registo para imagens de contentor, aplicado a cada referência a imagem de contentor sintetizadaNenhum prefixo
aggrega.ai/image-pull-secrethelm — apenas sintetizadoNome de imagePullSecrets do Kubernetes, unido às entradas existentes do pod sintetizadoNenhum

Categoria 3 — Rede

AnotaçãoAplicada porFinalidadePredefinição
aggrega.ai/cluster-domainreservada; nenhum fornecedor a lêReservada a um sufixo DNS para a descoberta de serviços entre namespaces—
aggrega.ai/ingress-classreservada; nenhum fornecedor a lêReservada a uma IngressClass do Kubernetes em recursos Ingress—
aggrega.ai/service-meshreservada; nenhum fornecedor a lêReservada a anotações de injeção de sidecar da malha—

Categoria 4 — Segurança

AnotaçãoAplicada porFinalidadePredefinição
aggrega.ai/service-accounthelm — apenas sintetizadoServiceAccount do Kubernetes para Pods sintetizados; substitui o workload.serviceAccount da Recipe quando ambos estão definidosO workload.serviceAccount da Recipe, ou não definido quando a Recipe não declara nenhum
aggrega.ai/pod-security-standardreservada; nenhum fornecedor a lêReservada a um nível dos Pod Security Standards—
aggrega.ai/iam-rolereservada; nenhum fornecedor a lêReservada a um papel de identidade de nuvem associado a uma carga de trabalho—

Categoria 5 — Empacotamento

AnotaçãoAplicada porFinalidadePredefinição
aggrega.ai/chart-namehelm-chart — por montagemNome do chart guarda-chuvaNome do Aggregate e caminho de montagem do guarda-chuva, unidos — ver Resolução do nome do chart
aggrega.ai/chart-versionreservada; nenhum fornecedor a lêReservada a uma versão de chart do Helm—
aggrega.ai/stack-namereservada; nenhum fornecedor a lêReservada a uma stack com nome explícito—
aggrega.ai/tf-backendreservada; nenhum fornecedor a lêReservada a um identificador de backend de estado do Terraform—

Categoria 6 — Destino de nuvem

AnotaçãoAplicada porFinalidadePredefinição
aggrega.ai/aws-accountcloudformation — por referência entre fronteirasConta da AWS em que a stack (fronteira) é implementadaMesma conta — uma referência entre stacks resolve-se através da importação de uma exportação de stack da mesma conta
aggrega.ai/aws-regioncloudformation — por referência entre fronteirasRegião da AWS em que a stack (fronteira) é implementadaMesma região — uma referência entre stacks resolve-se através da importação de uma exportação de stack da mesma região
aggrega.ai/aws-assume-role-arncloudformation — por referência entre fronteirasARN do papel do IAM que uma leitura de stack entre contas assume para alcançar os valores exportados de uma stack homólogaNão é fornecido nenhum papel numa referência entre contas

Cada fronteira do CloudFormation é renderizada numa única stack. Quando uma aresta uses passa de uma fronteira para outra, o fornecedor cloudformation precisa de saber onde se encontra a stack homóloga para moldar a referência: duas stacks na mesma conta e região trocam valores através de uma exportação e importação de stack; uma homóloga noutra conta ou região precisa de uma leitura de saídas de stack entre contas, opcionalmente sob um papel assumido. Estas anotações transportam esse contexto de posicionamento. Cada uma é lida no momento em que o fornecedor molda essa referência, e resolvida nesse momento através da cascata habitual de anotações — um valor definido no componente prevalece sobre um valor definido na fronteira, e um valor que a Release define prevalece sobre um que o Aggregate declara. Um valor ao nível da fronteira é, por isso, a forma comum de as exprimir, não a única. São cadeias de caracteres de ponteiro escalares opacas — o fornecedor encaminha-as para a referência que constrói e nunca as resolve face ao estado real da AWS; a conta, a região e o papel são fornecidos pela Release ou declarados no Aggregate, e o ambiente de execução resolve a leitura física final. Quando todas as anotações estão ausentes, o fornecedor trata a homóloga como estando na mesma conta e na mesma região e não fornece nenhum papel.

Suporte por fornecedor e tipo de entrada

As chaves com âmbito de nó, por fornecedor e por tipo de entrada. Os cabeçalhos das colunas omitem o prefixo aggrega.ai/ que todas as chaves têm. applied e — têm os níveis definidos acima, sendo — não aplicada; n/a significa que o fornecedor não renderiza de todo esse tipo de entrada, pelo que não existe aí nenhum caminho em que a chave possa ser aplicada ou deixar de o ser.

ProviderTipo de entradanamespaceimage-registryimage-pull-secretservice-accountkubernetes-version
helmsourcedapplied———applied
helmsynthesizedappliedappliedappliedapplied—
helmartifacts-only—————
composesourcedapplied————
composesynthesizedappliedapplied———
composeartifacts-only—————
helm-chartsourced—————
helm-chartsynthesizedn/an/an/an/an/a
helm-chartartifacts-onlyn/an/an/an/an/a
terraformsourced—————
terraformsynthesizedn/an/an/an/an/a
terraformartifacts-only—————
cloudformationsourced—————
cloudformationsynthesizedn/an/an/an/an/a
cloudformationartifacts-only—————

Cada fornecedor distribuído com o compilador tem aqui linhas, incluindo um que não lê nenhuma anotação de posicionamento — um conjunto de linhas vazio seria indistinguível de um fornecedor que ninguém descreveu ainda. Um fornecedor disponibilizado separadamente declara o que lê da mesma forma e não é listado aqui, porque uma página publicada não pode enumerar fornecedores que nunca viu.

Uma Recipe pode declarar mais do que um tipo de entrada ao mesmo tempo — um workload: com artifacts: ao lado, por exemplo. Convém ler a grelha por tipo: a saída sintetizada de um nó desses é a linha synthesized, e os seus ficheiros de artefactos são o caso dos artefactos. A linha artifacts-only é o tipo de entrada em que uma Recipe declara artifacts: e mais nada.

Não é preciso consultar a grelha para o descobrir. Definir uma chave que o destino de uma das suas renderizações não lê em nenhum dos tipos de entrada dessa renderização produz um aviso que nomeia a chave, o destino e cada tipo de entrada que essa renderização declara, pelo que uma célula em que se caiu por acidente se anuncia no momento da compilação, em vez de esperar que alguém se lembre de procurar aqui:

warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it

Numa renderização que declara mais do que um tipo de entrada, o aviso diz respeito a essa renderização no seu todo, não a uma das suas metades. Como os tipos se compõem por adição, um destino que lê a chave em qualquer um deles aplica-a de facto, e a saída dessa renderização tem o resultado — pelo que não é emitido nenhum aviso. Um aviso só aparece quando nenhum dos tipos que essa renderização declara aplica a chave, e nomeia-os a todos:

warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored it

Assim, um workload: ao lado de um source: basta para que aggrega.ai/service-account produza efeito nesse nó, e a compilação não diz nada sobre isso — o que é o relato honesto, porque o valor chega à metade sintetizada e aparece nos manifestos emitidos.

Convém ler a grelha por renderização, não por componente. Uma funcionalidade anexada a um nó gera os seus recursos através do destino que a sua própria FeatureRecipe nomeia, nos tipos de entrada que essa FeatureRecipe declara — pelo que vai parar à sua própria linha desta grelha, que não tem de ser a linha em que vai parar o seu componente anfitrião. Um componente que sintetiza o seu Workload enquanto uma funcionalidade anexada contribui com artifacts: ao lado lê a linha synthesized para os manifestos próprios do componente e a linha artifacts-only para os ficheiros do anexo, e uma chave aplicada na primeira pode não ser aplicada na segunda. O aviso segue a mesma divisão e informa sobre cada uma separadamente, porque são ficheiros diferentes. Uma funcionalidade anexada a uma fronteira em vez de a um componente com nome lê a grelha da mesma forma.

O valor continua a passar intacto — a compilação não é interrompida, porque uma fronteira que abrange componentes em destinos heterogéneos terá sempre alguma renderização que não consegue atuar sobre uma dada chave, e isso é uma Release normal e não um erro. Uma anotação de fronteira propaga-se em cascata, pelo que uma linha escrita gera um aviso por cada renderização que não consegue atuar sobre ela, e é assim que se vê que partes da saída são afetadas. Pertence à classe unsupported-field e é silenciado com a opção dessa classe; Avisos tem os pormenores. Dois limites que convém conhecer: só são verificadas as chaves com o prefixo aggrega.ai/ simples, já que uma chave com subprefixo é vocabulário próprio de quem a escreve, e um fornecedor que não declara nenhuma afirmação de suporte não produz nenhum aviso, porque não há nada com que comparar o que foi escrito. Um fornecedor que declara não ler nenhuma destas chaves não fica em silêncio dessa forma: readsNoWellKnownAnnotations: true na sua entidade Plugin é uma afirmação que não cobre nenhuma chave, pelo que cada chave com prefixo simples que chegue a uma das suas renderizações gera o aviso. O fornecedor terraform declara-o.

Porque é que um artefacto copiado localmente aplica menos chaves. Uma anotação com âmbito de nó é aplicada onde o fornecedor tem um slot de renderização para ela. Quando o fornecedor sintetiza ele próprio a unidade de implementação, é dono de cada campo do resultado, pelo que um prefixo de registo, um pull secret e uma service account têm todos onde ficar. Um artefacto copiado localmente — um chart do Helm, um ficheiro compose, um módulo do Terraform — tem antes a sua própria interface de configuração, e o compilador não lê essa interface, pelo que não pode saber a qual das chaves próprias do artefacto corresponderia um prefixo de registo ou uma service account. O posicionamento que a chamada de renderização envolvente controla continua a aplicar-se, e é por isso que aggrega.ai/namespace é aplicado a um chart renderizado a partir da fonte. O posicionamento que significaria decidir onde, dentro do artefacto de outra pessoa, um valor pertence não se aplica, e um autor fornece-o através dos valores próprios desse artefacto. É por isso que as linhas com fonte são esparsas onde as linhas sintetizadas estão completas, e é a forma a esperar de qualquer chave acrescentada mais tarde.

Chaves resolvidas por montagem e por referência

Quatro das chaves incluídas não têm âmbito de nó, pelo que ficam fora da grelha acima em vez de serem integradas nela: o tipo de entrada não é um eixo significativo para elas, e dar a cada uma uma linha por tipo de entrada repetiria uma única célula três vezes e sugeriria uma distinção que não existe. Cada uma declara o âmbito de fronteira, e a tabela abaixo é gerada a partir dessas declarações.

AnotaçãoAplicada porFinalidadePredefinição
aggrega.ai/chart-namehelm-chartNome do chart guarda-chuva do Helm montado.São usados o nome do Aggregate e o caminho de montagem do guarda-chuva — o seu diretório de saída em dist/, como boundaries/data/helm-chart —, cada um codificado, e unidos.
aggrega.ai/aws-accountcloudformationA conta da AWS em que a stack (fronteira) é implementada. Uma referência entre fronteiras lê-a para decidir se uma stack homóloga está na mesma conta.A homóloga é tratada como estando na mesma conta, e uma referência entre stacks resolve-se através da importação de uma exportação de stack da mesma conta em vez de uma leitura de saídas de stack entre contas.
aggrega.ai/aws-regioncloudformationA região da AWS em que a stack (fronteira) é implementada. Uma referência entre fronteiras lê-a para decidir se uma stack homóloga está na mesma região.A homóloga é tratada como estando na mesma região, e uma referência entre stacks resolve-se através da importação de uma exportação de stack da mesma região.
aggrega.ai/aws-assume-role-arncloudformationO ARN do papel do IAM que uma leitura de stack entre contas assume para alcançar os valores exportados de uma stack homóloga.Não é fornecido nenhum papel, e uma referência entre contas não tem nenhum assume-role.

Quando cada uma é resolvida, algo que a própria declaração não indica. aggrega.ai/chart-name é resolvida uma única vez por montagem de chart guarda-chuva, a partir da cascata de anotações da fronteira; cada contribuinte para uma mesma montagem tem de a resolver para o mesmo valor, e uma divergência interrompe a compilação nomeando as fronteiras. As três chaves aggrega.ai/aws-* são resolvidas por referência entre fronteiras com precedência do componente sobre a fronteira, pelo que um valor do componente prevalece sobre um valor da fronteira; a Categoria 6 acima descreve a referência que cada uma molda.

Nomes reservados que nenhum fornecedor lê

Onze chaves da matriz acima estão marcadas como reservada; nenhum fornecedor a lê: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name e aggrega.ai/tf-backend.

Definir uma delas numa Release ou num Aggregate não tem nenhum efeito na saída renderizada. Nenhum fornecedor as lê, e nenhum valor predefinido é aplicado em seu lugar — em particular, não é aplicado nenhum sufixo DNS para aggrega.ai/cluster-domain, pelo que uma Recipe que precise de um domínio de cluster tem de o fornecer como um valor normal em vez de depender desta anotação. Um autor de Recipe que precise de um destes comportamentos exprime-o como um valor da Recipe ou um campo infra do componente.

Nenhum fornecedor declara estas onze. O wellKnownAnnotations de um fornecedor lista apenas o que lê, pelo que nenhuma das onze aparece aí — quem abre o Plugin helm, helm-chart, compose ou cloudformation vê as chaves que funcionam e mais nada. Esse é o objetivo da declaração estreita: uma chave declarada é uma chave que funciona, e o âmbito ao lado dela diz em que caminho.

Dois dos nomes reservados estão próximos de chaves ativas e não são intercambiáveis com elas. aggrega.ai/region e aggrega.ai/account-id nomeiam uma região e uma conta no âmbito do posicionamento e não chegam a nenhum fornecedor; as chaves que o fornecedor cloudformation lê são aggrega.ai/aws-region e aggrega.ai/aws-account, no namespace da nuvem, na Categoria 6. Quando se pretende o contexto de posicionamento entre stacks do CloudFormation, convém escrever a forma aws- — o par sem prefixo está reservado contra colisões, e não ligado a nada. Outros dois nomes reservados são cobertos por outras superfícies em vez de por uma anotação: aggrega.ai/stack-name está reservado, enquanto o nome da stack em que uma fronteira cloudformation é renderizada é derivado de forma determinística da identidade da release e da fronteira; e o papel de identidade de nuvem de uma carga de trabalho é fornecido como um campo normal definido pelo operador na Feature que emite a associação, e não através de aggrega.ai/iam-role.

Os nomes continuam reservados, e continuam listados aqui, porque o prefixo aggrega.ai/ está reservado: um catálogo empresarial não deve reutilizar uma destas chaves com um significado próprio, porque a plataforma detém a chave para um significado seu. Esta matriz e o conjunto de prefixos reservados que o lint de publicação verifica constituem em conjunto o registo de reservas, e os dois são mantidos no mesmo conjunto de nomes por uma verificação que lê ambos e falha quando divergem. Escrever uma das onze, por isso, nem faz falhar a validação nem aciona a regra «não usar o prefixo aggrega.ai/ simples» — simplesmente não tem efeito.

A versão do chart guarda-chuva que uma fronteira helm-chart emite é sempre 0.1.0; é um valor fixo e não um valor predefinido de aggrega.ai/chart-version.

Nota: as associações features.annotations do Manifest que usam o prefixo aggrega.ai/ são rejeitadas no carregamento; o prefixo está reservado exclusivamente para as anotações bem conhecidas de fornecedor documentadas neste capítulo. Os autores de associações de Feature orientadas por anotações usam feature.aggrega.ai/ para atalhos da biblioteca padrão ou um domínio personalizado para atalhos empresariais.

Nota: um null explícito numa anotação da Release remove a associação herdada da fronteira ou do componente que a substitui (desativação de Feature orientada por anotações). Os componentes irmãos na mesma fronteira que não se desativaram mantêm a associação herdada; as chaves ausentes continuam a herdar da cascata ascendente como habitualmente.

Anotações escritas no catálogo que o compilador lê

Tudo o que precede é uma anotação de fornecedor: escrita na Release ou declarada no Aggregate, passada pelo compilador como uma cadeia de caracteres opaca, lida por um fornecedor. Um segundo vocabulário, muito mais pequeno, funciona no sentido inverso — escrito pelo Arquiteto nos metadata.annotations próprios de uma entidade do catálogo, lido pelo compilador e nunca visto por um fornecedor. O invariante 1 acima diz respeito ao vocabulário de fornecedor e não se estende a estas; o compilador lê exatamente as chaves listadas aqui e nenhuma outra.

Estas chaves ficam sob um subprefixo <scope>.aggrega.ai/, e não sob o prefixo aggrega.ai/ simples, pelo que estão fora do registo de reservas que a matriz acima contém e fora da regra de prefixos reservados que o lint de publicação aplica às chaves de prefixo simples.

AnotaçãoEscrita emLida porFinalidade
features.aggrega.ai/requiredType.<label>metadata.annotations do Componento compilador, sobre o grafo finalizadoDeclara um mandato de presença: cada instância deste Component tem de ter pelo menos um anexo cujo tipo seja igual ao valor da anotação. <label> é um sufixo escolhido pelo autor que nomeia o requisito no diagnóstico; não é um nome de slot e nada o desreferencia. Convém repetir a chave com etiquetas diferentes para declarar vários mandatos.

O mandato é satisfeito por um anexo em qualquer âmbito — um bloco features: ao nível do componente ou do subsistema, um bloco da Release ao nível da fronteira ou do componente, ou uma expansão orientada por anotações — porque testa o conjunto final de anexos da instância em vez da origem de cada anexo. Um mandato não satisfeito interrompe a compilação nomeando a etiqueta e o tipo exigido; um valor que não seja um URI de tipo de Feature, ou uma chave sem etiqueta depois do prefixo, é interrompido com um diagnóstico distinto de declaração malformada. O tratamento completo da escrita, e a forma como um mandato difere de um slot featuresSchema, encontram-se em entities/component.md «Mandatos de presença».

Etiquetas de proveniência emitidas pelos fornecedores

As anotações acima fluem para dentro da compilação — a Release ou o Aggregate escreve-as, os fornecedores consomem-nas. Os Providers emitem também um conjunto paralelo de etiquetas para fora da compilação, anexando-as à saída renderizada para que as ferramentas a jusante possam atribuir os recursos em tempo de execução ao conteúdo do catálogo que os produziu. Estas etiquetas de proveniência não são escritas na Release; são derivadas do próprio estado da compilação (identidade da Recipe, caminho da fronteira, nome do agregado, ambiente, sync wave, versão do compilador) e emitidas pelo fornecedor no momento da renderização.

O conjunto que os fornecedores emitem, anexado a cada manifesto do Kubernetes que o fornecedor helm renderiza, a cada artefacto carregado através de $import: que o fornecedor helm-chart acrescenta a um subchart e a cada serviço emitido pelo compose — os templates próprios de um subchart do helm-chart são copiados tal como o seu autor os escreveu, pelo que têm o que quer que esse autor tenha escrito:

EtiquetaOrigemEmissão
app.kubernetes.io/nameID do nó (ou, para um recurso que uma FeatureRecipe emite, o identificador derivado para esse anexo — ver abaixo)Apenas helm e helm-chart — etiqueta padrão do Kubernetes, não emitida nos serviços do compose
aggrega.ai/component-idID do nó (ou, para um recurso que uma FeatureRecipe emite, o identificador derivado para esse anexo — ver abaixo)Os três fornecedores
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> da Recipe produtora (ou da FeatureRecipe produtora para recursos emitidos por uma FR)Os três fornecedores, quando a entidade produtora tem definidos tanto o nome como a versão; uma anotação no helm e no helm-chart
aggrega.ai/boundary-pathCaminho da fronteira para o qual o componente foi encaminhadoOs três fornecedores, quando o caminho da fronteira não está vazio; uma anotação no helm e no helm-chart
aggrega.ai/aggregate-namemetadata.name do AggregateOs três fornecedores, quando definido
aggrega.ai/compiler-versionVersão do compilador carimbada no momento da compilaçãoOs três fornecedores, quando definido
aggrega.ai/providerO fornecedor que renderizou o recursoOs três fornecedores
aggrega.ai/provider-versionA versão desse fornecedorOs três fornecedores
aggrega.ai/environmentmetadata.environment da ReleaseOs três fornecedores — cada Release declara-o
aggrega.ai/sync-waveInteiro syncWave por fronteiraOs três fornecedores, quando diferente de zero; uma anotação no helm e no helm-chart

Os valores de aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider e aggrega.ai/provider-version provêm de cadeias que a compilação não sujeita às regras do Kubernetes para valores de etiqueta — um Aggregate chamado imported/flow, um ambiente chamado eu/prod, a versão (devel) de uma compilação de desenvolvimento. No helm e no helm-chart, cada uma destas etiquetas contém o seu valor tal como está escrito quando o valor 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. Caso contrário, a etiqueta contém o valor reescrito nessa forma — qualquer outro carácter passa a -, as sequências de - reduzem-se a um só, as extremidades são aparadas até uma letra ou um dígito e o resultado é cortado para no máximo 63 caracteres — e o valor literal é acrescentado como anotação sob a mesma chave. Um Aggregate chamado imported/flow recebe, portanto, a etiqueta aggrega.ai/aggregate-name: imported-flow e a anotação aggrega.ai/aggregate-name: imported/flow; um valor sem nenhum carácter que uma etiqueta mantenha é transportado apenas pela anotação. Um seletor compara o valor da etiqueta tal como aparece no resultado renderizado, e as ferramentas que precisam do nome exato leem a anotação quando existe. O Compose, cujos valores de etiqueta não têm restrições, contém o valor literal como etiqueta.

Notas de emissão por fornecedor

  • helm — as etiquetas vão para metadata.labels em cada recurso do Kubernetes renderizado (Deployment, Service, PVC, etc.), e as chaves que o valor de uma etiqueta não pode conter — aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave e o valor literal de qualquer etiqueta reescrita como descrito acima — para metadata.annotations. Os caminhos do modo com fonte (renderização através do SDK do Helm com injeção de etiquetas pós-renderização), do modo sintetizado (síntese da carga de trabalho) e de artifacts: produzem o mesmo conjunto.
  • helm-chart — as mesmas etiquetas e anotações vão para cada artefacto carregado através de $import: que o fornecedor acrescenta aos templates/ de um subchart. Os templates próprios do chart de origem, e um artefacto de conteúdo inline colocado na raiz do subchart, não têm nenhuma delas — ver helm-chart.md.
  • compose — as etiquetas vão para services.<name>.labels em cada serviço do compose emitido. O modo com fonte (injeção de etiquetas após a fusão no documento fundido de base + valuesMapping) e o modo sintetizado (síntese da carga de trabalho que define diretamente o bloco de etiquetas do serviço) produzem ambos o mesmo conjunto. A etiqueta app.kubernetes.io/name, específica do Kubernetes, é omitida da saída do compose.

Para os recursos que uma FeatureRecipe emite, o valor de 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, pelo que os recursos de um anexo nunca são indistinguíveis por etiqueta dos recursos do próprio componente anfitrião. Saber se essa identidade é também aquilo a partir do qual esses recursos recebem o nome depende da entrega: uma carga de trabalho que o Aggrega sintetiza recebe o nome da identidade, enquanto um chart ou fragmento fornecido pelo autor do anexo mantém o nome da release do Helm e o prefixo do ficheiro de saída do componente anfitrião, porque os templates próprios do autor são renderizados com esse nome. A forma como o valor é composto — os dois inícios possíveis, as partes e a sua junção com --, como um carácter que uma etiqueta não pode conter é escrito por extenso, como um valor demasiado longo para o seu destino é encurtado, e de que nomes é e não é a base — não depende do fornecedor, pelo que é indicada uma única vez em vocabulary/labels-and-annotations.md «Etiquetas de proveniência emitidas na saída renderizada» em vez de ser repetida aqui. Esta página ocupa-se da outra metade: onde as etiquetas vão parar na saída renderizada de cada fornecedor.

A chave aggrega.ai/recipe-uri resolve-se para o name:version próprio da FeatureRecipe, e não para a identidade da Recipe consumidora — as ferramentas a jusante que leem a etiqueta 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.

Anotações sync-wave

A chave aggrega.ai/sync-wave acima está emparelhada com uma anotação sync-wave que as ferramentas a jusante leem para ordenar o que aplicam. No compose, a chave é uma etiqueta, que expõe o valor da wave a consultas por seletor; no helm e no helm-chart, é uma anotação, e a anotação emparelhada expõe o valor onde cada ferramenta o lê por convenção.

AnotaçãoEmissãoConsumida por
argocd.argoproj.io/sync-wavehelm, em cada recurso do Kubernetes que renderiza, e helm-chart, em cada artefacto carregado através de $import: — onde syncWave é diferente de zero na fronteira contribuinteOrdenação sync-wave do ArgoCD
helm.sh/hook-weightApenas helm, em manifestos gerados pelos templates do chart que já têm uma anotação helm.sh/hook quando syncWave é diferente de zeroOrdenação por hook-weight do Helm dentro de uma fase de hook

A emissão de helm.sh/hook-weight depende do caminho

Uma subtileza que vale a pena assinalar aos autores de charts: helm.sh/hook-weight só é emitida em manifestos renderizados pelo caminho de templating do chart — o diretório templates/ do chart renderizado através do SDK do Helm. Os Manifests produzidos pelo caminho dos artefactos — no fornecedor helm, cada entrada do bloco artifacts: da Recipe, de conteúdo inline ou carregada através de $import:, e no helm-chart uma entrada carregada através de $import: — têm a anotação argocd.argoproj.io/sync-wave e o conjunto completo de etiquetas de proveniência, mas não recebem helm.sh/hook-weight — mesmo quando o artefacto tem uma anotação helm.sh/hook.

A distinção é estrutural: helm.sh/hook e helm.sh/hook-weight são primitivas de ordenação do runtime do Helm que se aplicam aos recursos de hook gerados pelos templates do chart. Os artefactos do autor da Recipe são recursos adicionais declarados na camada da Recipe; por predefinição, não participam no ciclo de vida dos hooks do Helm.

Quando for necessária a ordenação por hook-weight do Helm num recurso de hook, convém escrever o recurso como template de chart sob o diretório source: de uma Recipe que o fornecedor helm renderiza, em vez de como entrada de artifacts:; os templates de um subchart do helm-chart são copiados tal como foram escritos e não recebem nenhuma das duas anotações. O template do chart receberá tanto argocd.argoproj.io/sync-wave como helm.sh/hook-weight, correspondentes ao valor syncWave da fronteira contribuinte.

Exemplos de autoria

Posicionamento e configuração do registo ao nível da fronteira:

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
aggrega.ai/image-registry: registry.corp.com
aggrega.ai/image-pull-secret: corp-registry-creds
components:
api: {}
worker: {}

Substituição por componente (o componente prevalece sobre a fronteira na mesma chave de anotação):

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
components:
api: {}
legacy-thing:
annotations:
aggrega.ai/namespace: legacy-east # override — this component deploys elsewhere

Cascata de anotações do lado do Aggregate

As anotações encontram-se também na superfície de autoria do Aggregate — no âmbito do subsistema (spec.subsystems.<name>.annotations) e no âmbito da instância de componente (spec.subsystems.<name>.components.<name>.annotations ou spec.components.<name>.annotations para componentes de nível superior). A cascata do lado do Aggregate leva as anotações escritas pelo programador ao longo da árvore de subsistemas até aos componentes contidos.

A regra da cascata

Uma anotação ao nível do subsistema propaga-se a cada subsistema aninhado e a cada componente contido na subárvore do subsistema. As anotações de um nível mais próximo substituem as de um nível mais exterior com granularidade por chave: uma anotação ao nível do componente substitui qualquer anotação herdada ao nível do subsistema para a mesma chave, sem afetar as chaves irmãs nem os componentes irmãos.

Uma chave de anotação num âmbito encontra-se num de três estados:

  • Chave ausente — o âmbito não declara nenhum valor para esta anotação. Os subsistemas aninhados e os componentes contidos herdam qualquer associação de um âmbito antecessor.
  • Um valor de cadeia de caracteres — o âmbito declara um valor. Os subsistemas aninhados e os componentes contidos herdam esse valor, a menos que declarem um valor próprio ou renunciem a ele.
  • null YAML explícito — o âmbito remove da sua subárvore qualquer associação herdada para esta chave. Os componentes irmãos e os subsistemas irmãos mantêm a sua herança independente; apenas a subárvore do âmbito que renuncia perde a associação.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # propagates to api and worker
components:
api:
# inherits feature.myco/db-pool: "shared-pool"
worker:
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Anotações dos Provider declaradas no Aggregate

As chaves da matriz acima também descem em cascata através do Aggregate, e um fornecedor aplica o que a cascata deixa em cada componente. O aggrega.ai/namespace de um subsistema posiciona cada componente abaixo dele; o valor próprio de uma instância de componente posiciona, em vez disso, esse componente. Um módulo que o Aggregate importa tem a sua própria cascata: os seus subsistemas e instâncias de componente alcançam os componentes próprios do módulo, e nada do que o Aggregate importador declara chega ao interior de um módulo.

A Release está acima do Aggregate em todas as chaves. Onde a Release define uma chave para um componente — na sua fronteira ou na entrada própria do componente —, é aplicado o valor da Release; onde não define nenhum, o do Aggregate. Os dois lados sobrepõem-se chave a chave, pelo que uma Release que define apenas aggrega.ai/namespace deixa em vigor um aggrega.ai/image-registry que o Aggregate declarou.

Um null explícito na Release retira apenas o valor próprio da Release. Uma entrada de componente que escreve aggrega.ai/namespace: null remove o namespace que a fronteira da sua Release lhe teria atribuído, e o componente passa então a ter o valor que o seu Aggregate declara — ou nenhum, onde o Aggregate também não declara nenhum. Uma Release não pode remover um valor que o Aggregate declara; só pode definir um próprio por cima dele.

# Aggregate
spec:
subsystems:
billing:
annotations:
aggrega.ai/namespace: billing # api and worker render into billing
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0
annotations:
aggrega.ai/namespace: billing-batch # worker renders into billing-batch
# Release
spec:
boundaries:
production:
components:
api:
annotations:
aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing
worker: {}

aggrega.ai/chart-name é a única chave fora deste alcance: nomeia um chart guarda-chuva montado a partir de vários componentes, pelo que é lida a partir das fronteiras da Release que contribuem para esse chart, nunca a partir das anotações de um componente.

Um template de Recipe ou de FeatureRecipe lê os compartimentos de anotações pelo nome — .context.annotations.aggregate, .context.annotations.release e .context.annotations.catalog contêm cada um o que esse lado escreveu —, pelo que um template que lê uma chave de posicionamento de um compartimento vê apenas o valor desse lado.

A partição entre lado e pilar

A invariante do Aggregate como superfície de autoria restringe as anotações do lado do Aggregate ao pilar de valores. Uma associação de anotação de um Manifest declara caminhos de encaminhamento sob maps.infra (encaminhamento do lado da Release) ou sob maps.values (encaminhamento do lado do Aggregate); uma anotação do lado do Aggregate cuja associação declara apenas caminhos sob maps.infra interrompe a compilação com um diagnóstico claro que indica a chave da anotação, o pilar encaminhado e o lado de autoria. A regra simétrica aplica-se ao lado da Release: as anotações do lado da Release só podem ser encaminhadas através de maps.infra; uma anotação do lado da Release contra uma associação apenas de valores desencadeia o erro paralelo. Cada diagnóstico é classificado no domínio do documento em que o valor da anotação foi escrito — [DEVELOPER_ERROR] a partir de um Aggregate, [OPS_ERROR] a partir de uma Release —, pelo que o cabeçalho indica a superfície a abrir.

As associações que declaram caminhos nos dois pilares encaminham, em cada passagem, o subconjunto compatível com o lado: uma anotação do lado do Aggregate aciona apenas os caminhos do pilar de valores, e uma anotação do lado da Release aciona apenas os caminhos do pilar infra. A composição entre lados — values a partir do Aggregate, infra a partir da Release — produz um anexo de Feature por par (Component, Feature) com os dois pilares preenchidos e uma proveniência por folha que regista que lado contribuiu cada folha.

Exemplo de autoria — uma anotação de subsistema é encaminhada para values

# Manifest binding
spec:
mappings:
features:
type:
core/db-pool: db-pool-helm:1.0.0
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- pool # routes to values.pool
# Aggregate
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool"
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0

Após a expansão de anotações, tanto api como worker têm um anexo sintético da Feature feature.myco/db-pool cujo campo values.pool tem o valor "shared-pool". O grafo da compilação (aggrega validate --release <release> --ir-graph) regista cada folha com origin: annotation, side: aggregate e annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.

Valores de anotação estruturados

Uma Feature com vários campos configuráveis convida a usar uma única chave de anotação que contenha valores para vários deles de uma só vez. A forma de anotação estruturada permite que uma chave seja encaminhada para vários caminhos da associação numa única declaração:

# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)
boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100

A associação do Manifest declara o encaminhamento das quatro subchaves em listas maps: agrupadas por pilar:

# Manifest
spec:
mappings:
features:
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- db_name
- read_replicas
infra:
- pool_size
- max_connections

A forma do valor da anotação é uma de três:

  • Cadeia de caracteres escalar — um único valor. A associação tem de declarar exatamente um caminho no total; o escalar é encaminhado para esse caminho.
  • Objeto estruturado — um mapa de subchave para subvalor. O caminho de cada subchave tem de aparecer na lista maps.infra ou maps.values da associação; o subvalor é encaminhado para o campo do esquema da Feature indicado, no pilar declarado.
  • null YAML explícito — renuncia por completo à associação herdada para este âmbito da cascata.

Cada subchave dentro de um valor estruturado resolve-se de forma independente em relação à lista maps da associação. Uma subchave ausente tanto de maps.infra como de maps.values interrompe a compilação com um erro claro que indica a subchave em causa e os caminhos declarados.

Fusão em cascata para valores estruturados

As anotações estruturadas descem em cascata com fusão profunda por subchave. A anotação de um âmbito filho da cascata funde-se com a anotação do pai subchave a subchave; o nível mais próximo substitui o pai com granularidade de subchave:

subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "data-default"
read_replicas: 3
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-override" # overrides parent at this subkey only
# read_replicas not listed → inherits 3 from parent
analytics:
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out: removes inherited subkey
# db_name not listed → inherits "data-default" from parent

Anotações efetivas após a cascata:

  • Component api: { db_name: "api-override", read_replicas: 3 }
  • Component analytics: { db_name: "data-default" } — read_replicas excluída por renúncia neste âmbito

Um nível filho da cascata cujo valor é um escalar (face a um pai estruturado) substitui por completo em vez de se fundir. As divergências de forma entre níveis da cascata resolvem-se a favor do valor do nível mais próximo; o compilador não emite aviso em caso de divergência de forma.

null no valor inteiro versus null por subchave

A cascata oferece dois mecanismos de renúncia com granularidades diferentes:

# Whole-value null — opts out wholesale at this scope
components:
api:
annotations:
feature.myco/db-pool: null

Toda a associação da anotação é suprimida neste componente; nenhum anexo sintético de Feature é sintetizado a partir desta chave de anotação neste âmbito. Os componentes irmãos mantêm a sua associação herdada.

# Per-subkey null — opts out just one subkey
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-db"
read_replicas: null

A anotação continua a contribuir neste âmbito, mas a subchave read_replicas é suprimida. As outras subchaves (declaradas neste âmbito ou herdadas dos níveis pai da cascata) mantêm-se.

Orientação de autoria: convém usar null no valor inteiro para desativar num âmbito um anexo de Feature orientado por anotação. Convém usar null por subchave quando se pretende manter a maior parte da contribuição de uma anotação, mas suprimir um ou mais campos específicos.

Partição entre lado e pilar por subchave

A invariante do Aggregate como superfície de autoria aplica-se por subchave quando o valor de uma anotação é estruturado. O pilar de cada subchave (segundo a declaração maps da associação) tem de ser compatível com o lado de autoria:

  • Uma anotação do lado do Aggregate só pode conter subchaves encaminhadas para maps.values.
  • Uma anotação do lado da Release só pode conter subchaves encaminhadas para maps.infra.

Uma subchave encaminhada para um pilar incompatível interrompe a compilação com um erro claro que cita a subchave e o pilar específicos. A cadeia de erros reúne todas as subchaves incompatíveis por anotação antes de interromper — os operadores veem todos os problemas num único ciclo de compilação em vez de corrigir e recompilar repetidamente.

Validação de tipo por subchave

O valor em tempo de execução de cada subchave é validado em relação ao tipo declarado no spec.schema da Feature de destino, no pilar encaminhado. Os tipos declarados suportados são string, integer, number, boolean, object, array, null. Um subvalor cujo tipo YAML não corresponde ao tipo declarado do esquema interrompe a compilação com um erro claro que indica a subchave, o tipo real e o tipo declarado.

A correspondência de tipos é estrita — sem coerção. Uma cadeia de caracteres "20" face a um campo do esquema do tipo inteiro interrompe a compilação; os autores declaram os tipos corretamente no esquema da Feature ou usam anotações escalares que passam como cadeias de caracteres.

Alavanca de autoria para validação estrita. As propriedades sem um type declarado no spec.schema da Feature aceitam qualquer forma de valor em tempo de execução, incluindo mapas aninhados. Quando o esquema não declara uma restrição, a compilação não inventa nenhuma. Os autores que pretendem validação estrita de tipo por subchave declaram type em cada propriedade de spec.schema. A camada de renderização da FeatureRecipe, mais adiante, trata qualquer forma que a contribuição da anotação contenha.

Composição entre lados

Quando tanto uma anotação do lado do Aggregate (subchaves values) como uma anotação do lado da Release (subchaves infra) visam o mesmo anexo de Feature no mesmo Component, a compilação funde as contribuições num único anexo de Feature com os dois pilares preenchidos. A proveniência por folha regista a origem de cada subchave — o anexo sintetizado tem values.db_name atribuído ao ponto de autoria do Aggregate e infra.pool_size atribuído ao ponto de autoria da Release.

O padrão de composição entre lados é a forma de autoria canónica para Features com campos mistos de intenção do programador e de dimensionamento pelo operador: o Aggregate declara as escolhas cognitivas (que base de dados, quantas réplicas ao nível da aplicação); a Release declara o dimensionamento físico (qual o tamanho do pool, quantas ligações ao nível da infraestrutura). Uma única associação do Manifest liga-os com um só conjunto de declarações maps.