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

Referência da linguagem

O “o quê” e o “como usar” do Aggrega. Sintaxe, invocação da CLI, catálogo de erros, exemplos completos.

Leia os capítulos abaixo em ordem para uma primeira compreensão. Os subdiretórios de referência estão listados sob seu capítulo — vá direto a eles ao procurar uma entidade, palavra-chave, provider, comando da CLI ou erro específico.

Antes de ler a sequência de capítulos, consulte Status da linguagem para conhecer o estado atual de maturidade — quais superfícies da linguagem estão disponíveis hoje, quais são aceitas mas ainda não são tratadas pelo compilador e quais estão planejadas para iterações futuras. Compatibilidade informa o que uma release promete para os esquemas, a linha de comando, as ferramentas do assistente, os códigos de erro e os kits de plugin.

Modelo de níveis das entidades

Os tipos de entidade de authoring do Aggrega são organizados em três níveis que refletem a progressão da adoção (abaixo). Ao lado deles fica o Workload, de propriedade da plataforma, que não é um tipo de authoring próprio — é a forma que a entrada sintetizada de uma Recipe assume, expressando a forma de computação por meio do vocabulário form: (stateless, stateful, daemon, scheduled, task, reference). A divisão em níveis é um mecanismo de documentação e de onboarding, não uma restrição de tempo de execução: todo tipo de entidade é um cidadão de primeira classe da linguagem; o compilador os trata de forma uniforme; o Aggrega de código aberto oferece suporte a todos os níveis sem licenciamento nem restrição de funcionalidades. Os marcadores de nível sinalizam “avançado; pule se não precisar” para a navegação, não para a capacidade.

NívelTipos de entidadeQuando adotar
Nível 1 — a superfície mínima viávelAggregate, Component, Recipe, Manifest, ReleaseDia 1 — fundadores solo e equipes pequenas entregam software funcional usando apenas o Nível 1. O modelo mental: “Tenho um app; quero implantá-lo; é assim que se faz.”
Nível 2 — separação de papéisFeature, FeatureRecipe, PluginDia 30 — equipes pequenas em que os papéis se dividem (desenvolvedor + Ops + às vezes Segurança). O Nível 2 entra por meio de Plugins de renderização de providers (Ops escolhe entre Helm, helm-chart, Compose, Terraform e CloudFormation), Features (Segurança gerencia as credenciais separadamente da configuração do app) e FeatureRecipes (personalização no momento do binding, por provider).
Nível 3 — reutilização entre ComponentSchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibraryDia 365 — catálogos maduros em que formas comuns se repetem em muitas entidades. O limiar é informal: quando uma forma (por exemplo, PodResources) aparece em 5+ Components e coordenar as atualizações gera atrito, uma entrada de SchemaLibrary se justifica por si só.

Cada progressão é opcional. Um fundador solo nunca é obrigado a olhar para o Nível 3; um catálogo corporativo tem acesso total ao Nível 3 conforme necessário. O Nível 1 é completo para o caso de uso do fundador solo — um desenvolvedor pode entregar aplicações funcionais usando apenas entidades de Nível 1. É uma propriedade de design forte: o Nível 1 não é um “subconjunto que compila”; é um “subconjunto que entrega software”.

A superfície de Nível 1 com cinco entidades tem um custo de entrada — Aggregate + Component + Recipe + Manifest + Release é mais cerimônia do que “coloque um arquivo YAML, obtenha um serviço em execução”. O custo é o preço da separação do authoring em quatro domínios (Intenção do desenvolvedor / Catálogo da plataforma / Operações da plataforma / Roteamento) que torna o Aggrega diferente de Helm puro ou Terraform puro. Os tutoriais de Nível 1 percorrem explicitamente a configuração com cinco entidades.

Dentro do Nível 3, o mecanismo spec.templates / $instantiate: (helpers paramétricos na SchemaLibrary) é documentado como uma subfuncionalidade ainda mais avançada. A maioria de quem adota o Nível 3 não recorre a spec.templates de início; o limiar é “quando sua biblioteca tem 6+ schemas que compartilham uma estrutura parametrizada”.

Ordem de leitura

  1. Como usar esta referência
  2. Convenções de nomenclatura
  3. Visão geral da referência de entidades
  4. Visão geral do vocabulário
  5. Visão geral dos templates
  6. Visão geral dos Providers
  7. Visão geral da CLI
  8. Visão geral dos erros
  9. Visão geral dos exemplos

Referência para authoring de Plugin

A superfície de plugins Wasm fica ao lado da sequência de capítulos, e não dentro dela: um autor de plugins a lê independentemente do caminho de authoring de entidades. A página da entidade plugin cobre a superfície de authoring do catálogo; as páginas abaixo cobrem os sockets, os payloads e o fluxo de trabalho do autor.

  • plugin-contract — os sockets aos quais um plugin se conecta, sua posição no pipeline e as formas de entrada e saída de cada socket.
  • plugin-developer-guide — o fluxo de trabalho completo do autor: describe(), declarações de capacidade, limites de tempo de execução, o ciclo de vida publish/pull/build, assinatura, versionamento.
  • policy-socket — o socket de governança em profundidade: seus quatro papéis, as severidades dos vereditos, o canal de entrada do operador e como escrever uma policy para qualquer um dos dois motores incluídos no compilador.
  • governance-attachment-facts — os fatos por vinculação que uma policy de governança lê do grafo de build, incluindo as três unidades da marcação de sensibilidade e por que uma marcação ausente não é permissão.
  • when-to-use-a-pipeline-step — como escolher entre uma etapa de pipeline e uma FeatureRecipe baseada em templates.
  • embedded-plugins — os plugins incluídos no binário do compilador.
  • tagging-plugins — os dois plugins de governança integrados que gravam labels sem uma política, governance/label-injector e governance/selector-tagger: suas configurações e o que cada um grava.
  • core-importers — os dez importadores do compilador, de Langflow, Flowise e n8n a Compose, MCP e os frameworks de agentes: o que cada um lê e rascunha, suas configurações e sua publicação a cada release do compilador.
  • authoring-a-provider-walkthrough — um passo a passo prático da criação de um guest provider, de um diretório vazio até um build que grava os arquivos que o provider renderizou.
  • writing-a-governance-plugin — escrever seu próprio plugin de governança a partir do esqueleto de adaptador do kit de plugins: uma regra, o export de cada papel executado à mão, uma entidade Plugin no catálogo do workspace e um build que ele recusa.
  • compatibility — como os kits de plugin são versionados: o que uma release de patch e uma release menor de um kit podem mudar, e o que mantém um plugin já compilado carregando.