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

Arquitetura de Provider

Um provedor renderiza os tipos de entrada de uma Recipe em arquivos de manifesto nativos do provedor. Quando uma Recipe declara capability: helm, capability: compose ou qualquer outro nome de provedor, o compilador despacha a renderização para o provedor que atende esse nome. Este capítulo trata de como um provedor é realizado como um Plugin de renderização de provedores, de como o despacho funciona e do contrato do socket de plugins que vincula o compilador a cada provedor.

O que este capítulo não trata: o modelo de composição de três tipos de entrada (source: + valuesMapping:, workload:, artifacts: — cada um aceitando conteúdo em linha ou $import:) que uma Recipe usa para produzir sua saída. Esse modelo é transversal a todos os provedores e fica em ../../architecture/16-recipe-input-composition.md, incluindo a Matriz de capacidades por Provider que mapeia qual tipo de entrada cada provedor suporta.

O Plugin de renderização de provedores

A renderização Provider é fornecida por um Plugin com pluginType: provider. O Plugin de renderização de provedores:

  • atende a um ou mais nomes de provedor — declarados em spec.provider.capabilities. O nome de provedor que uma Recipe nomeia (spec.capability: helm) se vincula ao Plugin de renderização de provedores cuja lista spec.provider.capabilities inclui esse nome. Quando mais de um Plugin atende ao mesmo destino, o espaço de trabalho escolhe entre eles por meio de um binding de provedor em .aggrega-config.yaml, resolvido em aggrega pull e registrado no arquivo de bloqueio; sem binding e com exatamente um candidato, esse candidato é usado, e sem binding e com mais de um candidato o build é interrompido de forma explícita, nomeando os plugins candidatos.
  • carrega seus metadados do socket de provedor no mesmo bloco — spec.provider contém a lista de capacidades acima junto com o restante das declarações do provedor. spec.provider.workloadSchema é uma declaração JSON Schema 2020-12 que documenta como o tipo Workload, de propriedade da plataforma, se traduz na saída nativa deste provedor; o catálogo da biblioteca padrão a declara nos provedores que sintetizam, como o contrato de tradução documentado. spec.provider.wellKnownAnnotations enumera as anotações de fronteira aggrega.ai/ que o provedor lê. O suporte a entradas sintetizadas (workload:) é uma propriedade do provedor, aplicada no momento da renderização — e não é determinado pela presença de workloadSchema.

Veja ../entities/plugin.md para a superfície de autoria completa, no nível de campo, da entidade Plugin, incluindo o bloco spec.provider.

Despacho por provedor

Cada Recipe declara exatamente um capability: no topo do seu spec. O compilador lê esse campo e despacha a renderização para o provedor que atende o nome. Uma Recipe não pode ter como destino vários provedores ao mesmo tempo. A composição multiprovedor acontece no nível da Release: uma fronteira pode conter componentes de provedores diferentes, e os contribuidores de cada provedor no caminho de montagem avaliado da fronteira são montados de forma independente — uma montagem por tupla (path, provider).

O caminho de despacho para um único nó:

  1. O compilador resolve o URI da Recipe para este nó por meio da busca em três níveis do Manifest na seção de mapeamento do provedor de destino. O agrupamento pelo eixo de provedor do Manifest é o que torna “o mesmo Component, Recipes diferentes para provedores diferentes” um padrão natural.
  2. O spec.capability da Recipe resolvida identifica o nome de provedor para o qual despachar.
  3. O compilador vincula o provedor para esse nome: ele resolve o Plugin de renderização de provedores cuja lista spec.provider.capabilities inclui o nome e renderiza por meio do guest desse Plugin. A renderização é somente Wasm — não há renderizador dentro do host ao qual recorrer, então um nome de provedor que não se resolve em nenhum Plugin que o atenda interrompe o build de forma explícita no momento do roteamento.
  4. O provedor é invocado com o contexto de renderização por nó (valores dos pilares, projeções .context.*, os tipos de entrada da Recipe).
  5. O provedor retorna a saída renderizada. O compilador roteia os arquivos renderizados para o montador por (path, provider) indexado pelo directory: avaliado da fronteira unido ao subDirectory: por componente. Duas fronteiras que avaliam para o mesmo caminho sob o mesmo provedor compartilham um montador — o padrão canônico é uma fronteira pai mais duas fronteiras filhas com directory: "{{ .parent_boundary.directory }}" que convergem em uma única montagem mesclada.

