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

extends e implements

Herança via extends

As entidades do catálogo (Component, Feature) oferecem suporte a herança simples por meio da palavra-chave extends, que permite aos arquitetos de plataforma construir entidades especializadas sobre uma base compartilhada. A mesclagem profunda do envelope YAML é comum aos dois tipos: os metadados, os rótulos e as tabelas estruturais declarativas da entidade que estende sobrescrevem as chaves correspondentes na base, e os mapas aninhados são mesclados recursivamente. Os dois tipos se separam nos pilares de dados.

Esta página trata dos tipos do catálogo, e eles não são os únicos tipos que declaram extends. Uma Release e um Manifest também o declaram, e ambos são documentos do lado da implantação escritos um ao lado do outro, em vez de entidades indexadas no catálogo — por isso as suas referências nomeiam arquivos, não entidades do catálogo, e o que é mesclado é uma superfície de autoria, não um esquema. Para eles, veja entities/release.md e entities/manifest.md.

O extends de um Component compõe a estrutura e herda os pilares por inteiro

Para um Component, extends compõe metadata.labels, metadata.annotations, spec.featuresSchema (slots de vinculação), spec.usesSchema (sockets de topologia) e spec.inject (a allowlist do self-inject, cujas entradas são concatenadas começando pela base e sem duplicatas). Os três pilares de dados — values, infra, provides — não são compostos. Um Component que estende não escreve conteúdo de pilar: ele escreve o marcador literal schema: inherited e recebe o bloco schema: da base exatamente como a base o escreveu, em qualquer profundidade de uma cadeia.

O esquema Component publicado torna esse marcador ao mesmo tempo obrigatório e exclusivo, e rejeita cada desvio em relação a ele quando o documento é carregado, com um diagnóstico próprio para cada um: conteúdo de pilar escrito sob schema: em um Component que declara extends:; schema: omitido por completo nesse caso; e schema: inherited em um Component que não declara nenhum extends:.

Daí decorrem duas consequências, e elas puxam em direções opostas:

  • O conjunto de chaves é fixado pela base. Um Component que estende não declara chaves de pilar, então não pode ocultar, remover ou mudar o tipo de uma que a base declara, e não acrescenta nenhuma própria. Uma instância da base e uma instância de qualquer coisa que a estenda são validadas contra o mesmo contrato de pilar.
  • O reforço passa para assertions:. Uma especialização que precisa admitir menos do que os pilares herdados admitem diz isso como um predicado sobre si mesma, não como uma folha de esquema restringida. Se uma base core/base-server declara tls_enabled: { type: boolean, default: true }, uma especialização que exige TLS incondicionalmente escreve:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/tls-only-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
extends: core/base-server
schema: inherited # values, infra and provides are the base's, verbatim
assertions:
tls-is-mandatory: |
{{- if not .values.tls_enabled -}}
{{- fail "this component requires tls_enabled: true" -}}
{{- end -}}

A regra rejeita um valor que o bloco de pilar herdado aceita, que é exatamente o que reforçar significa aqui. A direção inversa não tem nenhuma expressão: uma especialização não pode relaxar uma restrição herdada, porque não pode reformular a folha que a carrega. Veja entities/component.md “Catalog Authoring: Extending Base Components (Autoria de catálogo: estendendo Components base)” para a tabela de composição completa e o par completo de base e extensão.

O extends de uma Feature compõe os seus pilares

Para uma Feature, o schema: da filha se compõe com o da base segundo a semântica de composição do JSON Schema 2020-12, produzindo um único esquema mesclado contra o qual uma instância escrita é validada. As Features de credenciais — aquelas com o rótulo feature.aggrega.ai/kind: secret — usam isso para construir sobre uma base compartilhada: uma Feature de credenciais filha estende um pai para herdar o seu esquema de consulta ao vault enquanto estreita as restrições.

O compilador não toma posição sobre a direção dessa mudança. A composição é estrutural, então uma restrição da filha que amplia a da base é composta sem interromper o build e aparece como um aviso. Nada a rejeita: a restrição de uma base de Feature é uma expectativa compartilhada que os autores do catálogo mantêm por meio de revisão, não um contrato que a plataforma faz cumprir.

Ligação de interface por meio de implements

