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

Composição da saída

Uma única compilação do Aggrega produz ficheiros de saída em diretórios por fronteira sob dist/ através de seis mecanismos distintos — renderização a partir de fonte, síntese de carga de trabalho, geração de recursos da FeatureRecipe, patches do pipeline de plugins da FeatureRecipe, composição ao nível da Release e emissão direta de artefactos. Os mecanismos são executados numa ordem definida; as saídas colidem de forma determinística quando dois mecanismos produzem um ficheiro com o mesmo nome no mesmo diretório de fronteira; a compilação é interrompida antes da emissão, nomeando cada contribuidor, quando é detetada uma colisão, sob a categoria que a regra de colisão nomeia.

Esta página documenta os seis mecanismos num só lugar e nomeia a ordem de renderização entre eles. As referências por capítulo e por entidade cobrem as suas próprias superfícies; as regras de deteção de colisões entre os seis encontram-se aqui.

Os seis mecanismos que produzem saída

Cada mecanismo situa-se numa superfície de autoria específica de Recipe / FeatureRecipe e produz ficheiros segundo convenções de nomenclatura específicas. Os mecanismos acumulam-se por nó — uma única instância de componente pode acionar vários mecanismos ao mesmo tempo (uma Recipe base com fonte + um ficheiro complementar sintetizado pelo Workload + um CRD ExternalSecret emitido por uma FeatureRecipe + um patch do pipeline de plugins aplicado ao Deployment sintetizado).

1 — Renderização a partir de fonte da Recipe (source: + valuesMapping:)

Superfície de autoria. A Recipe declara source: <path> mais valuesMapping: (o campo aceita um template Go inline, um $import: de ficheiro ou um $import: de biblioteca para uma entrada de uma MappingLibrary — consulte entities/recipe.md «The valuesMapping field — three authoring modes (O campo valuesMapping — três modos de autoria)»). A fonte aponta para um chart Helm em disco, um ficheiro YAML do docker-compose ou outro artefacto nativo do fornecedor.

Posição no pipeline. Renderização base, depois de os locals e os provides da Recipe serem resolvidos.

Forma da saída. Específica do Provider:

  • fornecedor helm — ficheiros YAML do Kubernetes planos, nomeados pela identidade do componente e depois pelo próprio recurso: <component-id>-<kind>[-<namespace>]-<name>.yaml, sendo um documento que não traz nenhum kind ou nenhum nome nomeado, em vez disso, pelo caminho do seu template. O nome vem do recurso e não do template, pelo que dois templates em subdiretórios diferentes que partilham um nome de ficheiro continuam a ser dois ficheiros. O SDK do Helm renderiza o chart com os valores fundidos; o Aggrega injeta etiquetas e anotações de proveniência após a renderização.
  • fornecedor helm-chart — ficheiros de subchart copiados para charts/<instance_id>/, sem alterações exceto o name do próprio chart, que o umbrella define como a identidade codificada da instância para que dois componentes que incorporam charts que declaram um mesmo nome continuem distinguíveis (consulte providers/helm-chart.md); um Chart.yaml + values.yaml umbrella por fronteira emitidos ao lado.
  • fornecedor compose — ficheiros intermédios <nodeID>.compose-fragment.yaml que fluem para a composição ao nível da Release (mecanismo 5).

2 — Síntese de Workload da Recipe (workload:)

Superfície de autoria. A Recipe declara workload: contendo um documento Workload. O campo aceita conteúdo inline (block scalar) ou $import: (caminho de ficheiro).

Posição no pipeline. Renderização base, depois de o valuesMapping da Recipe ser resolvido (o corpo do Workload é ele próprio uma string com template Go avaliada com o contexto de template completo).