Veja ../entities/manifest.md para a forma de despacho por eixo de provedor do Manifest, e ../entities/recipe.md para a declaração de provedor único do lado da Recipe. O modelo de montagem por (path, provider) e a lista de variáveis permitidas dos templates de caminho que controla os caminhos avaliados estão documentados em ../path-template-variables.md.

O contrato de plugins Wasm

A renderização Provider é executada dentro de um sandbox WebAssembly. O compilador Go é o host; o Plugin de renderização de provedores é o guest. Para cada nó, o compilador entrega ao plugin o contexto de renderização do nó, e o plugin retorna os arquivos que renderizou. Esse contrato é uniforme para todos os provedores:

  • Uma codificação binária canônica nas duas direções. O compilador codifica o contexto de renderização — os valores e as vinculações do nó, o .workload analisado, as entradas de artefato avaliadas, a listagem somente de nomes de um .source resolvido e os metadados da fronteira — como CBOR canônico (RFC 8949 §4.2.1) e o entrega ao plugin. O plugin responde na mesma codificação com a lista de arquivos que renderizou — cada um, um caminho relativo à raiz de saída do nó e os bytes exatos a serem gravados ali, opcionalmente com o formato do arquivo — junto com eventuais diagnósticos. Cada export do socket, desde renderizar um nó até montar uma fronteira e fazer a fiação de um vínculo entre fronteiras, carrega essa codificação nas duas direções, e o kit de desenvolvimento de plugins de cada linguagem a decodifica e codifica para o plugin. Uma resposta que não tenha a forma de saída do export nessa codificação interrompe o build. O contrato de plugins documenta o payload de cada export.
  • Sem acesso ao sistema de arquivos. Os Plugins não podem ler arquivos arbitrários do sistema de arquivos do host. Uma fonte que uma Recipe nomeia — um chart em um registro, um módulo em um repositório — é resolvida pelo compilador antes de o plugin ser executado; o plugin recebe uma listagem somente de nomes dela e pede ao compilador os arquivos que seleciona por meio de uma função do host, que responde apenas para arquivos sob a fonte daquele nó.
  • Sem acesso à rede. Os Plugins são determinísticos e herméticos, e não abrem nenhuma conexão própria. Uma entrada externa de que um plugin precisa durante a renderização — um schema remoto referenciado pelos valores de um chart — é solicitada por meio da função do host para entradas externas do compilador, que responde a partir do conteúdo que o espaço de trabalho fixou para essa referência.
  • Saída determinística. Com entrada idêntica e a mesma versão do plugin, um plugin deve produzir saída idêntica byte a byte. Esse é o contrato que faz a garantia de saída idêntica byte a byte do compilador valer de ponta a ponta através da camada de plugins. Um build executado com --verify-determinism renderiza cada nó duas vezes e é interrompido quando as duas renderizações de um nó diferem.

A arquitetura de sockets de plugins no nível mais amplo da extensibilidade, incluindo os outros sockets Wasm no pipeline de compilação (os papéis de transformação e de veredito do socket de governança), está em ../../architecture/14-extensibility.md.

Os provedores da biblioteca padrão do Aggrega

Os provedores helm, helm-chart, compose, terraform e cloudformation formam juntos o conjunto de provedores da biblioteca padrão. Eles cobrem os destinos de implantação comuns sem exigir que equipes corporativas criem seus próprios provedores.

helm suporta os três tipos de entrada: proveniente de uma fonte (um chart Helm upstream obtido por meio do SDK do Helm, com a saída do valuesMapping da Recipe como substituições do chart), sintetizado (YAML plano do Kubernetes — um objeto controlador escolhido pelo form do Workload (Deployment, StatefulSet, DaemonSet, Job ou CronJob) mais Services e PVCs — emitido a partir de um Workload analisado) e artefatos (arquivos YAML independentes ao lado da saída do chart). Veja a Matriz de capacidades por Provider em ../../architecture/16-recipe-input-composition.md para saber quais dos três tipos ele aceita.