As Recipes e as FeatureRecipes se ligam a uma interface de Component ou de Feature por meio da palavra-chave implements: no topo do seu spec. A ligação declara de qual interface do catálogo esta Recipe / FeatureRecipe é a implementação concreta, e oferece suporte a três formas de correspondência de versões:

  • Exata — implements: core/api-server:1.0.0 — corresponde a uma versão específica do tipo de Component.
  • Intervalo compatível com a versão principal — implements: core/api-server:^1.0.0 — corresponde a qualquer versão que satisfaça >=1.0.0, <2.0.0 (compatível com a versão principal segundo o SemVer). Usado quando uma Recipe oferece suporte a um intervalo compatível em vez de uma única versão fixada.
  • Sem versão — implements: core/api-server — corresponde a qualquer versão do tipo de Component. Usado quando uma Recipe atende a todas as versões do tipo.

implements: nunca seleciona uma Recipe: quem faz isso é o mapeamento do Manifest. O que a declaração determina é a verificação de consistência em cada entrada de mapeamento — a versão do tipo mapeado deve satisfazer o implements: da Recipe mapeada em uma das três formas, ou a Recipe deve implementar uma base que esse tipo estende — e a lista de candidatos que o diagnóstico de mapeamento ausente e o preenchimento automático do editor oferecem. Uma entrada de mapeamento cuja Recipe tem um implements: que não corresponde nem ao tipo mapeado nem a nenhuma das suas bases interrompe o build, nomeando o mapeamento, a Recipe e o seu valor implements:. Onde uma chave components.type alcança uma instância de componente em uma versão que a chave não nomeia — todas as instâncias, para uma chave escrita sem versão —, a verificação é feita novamente com o tipo próprio dessa instância, na versão com que o build a compila, e uma Recipe que não a satisfaz interrompe o build da mesma forma, nomeando a instância.

A ligação implements: é o mecanismo que faz funcionar “o mesmo tipo de Component, Recipes diferentes para provedores diferentes”: um Component core/postgres pode ter uma Recipe que o implementa para o provedor helm e outra Recipe que o implementa para o provedor compose. Cada Recipe declara o mesmo valor implements:, e o Manifest com o qual uma Release faz o build mapeia o tipo para a que ela deseja.

Uma Recipe escrita para uma base atende tudo o que a estende

implements: nomeia uma base, e uma Recipe que nomeia uma é a implementação concreta para todo Component que estende essa base, em qualquer profundidade da cadeia. Assim, uma especialização construída com extends não precisa de uma Recipe própria — e é isso que torna barato consumir um wrapper publicado: a equipe que o publica escreve um Component, e as equipes que o implantam reutilizam as Recipes da base em todos os destinos.

Aqui valem dois fatos ao mesmo tempo, e eles são separados. Um leitor que os reduz a “a especialização não precisa de nada” escreve um Manifest que falha, por um motivo que vai procurar no arquivo errado:

  • A Recipe corresponde. A verificação de consistência entre a chave de tipo de um mapeamento do Manifest e o implements: da Recipe mapeada aceita o mapeamento quando a Recipe implementa o próprio tipo mapeado ou qualquer base que esse tipo estende. As três formas de versão acima se aplicam a uma base exatamente como ao próprio tipo: uma Recipe que declara implements: core/base-server:^1.0.0 satisfaz uma especialização cuja base está na versão 1.4.0, e não satisfaz uma cuja base está em 2.0.0.
  • O Manifest ainda mapeia o tipo próprio da especialização. A seleção da Recipe é feita pela chave de mapeamento exata. Uma instância de enterprise/labelled-server precisa da sua própria entrada mappings.components.type; ela não herda a entrada escrita para core/base-server. Uma especialização sem entrada própria é interrompida com o diagnóstico de instância não mapeada mesmo quando a sua base está mapeada.

O custo de autoria de uma especialização é, portanto, uma linha de Manifest e nenhuma Recipe nova:

# The wrapper extends core/base-server and authors no pillars.
# core/helm/base-server declares: implements: core/base-server
spec:
mappings:
components:
type:
enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0