Forma da saída. Específica do Provider:

  • fornecedor helm — um objeto controlador escolhido pelo form do Workload (Deployment para stateless, StatefulSet para stateful, DaemonSet para daemon, Job para task, CronJob para scheduled) + um Service por serviço + um PVC por volume persistent. Duas formas de nomenclatura, e não são a mesma: o objeto controlador é nomeado pelo nome da release do nó e pelo seu kind — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml — enquanto um ficheiro por recurso é nomeado pelo recurso que contém, com o kind no fim: <release name>-<svcName>-service.yaml e <release name>-<volName>-pvc.yaml, porque cada um é nomeado a partir do próprio metadata.name desse recurso. O nome da release é a identidade do nó escrita no alfabeto que um nome do Kubernetes admite, pelo que é igual ao ID do nó sempre que este não contém sublinhado nem letra maiúscula: o nó my_api escreve my-zuapi-deployment.yaml (consulte entities/workload.md «Synthesized-name convention (Convenção de nomes sintetizados)»). Um Workload cuja única exposição é um nome externo emite, em vez disso, <release name>-service.yaml, uma vez que não há chave de serviço para transportar.
  • fornecedor compose — ficheiros intermédios <nodeID>.compose-fragment.yaml que fluem para a composição ao nível da Release.
  • fornecedor helm-chart — não suportado; o papel do helm-chart é apenas a composição de charts no modo com fonte. Uma Recipe que tem como destino o helm-chart com workload: é rejeitada no momento da renderização (o fornecedor helm-chart não declara nenhuma capacidade de síntese).

3 — Geração de recursos da FeatureRecipe (modo com fonte para as FeatureRecipes)

Superfície de autoria. A FeatureRecipe declara source: mais valuesMapping: (ou equivalente), o mesmo padrão da renderização a partir de fonte da Recipe, mas para anexos de Feature em vez de Components primários.

Posição no pipeline. Renderização base, ao lado da renderização da Recipe base para o Component pai. Cada anexo de Feature executa a sua própria passagem de renderização da FeatureRecipe.

Forma da saída. Decidida pelo fornecedor do Component pai, porque a saída do anexo junta-se ao grupo de montagem desse Component em vez de a um grupo próprio — e decorre da forma como esse fornecedor combina o grupo, já que é isso que diz se existe sequer um lugar onde colocar um anexo. Três formas, uma por cada maneira de combinar:

  • Um fornecedor que dá a cada contribuidor uma posição própria — um chart que contém um chart por contribuidor, uma configuração raiz que contém um módulo por contribuidor — dá também a um anexo uma posição própria, ao lado do componente ao qual foi anexado em vez de dentro dele. As duas coordenadas compõem o único segmento de diretório dessa posição, <component-id>--<feature-instance-id>, pelo que um componente api que tem um anexo aux fica em api--aux ao lado de api, sob qualquer diretório que esse fornecedor designe para os seus contribuidores. Ao lado e não dentro, porque o destino de um tal fornecedor descobre os seus contribuidores nas posições que lhes deu: um diretório um nível abaixo de uma dessas posições é conteúdo que pertence a esse contribuidor e não um contribuidor por direito próprio, pelo que nada o endereça e nada o lê. Um anexo declarado na fronteira não tem nenhum componente anfitrião para nomear, pelo que o seu segmento é apenas o seu nome de instância. Cada coordenada é codificada antes de as duas serem unidas, de modo que uma coordenada que contenha ela própria a sequência de junção não possa ser confundida com a junção.
  • Um fornecedor que escreve cada documento diretamente no diretório de fronteira não tem tal lugar, porque é exatamente isso que declara sobre o seu destino: só são lidos os ficheiros que estão diretamente num diretório. Assim, as mesmas duas coordenadas saem dos segmentos de diretório e passam para o nome do ficheiro, e os ficheiros do anexo ficam ao lado dos do componente como <component-id>--<feature-instance-id>--<file>. As duas coordenadas são codificadas, porque um nome de ficheiro não tem nenhum separador a que recorrer, e são unidas ao próprio nome do ficheiro num limite de dois caracteres que nenhuma coordenada codificada pode conter — e é isso que mantém dois anexos que emitem um mesmo nome de ficheiro em dois ficheiros distintos.
  • Um fornecedor que funde os contribuidores do seu grupo num único documento funde também a saída do anexo nesse documento, onde cada recurso tem a identidade própria do anexo para que aquilo que veio de onde continue legível. Quando um tal fornecedor tem um anexo que foi renderizado para um destino diferente, esse conteúdo não pode ser fundido num documento ao qual não pertence, pelo que é escrito ao lado do documento montado — na forma com prefixo no nome do ficheiro descrita acima, pela mesma razão.

