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

Composição da saída

Um único build do Aggrega produz arquivos de saída em diretórios por fronteira sob dist/ por meio 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 no nível da Release e emissão direta de artefatos. Os mecanismos são executados em uma ordem definida; as saídas colidem de forma determinística quando dois mecanismos produzem um arquivo com o mesmo nome no mesmo diretório de fronteira; o build é interrompido antes da emissão, nomeando cada contribuidor, quando uma colisão é detectada, sob a categoria que a regra de colisão nomeia.

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

Os seis mecanismos que produzem saída

Cada mecanismo fica em uma superfície de autoria específica de Recipe / FeatureRecipe e produz arquivos segundo convenções de nomenclatura específicas. Os mecanismos se acumulam por nó — uma única instância de componente pode acionar vários mecanismos ao mesmo tempo (uma Recipe base com fonte + um arquivo 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 arquivo ou um $import: de biblioteca para uma entrada de uma MappingLibrary — veja 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 arquivo YAML do docker-compose ou outro artefato nativo do provedor.

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

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

  • provedor helm — arquivos YAML do Kubernetes planos, nomeados pela identidade do componente e depois pelo próprio recurso: <component-id>-<kind>[-<namespace>]-<name>.yaml, e um documento que não traz nenhum kind ou nenhum nome é nomeado pelo caminho do seu template. O nome vem do recurso e não do template, então dois templates em subdiretórios diferentes que compartilham um nome de arquivo continuam sendo dois arquivos. O SDK do Helm renderiza o chart com os valores mesclados; o Aggrega injeta rótulos e anotações de proveniência após a renderização.
  • provedor helm-chart — arquivos de subchart copiados em 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 (veja providers/helm-chart.md); um Chart.yaml + values.yaml umbrella por fronteira emitidos ao lado.
  • provedor compose — arquivos intermediários <nodeID>.compose-fragment.yaml que fluem para a composição no 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 arquivo).

Posição no pipeline. Renderização base, depois que o valuesMapping da Recipe é 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:

  • provedor 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 elas 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 arquivo por recurso é nomeado pelo recurso que ele carrega, com o kind por último: <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, então ele é 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 (veja entities/workload.md “Synthesized-name convention (Convenção de nomes sintetizados)”). Um Workload cuja única exposição é um nome externo emite <release name>-service.yaml em vez disso, já que não há chave de serviço para carregar.
  • provedor compose — arquivos intermediários <nodeID>.compose-fragment.yaml que fluem para a composição no nível da Release.
  • provedor 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 alvo o helm-chart com workload: é rejeitada no momento da renderização (o provedor helm-chart não informa 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 vinculações 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 vinculação de Feature executa sua própria passagem de renderização da FeatureRecipe.

Forma da saída. Decidida pelo provedor do Component pai, porque a saída da vinculação se junta ao grupo de montagem desse Component em vez de a um grupo próprio — e decorre de como esse provedor combina o grupo, já que é isso que diz se existe ou não um lugar para colocar uma vinculação. Três formas, uma por maneira de combinar:

  • Um provedor 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 uma vinculação uma posição própria, ao lado do componente ao qual ela foi vinculada em vez de dentro dele. As duas coordenadas compõem o único segmento de diretório dessa posição, <component-id>--<feature-instance-id>, de modo que um componente api que carrega uma vinculação aux fica em api--aux ao lado de api, sob qualquer diretório que esse provedor designe para seus contribuidores. Ao lado e não dentro, porque o alvo de um provedor assim descobre 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 si só, então nada o endereça e nada o lê. Uma vinculação declarada na fronteira não tem nenhum componente hospedeiro para nomear, então seu segmento é apenas o seu nome de instância. Cada coordenada é codificada antes que as duas sejam unidas, de modo que uma coordenada que contenha ela mesma a sequência de junção não possa ser confundida com a junção.
  • Um provedor que escreve cada documento diretamente no diretório de fronteira não tem esse lugar, porque é exatamente isso que ele declara sobre seu alvo: somente os arquivos que estão diretamente em um diretório são lidos. Assim, as mesmas duas coordenadas saem dos segmentos de diretório e passam para o nome do arquivo, e os arquivos da vinculação ficam ao lado dos do componente como <component-id>--<feature-instance-id>--<file>. As duas coordenadas são codificadas, porque um nome de arquivo não tem nenhum separador a que recorrer, e são unidas ao próprio nome do arquivo em um limite de dois caracteres que nenhuma coordenada codificada pode conter — e é isso que mantém duas vinculações que emitem um mesmo nome de arquivo em dois arquivos distintos.
  • Um provedor que funde os contribuidores do seu grupo em um único documento funde também a saída da vinculação nesse documento, onde cada recurso carrega a identidade própria da vinculação para que o que veio de onde continue legível. Quando um provedor assim carrega uma vinculação que foi renderizada para um alvo diferente, esse conteúdo não pode ser fundido em um documento ao qual não pertence, então ele é escrito ao lado do documento montado — na forma com prefixo no nome do arquivo descrita acima, pelo mesmo motivo.

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 roteamento.

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

Superfície de autoria. A FeatureRecipe declara pipeline: — um array de etapas 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 que a renderização base e a renderização a partir de fonte da FeatureRecipe são concluídas.

Forma da saída. Específica do Plugin. Uma etapa retorna 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 contêiner sidecar, montar um volume de secret, reescrever uma variável de ambiente no Deployment sintetizado).
  • Efeitos colaterais — recursos novos completos emitidos ao lado do patch por meio do side_effects de uma etapa (tipicamente o CRD vault-fetch do Fetcher que o Injector depois referencia).