Quando a cadeia extends do tipo mapeado não pode ser percorrida — ela forma um ciclo, ou uma base que ela nomeia está ausente do catálogo —, o build é interrompido nessa falha da cadeia em vez de no mapeamento, porque um mapeamento não pode ser avaliado até que a cadeia da qual depende seja resolvida. A verificação percorre a cadeia apenas pelos Components que já estão nesta máquina — os de um diretório de catálogo e os que o cache local de artefatos guarda sob um pin do lockfile — e nunca consulta um registry, então uma base guardada apenas por um registry conta aqui como ausente. Buscá-la é o que aggrega pull faz: uma base é uma dependência de tudo o que a estende, então um pull segue toda cadeia extends: que a Release alcança, busca cada base que nenhum diretório de catálogo guarda e a fixa no lockfile, onde o build seguinte a encontra. O Manifest não precisa de nenhuma linha para a própria base, a menos que um Aggregate também declare uma instância da base.

As sugestões de Recipe continuam mais restritas do que essa regra de correspondência. A lista de candidatos que um diagnóstico de mapeamento ausente imprime, e a ordenação que o preenchimento automático do editor aplica a um valor de mapeamento, nomeiam as receitas que implementam o próprio tipo solicitado; elas não se ampliam para receitas que implementam uma das suas bases.

Para um passo a passo completo e executável — um wrapper publicado no catálogo, a única linha de Manifest que o consome, a Recipe da base dando forma à sua saída renderizada, e a interrupção que uma instância do wrapper sem mapeamento próprio produz —, veja o exemplo completo examples/extends-wrapper/.

Consumo de versões entre entidades

Todo tipo de entidade do Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — carrega um campo obrigatório metadata.version validado contra a mesma regex SemVer (MAJOR.MINOR.PATCH conforme architecture/02-ecosystem-philosophy.md). As versões são uniformes na forma; o consumo das versões varia por tipo de entidade. Algumas versões participam ativamente da resolução; outras são proveniência descritiva contra a qual o compilador não faz correspondência. A tabela abaixo cobre os tipos que não são bibliotecas, nomeando o que o compilador faz com o campo de versão de cada entidade e usando a taxonomia de status de quatro rótulos de 10-status.md para classificar cada regime de consumo. Os quatro tipos de biblioteca ficam fora da tabela porque o seu regime é uniforme e diferente: um consumidor referencia uma biblioteca pelo nome simples, pode afirmar um piso de versão mínima opcional :<version>, e o lockfile por Release detém a versão resolvida e o seu digest de conteúdo.

EntidadeRegime de consumoStatus
ComponentResolução de referências de tipo; correspondência de implements: da Recipeavailable — formas exata, de intervalo caret (^MAJOR.MINOR.PATCH) e sem versão em ambos (veja Resolução de versões e Status da linguagem → Correspondência de versões)
FeatureResolução de referências de vinculação; correspondência de implements: da FeatureRecipeIgual a Component
RecipeResolução dos níveis de mapeamento do Manifestavailable — formas exata, de intervalo caret e sem versão em um valor de mapeamento, cada uma selecionando a versão mais alta que a satisfaz
FeatureRecipeResolução dos níveis de mapeamento do ManifestIgual a Recipe
AggregateResolução da referência aggregates[].type do paiavailable — formas exata, de intervalo caret e sem versão, cada uma selecionando a versão mais alta que a satisfaz (veja Resolução de versões)
PluginDespacho do Provider por meio de recipe.spec.capability → spec.provider.capabilitiesavailable — a capacidade simples seleciona o provedor, e um pin sobre ela (helm:<version>, helm:^<version>) seleciona qual versão desse plugin renderiza; a identidade do plugin é a referência oci://<repository> sem digest mais metadata.version, e o digest de conteúdo é registrado no lockfile da release contra o qual o build verifica os bytes baixados
ManifestProveniência do grafo IR (manifest_version)available (lido apenas para a proveniência; nenhum papel no despacho da resolução)
ReleaseProveniência do grafo IR (release_version) + metadados de template (.metadata.release_version)Igual a Manifest

