Visão geral da referência de entidades
O vocabulário de escrita do Aggrega compreende Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary e ArtifactLibrary — além do tipo Workload, de propriedade da plataforma, incorporado na entrada sintetizada de uma Recipe. Cada entidade é um documento YAML em conformidade com um JSON Schema; cada campo, palavra-chave e referência entre entidades que esta referência descreve faz parte desse contrato de escrita.
Este conjunto de capítulos cobre a superfície de escrita: quais 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, containers.<name>.attachments de um Workload que referencia slots declarados no featuresSchema do Component). O papel conceitual de cada entidade — por que a taxonomia tem a forma que tem, qual domínio é dono de qual entidade, como os quatro domínios separam as responsabilidades de escrita — está descrito em ../architecture/04-entity-taxonomy.md. O papel arquitetural do tipo Workload como um dos três tipos de entrada de uma Recipe está descrito em ../architecture/16-recipe-input-composition.md.
Como esta referência está organizada
Duas superfícies documentam o vocabulário de escrita, e elas respondem a perguntas diferentes.
Cada tipo listado acima tem uma referência de schema gerada. Essas páginas são geradas a partir dos schemas que o próprio compilador publica, e schema/README.md indexa o conjunto completo — tipos de entidade, formatos de transmissão dos plugins e arquivos do workspace. Recorra à referência de schema para responder a “o que este documento pode conter”: cada campo, seu tipo, se é obrigatório e as restrições que o envelope impõe.
As páginas abaixo são os guias de escrita. Elas são escritas à mão para ensinar o que o schema não consegue: para que serve um tipo, como seus campos interagem com outros tipos, qual forma de escrita se adapta a qual situação e as convenções que o catálogo da biblioteca padrão segue. Recorra a um guia de escrita para responder a “como escrevo um, e por que ele tem essa forma”.
Referência por entidade
- Aggregate — o artefato de intenção declarativa do desenvolvedor. Declara os componentes, sua topologia via
uses, contratos de parâmetros para variação por ambiente e attachments de Feature. - Component — entidade de catálogo escrita pelo Platform Architect que define um tipo de componente reutilizável. Declara seus schemas
valueseinfra(cada um uma declaração JSON Schema 2020-12 em forma compacta ou completa), seu contrato de saídaprovides, seu contrato de arestas de entradausesSchemae slots de credenciais viafeaturesSchema. - Feature — entidade de catálogo escrita pelo Platform Architect para uma responsabilidade transversal (sidecar de monitoramento, mascaramento de dados, política de roteamento). Declara seus schemas
valueseinfra(cada um uma declaração JSON Schema 2020-12), seletores de attachmentappliesToe restrições de interoperabilidade. - Recipe — tradução escrita por Ops de um Component para um provider específico. Compõe três tipos de entrada (
source:+valuesMapping:,workload:,artifacts:— cada um aceita conteúdo inline ou$import:segundo o vocabulário unificado de importação de arquivos) mais um blocoprovidesque forma o contrato de injeção para o chamador. - FeatureRecipe — tradução escrita por Ops de uma Feature para um provider específico. Usa o mesmo contrato de três tipos de entrada da Recipe, mais um
injectMappingque intercepta 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—, sua versão de ABI e as capacidades que esse tipo de socket atende. Um Plugin de renderização de provider (pluginType: provider) declara o nome ou os nomes de provider que atende emspec.provider.capabilitiese traz os metadados do seu socket de provider —workloadSchemaewellKnownAnnotations— nesse mesmo blocospec.provider. - Manifest — tabela de mapeamento por projeto. Vincula os tipos abstratos Component e Feature a URIs concretos de Recipe e FeatureRecipe, sob
componentsefeatures, com a ordem de buscaname>typecom versão >typesem versão. - Release — roteador de implantação por ambiente. Vincula um Aggregate a um Manifest, mapeia componentes em fronteiras físicas, fornece valores de parâmetros por ambiente e anexa Features gerenciadas por 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 em suas entidades, e dispensa-as caso contrário. Cada uma contém um único tipo de conteúdo, e o fragmento em uma referência (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) indica qual biblioteca a referência endereça.
- SchemaLibrary — definições JSON Schema 2020-12 reutilizáveis mais helpers parametrizados opcionais, referenciados a partir dos schemas de um Component ou de uma Feature por
$ref: <Library>#/schemas/<name>. - MappingLibrary — fragmentos de templates Go reutilizáveis, importados no
valuesMapping:de uma Recipe ou de uma FeatureRecipe por$import: <Library>#/mappings/<name>. - WorkloadLibrary — conteúdo Workload reutilizável, importado no
workload:de uma Recipe ou de uma FeatureRecipe por$import: <Library>#/workloads/<name>. - ArtifactLibrary — pacotes reutilizáveis de arquivos de saída auxiliares, importados nos
artifacts:de uma Recipe ou de uma FeatureRecipe por$import: <Library>#/artifacts/<name>. Um pacote é a unidade de reutilização: uma importação se expande em uma saída por arquivo do pacote.
Tipos de propriedade da plataforma
- Workload — tipo do compilador de propriedade da plataforma (não uma entidade de catálogo escrita pelo usuário). Incorporado no campo
workload:de uma Recipe (inline ou via$import:); descreve a forma de implantação que o provider sintetiza em manifestos nativos do provider.