Status atual: disponível conforme Status da linguagem → Fases do pipeline de compilação. Cada etapa declarada é executada durante aggrega build: o host invoca o plugin Wasm da etapa sobre o conjunto renderizado, aplica os patches retornados e emite os efeitos colaterais da etapa. Veja plugins/plugin-contract.md para a superfície do contrato de plugins.

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

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

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

Forma da saída. Por provedor:

  • provedor compose — um único docker-compose.yaml na raiz da fronteira, agregando os serviços, volumes e redes de cada nó contribuidor. Os arquivos intermediários <nodeID>.compose-fragment.yaml (mecanismos 1 + 2) são mesclados na saída única; os fragmentos não aparecem no diretório final da fronteira.
  • provedor 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 artefatos da Recipe (artifacts:)

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

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

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

Status atual: disponível conforme Status 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 arquivo resultante é emitido sob a chave da entrada. O que um alvo faz com um artefato emitido depende da capacidade: um provedor que aceita um artefato independente o emite como um arquivo próprio, enquanto um que só aceita artefatos junto com outro tipo de entrada incorpora a entrada no que monta — de modo que um corpo que não tem a forma que esse montador espera provoca uma interrupção sob a categoria TRANSLATION_ERROR em vez de ser emitido literalmente. Consulte a grade por capacidade em architecture/16-recipe-input-composition.md antes de escrever um artefato para uma capacidade.

Ordem de renderização