Regimes de resolução do catálogo (Component, Feature, Aggregate, Plugin). Uma referência a um desses tipos — o type de um componente, o type de uma vinculação de funcionalidade, o aggregates[].type de uma importação de subagregado, o plugin de uma etapa de pipeline — é resolvida pela regra que Resolução de versões ensina: uma referência exata, de intervalo caret ou sem versão seleciona a versão mais alta que a satisfaz entre as que o catálogo contém, e o pull, o build, uma validação, o editor e as ferramentas voltadas ao assistente aplicam essa única regra da mesma forma. Para um Component ou uma Feature, a correspondência de implements: lê as mesmas três formas na direção oposta — uma versão concreta do tipo contra a forma que uma Recipe ou uma FeatureRecipe declara — como a verificação de consistência descrita abaixo, não como uma seleção. O despacho para o plugin de renderização do Provider usa uma forma mais simples: ele procura pelo nome a recipe.spec.capability simples nas spec.provider.capabilities do plugin de renderização do provedor, e um pin de versão escrito sobre a capacidade seleciona qual versão desse plugin renderiza, interrompendo quando nenhuma versão o satisfaz.

Resolução dos níveis de mapeamento do Manifest. O mecanismo de resolução plano mappings.{components,features} do Manifest (com os níveis name e type, o nome prevalecendo sobre o tipo, e o tipo com versão prevalecendo sobre o tipo sem versão) está documentado em entities/manifest.md. O resolvedor consome esses mapeamentos: a seleção de Recipe e de FeatureRecipe é uma busca direta do valor de mapeamento no lockfile e no catálogo, e um componente ou uma vinculação cujo tipo não tem mapeamento interrompe o build. spec.implements não seleciona uma Recipe — é a verificação de consistência no carregamento sobre um mapeamento que o autor já escreveu, e a fonte da lista de candidatos que o diagnóstico de mapeamento ausente e o preenchimento automático do editor oferecem. O despacho de capacidades parte então do campo spec.capability da Recipe resolvida, não da forma estrutural do Manifest.

Regimes de proveniência descritiva (Manifest, Release). O metadata.version do Manifest e o metadata.version da Release são lidos quando o compilador preenche a proveniência, e aparecem no bloco de proveniência do grafo IR como manifest_version e release_version; nenhum rótulo na saída renderizada carrega nenhum dos dois. Os templates também veem a versão da Release exposta como .metadata.release_version. Nenhuma das duas versões é comparada com a versão de outra entidade para o despacho da resolução; são pura proveniência.

Lendo a tabela. A classificação de quatro rótulos distingue “o campo de versão é aceito pelo esquema e existe na entidade” (sempre verdadeiro — regex SemVer uniforme) de “o compilador faz correspondência com esta versão durante a resolução” (varia por entidade).

Canalização entre pilares por ponte de esquema: ligando a intenção à infraestrutura

O Aggrega expressa uma forte separação de responsabilidades entre o Domínio 1 e o Domínio 4: o desenvolvedor escreve a lógica cognitiva no bloco values, enquanto o operador dita o dimensionamento físico no bloco infra. O esquema Aggregate.yaml impõe um corolário concreto: a palavra-chave infra está ausente das instâncias de componente do Aggregate e das suas vinculações features e, combinada com additionalProperties: false, é rejeitada pela validação do esquema. Os desenvolvedores não devem ditar o dimensionamento físico dentro da intenção do desenvolvedor; quando um valor específico se encaixa no caso da aplicação (por exemplo, uma porta fixada no código ou um número específico de CPUs), o arquiteto pode expô-lo explicitamente na declaração schema: do Component, e o valor flui por values.

Para os casos em que uma restrição de infraestrutura específica é parte intrínseca do contrato de um componente — um banco de dados de trading de alta vazão que precisa ter 10.000 IOPS provisionadas, uma carga de trabalho de ML que precisa rodar em exatamente 4 GPUs —, os arquitetos de plataforma expõem a restrição por meio de um Component construído para esse fim, usando o padrão de canalização entre pilares por ponte de esquema.

O padrão de ponte de esquema para componentes cientes da infraestrutura. O Component expõe o controle de infraestrutura específico dentro do bloco values do desenvolvedor por meio da sua declaração schema:, e o template valuesMapping: da Recipe associada canaliza o valor para a saída renderizada com a forma de infra:. O resultado é uma ponte tipada entre a intenção cognitiva e o dimensionamento físico: o desenvolvedor dita a restrição de hardware por meio de um campo validado, e a restrição flui para Ops sem que nenhum dos lados escreva código de infraestrutura bruto. O controle é uma chave de pilar, então é declarado no Component cujo contrato o possui — um Component que faz extends: de uma base não declara chaves de pilar e, portanto, não pode introduzir uma.

