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

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