Formas comuns:

  • Um CRD ExternalSecret / VaultSecret gerado pelo Fetcher de uma FeatureRecipe de credenciais.
  • Um CRD ServiceMonitor / PrometheusRule gerado por uma Feature de observabilidade.
  • Um CRD HTTPRoute / Gateway gerado por uma Feature de encaminhamento.

4 — Pipeline de plugins da FeatureRecipe (patches RFC 6902 + emissão de recursos)

Superfície de autoria. A FeatureRecipe declara pipeline: — um array de passos de plugins Wasm (princípio do Plugin em duas partes: Fetcher + Injector para Features de credenciais; pipelines de plugins arbitrários para Features que não são de credenciais).

Posição no pipeline. O pipeline de plugins, depois de concluídas a renderização base e a renderização a partir de fonte da FeatureRecipe.

Forma da saída. Específica do Plugin. Um passo devolve duas classes de saída:

  • Patches RFC 6902 que o motor de aplicação aplica aos documentos endereçados no conjunto renderizado (por exemplo, acrescentar um contentor sidecar, montar um volume de secret, reescrever uma variável de ambiente no Deployment sintetizado).
  • Efeitos secundários — recursos novos completos emitidos ao lado do patch através do side_effects de um passo (tipicamente o CRD vault-fetch do Fetcher que o Injector depois referencia).

Estado atual: disponível conforme Estado da linguagem → Fases do pipeline de compilação. Cada passo declarado é executado durante aggrega build: o anfitrião invoca o plugin Wasm do passo sobre o conjunto renderizado, aplica os patches devolvidos e emite os efeitos secundários do passo. Consulte plugins/plugin-contract.md para a superfície do contrato de plugins.

5 — Composição ao nível da Release (montagem da fronteira por fornecedor)

Superfície de autoria. Determinada pela forma da Release — sem autoria por Recipe. Uma capacidade que monta uma fronteira fá-lo uma única vez, depois de cada nó dessa fronteira ter sido renderizado: a capacidade compose reúne todos os fragmentos por nó num único docker-compose.yaml por fronteira, e a capacidade helm-chart reúne as cópias de subcharts por nó num único chart umbrella por fronteira.

Posição no pipeline. Depois da renderização base, assim que a saída por Recipe de cada nó se tiver acumulado para a fronteira.

Forma da saída. Por fornecedor:

  • fornecedor compose — um único docker-compose.yaml na raiz da fronteira, que agrega os serviços, volumes e redes de cada nó contribuidor. Os ficheiros intermédios <nodeID>.compose-fragment.yaml (mecanismos 1 + 2) são fundidos na saída única; os fragmentos não aparecem no diretório final da fronteira.
  • fornecedor helm-chart — um Chart.yaml + values.yaml umbrella na raiz da fronteira, mais diretórios de subchart por nó em charts/<instance_id>/.

6 — Emissão direta de artefactos da Recipe (artifacts:)

Superfície de autoria. A Recipe declara artifacts: como um mapa de entradas com nome; cada entrada é ou conteúdo inline (uma string com template que contém o corpo do ficheiro) ou uma referência $import: a um caminho de ficheiro de template — emissão direta de ficheiros sem passar por um fornecedor.

Posição no pipeline. Avaliação de artefactos, dentro da renderização base.

Forma da saída. Um ficheiro por entrada de artefacto, nomeado pela chave da entrada no mapa artifacts:. O autor da Recipe dita diretamente o nome do ficheiro e o conteúdo.