# Domain 2: The Platform Catalog (the schema-bridge Component)
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/high-perf-postgres
version: 1.0.0
labels:
component.aggrega.ai/type: "stateful-server"
spec:
schema:
values:
# Expose the dial safely to the Developer with a typed contract.
required_iops: { type: integer, min: 1000, max: 100000, required: true }
infra:
# Operator-owned sizing the Recipe below reads alongside the dial.
storage: { size: { type: string, default: 100Gi } }
compute: { instance_class: { type: string, default: db.m5.large } }
# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-rds-high-perf-postgres
version: 1.0.0
spec:
implements: core/high-perf-postgres:^1.0.0
capability: terraform
source: ./modules/rds
valuesMapping: |
# The Recipe pipes the developer's values.required_iops into the provider's infra-side knob.
iops: {{ .values.required_iops }}
allocated_storage: "{{ .infra.storage.size }}"
instance_class: "{{ .infra.compute.instance_class }}"
# Domain 1: The Developer Intent (remains capability-agnostic)
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: 10000 # Developer dictates the hardware constraint safely

Escalonamento multiambiente (o requisito de elevação de parâmetros). Para escalonar essa restrição de hardware entre ambientes GitOps (Dev vs. Prod) sem alterar o Aggregate.yaml do desenvolvedor, o desenvolvedor eleva o valor para o contrato tipado parameters. Ops atende o requisito específico de IOPS por meio de arquivos Release específicos de cada ambiente. A ordem de execução do compilador protege o fluxo: a validação do contrato de parâmetros é executada na resolução; a interpolação resolve o parâmetro na string values: circundante; o template valuesMapping: da Recipe canaliza o valor resolvido para a saída renderizada.

1. A intenção do desenvolvedor (abstraindo o controle). O desenvolvedor sabe que precisa controlar as IOPS, mas abstrai o número explícito para o nível do ambiente por meio do contrato tipado parameters.

spec:
parameters:
env_iops:
type: integer
min: 1000
max: 100000
description: Provisioned IOPS for the trading-db instance
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: {{ .parameters.env_iops }} # Hoisted to the environment

2. As Releases de GitOps (atendimento por Ops). Ops atende o contrato parameters em arquivos Release específicos de cada ambiente. O contrato tipado valida cada valor fornecido pela Release antes que a interpolação seja executada.

  • Ambiente Dev (release-dev.yaml): env_iops: 1000
  • Ambiente Prod (release-prod.yaml): env_iops: 25000

A ordem de compilação. Esse mecanismo é protegido pela ordem de execução estrita do compilador na resolução:

  1. Validação do contrato de parâmetros. Cada valor de parâmetro fornecido pela Release é validado contra a declaração tipada parameters: do Aggregate. Um valor de Prod de 25000 é válido (dentro de min: 1000, max: 100000); um valor de 500 interromperia com um erro claro.
  2. Interpolação. O compilador lê os valores de parâmetros da Release de Prod e interpola 25000 na string YAML do Aggregate em values.required_iops. O mapa de parâmetros mesclado permanece ativo durante a renderização para que as superfícies de template de caminho possam ler .parameters.<slot> diretamente; as superfícies de template de valor consomem o literal pós-interpolação já escrito no bloco values: do Aggregate. O mapa permanece legível até que toda fase de renderização seja concluída, e só pode ser alcançado a partir da compilação para a qual foi resolvido.
  3. Validação de esquema. A declaração schema: do Component valida o dicionário values: resultante; values.required_iops: 25000 satisfaz o min: 1000, max: 100000 do esquema.
  4. Renderização do valuesMapping da Recipe. O template valuesMapping: da Recipe associada canaliza values.required_iops para a saída com a forma de infra do provedor (iops: 25000). O plugin Wasm do provedor gera a configuração física correta do banco de dados. O desenvolvedor obtém o seu controle explícito de hardware, Ops obtém o seu escalonamento específico de cada ambiente, e o Aggregate continua agnóstico em relação às capacidades.