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

A taxonomia de entidades

A arquitetura do Aggrega está organizada em quatro domínios, cada um detido por uma persona diferente e com tipos de entidade específicos, mais uma camada de bibliotecas Tier 3 — o terceiro nível do modelo de níveis de entidades da referência da linguagem — que contém conteúdo reutilizável de esquemas, mapeamentos, cargas de trabalho e artefactos. A visão geral abaixo mostra como os quatro domínios e as bibliotecas Tier 3 se relacionam entre si; cada secção seguinte abre com um diagrama das suas próprias entidades, em que uma entidade de outro domínio é desenhada com um contorno tracejado. As superfícies de criação detalhadas (campos, esquemas, exemplos) de cada entidade encontram-se no catálogo de entidades da referência da linguagem.

graph TD
    Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
    Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
    Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
    Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
    Libs["<b>Tier 3: Libraries</b>"]

    Intent -->|"requests, attaches"| Catalog
    Intent -->|"binds via"| Routing
    Routing -->|"attaches"| Catalog
    Catalog -->|"resolved to"| Infra
    Routing -->|"resolves, renders via"| Infra
    Catalog -.->|"$ref"| Libs
    Infra -.->|"$import"| Libs

O corpus abrange quatro domínios mais a camada de bibliotecas Tier 3:

#EntidadeDomínioPapel
1AggregateDomínio 1 — Intenção do programadorPlanta da topologia da aplicação
2ComponentDomínio 2 — Catálogo da plataformaInterface abstrata de nó de computação
3FeatureDomínio 2 — Catálogo da plataformaTraço operacional (incluindo as Features de credenciais)
4RecipeDomínio 3 — Base de infraestruturaImplementação de Component, por fornecedor
5FeatureRecipeDomínio 3 — Base de infraestruturaImplementação de Feature, por fornecedor
6PluginDomínio 3 — Base de infraestruturaPlugin WebAssembly endereçado por conteúdo (renderização de fornecedor, passos de pipeline, linting)
7ManifestDomínio 4 — Encaminhamento e políticasLockfile de dependências que mapeia interfaces para Recipes
8ReleaseDomínio 4 — Encaminhamento e políticasEncaminhador de implantação que vincula o Aggregate ao Manifest
9SchemaLibraryTier 3 — BibliotecasDefinições JSON Schema 2020-12 reutilizáveis
10MappingLibraryTier 3 — BibliotecasFragmentos de templates Go reutilizáveis
11WorkloadLibraryTier 3 — BibliotecasFragmentos de templates de Workload reutilizáveis
12ArtifactLibraryTier 3 — BibliotecasPacotes de artefactos nomeados reutilizáveis

Essa tabela é o conjunto completo dos tipos de entidade de criação — os tipos que um autor declara num campo kind:. O tipo Workload é conteúdo detido pela plataforma, incorporado na entrada sintetizada de uma Recipe, e não uma entidade de catálogo autónoma (ver o capítulo 16), pelo que está deliberadamente ausente da tabela acima.

O Plugin é uma entidade de criação de primeira classe — com o seu próprio tipo, JSON Schema e diretório de catálogo — detida pelo Platform Ops no Domínio 3. Um Plugin é uma referência endereçada por conteúdo a um artefacto WebAssembly, que declara o único tipo de socket que implementa. A taxonomia tem sete membros: provider (renderiza nós da IR em artefactos nativos do fornecedor), linter (emite diagnósticos sobre o conteúdo criado), pipeline-step (um passo da pipeline de feature-recipe), governance (serve um papel de governação — transformando etiquetas ou anotações, ou devolvendo um veredicto de aceitação/rejeição sobre o grafo da IR ou sobre os artefactos renderizados), cli (contribui com um subcomando aggrega que um operador invoca na linha de comandos), parser (converte um texto de origem externo numa árvore estruturada canónica) e importer (converte uma origem externa de infraestrutura ou de definição de agentes em ficheiros de criação Aggrega preliminares). Um Plugin de renderização de fornecedor (pluginType: provider) é a unidade que serve a renderização do fornecedor: declara o(s) nome(s) de fornecedor que renderiza em spec.provider.capabilities e transporta os restantes metadados do socket de fornecedor nesse mesmo bloco spec.provider. O compilador fixa e encaminha a referência; o runtime WebAssembly executa os bytes; o compilador não interpreta o que o plugin faz — o plugin é o transporte da inteligência específica do domínio que vive em WebAssembly. A sua superfície de criação e de metadados está documentada em language-reference/entities/plugin.md.