Estado atual: disponível conforme Estado da linguagem → Tipos de entrada da Recipe. Cada entrada é avaliada com o contexto de template completo depois da síntese de carga de trabalho e da resolução da fonte, e o ficheiro resultante é emitido sob a chave da entrada. O que um destino faz com um artefacto emitido depende da capacidade: um fornecedor que aceita um artefacto autónomo emite-o como ficheiro próprio, enquanto um que só aceita artefactos juntamente com outro tipo de entrada incorpora a entrada naquilo que monta — pelo que um corpo que não tem a forma que esse montador espera provoca uma paragem sob a categoria TRANSLATION_ERROR em vez de ser emitido literalmente. Consulte a grelha por capacidade em architecture/16-recipe-input-composition.md antes de escrever um artefacto para uma capacidade.

Ordem de renderização

Os seis mecanismos são executados numa ordem definida para que os mecanismos a jusante possam ler as saídas dos mecanismos a montante. A ordem:

  1. Avaliação dos provides — por nó, o bloco locals: da Recipe é resolvido primeiro, pela ordem do autor, com cada entrada a ler as entradas acima dela; os templates provides: do nó são depois avaliados, em qualquer ordem entre si (autocontidos: .context.instance_id, .context.rendered_name onde o fornecedor do nó indica um, .values, .infra, os .locals resolvidos, texto estático). A ordem locals-antes-de-provides é o que permite a uma entrada provides: ler um local e receber um valor resolvido.
  2. Publicação dos locals e resolução da fonte — esses locals são publicados em .locals, e o template de URI source: da Recipe é avaliado em relação a eles (resolvendo o ponteiro da fonte se for um template). A superfície da fonte partilha o contexto dos locals, pelo que lê .locals e não .provides.
  3. Mapeamento de injeção — os blocos injectMapping: da FeatureRecipe são avaliados (o pipe de injeção é intercetado antes da renderização da Recipe).
  4. Mapeamento de valores — o valuesMapping: da Recipe é avaliado (o modo com fonte + o modo sem fonte produzem dicionários de valores).
  5. Síntese de Workload — síntese de Workload da Recipe (o mecanismo 2 emite manifestos para o modo sintetizado).
  6. Avaliação de artefactos — avaliação de artifacts: da Recipe (mecanismo 6).
  7. Renderização do Provider — o fornecedor renderiza (mecanismo 1 — o modo com fonte produz manifestos planos; o modo sem fonte produz manifestos generativos).
  8. Renderização de Feature — renderização da FeatureRecipe para cada anexo de Feature no nó (mecanismos 3 + 4 — a geração de recursos é executada aqui; o pipeline de plugins é executado mais tarde, no passo 9).
  9. O pipeline de plugins — mutação pós-renderização: os passos de plugin pipeline: da FeatureRecipe aplicam patches RFC 6902 e emitem recursos adicionais (mecanismo 4).
  10. Composição ao nível da Release — a montagem da fronteira da capacidade reúne os fragmentos por nó em saídas por fronteira (mecanismo 5).

A ordem importa porque os mecanismos a jusante podem ler as saídas dos mecanismos a montante — por exemplo, um passo do pipeline de plugins pode aplicar um patch a um Deployment renderizado pelo fornecedor, e um compositor ao nível da Release pode fundir fragmentos emitidos pela renderização do fornecedor, pela renderização de funcionalidades e pelo pipeline de plugins.

Conjunto de regras de deteção de colisões

Quando dois mecanismos produzem um ficheiro com o mesmo nome no mesmo diretório de fronteira, a compilação é interrompida, nomeando cada contribuidor, sob a categoria que cada regra abaixo nomeia. O conjunto de regras:

Regra de forma da Recipe: colisão de chaves de entrada de artifacts:

