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

Arquitetura de Provider

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

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 a sua saída. Esse modelo é transversal a todos os fornecedores e encontra-se em ../../architecture/16-recipe-input-composition.md, incluindo a Matriz de capacidades de Provider que mapeia que tipo de entrada cada fornecedor suporta.

O Plugin de renderização de fornecedores

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

  • serve um ou mais nomes de fornecedor — declarados em spec.provider.capabilities. O nome de fornecedor que uma Recipe indica (spec.capability: helm) liga-se ao Plugin de renderização de fornecedores cuja lista spec.provider.capabilities inclui esse nome. Quando mais de um Plugin serve o mesmo destino, o espaço de trabalho escolhe entre eles através de uma associação de fornecedor em .aggrega-config.yaml, resolvida em aggrega pull e registada no ficheiro de bloqueio; sem associação e com exatamente um candidato, é usado esse candidato, e sem associação e com mais de um candidato a compilação é interrompida de forma explícita, indicando os plugins candidatos.
  • transporta os seus metadados do socket de fornecedor no mesmo bloco — spec.provider contém a lista de capacidades acima juntamente com o resto das declarações do fornecedor. spec.provider.workloadSchema é uma declaração JSON Schema 2020-12 que documenta a forma como o tipo Workload, pertencente à plataforma, se traduz na saída nativa deste fornecedor; o catálogo da biblioteca standard declara-a nos fornecedores que sintetizam, como o contrato de tradução documentado. spec.provider.wellKnownAnnotations enumera as anotações de fronteira aggrega.ai/ que o fornecedor lê. O suporte de entradas sintetizadas (workload:) é uma propriedade do fornecedor, aplicada no momento da renderização — e não é determinado pela presença de workloadSchema.

Ver ../entities/plugin.md para a superfície de autoria completa, ao nível dos campos, da entidade Plugin, incluindo o bloco spec.provider.

Despacho por fornecedor

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

O caminho de despacho para um único nó:

  1. O compilador resolve o URI da Recipe para este nó através da pesquisa em três níveis do Manifest na secção de mapeamento do fornecedor de destino. O agrupamento pelo eixo de fornecedor do Manifest é o que faz de «o mesmo Component, Recipes diferentes para fornecedores diferentes» um padrão natural.
  2. O spec.capability da Recipe resolvida identifica o nome de fornecedor para o qual despachar.
  3. O compilador liga o fornecedor para esse nome: resolve o Plugin de renderização de fornecedores cuja lista spec.provider.capabilities inclui o nome e renderiza através do guest desse Plugin. A renderização é exclusivamente Wasm — não existe nenhum renderizador dentro do anfitrião ao qual recorrer, pelo que um nome de fornecedor que não se resolva em nenhum Plugin que o sirva interrompe a compilação de forma explícita no momento do encaminhamento.
  4. O fornecedor é invocado com o contexto de renderização por nó (valores dos pilares, projeções .context.*, os tipos de entrada da Recipe).
  5. O fornecedor devolve a saída renderizada. O compilador encaminha os ficheiros renderizados para o montador por (path, provider) indexado pelo directory: avaliado da fronteira unido ao subDirectory: por componente. Duas fronteiras que se avaliam para o mesmo caminho sob o mesmo fornecedor partilham um montador — o padrão canónico é uma fronteira pai mais duas fronteiras filhas com directory: "{{ .parent_boundary.directory }}" que convergem numa única montagem fundida.

