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:
| # | Entidade | Domínio | Papel |
|---|---|---|---|
| 1 | Aggregate | Domínio 1 — Intenção do programador | Planta da topologia da aplicação |
| 2 | Component | Domínio 2 — Catálogo da plataforma | Interface abstrata de nó de computação |
| 3 | Feature | Domínio 2 — Catálogo da plataforma | Traço operacional (incluindo as Features de credenciais) |
| 4 | Recipe | Domínio 3 — Base de infraestrutura | Implementação de Component, por fornecedor |
| 5 | FeatureRecipe | Domínio 3 — Base de infraestrutura | Implementação de Feature, por fornecedor |
| 6 | Plugin | Domínio 3 — Base de infraestrutura | Plugin WebAssembly endereçado por conteúdo (renderização de fornecedor, passos de pipeline, linting) |
| 7 | Manifest | Domínio 4 — Encaminhamento e políticas | Lockfile de dependências que mapeia interfaces para Recipes |
| 8 | Release | Domínio 4 — Encaminhamento e políticas | Encaminhador de implantação que vincula o Aggregate ao Manifest |
| 9 | SchemaLibrary | Tier 3 — Bibliotecas | Definições JSON Schema 2020-12 reutilizáveis |
| 10 | MappingLibrary | Tier 3 — Bibliotecas | Fragmentos de templates Go reutilizáveis |
| 11 | WorkloadLibrary | Tier 3 — Bibliotecas | Fragmentos de templates de Workload reutilizáveis |
| 12 | ArtifactLibrary | Tier 3 — Bibliotecas | Pacotes 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
componentslógicos e anexa, emfeatures, as Features cujo comportamento é intenção da aplicação, com os seusvalues; 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çãofeatures, através de uma Feature de credenciais — não existe um bloco separado para ela. Define requisitos de capacidade abstratos através deparameters(contratos tipados criados no vocabulário de forma compacta) e o estado do payload através devalues. As instâncias de Component suportam um campodescriptionopcional 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 defeaturesSchema(obrigatórios/opcionais, blackbox/transparentes) e usaschema:(JSON Schema 2020-12, normalmente criado com a abreviatura de forma compacta) para validar estritamente o blocovaluesopaco do programador. - 3. Feature: Um traço operacional modular (por exemplo, mascaramento de dados, encaminhamento DNS, gestão de segredos). Usa seletores de etiquetas
appliesTopara se vincular dinamicamente a etiquetas semânticas específicas. Tal como os Components, declara slots de credenciais através defeaturesSchemapara impor o aprovisionamento de chaves de API. Fundamentalmente, usametadata.annotationspara 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 emfeatures: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 entregainject(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 emfeatures.typeno Manifest.
- Features de credenciais: A plataforma unifica a gestão de credenciais na entidade Feature: uma Feature com a etiqueta
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.valuesdo programador para o formato físico. Codifica as portas de rede físicas (por exemplo,5432) e lê osprovidesdo 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
Featurepara uma implementação de infraestrutura concreta através da palavra-chaveimplements. Exige uma capacidade do fornecedor de destino emcapability(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: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).sourceevaluesMapping,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 CRDHTTPRouteou um CRDExternalSecret) ao lado do componente base.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.injectdo 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: apipelineencadeia 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 emspec.provider.capabilities(por exemplo,helm), anunciando uma exportaçãorender_nodepara a qual o compilador despacha, e transporta os restantes metadados do socket de fornecedor (workloadSchema,wellKnownAnnotations) nesse mesmo blocospec.provider. Os outros tipos de socket que um Plugin pode declarar sãopipeline-step,linter,governance,cli,parsereimporter. 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.typemapeia os tipos de componentes do catálogo para URI de Recipes, e um dicionáriofeatures.typemapeia 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 campospec.capabilityde 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-chaveextends, 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
aggregatea ummanifeste 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-chaveextends, 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 blocoparameters, e injeta o dimensionamento físico (como CPU ou portas) através do namespace paraleloinfra. Para proteger o Aggregate como fonte única de verdade, o esquema da Release proíbe mecanicamente um blocovalues:— o Ops não pode declararvaluesem 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 tipadoparameters.*no Aggregate, o templatevaluesdo 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 usaextends, declarar umaggregateé rejeitado pelo esquema da Release (a restrição do esquema não permite declararaggregatequando se usaextends). A versão filha tem de mapear para exatamente a mesma intenção do programador que a sua mãe. Omanifest, 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
featuresnuma fronteira ou num componente. Uma Feature cujas entradas são todas operacionais é anexada diretamente, com o seutypee o seuinfra; uma Feature que o Aggregate anexou é dimensionada pela Release, que escreve oinfradessa anexação sob o mesmo nome.
- Anexação de Features: A Release também anexa Features, em
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 emspec.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 comoPodResources,PersistenceSpec,NodePool,MetricsServiceMonitorrepetem-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 devaluesMapping: { $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 deworkload: { $import: <library>#/workloads/<entry> }, e o corpo importado é validado contra o esquema de Workload detido pela plataforma exatamente como um blocoworkload: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 deartifacts.<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).