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

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 values e infra (cada um uma declaração JSON Schema 2020-12 em forma compacta ou completa), seu contrato de saída provides, seu contrato de arestas de entrada usesSchema e slots de credenciais via featuresSchema.
  • 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 values e infra (cada um uma declaração JSON Schema 2020-12), seletores de attachment appliesTo e 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 bloco provides que 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 injectMapping que 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, parser ou importer —, 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 em spec.provider.capabilities e traz os metadados do seu socket de provider — workloadSchema e wellKnownAnnotations — nesse mesmo bloco spec.provider.
  • Manifest — tabela de mapeamento por projeto. Vincula os tipos abstratos Component e Feature a URIs concretos de Recipe e FeatureRecipe, sob components e features, com a ordem de busca name > type com versão > type sem 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.