Uma Recipe declara duas entradas sob artifacts: com a mesma chave (a chave dita o nome do ficheiro emitido, quer o corpo da entrada seja escrito inline, quer seja carregado através de $import:). Detetada no momento do carregamento da Recipe conforme errors/fatal-halts.md «artifacts: entry keys must be unique (As chaves das entradas de artefactos têm de ser únicas)».

Regra de forma da Recipe: colisão no momento da emissão entre tipos de entrada

Os três tipos de entrada de uma Recipe — com fonte, sintetizado e artefactos — emitem cada um ficheiros para o mesmo diretório de fronteira. Se a saída renderizada a partir da fonte, sintetizada a partir da carga de trabalho ou emitida como artefacto produzir um ficheiro cujo nome outro tipo de entrada também produziu, a compilação é interrompida na emissão. Detetada no momento da emissão conforme errors/fatal-halts.md «Emission-time filename collision across input kinds (Colisão de nomes de ficheiro no momento da emissão entre tipos de entrada)».

Colisão de nomes de serviço do Compose (nível de Release)

Quando dois nós diferentes (em qualquer combinação de fronteiras) contribuem com serviços com o mesmo nome para a saída compose fundida, o fornecedor compose interrompe-se ao compor a fronteira, sob a categoria TRANSLATION_ERROR, nomeando cada tuplo (boundary, node, serviceName) contribuidor. Detetada na composição ao nível da Release conforme a secção de saída ao nível da Release de providers/compose.md.

Um serviço é recusado apenas pelo nome, sem comparar o que os dois nós declararam. Um serviço compose é um único contentor em execução, pelo que dois nós que queriam um cada obtêm apenas um entre os dois, e a intenção de um contribuidor perde-se por mais idênticas que sejam as duas definições.

Conflito de nomes de volume e de config do Compose (nível de Release)

Quando dois nós diferentes contribuem com uma entrada volumes: ou configs: de nível superior com o mesmo nome para a saída compose fundida, e as duas declarações diferem, o fornecedor compose interrompe-se sob a categoria TRANSLATION_ERROR, nomeando a entrada e cada tuplo (boundary, node) contribuidor. Detetado na composição ao nível da Release conforme a secção de saída ao nível da Release de providers/compose.md.

Ao contrário da regra de serviços acima, esta compara as declarações, e um nome partilhado é legítimo onde os contribuidores concordam. Um volume ou uma config com nome são um único objeto, pelo que dois nós que o declaram de forma idêntica pediram ambos exatamente a entrada com que o documento fundido acaba, e nada se perde. Dois nós que o declaram de forma diferente discordam sobre esse único objeto, e manter qualquer uma das declarações descartaria a outra de uma compilação que, de outro modo, teria êxito. Duas declarações contam como concordantes quando descrevem a mesma entrada no ficheiro montado, pelo que um corpo escrito como um mapeamento vazio e um omitido por completo concordam.

Alias e diretório dos subcharts do helm-chart

Um subchart do helm-chart fica em charts/<instance_id>/ e os seus valores ficam delimitados sob o seu alias, que é o ID da instância codificado para a posição de alias. Duas instâncias não podem chegar a um mesmo alias a menos que os seus IDs de instância sejam a mesma string, porque a codificação escreve por extenso os caracteres que um alias não aceita em vez de os substituir — pelo que um alias identifica exatamente um subchart, e os valores escritos sob ele chegam apenas a esse subchart. Os IDs de instância são, por sua vez, únicos por fronteira segundo as regras de achatamento do Aggregate, pelo que o diretório também não pode colidir. Ambas as metades são estruturais: nenhuma depende de uma verificação.

Colisão de nomes de recursos renderizados pelo Helm

Dentro de uma fronteira, dois nós que renderizam para o mesmo nome de recurso do Kubernetes produzem dois ficheiros YAML com campos metadata.name sobrepostos. Os nomes de ficheiro diferem, porque cada um recebe como prefixo a sua própria base de nomenclatura, enquanto o metadata.name dentro deles ainda pode coincidir — pelo que a compilação verifica os nomes que os recursos renderizados têm, e dois contribuidores que derivam um mesmo nome para um mesmo kind num mesmo namespace interrompem-na sob a categoria TRANSLATION_ERROR antes de qualquer coisa ser escrita, nomeando o nome e cada componente, e cada anexo, que o derivou (consulte errors/fatal-halts.md).

