Visão geral da referência de entidades
O vocabulário de autoria do Aggrega compreende Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary — mais o tipo Workload detido pela plataforma, incorporado na entrada sintetizada de uma Recipe. Cada entidade é um documento YAML conforme a um JSON Schema; cada campo, palavra-chave e referência entre entidades que esta Referência descreve faz parte desse contrato de autoria.
Este conjunto de capítulos aborda a superfície de autoria: que campos cada entidade aceita, o que cada campo significa para o autor, como os campos interagem entre entidades (o implements: de uma Recipe que nomeia o Component que ela implementa, o ponteiro manifest: de uma Release para um Manifest, o containers.<name>.attachments de um Workload que referencia slots declarados no featuresSchema do Component). O papel conceptual de cada entidade — porque é que a taxonomia tem a forma que tem, que domínio detém que entidade, como os quatro domínios separam as preocupações de autoria — está em ../architecture/04-entity-taxonomy.md. O papel arquitetónico do tipo Workload como um dos três tipos de entrada da Recipe está em ../architecture/16-recipe-input-composition.md.
Como esta referência está organizada
Duas superfícies documentam o vocabulário de autoria, e respondem a perguntas diferentes.
Cada tipo listado acima tem uma referência de esquema gerada. Essas páginas são geradas a partir dos esquemas que o próprio compilador publica, e schema/README.md indexa o conjunto completo — tipos de entidade, formatos de comunicação dos plugins e ficheiros de workspace. A referência de esquema responde a «o que pode este documento conter»: cada campo, o seu tipo, se é obrigatório e as restrições que o envelope impõe.
As páginas abaixo são os guias de autoria. São escritas à mão para ensinar o que o esquema não consegue: para que serve um tipo, como os seus campos interagem com outros tipos, que forma de autoria convém a que situação e as convenções que o catálogo da biblioteca padrão segue. Um guia de autoria responde a «como escrevo um, e porque tem esta forma».
Referência por entidade
- Aggregate — o artefacto de intenção declarativa do programador. Declara os componentes, a sua topologia através de
uses, contratos de parâmetros para variação por ambiente e associações de Feature. - Component — entidade de catálogo escrita pelo arquiteto de plataforma que define um tipo de componente reutilizável. Declara os seus esquemas
valueseinfra(cada um uma declaração JSON Schema 2020-12 em forma compacta ou completa), o seu contrato de outputprovides, o seu contrato de arestas de entradausesSchemae slots de credenciais através defeaturesSchema. - Feature — entidade de catálogo escrita pelo arquiteto de plataforma para uma preocupação transversal (sidecar de monitorização, ocultação de dados, política de encaminhamento). Declara os seus esquemas
valueseinfra(cada um uma declaração JSON Schema 2020-12), seletores de associaçãoappliesToe restrições de interoperabilidade. - Recipe — tradução escrita pela equipa de Ops de um Component para um provider específico. Compõe três tipos de entrada (
source:+valuesMapping:,workload:,artifacts:— cada um a aceitar conteúdo inline ou$import:segundo o vocabulário unificado de importação de ficheiros) mais um blocoprovidesque forma o contrato de injeção do chamador. - FeatureRecipe — tradução escrita pela equipa de Ops de uma Feature para um provider específico. Usa o mesmo contrato de três tipos de entrada que a Recipe, mais um
injectMappingque interceta o pipe de inject para reescrever variáveis do lado do chamador. - Plugin — plugin WebAssembly endereçado por conteúdo. Declara o único tipo de socket que implementa —
provider,linter,pipeline-step,governance,cli,parserouimporter—, a sua versão de ABI e as capacidades que esse tipo de socket serve. Um Plugin de renderização de provider (pluginType: provider) declara o(s) nome(s) de provider que serve emspec.provider.capabilitiese transporta os metadados do seu socket de provider —workloadSchemaewellKnownAnnotations— nesse mesmo blocospec.provider. - Manifest — tabela de mapeamento por projeto. Associa tipos abstratos de Component e Feature a URIs concretos de Recipe e FeatureRecipe, sob
componentsefeatures, com a ordem de pesquisaname>typeversionado >typenão versionado. - Release — router de implementação por ambiente. Associa um Aggregate a um Manifest, mapeia os componentes para fronteiras físicas, fornece valores de parâmetros por ambiente e associa Features geridas pela equipa de Ops.
Entidades de biblioteca
Os quatro tipos de biblioteca são de nível 3 — entidades de reutilização opcionais. Um catálogo declara uma quando o mesmo conteúdo se repete nas suas entidades, e dispensa-as caso contrário. Cada uma contém um tipo de conteúdo, e o fragmento numa referência (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) diz que biblioteca uma referência endereça.
- SchemaLibrary — definições JSON Schema 2020-12 reutilizáveis mais helpers parametrizados opcionais, referenciadas a partir dos esquemas de um Component ou de uma Feature por
$ref: <Library>#/schemas/<name>. - MappingLibrary — fragmentos de template Go reutilizáveis, importados para o
valuesMapping:de uma Recipe ou FeatureRecipe por$import: <Library>#/mappings/<name>. - WorkloadLibrary — conteúdo de Workload reutilizável, importado para o
workload:de uma Recipe ou FeatureRecipe por$import: <Library>#/workloads/<name>. - ArtifactLibrary — pacotes reutilizáveis de ficheiros de saída auxiliares, importados para os
artifacts:de uma Recipe ou FeatureRecipe por$import: <Library>#/artifacts/<name>. Um pacote é a unidade de reutilização: uma importação expande-se numa saída por cada ficheiro do pacote.
Tipos detidos pela plataforma
- Workload — tipo de compilador detido pela plataforma (não uma entidade de catálogo escrita pelo utilizador). Incorporado no campo
workload:de uma Recipe (inline ou via$import:); descreve a forma de implementação que o provider sintetiza em manifestos nativos do provider.