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

extends e implements

Herança através de extends

As entidades do catálogo (Component, Feature) suportam herança simples através da palavra-chave extends, que permite aos arquitetos de plataforma construir entidades especializadas sobre uma base partilhada. A fusão profunda do envelope YAML é comum aos dois tipos: os metadados, as etiquetas e as tabelas estruturais declarativas da entidade que estende sobrepõem-se às chaves correspondentes da base, e os mapas aninhados são fundidos recursivamente. Os dois tipos separam-se nos pilares de dados.

Esta página trata dos tipos do catálogo, e estes 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 implementação escritos lado a lado, em vez de entidades indexadas no catálogo — por isso as suas referências nomeiam ficheiros, não entidades do catálogo, e o que é fundido é uma superfície de criação e não um esquema. Para esses, ver 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 anexo), spec.usesSchema (sockets de topologia) e spec.inject (a lista de permissões do self-inject, cujas entradas são concatenadas começando pela base e sem duplicados). 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: 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 simultaneamente 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: num Component que declara extends:; schema: totalmente omitido nesse caso; e schema: inherited num Component que não declara nenhum extends:.

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

  • O conjunto de chaves é fixado pela base. Um Component que estende não declara chaves de pilar, pelo que não pode ocultar, remover nem 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 face ao mesmo contrato de pilar.
  • O reforço passa para assertions:. Uma especialização que tem de admitir menos do que os pilares herdados admitem exprime-o como um predicado sobre si própria, não como uma folha de esquema restringida. Se uma base core/base-server declarar 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 qualquer expressão: uma especialização não pode relaxar uma restrição herdada, porque não pode reformular a folha que a contém. Ver entities/component.md «Catalog Authoring: Extending Base Components (Criação no catálogo: estender 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 compõe-se com o da base segundo a semântica de composição do JSON Schema 2020-12, produzindo um único esquema fundido face ao qual uma instância escrita é validada. As Features de credenciais — as que têm a etiqueta feature.aggrega.ai/kind: secret — usam isto para construir sobre uma base partilhada: uma Feature de credenciais filha estende um pai para herdar o seu esquema de consulta ao vault, estreitando ao mesmo tempo as restrições.

O compilador não toma posição sobre a direção dessa alteração. A composição é estrutural, pelo que uma restrição da filha que alarga a da base é composta sem interromper a compilação e surge como um aviso. Nada a rejeita: a restrição de uma base de Feature é uma expectativa partilhada que os autores do catálogo mantêm através de revisão, não um contrato que a plataforma faz cumprir.

Associação de interface através de implements

As Recipes e as FeatureRecipes associam-se a uma interface de Component ou de Feature através da palavra-chave implements: no topo do seu spec. A associação declara de que interface do catálogo esta Recipe / FeatureRecipe é a implementação concreta, e suporta 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). Usa-se quando uma Recipe suporta 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. Usa-se quando uma Recipe serve todas as versões do tipo.

implements: nunca seleciona uma Recipe: quem o faz é 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 tem de satisfazer o implements: da Recipe mapeada numa das três formas, ou a Recipe tem de implementar uma base que esse tipo estende — e a lista de candidatos que o diagnóstico de mapeamento em falta e a conclusão automática 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 a compilação, indicando o mapeamento, a Recipe e o seu valor implements:. Quando uma chave components.type alcança uma instância de componente numa versão que a chave não indica — todas as instâncias, no caso de uma chave escrita sem versão —, a verificação é feita de novo com o tipo próprio dessa instância, na versão com que a compilação a processa, e uma Recipe que não a satisfaça interrompe a compilação da mesma forma, indicando a instância.

A associação implements: é o mecanismo que faz funcionar «o mesmo tipo de Component, Recipes diferentes para fornecedores diferentes»: um Component core/postgres pode ter uma Recipe que o implementa para o fornecedor helm e outra Recipe que o implementa para o fornecedor compose. Cada Recipe declara o mesmo valor implements:, e o Manifest com que uma Release é compilada mapeia o tipo para aquela que ela pretende.

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

implements: indica uma base, e uma Recipe que indica uma é a implementação concreta para cada 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 equipa que o publica escreve um Component, e as equipas que o implementam reutilizam as Recipes da base em todos os destinos.

Aqui valem dois factos ao mesmo tempo, e são distintos. Um leitor que os reduza a «a especialização não precisa de nada» escreve um Manifest que falha, por um motivo que irá procurar no ficheiro 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 aplicam-se 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 continua a mapear o tipo próprio da especialização. A seleção da Recipe faz-se pela chave de mapeamento exata. Uma instância de enterprise/labelled-server precisa da sua própria entrada mappings.components.type; 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 criação 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 — forma um ciclo, ou uma base que indica está ausente do catálogo —, a compilação é interrompida nessa falha da cadeia em vez de no mapeamento, porque um mapeamento não pode ser avaliado até que a cadeia de que depende seja resolvida. A verificação percorre a cadeia apenas através dos Components que já estão nesta máquina — os de um diretório de catálogo e os que a cache local de artefactos guarda sob um pin do lockfile — e nunca consulta um registo, pelo que uma base guardada apenas por um registo conta aqui como ausente. Obtê-la é o que faz aggrega pull: uma base é uma dependência de tudo o que a estende, pelo que um pull segue cada cadeia extends: que a Release alcança, obtém cada base que nenhum diretório de catálogo guarda e fixa-a no lockfile, onde a compilação 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 esta regra de correspondência. A lista de candidatos que um diagnóstico de mapeamento em falta imprime, e a ordenação que a conclusão automática do editor aplica a um valor de mapeamento, indicam as receitas que implementam o próprio tipo pedido; não se alargam a receitas que implementam uma das suas bases.

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