O caso mais amplo é fechado por construção em vez de verificado. Um chart com fonte que nomeia os seus recursos pelo nome da release já não pode produzir isto entre dois componentes, porque duas bases de nomenclatura que difiram minimamente chegam a dois nomes de release — consulte providers/helm.md «How the release name is derived (Como é derivado o nome da release)». Restam dois casos, e a verificação acima é o que os comunica. Um é um chart que escreve literalmente um nome de recurso nos seus templates, e nenhuma derivação consegue distinguir esse nome de qualquer outro literal. O outro são dois anexos de Feature em um componente que entregam cada um um chart escrito pelo seu autor: ambos renderizam com o nome da release desse componente, por conceção, pelo que dois charts que nomeiam um recurso segundo .Release.Name se encontram aí — dê nomes distintos aos recursos dos dois charts, ou anexe-os a componentes diferentes.

Todo o nome sintetizado começa pela identidade própria do nó — o do objeto controlador, e cada nome por recurso através da convenção sintetizada de nomes de Service <release name>-<svcName> (conforme entities/workload.md «Synthesized-name convention (Convenção de nomes sintetizados)») — o que torna as colisões entre nós estruturalmente impossíveis por construção. Os autores cuja compilação é interrompida num nome de Deployment / Service devem verificar primeiro se duas Recipes diferentes estão a emitir recursos com o mesmo nome por caminhos de renderização diferentes (por exemplo, o templates/deployment.yaml de um chart com fonte a colidir com o metadata.name de um Deployment sintetizado a partir da carga de trabalho).

Padrões de interação entre mecanismos

Workload sintetizado + patch do pipeline de plugins

O padrão canónico: o mecanismo 2 (síntese de carga de trabalho) emite um Deployment base; o mecanismo 4 (o plugin Injector) aplica um patch RFC 6902 que monta um volume de secret no Deployment. Os dois mecanismos compõem-se — o Deployment é o mesmo recurso K8s, com o patch a sobrepor referências a ConfigMap / Secret à base sintetizada.

Este é o padrão dominante para a injeção de credenciais em cargas de trabalho sintetizadas. O Fetcher (mecanismo 3, geração de recursos) emite um CRD ExternalSecret que o cluster obtém em tempo de execução; o Injector (mecanismo 4, um patch do pipeline de plugins) modifica o Deployment para montar o Secret K8s resultante.

Com fonte + síntese de Workload em fronteiras diferentes

Um único Aggregate pode ter um componente associado a uma Recipe helm com fonte (mecanismo 1) na fronteira A e um componente irmão associado a uma Recipe helm que sintetiza um Workload (mecanismo 2) na fronteira B. O diretório de cada fronteira tem a forma de saída adequada; a nomeação de ficheiros entre fronteiras não colide porque os diretórios dist/ por fronteira estão isolados entre si.

Fusão do Compose ao nível da Release por diretório de saída

A montagem da capacidade compose reúne os fragmentos por nó de cada fronteira cujo diretório é avaliado como um mesmo caminho num único docker-compose.yaml nesse caminho; duas fronteiras destinadas ao compose numa mesma Release escrevem dois ficheiros quando os seus diretórios diferem, e um único ficheiro fundido quando partilham um diretório.

As colisões de nomes de serviço são, portanto, detetadas por ficheiro, na sua fusão ao nível da Release, conforme a regra acima. Duas fronteiras destinadas ao compose em diretórios diferentes que declaram cada uma um serviço chamado api não colidem: o ficheiro de cada fronteira tem o seu. Duas que partilham um diretório escrevem um único ficheiro, e a compilação é interrompida nomeando ambos os contribuidores.

Referências cruzadas