Os seis mecanismos são executados em uma ordem definida para que os mecanismos posteriores possam ler as saídas dos anteriores. A ordem:

  1. Avaliação dos provides — por nó, o bloco locals: da Recipe é resolvido primeiro, na ordem do autor, com cada entrada lendo as entradas acima dela; os templates provides: do nó são então avaliados, em qualquer ordem entre si (autocontidos: .context.instance_id, .context.rendered_name onde o provedor do nó informa 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 compartilha o contexto dos locals, então ela lê .locals e não .provides.
  3. Mapeamento de injeção — os blocos injectMapping: da FeatureRecipe são avaliados (o pipe de injeção é interceptado 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 artefatos — avaliação de artifacts: da Recipe (mecanismo 6).
  7. Renderização do Provider — o provedor 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 vinculação de Feature no nó (mecanismos 3 + 4 — a geração de recursos é executada aqui; o pipeline de plugins é executado depois, na etapa 9).
  9. O pipeline de plugins — mutação pós-renderização: as etapas de plugin pipeline: da FeatureRecipe aplicam patches RFC 6902 e emitem recursos adicionais (mecanismo 4).
  10. Composição no 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 posteriores podem ler as saídas dos anteriores — por exemplo, uma etapa do pipeline de plugins pode aplicar um patch a um Deployment renderizado pelo provedor, e um compositor no nível da Release pode mesclar fragmentos emitidos pela renderização do provedor, pela renderização de funcionalidades e pelo pipeline de plugins.

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

Quando dois mecanismos produzem um arquivo com o mesmo nome no mesmo diretório de fronteira, o build é interrompido, 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 arquivo emitido, quer o corpo da entrada seja escrito inline, quer seja carregado via $import:). Detectada no momento do carregamento da Recipe conforme errors/fatal-halts.md “artifacts: entry keys must be unique (As chaves das entradas de artefatos devem 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 artefatos — emitem cada um arquivos no mesmo diretório de fronteira. Se a saída renderizada a partir da fonte, sintetizada a partir da carga de trabalho ou emitida como artefato produzir um arquivo cujo nome outro tipo de entrada também produziu, o build é interrompido na emissão. Detectada no momento da emissão conforme errors/fatal-halts.md “Emission-time filename collision across input kinds (Colisão de nomes de arquivo 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 de mesmo nome para a saída compose mesclada, o provedor compose é interrompido ao compor a fronteira, sob a categoria TRANSLATION_ERROR, nomeando cada tupla (boundary, node, serviceName) contribuidora. Detectada na composição no nível da Release conforme a seção de saída no 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 contêiner em execução, então dois nós que queriam um cada recebem um só entre os dois, e a intenção de um contribuidor se perde 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 de mesmo nome para a saída compose mesclada, e as duas declarações diferem, o provedor compose é interrompido sob a categoria TRANSLATION_ERROR, nomeando a entrada e cada tupla (boundary, node) contribuidora. Detectado na composição no nível da Release conforme a seção de saída no 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 compartilhado é legítimo onde os contribuidores concordam. Um volume ou uma config nomeados são um único objeto, então dois nós que o declaram de forma idêntica pediram ambos exatamente a entrada com que o documento mesclado 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 um build que de outra forma teria sucesso. Duas declarações contam como concordantes quando descrevem a mesma entrada no arquivo montado, então 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 seus valores ficam delimitados sob 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 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 substituí-los — então 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 pelas regras de achatamento do Aggregate, então 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 arquivos YAML com campos metadata.name sobrepostos. Os nomes de arquivo diferem, porque cada um recebe como prefixo sua própria base de nomenclatura, enquanto o metadata.name dentro deles ainda pode coincidir — então o build verifica os nomes que os recursos renderizados carregam, e dois contribuidores que derivam um mesmo nome para um mesmo kind em um mesmo namespace o interrompem sob a categoria TRANSLATION_ERROR antes que qualquer coisa seja escrita, nomeando o nome e cada componente, e cada vinculação, que o derivou (veja errors/fatal-halts.md).

O caso mais amplo é fechado por construção em vez de verificado. Um chart com fonte que nomeia seus recursos pelo nome da release não pode mais produzir isso entre dois componentes, porque duas bases de nomenclatura que diferem minimamente chegam a dois nomes de release — veja providers/helm.md “How the release name is derived (Como o nome da release é derivado)”. Restam dois casos, e a verificação acima é o que os informa. Um é um chart que escreve um nome de recurso literalmente em seus templates, e nenhuma derivação consegue distinguir esse nome de qualquer outro literal. O outro são duas vinculações de Feature em um componente que entregam cada uma um chart escrito pelo seu autor: ambas renderizam com o nome da release desse componente, por design, então dois charts que nomeiam um recurso por .Release.Name se encontram ali — dê nomes distintos aos recursos dos dois charts ou vincule-os a componentes diferentes.

Todo nome sintetizado começa com a identidade própria do nó — o do objeto controlador, e cada nome por recurso por meio 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. Autores cujo build é interrompido em um nome de Deployment / Service devem verificar primeiro se duas Recipes diferentes estão emitindo recursos de mesmo nome por caminhos de renderização diferentes (por exemplo, o templates/deployment.yaml de um chart com fonte colidindo 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 se compõem — o Deployment é o mesmo recurso K8s, com o patch sobrepondo referências a ConfigMap / Secret à base sintetizada.

Este é o padrão dominante para injeção de credenciais em cargas de trabalho sintetizadas. O Fetcher (mecanismo 3, geração de recursos) emite um CRD ExternalSecret que o cluster busca 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 traz a forma de saída apropriada; a nomeação de arquivos entre fronteiras não colide porque os diretórios dist/ por fronteira são isolados entre si.

Mesclagem do Compose no 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 em um único docker-compose.yaml nesse caminho; duas fronteiras voltadas para compose em uma mesma Release escrevem dois arquivos quando seus diretórios diferem, e um único arquivo mesclado quando compartilham um diretório.

As colisões de nomes de serviço são, portanto, detectadas por arquivo, na sua mesclagem no nível da Release, conforme a regra acima. Duas fronteiras voltadas para compose em diretórios diferentes que declaram cada uma um serviço chamado api não colidem: o arquivo de cada fronteira traz o seu. Duas que compartilham um diretório escrevem um único arquivo, e o build é interrompido nomeando ambos os contribuidores.

Referências cruzadas