Ver ../entities/manifest.md para a forma de despacho por eixo de fornecedor do Manifest, e ../entities/recipe.md para a declaração de fornecedor ú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 de Provider é executada dentro de uma sandbox WebAssembly. O compilador Go é o anfitrião; o Plugin de renderização de fornecedores é o guest. Para cada nó, o compilador entrega ao plugin o contexto de renderização do nó, e o plugin devolve os ficheiros que renderizou. Este contrato é uniforme para todos os fornecedores:

  • Uma codificação binária canónica em ambos os sentidos. O compilador codifica o contexto de renderização — os valores e os anexos do nó, o .workload analisado, as entradas de artefacto avaliadas, a listagem apenas de nomes de um .source resolvido e os metadados da fronteira — como CBOR canónico (RFC 8949 §4.2.1) e entrega-o ao plugin. O plugin responde na mesma codificação com a lista dos ficheiros que renderizou — cada um, um caminho relativo à raiz de saída do nó e os bytes exatos a escrever aí, opcionalmente com o formato do ficheiro — juntamente com eventuais diagnósticos. Cada export do socket, desde a renderização de um nó até à montagem de uma fronteira e à cablagem de uma ligação entre fronteiras, transporta esta codificação em ambos os sentidos, e o kit de desenvolvimento de plugins de cada linguagem descodifica-a e codifica-a para o plugin. Uma resposta que não tenha a forma de saída do export nesta codificação interrompe a compilação. O contrato de plugins documenta o payload de cada export.
  • Sem acesso ao sistema de ficheiros. Os Plugins não podem ler ficheiros arbitrários do sistema de ficheiros do anfitrião. Uma fonte que uma Recipe indica — um chart num registo, um módulo num repositório — é resolvida pelo compilador antes de o plugin ser executado; o plugin recebe uma listagem apenas de nomes dessa fonte e pede ao compilador os ficheiros que seleciona através de uma função do anfitrião, que só responde para ficheiros sob a fonte desse nó.
  • Sem acesso à rede. Os Plugins são determinísticos e herméticos, e não abrem nenhuma ligação própria. Uma entrada externa de que um plugin necessite durante a renderização — um schema remoto referenciado pelos valores de um chart — é pedida através da função do anfitrião 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 tem de produzir uma saída idêntica byte a byte. Este é o contrato que faz com que a garantia de saída idêntica byte a byte do compilador se mantenha de ponta a ponta através da camada de plugins. Uma compilação executada com --verify-determinism renderiza cada nó duas vezes e é interrompida quando as duas renderizações de um nó diferem.

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

Os fornecedores da biblioteca standard do Aggrega

Os fornecedores helm, helm-chart, compose, terraform e cloudformation constituem, juntos, o conjunto de fornecedores da biblioteca standard. Cobrem os destinos de implementação comuns sem exigir que as equipas empresariais criem os seus próprios fornecedores.

helm suporta os três tipos de entrada: proveniente de uma fonte (um chart Helm upstream obtido através 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 artefactos (ficheiros YAML autónomos ao lado da saída do chart). Ver a Matriz de capacidades de Provider em ../../architecture/16-recipe-input-composition.md para saber quais dos três tipos 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, em ambas as 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 qualquer proveniência fundida, onde os próprios templates do chart a leem através de .Files.Get / .Files.Glob do Helm. Uma Recipe autónoma composta apenas por artefactos não é um dos tipos que declara, nem o tipo sintetizado: o chart guarda-chuva orquestra subcharts, enquanto o tipo Workload é um conceito folha que pertence a cada subchart (o domínio do fornecedor helm).

compose suporta proveniente de uma fonte (carrega um ficheiro compose e funde 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 reduzem-se a um único volume com nome partilhado, com um aviso; as formas daemon, scheduled e task não têm correspondência no compose e são interrompidas de forma explícita) e artefactos (fragmentos de compose cujas chaves de nível superior services: / networks: / volumes: / configs: são fundidas no docker-compose.yaml combinado por fronteira). Os artefactos podem acompanhar qualquer um dos outros dois tipos, e uma Recipe autónoma composta apenas por artefactos — artifacts: sem source: e sem workload: — é também um tipo que este fornecedor declara: os seus fragmentos são fundidos segundo as mesmas regras, pelo 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 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 artefactos (emite um corpo HCL ou .tf.json escrito pelo autor tal como o seu template o avalia, sem o reescrever). Não oferece o tipo de entrada sintetizado — não existe uma correspondência fiel do tipo Workload da plataforma para recursos Terraform arbitrários. O fornecedor emite configuração e nunca executa o Terraform; os valores dependentes do tempo de execução permanecem como cadeias de caracteres de interpolação ${ ... } que o runtime do Terraform resolve no momento do apply.

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

O índice de referência de Provider encaminha para a página de referência própria de cada fornecedor; os tipos de entrada que cada um aceita são indicados pela matriz de capacidades em ../../architecture/16-recipe-input-composition.md.

Fornecedores personalizados

As equipas empresariais que criam os seus próprios fornecedores seguem o mesmo modelo da biblioteca standard: criar um Plugin de renderização de fornecedores (pluginType: provider) que declare em spec.provider.capabilities o nome ou os nomes de fornecedor que serve, juntamente com o resto dos seus metadados spec.provider, e depois publicar o artefacto Wasm que implementa o contrato de renderização descrito acima. O compilador trata os fornecedores personalizados de forma idêntica aos fornecedores da biblioteca standard; o despacho por fornecedor funciona com o nome de fornecedor declarado pela Recipe.

A criação de um fornecedor está documentada, e não adiada. Criar um fornecedor constrói de ponta a ponta um guest de fornecedor funcional — a autodescrição describe(), a compilação, a entidade Plugin, o anexo e uma renderização cuja saída é possível ler. O Guia do programador de plugins Wasm é a referência para a entidade e para 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.