Consumo de versões entre entidades

Cada tipo de entidade do Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — contém um campo obrigatório metadata.version validado face à mesma regex SemVer (MAJOR.MINOR.PATCH segundo 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 na resolução; outras são proveniência descritiva face à qual o compilador não faz correspondência. A tabela abaixo abrange os tipos que não são bibliotecas, indicando o que o compilador faz com o campo de versão de cada entidade e usando a taxonomia de estado de quatro etiquetas 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 mínimo de versão opcional :<version>, e o lockfile por Release detém a versão resolvida e o seu digest de conteúdo.

EntidadeRegime de consumoEstado
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 (ver Resolução de versões e Estado da linguagem → Correspondência de versões)
FeatureResolução de referências de anexo; 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 num valor de mapeamento, cada uma a selecionar 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 a selecionar a versão mais alta que a satisfaz (ver Resolução de versões)
PluginDespacho do Provider através de recipe.spec.capability → spec.provider.capabilitiesavailable — a capacidade simples seleciona o fornecedor, e um pin sobre ela (helm:<version>, helm:^<version>) seleciona que 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 fica registado no lockfile da release face ao qual a compilação verifica os bytes transferidos
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 destes tipos — o type de um componente, o type de um anexo de funcionalidade, o aggregates[].type de uma importação de subagregado, o plugin de um passo 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, a compilação, uma validação, o editor e as ferramentas destinadas 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 face à 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: procura pelo nome a recipe.spec.capability simples nas spec.provider.capabilities do plugin de renderização do fornecedor, e um pin de versão escrito sobre a capacidade seleciona que 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 a prevalecer sobre o tipo, e o tipo com versão a prevalecer 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 pesquisa direta do valor de mapeamento no lockfile e no catálogo, e um componente ou um anexo cujo tipo não tenha mapeamento interrompe a compilação. 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 origem da lista de candidatos que o diagnóstico de mapeamento em falta e a conclusão automática 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; nenhuma etiqueta na saída renderizada contém qualquer um 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.

Ler a tabela. A classificação de quatro etiquetas distingue «o campo de versão é aceite 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: ligar a intenção à infraestrutura

O Aggrega exprime uma forte separação de responsabilidades entre o Domínio 1 e o Domínio 4: o programador 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 dos seus anexos features e, combinada com additionalProperties: false, é rejeitada pela validação do esquema. Os programadores não devem ditar o dimensionamento físico dentro da intenção do programador; quando um valor específico se adequa ao caso da aplicação (por exemplo, uma porta fixada no código ou um número específico de CPU), o arquiteto pode expô-lo explicitamente na declaração schema: do Component, e o valor flui através de values.

Para os casos em que uma restrição de infraestrutura específica é parte intrínseca do contrato de um componente — uma base de dados de trading de alto débito que tem de ter 10 000 IOPS provisionadas, uma carga de trabalho de ML que tem de ser executada em exatamente 4 GPU —, os arquitetos de plataforma expõem a restrição através 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 conscientes da infraestrutura. O Component expõe o controlo de infraestrutura específico dentro do bloco values do programador através 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 programador dita a restrição de hardware através de um campo validado, e a restrição flui para Ops sem que nenhum dos lados escreva código de infraestrutura em bruto. O controlo é uma chave de pilar, pelo que é declarado no Component cujo contrato o detém — um Component que faz extends: de uma base não declara chaves de pilar e, por isso, não pode introduzir nenhuma.

# 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

Escalamento multiambiente (o requisito de elevação de parâmetros). Para escalar esta restrição de hardware entre ambientes GitOps (Dev vs. Prod) sem alterar o Aggregate.yaml do programador, o programador eleva o valor para o contrato tipado parameters. Ops cumpre o requisito específico de IOPS através de ficheiros 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 programador (abstrair o controlo). O programador sabe que precisa de controlar as IOPS, mas abstrai o número explícito para o nível do ambiente através 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 (cumprimento por Ops). Ops cumpre o contrato parameters em ficheiros Release específicos de cada ambiente. O contrato tipado valida cada valor fornecido pela Release antes de a interpolação ser executada.

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

A ordem de compilação. Este mecanismo está 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 face à declaração tipada parameters: do Aggregate. Um valor de Prod de 25000 é válido (dentro de min: 1000, max: 100000); um valor de 500 provocaria uma interrupção 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 combinado 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 todas as fases de renderização estejam concluídas, e só é alcançável 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 fornecedor (iops: 25000). O plugin Wasm do fornecedor gera a configuração física correta da base de dados. O programador obtém o seu controlo explícito do hardware, Ops obtém o seu escalamento específico de cada ambiente, e o Aggregate mantém-se agnóstico em relação às capacidades.