helm-chart suporta o modo proveniente de uma fonte (composição de chart guarda-chuva: um chart por fronteira, um subchart por componente) e artifacts: que o acompanham, nas duas formas de autoria. Uma entrada artifacts: carregada por $import: é primeiro processada como template Go pelo Aggrega e depois injetada no diretório templates/ do chart antes da renderização; uma entrada artifacts: com conteúdo em linha é avaliada da mesma forma e colocada na raiz do subchart, sem nenhuma proveniência mesclada, onde os próprios templates do chart a leem via .Files.Get / .Files.Glob do Helm. Uma Recipe independente composta só de artefatos não é um dos tipos que ele declara, e o tipo sintetizado também não: o chart guarda-chuva orquestra subcharts, enquanto o tipo Workload é um conceito folha que pertence a cada subchart (o domínio do provedor helm).

compose suporta proveniente de uma fonte (carrega um arquivo compose e mescla em profundidade a sobreposição do valuesMapping), sintetizado (emite services: + volumes: + networks: do compose a partir de um Workload analisado para as formas stateless e stateful, com tratamento degradado de volumes para persistentTemplate — os PVCs por réplica se reduzem a um único volume nomeado compartilhado, com um aviso; as formas daemon, scheduled e task não têm mapeamento no compose e são interrompidas de forma explícita) e artefatos (fragmentos de compose cujas chaves de nível superior services: / networks: / volumes: / configs: são mescladas no docker-compose.yaml combinado por fronteira). Os artefatos podem acompanhar qualquer um dos outros dois tipos, e uma Recipe independente composta só de artefatos — artifacts: sem source: e sem workload: — também é um tipo que este provedor declara: seus fragmentos são mesclados pelas mesmas regras, de modo que o nó contribui exatamente com o que declara e não precisa de nenhum Workload que faça as vezes de uma computação que ele não tem.

terraform suporta proveniente de uma fonte (incorpora um módulo Terraform tal como está e fornece a saída do valuesMapping como os argumentos do bloco module desse componente na configuração raiz da fronteira) e artefatos (emite um corpo HCL ou .tf.json escrito pelo autor tal como seu template o avalia, sem reescrevê-lo). Ele não oferece o tipo de entrada sintetizado — não existe um mapeamento fiel do tipo Workload da plataforma para recursos Terraform arbitrários. O provedor emite configuração e nunca executa o Terraform; valores dependentes do tempo de execução permanecem como strings de interpolação ${ ... } que o runtime do Terraform resolve no momento do apply.

cloudformation renderiza uma fronteira em um único template de stack do AWS CloudFormation, montando os fragmentos de recursos que seus componentes escrevem em um único template em JSON puro, expondo os provides de cada componente como Outputs do stack e fazendo a fiação das arestas uses como Fn::GetAtt dentro de um stack e como Fn::ImportValue / Fn::GetStackOutput entre stacks. Ele suporta entradas provenientes de uma fonte e de artefatos e emite configuração sem jamais executar o CloudFormation; valores que só existem em tempo de execução permanecem como funções intrínsecas do CloudFormation.

O índice de referência de Provider leva você à página de referência própria de cada provedor; quais tipos de entrada cada um aceita é respondido pela matriz de capacidades em ../../architecture/16-recipe-input-composition.md.

Provedores personalizados

Equipes corporativas que criam seus próprios provedores seguem o mesmo modelo da biblioteca padrão: criar um Plugin de renderização de provedores (pluginType: provider) que declare em spec.provider.capabilities o nome ou os nomes de provedor que ele atende, junto com o restante de seus metadados spec.provider, e então publicar o artefato Wasm que implementa o contrato de renderização descrito acima. O compilador trata provedores personalizados de forma idêntica aos provedores da biblioteca padrão; o despacho por provedor funciona com o nome de provedor declarado pela Recipe.

Como criar um está documentado, não adiado. Criar um provedor constrói de ponta a ponta um guest de provedor funcional — o autorrelato describe(), o build, a entidade Plugin, a vinculação e uma renderização cuja saída você pode ler. O Guia do desenvolvedor de plugins Wasm é a referência para a entidade e o ciclo de vida de publicação, e o contrato de plugins documenta as formas de payload e de resultado de cada socket. Os guests são escritos em Go, Rust ou TypeScript com o kit de desenvolvimento de plugins.