Domínio 1: Intenção do programador (o «quê»)

graph LR
    classDef ext stroke-dasharray:5 4;

    A["Aggregate<br/>The 'What'"]
    CC["Component"]:::ext
    CapC["Feature"]:::ext
    EB["Release"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    A -->|"Binds via"| EB
  • Papel: O programador. Concentra-se apenas na arquitetura de IA, nos ciclos cognitivos e nos requisitos de sobrevivência da aplicação. Não precisa de conhecer CEL, OPA nem portas físicas.
  • 1. Aggregate: A planta declarativa, baseada em mapas, da topologia da aplicação. Servindo como o Aggregate raiz que uma Release constrói ou como módulo reutilizável e parametrizado, define components lógicos e anexa, em features, as Features cujo comportamento é intenção da aplicação, com os seus values; uma Feature cujas entradas são todas operacionais é anexada pelo operador na Release (ver o Domínio 4). Uma credencial é pedida nessa mesma superfície de anexação features, através de uma Feature de credenciais — não existe um bloco separado para ela. Define requisitos de capacidade abstratos através de parameters (contratos tipados criados no vocabulário de forma compacta) e o estado do payload através de values. As instâncias de Component suportam um campo description opcional para documentação e para a renderização no Studio. Promove a convenção «Zero-Port» (abstraindo as portas de rede, exceto quando exigidas explicitamente por código legado), sem plataforma de destino nem namespace codificados.

Domínio 2: Catálogo da plataforma (as «interfaces e inteligência»)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release"]:::ext
    CC["Component<br/>The Compute Interface"]
    CapC["Feature<br/>The Operational Trait"]
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    EB -.->|"Attaches"| CapC
    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
  • Papel: O arquiteto de plataforma. O «programador» da plataforma. Coloca cada componente na ontologia operacional, cria as políticas programáveis (mutadores e validadores Wasm) e estabelece as etiquetas semânticas de duck typing.
  • 2. Component: A interface abstrata de um nó de computação. Declara a sua forma base através da ontologia cloud operacional (por exemplo, component.aggrega.ai/type: server) e sobrepõe a sua identidade cognitiva através de etiquetas de duck typing (por exemplo, model.aggrega.ai/capability: generative). Declara slots de credenciais através de featuresSchema (obrigatórios/opcionais, blackbox/transparentes) e usa schema: (JSON Schema 2020-12, normalmente criado com a abreviatura de forma compacta) para validar estritamente o bloco values opaco do programador.
  • 3. Feature: Um traço operacional modular (por exemplo, mascaramento de dados, encaminhamento DNS, gestão de segredos). Usa seletores de etiquetas appliesTo para se vincular dinamicamente a etiquetas semânticas específicas. Tal como os Components, declara slots de credenciais através de featuresSchema para impor o aprovisionamento de chaves de API. Fundamentalmente, usa metadata.annotations para marcar explicitamente elementos no grafo IR plano, o que indica aos validadores de políticas Wasm e aos plugins de renderização a jusante como tratar o payload de configuração da Feature.
    • Features de credenciais: A plataforma unifica a gestão de credenciais na entidade Feature: uma Feature com a etiqueta feature.aggrega.ai/kind: secret é uma funcionalidade de credenciais — define uma interface de consulta sobre um cofre de segredos (por exemplo, AWS Secrets Manager, HashiCorp Vault). É anexada em features: como qualquer outra Feature, na mesma superfície e com a mesma forma; a etiqueta é um metadado que o catálogo transporta para descrever o que a anexação produz, e nenhum ramo do compilador a lê. Não existe um tipo separado de cofre de segredos nem de recipe de segredos: uma FeatureRecipe de credenciais tem a mesma forma que qualquer outra FeatureRecipe, a pipeline de obter-e-entregar é a mesma para ambas e o contrato de entrega inject (env, file, arg) é partilhado. Uma entidade, uma palavra-chave de anexação, um caminho de execução de modificadores ao longo da renderização — e as credenciais mapeiam-se em features.type no Manifest.

Ontologia como etiqueta. A ontologia cloud operacional é declarada em metadata.labels["component.aggrega.ai/type"] e não como um campo spec.type de nível superior. Esta escolha permite ao motor de seletores de etiquetas do compilador visar diretamente os valores da ontologia — uma Feature declara appliesTo: "component.aggrega.ai/type in (server, worker)" para se anexar dinamicamente a todos os componentes server ou worker, sem nova lógica Go no núcleo do compilador. A mesma maquinaria de seletores aplica-se a todas as etiquetas Aggrega, pelo que uma Feature, um seletor de socket ou um mapeamento de fronteira de uma Release lê a chave de etiqueta própria de um catálogo exatamente como lê esta.

component.aggrega.ai/type é a chave do Aggrega, e o seu conjunto de valores é fechado: o esquema publicado do Component enumera as primitivas, e um documento que contenha qualquer outro valor é recusado quando é carregado, com E0215 a indicar a etiqueta e a listar o que aceita. Um catálogo que precise de uma classificação que o Aggrega não define acrescenta a sua própria chave de etiqueta ao lado dela — o esquema do Component aceita qualquer chave de etiqueta adicional com um valor de cadeia —, pelo que um novo eixo custa uma chave própria e nenhuma versão do compilador, enquanto a chave reservada mantém um único significado em todo o lado. É isso que faz com que uma Feature escrita contra component.aggrega.ai/type in (stateful-server) funcione com Components de autores que nunca se conheceram.

Domínio 3: Base de infraestrutura (as «implementações»)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    ENV["Manifest"]:::ext
    EB["Release"]:::ext
    CD["Recipe<br/>The Implementation"]
    CapD["FeatureRecipe<br/>The Binding"]
    T["Plugin<br/>The Wasm Plugin"]

    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
    EB -->|"Renders via"| T
  • Papel: O engenheiro de infraestrutura / Ops. Detém a realidade física, a atribuição de portas de rede e a lógica de templates.
  • 4. Recipe: O template de tradução multifornecedor (por exemplo, Helm ou Docker Compose). Estabelece um contrato de API 1:1 estrito com o componente do catálogo através da palavra-chave implements. A Recipe mapeia os .values do programador para o formato físico. Codifica as portas de rede físicas (por exemplo, 5432) e lê os provides do destino através do pipe .context.uses, satisfazendo o contrato de injeção sem codificar nomes de bases de dados.
  • 5. FeatureRecipe: Mapeia explicitamente uma Feature para uma implementação de infraestrutura concreta através da palavra-chave implements. Exige uma capacidade do fornecedor de destino em capability (por exemplo, helm, compose). Como a plataforma unifica a gestão de credenciais na entidade Feature, as FeatureRecipes tratam tanto funcionalidades operacionais (mascaramento de dados, encaminhamento DNS, injeção de sidecars) como funcionalidades de credenciais (geração de CRD de cofre, montagem de volumes de segredos). Para cobrir todo este espetro, suporta três blocos de execução distintos:
    1. pipeline: Um array sequencial de plugins WebAssembly (Wasm) para a mutação de Workload pós-renderização (por exemplo, injetar um sidecar Envoy através de JSONPatch, ou montar um volume de segredo).
    2. source e valuesMapping, workload, artifacts: Os mesmos três tipos de entrada que uma Recipe transporta, usados para a geração de recursos, permitindo às Ops renderizar templates estáticos de forma nativa (por exemplo, gerar um novo CRD HTTPRoute ou um CRD ExternalSecret) ao lado do componente base.
    3. injectMapping (interceção pré-renderização): Um bloco de template Go nativo executado antes de a Recipe base renderizar. Produz um dicionário JSON que o compilador funde em profundidade, de forma nativa, sobre o pipe de memória .context.inject do chamador, permitindo a mutação do lado do chamador, sem Wasm, de variáveis de ambiente e cadeias de ligação.
    • O padrão de FeatureRecipe de credenciais: Quando uma FeatureRecipe implementa uma Feature de credenciais (com a etiqueta feature.aggrega.ai/kind: secret), aplica-se o princípio padrão do Plugin em duas partes: a pipeline encadeia um plugin Fetcher (que gera o CRD específico do cofre) seguido de um plugin Injector (que monta o segredo no contentor de destino). A divisão Fetcher/Injector maximiza a reutilização — mudar de AWS Secrets Manager para HashiCorp Vault só exige substituir o plugin Fetcher; o Injector permanece idêntico.
  • 6. Plugin: O plugin WebAssembly endereçado por conteúdo. Um Plugin de renderização de fornecedor (pluginType: provider) é a unidade que transforma os tipos de entrada de uma Recipe no formato final de ficheiro em cadeia: declara o(s) nome(s) de fornecedor que serve em spec.provider.capabilities (por exemplo, helm), anunciando uma exportação render_node para a qual o compilador despacha, e transporta os restantes metadados do socket de fornecedor (workloadSchema, wellKnownAnnotations) nesse mesmo bloco spec.provider. Os outros tipos de socket que um Plugin pode declarar são pipeline-step, linter, governance, cli, parser e importer. O compilador encaminha a referência fixada; o runtime WebAssembly executa os bytes.

Domínio 4: Encaminhamento e políticas (a «cola»)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release<br/>The Deployment Router"]
    ENV["Manifest<br/>The Dependency Lockfile"]
    CapC["Feature"]:::ext
    T["Plugin"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -->|"Binds via"| EB
    EB -.->|"Attaches"| CapC
    EB -->|"Uses"| ENV
    EB -->|"Renders via"| T
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
  • Papel: O operador de plataforma / DevOps.
  • 7. Manifest: O lockfile de dependências. Usa um mapeamento plano de URI: um dicionário components.type mapeia os tipos de componentes do catálogo para URI de Recipes, e um dicionário features.type mapeia os tipos de Feature para URI de FeatureRecipes. A resolução é uma pesquisa direta de URI no lockfile + catálogo; a determinação da capacidade decorre do campo spec.capability de cada Recipe resolvida, no momento da compilação. Após a resolução, cada entidade tem de ter um mapeamento, ou o compilador interrompe-se. Para manter um ecossistema DRY, os Manifests suportam um padrão de composição ao estilo Kustomize através de uma palavra-chave extends, permitindo que manifestos específicos de um ambiente (como local ou staging) herdem de forma limpa de um manifesto base global e declarem apenas as suas substituições específicas.
  • 8. Release: O encaminhador. Vincula um aggregate a um manifest e mapeia componentes para fronteiras físicas (por exemplo, aws-eks-production). Para manter um fluxo de trabalho DRY, as Releases suportam herança através da palavra-chave extends, permitindo que as versões específicas de um ambiente herdem de forma limpa de uma versão base global. Cumpre o contrato abstrato do aggregate injetando realidades físicas estritamente no bloco parameters, e injeta o dimensionamento físico (como CPU ou portas) através do namespace paralelo infra. Para proteger o Aggregate como fonte única de verdade, o esquema da Release proíbe mecanicamente um bloco values: — o Ops não pode declarar values em nenhum Component nem Feature a partir de uma Release. A variação por ambiente dos valores visíveis para o programador flui através do Parameter Hoisting: o programador expõe um campo tipado parameters.* no Aggregate, o template values do Component referencia-o e a Release cumpre o parâmetro para o seu ambiente. Os valores renderizados diferem entre ambientes, enquanto o Aggregate — a superfície de criação de quais valores existem e de como fluem — permanece a fonte única de verdade. Ver a restrição 4, «A Release não pode substituir os valores do programador», em Restrições arquiteturais e padrões recomendados para a proibição a nível de esquema declarada explicitamente. Fundamentalmente, para evitar Releases «que mutam o aggregate» impossíveis de rastrear, quando uma Release usa extends, declarar um aggregate é rejeitado pelo esquema da Release (a restrição do esquema não permite declarar aggregate quando se usa extends). A versão filha tem de mapear para exatamente a mesma intenção do programador que a sua mãe. O manifest, no entanto, torna-se opcional, desbloqueando o «Late Binding» — permitindo ao Ops herdar toda a topologia física, mas trocar cirurgicamente o lockfile de dependências.
    • Anexação de Features: A Release também anexa Features, em features numa fronteira ou num componente. Uma Feature cujas entradas são todas operacionais é anexada diretamente, com o seu type e o seu infra; uma Feature que o Aggregate anexou é dimensionada pela Release, que escreve o infra dessa anexação sob o mesmo nome.

Porquê separar o Manifest da Release. Separar o lockfile de software (Manifest) do encaminhador de implantação (Release) permite uma forma que as duas entidades não conseguiriam produzir sozinhas: o DevOps implanta uma única aplicação em vários encaminhadores de implantação regionais — Releases diferentes que visam regiões cloud diferentes, todas a referenciar o mesmo Manifest — sem duplicar as vinculações de Recipe entre ambientes. Cada Release regional transporta a sua disposição de fronteiras e os parâmetros específicos do ambiente, consumindo o mesmo lockfile de software que o Manifest fornece. A escala multirregião decorre da separação de domínios, não da duplicação do Manifest.

Tier 3: Bibliotecas (reutilização do catálogo)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext
    SL["SchemaLibrary<br/>JSON Schema definitions"]
    ML["MappingLibrary<br/>Go template fragments"]
    WL["WorkloadLibrary<br/>Workload template fragments"]
    AL["ArtifactLibrary<br/>Named artifact bundles"]

    CC -.->|"$ref"| SL
    CapC -.->|"$ref"| SL
    CD -.->|"valuesMapping $import"| ML
    CapD -.->|"$import"| ML
    CD -.->|"workload $import"| WL
    CD -.->|"artifacts $import"| AL
    CapD -.->|"$import"| AL
  • Papel: O arquiteto de plataforma (a mesma persona do Domínio 2), mas o papel só entra em ação quando o conteúdo do catálogo cresce o suficiente para beneficiar da reutilização de esquemas de Component para Component ou da reutilização, de Recipe para Recipe, de templates, formas de carga de trabalho ou pacotes de artefactos. Autores individuais e catálogos pequenos funcionam sem quaisquer entidades Tier 3.
  • 9. SchemaLibrary: Definições JSON Schema 2020-12 reutilizáveis. Uma biblioteca declara esquemas nomeados em spec.schemas: e helpers parametrizados opcionais em spec.templates: (com declarações $params: e referências $instantiate: para reutilização paramétrica). As entidades do catálogo consomem entradas da biblioteca através da palavra-chave padrão do JSON Schema $ref:, apontando para a entrada da biblioteca pela identidade — a forma sem host <library>#/schemas/<name> (a versão vem do lockfile, não da referência). Nomenclatura PascalCase, distribuição por OCI, fixação no lockfile. Opcional para catálogos que precisam de reutilizar esquemas de Component para Component — formas comuns como PodResources, PersistenceSpec, NodePool, MetricsServiceMonitor repetem-se em cada Component de armazenamento de dados e em cada Component de carga de trabalho, e as entradas de SchemaLibrary eliminam essa repetição da criação por Component.
  • 10. MappingLibrary: Fragmentos de templates Go reutilizáveis. Uma biblioteca declara templates nomeados em spec.mappings:. As Recipes e as FeatureRecipes consomem entradas da biblioteca pela identidade através de valuesMapping: { $import: <library>#/mappings/<name> }. Modo de criação único (apenas templates Go); não existe um caminho paralelo de criação em Jsonnet. Opcional para catálogos que precisam de reutilizar mapeamentos de Recipe para Recipe — padrões comuns, como a lógica de helpers de charts Bitnami ou padrões partilhados de pod template, repetem-se em cada Recipe de armazenamento de dados que vise o mesmo fornecedor, e as entradas de MappingLibrary eliminam essa repetição da criação por Recipe.
  • 11. WorkloadLibrary: Fragmentos de templates de Workload reutilizáveis. Uma biblioteca declara entradas de carga de trabalho nomeadas em spec.workloads:. Uma Recipe consome uma entrada pela identidade através de workload: { $import: <library>#/workloads/<entry> }, e o corpo importado é validado contra o esquema de Workload detido pela plataforma exatamente como um bloco workload: inline — pelo que uma carga de trabalho importada de uma biblioteca é renderizada de forma idêntica à equivalente inline. Modo de criação único (apenas templates Go). Opcional para catálogos que precisam de reutilizar cargas de trabalho de Recipe para Recipe, quando várias Recipes partilham uma forma de implantação e apenas os seus valores diferem.
  • 12. ArtifactLibrary: Pacotes de artefactos nomeados reutilizáveis. Uma biblioteca declara pacotes nomeados em spec.artifacts:, cada um a agrupar os ficheiros de saída que pertencem juntos — um CRD, o seu RBAC e um ConfigMap, por exemplo — e importado como uma unidade. As Recipes e as FeatureRecipes consomem um pacote pela identidade através de artifacts.<name>: { $import: <library>#/artifacts/<name> }. Modo de criação único (apenas templates Go). Opcional para catálogos que precisam de reutilizar artefactos de Recipe para Recipe, quando o mesmo conjunto de recursos auxiliares acompanha muitas Recipes.

Todas as bibliotecas são publicadas por OCI, fixadas no lockfile (as secções schema_libraries:, mapping_libraries:, workload_libraries: e artifact_libraries:) e apresentadas na UI do Hub com conhecimento dos consumidores (que Components referenciam que entradas de biblioteca; que Recipes consomem que entradas de biblioteca).