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

Aggregate

O papel conceitual da entidade Aggregate (Domínio 1 — a planta declarativa da topologia do desenvolvedor) está descrito em architecture/04-entity-taxonomy.md. Os padrões de composição (subsistemas, agregados aninhados, convenção Zero-Port, Parameter Hoisting) estão descritos em architecture/06-data-taxonomy-and-composition.md. Esta página trata da superfície de autoria do catálogo para o Aggregate — especificamente, da autoria de módulos Aggregate reutilizáveis para distribuição pelo catálogo.

Escopo de Component: o subsistema padrão

Um Aggregate organiza componentes em subsistemas — agrupamentos nomeados para preocupações transversais (uma camada de dados, uma camada de borda) que carregam sua própria cascata de anotações. A maioria dos Aggregates tem um único agrupamento, então ele não exige cerimônia.

Escopo único (o padrão). Escreva os componentes diretamente em spec.components: e omita o bloco subsystems::

spec:
components:
api:
type: core/server:1.0.0
worker:
type: core/worker:1.0.0

O compilador os agrupa em um subsistema default sintetizado. A identidade dos nós não muda — api continua api, nunca default.api — de modo que um Aggregate escrito assim é intercambiável com a forma explícita de subsistema único, e o endereçamento dele (em destinos uses:, em diagnósticos) usa o caminho simples spec.components.<name>. O escopo sintetizado é registrado fielmente na IR exportada (com um marcador de subsistema sintetizado), mas nunca aparece nos caminhos que um autor escreve ou lê.

Vários escopos. Quando os componentes se dividem em grupos transversais distintos, declare subsistemas nomeados em subsystems:. Cada subsistema carrega seus próprios componentes e sua própria cascata de anotações, e pode aninhar outros subsistemas.

Exclusão mútua. spec.components: e spec.subsystems: são mutuamente exclusivos na raiz do Aggregate — escreva um ou outro, nunca ambos. Um documento que declara ambos é interrompido no carregamento com um erro de envelope. (Um subsistema que um desenvolvedor nomeia explicitamente default é um subsistema declarado comum, endereçado em seu caminho qualificado spec.subsystems.default.components.<name> — a omissão do escopo sintetizado depende da proveniência, não do nome.)

Módulos Aggregate reutilizáveis

Os Aggregates servem tanto como o Aggregate raiz que uma Release compila quanto como módulos reutilizáveis. Um Aggregate pai pode declarar um Aggregate filho exatamente como um componente, passando parameters para ele. Para evitar acoplamento forte, os Aggregates filhos expõem um contrato exportedComponents:, que estabelece um nome de interface pública estável. O pai alcança os componentes do módulo apenas por meio dessa interface: um destino uses: é o nome do módulo, um ponto e um de seus aliases exportados, e o compilador conecta a aresta ao componente interno que o alias nomeia. Um destino que entra em um módulo por qualquer outro nome — o nome do componente dentro do módulo, ou um caminho para um módulo aninhado dentro dele — interrompe o build, nomeando o módulo e os aliases que ele exporta; consulte A uses target names a module’s component the module does not export (Um destino nomeia um componente de um módulo que o módulo não exporta).

Por que uma lista exportedComponents: explícita. Os autores de um módulo decidem quais de seus componentes formam a interface pública e quais permanecem detalhes de implementação. Como um pai só pode nomear o que a lista publica, o interior do módulo pode ser refatorado — um componente renomeado, um componente dividido em dois, um worker trocado por um serviço gerenciado — sem quebrar nenhum pai, desde que cada nome publicado ainda aponte para um componente. A lista custa uma entrada por componente publicado, e um componente pode ser publicado com seu próprio nome (store: store) quando esse é o nome que os importadores devem usar. A mesma regra vale dentro de uma composição: um módulo alcança um módulo que importa por meio dos aliases exportados desse módulo. Uma Release pode conectar entre si dois componentes de um mesmo módulo, já que essa conexão não atravessa a interface de nenhum módulo.

Reexportar a interface de um módulo aninhado. Uma entrada de exportedComponents: pode apontar para o alias exportado de um subagregado aninhado em vez de para um componente declarado diretamente — um módulo que republica parte de um módulo que importa, sob seu próprio nome de interface e opcionalmente com um novo nome. Uma aresta uses: cujo destino é um alias reexportado desse tipo se resolve de forma transitiva ao longo da cadeia até o nó interno concreto, de modo que um módulo compõe módulos mais profundos em sua própria interface pública sem expor a organização interna deles, e um consumidor nunca precisa saber a que profundidade o destino está aninhado. A disciplina da interface estável vale em cada salto: cada módulo reexporta apenas o que escolhe publicar. Um destino reexportado que não se resolve em nenhum nó interno interrompe o build de forma explícita, da mesma forma que um destino direto pendente, e uma cadeia de reexportação que se fecha sobre si mesma é rejeitada em vez de ser seguida indefinidamente.

As declarações de um módulo são verificadas como as do Aggregate. O documento de um módulo só é lido quando a composição que o importa é compilada, e suas declarações são verificadas a partir desse ponto, em qualquer profundidade de aninhamento. O bloco inject: próprio de um componente do módulo é submetido à allowlist spec.inject de seu tipo, e às regras que proíbem reivindicar duas vezes uma mesma chave de entrega e ler uma chave que o tipo não publica. Uma vinculação escrita em um dos subsistemas próprios do módulo só pode nomear um socket que sua Feature declara, e o mesmo vale para uma vinculação que a Release escreve em um componente fornecido por um módulo.

As vinculações de subsistema de um módulo alcançam seus componentes. Uma Feature que um módulo vincula a um de seus próprios subsistemas se propaga em cascata a cada componente que o módulo declara sob esse subsistema, subsistemas aninhados incluídos, exatamente como faz uma vinculação de subsistema no Aggregate — e somente a esses componentes, nunca ao componente de um Aggregate importador sob um subsistema de mesmo nome. Ela é avaliada logo após as vinculações próprias do componente, subsistemas externos antes dos internos. Em um campo que ambas escrevem, prevalece a vinculação própria do componente de mesmo nome, e os campos que ela omite mantêm os valores do subsistema. Cada componente que ela alcança a submete ao appliesTo da Feature. Uma constatação sobre as declarações próprias de um módulo nomeia o módulo e a chave dentro de seu documento — .spec.subsystems.<subsystem>.features.<attachment>, por exemplo — para que a edição seja feita no módulo, onde a declaração está, e não no Aggregate que o importa.

Localização no catálogo

Um módulo Aggregate reutilizável fica no diretório de tipo aggregate/, no caminho que seu metadata.name descreve, segmento por segmento, com um diretório de versão como folha:

aggrega-catalog/
└── aggregate/
└── {module-name}/ # the module's metadata.name, segment for segment
└── {version}/ # the module's metadata.version
└── aggregate.yaml # The module definition

O nome de um módulo pode ter um segmento inicial {publisher} que nomeia o fornecedor ou autor — core para a biblioteca padrão, acme para uma empresa — e os módulos publicados da biblioteca padrão são nomeados assim: core/agenta fica em aggregate/core/agenta/1.0.0/aggregate.yaml. Um nome que é um único token fica um nível menos profundo, em aggregate/{module-name}/{version}/aggregate.yaml. Ambas as formas são bem formadas; o nome é o que o autor escreve, e o diretório o espelha. Esse espelhamento é uma convenção do catálogo, e não algo que o compilador verifica — um módulo é encontrado pelo nome que declara, não por onde seu arquivo está.

URI OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, em minúsculas — assim, um módulo chamado core/agenta é publicado em hub.aggrega.ai/aggregate/core/agenta:1.0.0, e um chamado db-module em hub.aggrega.ai/aggregate/db-module:1.0.0.

O padrão de módulos

Módulo filho (aggregate/child-database-module/1.0.0/aggregate.yaml, publicado como hub.aggrega.ai/aggregate/child-database-module:1.0.0):

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"

Aggregate pai:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db

Rótulos de módulo

Quando um Aggregate é publicado no catálogo como módulo reutilizável, ele pode ter metadata.labels em seu envelope YAML — por exemplo aggregate.aggrega.ai/tier: infrastructure ou aggregate.aggrega.ai/compliance: pci-dss. Esses rótulos descrevem a identidade do módulo e são mantidos no documento do módulo como publicado; nenhum comando os lê ainda. A busca no catálogo não indexa Aggregates, e o grafo de build não carrega nem os rótulos de um módulo nem seu nome de catálogo, então uma política de governança não pode selecionar os componentes de um módulo pelo módulo de onde vieram.

A distinção crítica. Os rótulos do Aggregate descrevem a identidade do módulo reutilizável no catálogo. Eles não se propagam em cascata para os nós de componente filhos. Os rótulos dos componentes vêm exclusivamente da entidade de catálogo Component no Domínio 2. Se um desenvolvedor importa um módulo rotulado aggregate.aggrega.ai/tier: infrastructure, os componentes individuais dentro desse módulo mantêm apenas seus próprios rótulos definidos no catálogo (por exemplo, component.aggrega.ai/type: stateful-server). O rótulo do Aggregate nunca é injetado no dicionário labels do nó da IR.

Consulte architecture/06-data-taxonomy-and-composition.md §6 para a discussão completa sobre Aggregates compostos / o padrão de módulos (incluindo a regra de que Components não têm subcomponentes), e para o mecanismo de agrupamento transversal subsystems. Consulte vocabulary/data-pillars para a superfície de autoria do contrato tipado parameters.

Contratos de parâmetros tipados

O bloco spec.parameters: do Aggregate declara o contrato tipado dos parâmetros que a Release preenche. Cada slot de parâmetro tem um type declarado, uma description opcional, um default opcional, restrições opcionais do espaço de valores e (para slots do tipo objeto) uma estrutura aninhada. O compilador valida cada valor fornecido pela Release em relação ao contrato durante a resolução, antes que a interpolação de parâmetros seja executada.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
parameters:
region:
type: string
description: Cloud region the deployment targets
enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]
default_locale:
type: string
description: Default UI locale presented to end users
enum: [en-US, en-GB, fr-FR, ja-JP]
default: en-US
enable_debug:
type: boolean
description: Toggle verbose request logging
default: false
feature_flags:
type: object
description: Per-feature enablement map
valuesType: { type: boolean }
default: {}
allowed_hosts:
type: array
description: Hostnames the ingress accepts
items: { type: string, format: hostname }
min: 1
default: ["web-app.example.com"]
components:
web:
type: core/web-server:1.0.0
values:
default_locale: "{{ .parameters.default_locale }}"
region: "{{ .parameters.region }}"
debug: {{ .parameters.enable_debug }}

As aspas em cada referência são intencionais: são elas que decidem o tipo com que o valor elevado chega. Consulte templates/parameters-context.md.

Vocabulário dos slots de parâmetro

O bloco tipado parameters: aceita o vocabulário da forma compacta: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate e validateMessage (uma verificação personalizada e a mensagem que ela relata), items (para arrays), properties (para objetos), valuesType (para mapas de valores tipados) e required: true (marcador por slot). Três dessas palavras-chave recebem um contrato como valor em vez de uma configuração simples — items, valuesType e cada entrada em properties — e, em um slot de parâmetro, esse contrato aninhado é escrito na mesma forma tipada do slot ao seu redor: valuesType: { type: boolean }, e não valuesType: boolean. Antes da interpolação, o compilador verifica o mapa de parâmetros mesclado diretamente em relação a essas declarações: um parâmetro que nenhum slot declara é rejeitado, um slot marcado com required: true que nem a Release preenche nem um default fornece interrompe a compilação, e cada valor fornecido é verificado em relação ao type declarado do seu slot, à pertinência ao seu enum, aos limites minLength e maxLength, à expressão regular pattern e ao format em um slot de string, e aos limites min e max — o valor de um slot numérico, o comprimento de um slot de string e o número de itens de um slot de array. Os slots de objeto e de array são recursivos: cada entrada em properties e cada elemento em relação a items são verificados da mesma forma, um contrato valuesType rege as chaves que properties não nomeia, e uma chave aninhada que nenhuma declaração nomeia é rejeitada. Consulte vocabulary/compact-form-authoring.md para o vocabulário completo de palavras-chave, incluindo onde um pilar schema: escreve essas palavras-chave de forma diferente.

As palavras-chave abaixo também são verificadas na própria declaração, antes que qualquer valor da Release seja lido, de modo que um slot que não poderia restringir nada interrompe a compilação mesmo quando nenhuma Release o fornece:

  • Os limites de comprimento são zero ou mais. Um minLength ou maxLength negativo na própria declaração de um parâmetro é recusado pelo schema do Aggregate quando o Aggregate é carregado, nomeando o parâmetro e a chave. Dentro de um contrato aninhado — em items, properties ou valuesType — um limite de comprimento é lido como está escrito e não é submetido a esse piso quando o Aggregate é carregado; portanto, escreva-o também ali como zero ou mais: um minLength negativo não impõe nada, e um maxLength negativo recusa todos os valores.
  • min e max precisam limitar algo. Em um slot booleano ou de objeto, o par não limita nada; por isso, um min ou max escrito ali é recusado quando o Aggregate é carregado, nomeando o parâmetro e a chave.
  • Um pattern precisa compilar. Cada pattern é compilado como expressão regular quando o contrato de parâmetros é lido — no próprio slot e dentro de qualquer contrato aninhado, em qualquer profundidade — e um que não compila é recusado nomeando o parâmetro, o pattern e o motivo. O contrato é lido em cada compilação, pull e validação de Release que alcança o Aggregate, seja o próprio Aggregate da Release ou um módulo que esse Aggregate importa. A verificação de valores então compara cada valor fornecido com essa mesma expressão compilada.
  • Um formato precisa ser um dos que o compilador verifica. format nomeia um entre email, uri, hostname, ipv4, ipv6, uuid, date-time e date, grafados como o JSON Schema os grafa. Qualquer outro nome — um erro de digitação como emial, ou um nome que o JSON Schema não define, como password — é recusado quando o Aggregate é carregado, nomeando o parâmetro e listando os nomes suportados: no próprio slot, pelo schema do Aggregate, e dentro de um contrato aninhado, em qualquer profundidade, quando o contrato de parâmetros é lido. Uma string fornecida que não tem o formato nomeado é então recusada nomeando o parâmetro, o valor e o formato. O que cada nome verifica está descrito em vocabulary/compact-form-authoring.md.

Parâmetros do tipo objeto e do tipo array

Os slots de parâmetro aceitam qualquer tipo que a forma compacta suporta, incluindo objetos aninhados e arrays de elementos tipados:

spec:
parameters:
database_config:
type: object
description: Database connection configuration
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full], default: require }
pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels:
type: array
description: Custom Prometheus labels to attach to scraped metrics
items:
type: object
properties:
name: { type: string, required: true }
value: { type: string, required: true }

A Release preenche parâmetros do tipo objeto com YAML estruturado; o compilador valida a estrutura em relação ao schema declarado antes da interpolação. Os templates que referenciam os campos do objeto usam a sintaxe padrão de templates Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} etc.

Validação do contrato de parâmetros

O próprio contrato é verificado primeiro, quando é lido — as verificações de limites de comprimento e de patterns descritas acima em “Vocabulário dos slots de parâmetro”. Em seguida, o compilador executa três subetapas durante o processamento de parâmetros:

  1. Preenchimento de defaults — slots com default: definido e sem valor fornecido pela Release recebem seu default. Parâmetros de objeto aninhado seguem uma semântica de autoria com três casos para slots pai omitidos, explicitamente vazios e parcialmente escritos: omitir o pai preenche os defaults dos filhos, escrever o pai como {} preserva o vazio explícito (suprime os defaults dos filhos), e escrever o pai como um mapa não vazio preenche apenas os filhos que a Release não forneceu. Consulte templates/parameters-context.md para os exemplos em YAML e o guia de decisão “quando usar cada forma”.
  2. Validação do contrato — cada valor do mapa mesclado, seja fornecido pela Release ou preenchido por um default:, é validado em relação às restrições declaradas de type / enum / min / max / pattern / estrutura aninhada. Falhas de validação interrompem a compilação com um erro claro que nomeia o slot problemático, o valor fornecido e a restrição violada. Parâmetros obrigatórios ausentes sem default: produzem uma interrupção semelhante com o nome do slot.
  3. Interpolação — o compilador avalia todo o texto do Aggregate como um template, antes de lê-lo como YAML, e substitui cada referência {{ .parameters.<slot> }} — normalmente dentro de strings values: de componentes / funcionalidades / subagregados — pelo valor resolvido; qualquer outro {{ no texto também é lido como sintaxe de template, de modo que um valor que carrega suas próprias chaves duplas — a definição exportada de uma plataforma de fluxos, por exemplo — escreve cada {{ como {{"{{"}}, como descreve Texto que carrega suas próprias chaves duplas. Após essa passagem, as superfícies de templates de valores consomem literais já interpolados e não recebem .parameters em seu contexto de template.

O mapa de parâmetros mesclado permanece vivo durante a renderização para dar suporte à avaliação de templates de caminho. Os templates directory: e subDirectory: escritos pelo operador nos limites da Release leem .parameters.<slot> diretamente no momento da renderização, em relação a uma lista fechada de valores permitidos; a emissão de caminhos precisa de vocabulário de região / ambiente para o layout de artefatos por ambiente, e a concessão assimétrica mantém essa responsabilidade do operador dentro da superfície do operador, sem passar pelos values do Aggregate. O mapa continua legível até que todas as fases de renderização tenham terminado e só é acessível a partir da compilação para a qual foi resolvido; as receitas que consomem values: escritos pelo desenvolvedor veem as strings pós-interpolação, enquanto os templates de caminho veem dados .parameters vivos durante a renderização. Consulte templates/expansion-matrix.md linha 3 para a matriz de disponibilidade dos templates de caminho e path-template-variables.md para a lista de variáveis permitidas nos templates de caminho.

Para o checklist mais amplo do parameter hoisting (declaração no Aggregate → referência nos values → preenchimento na Release → consumo na Recipe) e a mecânica entre pilares, consulte vocabulary/data-pillars.md §“Parâmetros” e §“O checklist do parameter hoisting”. Para os campos do contexto de template expostos durante a interpolação e a exceção dos templates de caminho, consulte templates/parameters-context.md.

Uma aresta uses é uma chamada que o Aggregate declara

Uma aresta uses é a declaração do Aggregate de que um componente chama outro. O compilador canaliza para o chamador os valores que o destino publica e não restringe nada: sozinha, uma aresta não admite o chamador nem recusa mais ninguém, e uma carga de trabalho que alcança o endereço do destino sem uma aresta o alcança do mesmo jeito.

Restringir quem pode chamar um componente, e o que ele pode chamar, é decisão do operador, tomada por ambiente na Release. Quando uma Release anexa a um componente a Feature core/caller-allowlist do catálogo da biblioteca padrão, a compilação escreve uma network policy que admite exatamente os componentes cujas arestas uses apontam para ele, os próprios pods desse componente e as origens que o anexo nomeia. Sua contraparte de saída, core/egress-allowlist, permite que o componente ao qual está anexada alcance apenas os componentes para os quais suas próprias arestas uses apontam, seus próprios pods, o DNS do cluster e os intervalos de endereços que a Release lista. Uma chamada que o Aggregate não declara como aresta pode então ser recusada pelo cluster em qualquer uma das pontas, onde quer que seu plugin de rede aplique network policies. Por isso, escreva uma aresta para cada chamada que seus componentes fazem, inclusive uma que não injeta nenhum valor: uma aresta ausente é uma chamada que um componente isolado pode recusar. model-server-caller-allowlist mostra um servidor de modelos acessível apenas pelo gateway à sua frente.

Os anexos próprios de uma conexão: features em uma entrada uses

Uma conexão que um componente traça em sua forma detalhada de uses: é uma entrada própria e, ao lado de target, inject e values, pode carregar anexos, em features:. Cada um é indexado por um slot que o socket declara: o Component consumidor lista, no featuresSchema do socket, os slots que cada conexão ligada por esse socket pode preencher (consulte Sockets de topologia). É assim que um componente mantém uma credencial diferente para cada componente que alcança — um gateway que chama dois modelos com duas chaves, ou um agente que apresenta uma chave própria a um modelo.

spec:
parameters:
openai_key_secret: { type: string }
components:
router:
type: core/gateway/litellm # its `models` socket declares a `credential` slot
values: { model: gpt } # the alias it publishes as its model
uses:
models:
gpt:
target: gpt
features:
credential:
type: core/referenced-secret
values:
origin: "{{ .parameters.openai_key_secret }}"
key: api-key
plain:
target: plain # this connection carries no attachment
gpt:
type: core/ai-model/openai
values: { model: gpt-4o-mini }
plain:
type: core/ai-model/ollama
values: { model: llama3.1 }

Um anexo em uma conexão carrega type (obrigatório), uma description opcional e values para a Feature. Ele não carrega uses nem inject: um anexo em uma conexão não se aninha, e como seu material chega ao consumidor é decisão da Recipe do componente consumidor, e não de um bloco inject. Um documento que escreva qualquer uma dessas chaves é recusado ao ser carregado, nomeando a chave.

Somente os slots que o socket declara. Um anexo com um nome que o featuresSchema do socket não lista interrompe a compilação ao ser carregado, nomeando a conexão, o socket, o componente e os slots que o socket declara — e, quando o nome está a uma edição de um deles, esse slot, como a grafia provavelmente pretendida. Um slot preenchido é então submetido à própria declaração do slot em cada conexão: um selector que os labels da Feature não satisfazem interrompe a compilação nesta entrada, e um slot required deixado vazio em qualquer conexão a interrompe nomeando essa conexão. Um socket que não declara slots não admite anexos em suas conexões, nem um socket ad hoc — um que o Aggregate liga sem que o Component o declare —, já que ele não declara nenhum slot. Um componente que um submódulo contribui segue a mesma regra, e o achado aponta para o próprio documento do submódulo. Consulte A connection carries an attachment under a name its socket declares no slot for (Uma conexão carrega um anexo com um nome para o qual seu socket não declara nenhum slot).

Uma conexão que uma Feature traça não carrega nenhum. O bloco uses: próprio de uma Feature anexada — em um componente ou em um subsistema — é escrito na mesma forma, mas recusa features: quando o documento é carregado. Uma credencial de que essa conexão precise preenche um slot que a Feature declara em seu próprio featuresSchema, anexado ao lado da Feature; consulte A credencial própria de uma Feature.

O nome que o anexo recebe. Cada anexo de conexão se torna um anexo do componente consumidor, chamado <alias>.<slot> — o alias sob o qual a conexão é escrita, um ponto e o slot: gpt.credential acima. O ponto é o separador reservado para nomes que o compilador compõe, que nenhum alias, slot ou nome de anexo em um Aggregate pode conter, de modo que o nome composto nunca coincide com um escrito no bloco features: próprio do componente; uma Release que o escreva em um componente ou em um limite é recusada (consulte Configuração de conexões por aresta). É o nome pelo qual o nível por instância do Manifest indexa o anexo (consulte Mapeamento de URI plano), o nome com que os diagnósticos e o grafo IR o relatam, e o valor que a FeatureRecipe do anexo lê como .attachment_name (consulte Nomes derivados do anexo de uma conexão).

A partir daí, ele é resolvido como qualquer anexo: o Manifest vincula seu tipo de Feature a uma FeatureRecipe, seus values são validados em relação ao schema da Feature — uma falha é relatada na entrada de conexão que os escreveu — e sua FeatureRecipe renderiza com os values e a infra próprios do anexo. Duas coisas o distinguem dos anexos próprios do componente:

  • Ele não está em .features da Recipe consumidora. Esse pilar carrega apenas os anexos escritos no bloco próprio do componente, de modo que uma Recipe que procura em .features seus próprios anexos por tipo nunca recebe a credencial de uma conexão. Uma Recipe lê o anexo de uma conexão a partir da própria conexão, em .context.uses.<alias>.features.<slot>, na forma que .features carrega — incluindo seus provides resolvidos (consulte Os anexos de uma conexão).
  • Ele chega apenas ao consumidor. A saída renderizada de um destino é a mesma, seja o que for que as conexões que chegam a ele carreguem.

A cópia do bloco escrito no grafo. O grafo IR mantém o bloco uses: de cada componente como foi escrito, e ali um anexo de conexão mantém seu type e sua description e nenhum dos seus values. Os valores aparecem uma única vez, no anexo que o consumidor carrega, onde um valor que a Feature declara sensível é omitido.

Uma Release pode dimensionar com infra um anexo declarado aqui, ou anexar um próprio em uma conexão que alcança — consulte Configuração de conexões por aresta.

Desativar um componente ou módulo: active:

Uma instância de componente e um módulo subagregado aceitam, cada um, um interruptor active: que decide se essa entidade faz parte ou não da topologia compilada. Se você o omitir, a entidade estará presente; esse é o padrão e o caso comum.

spec:
parameters:
enable_cache:
type: boolean
default: false
components:
api:
type: core/server:1.0.0
redis:
type: core/redis:1.0.0
active: "{{ .parameters.enable_cache }}"
aggregates:
reporting:
type: my-catalog/reporting-module:1.0.0
active: false

Escreva um booleano diretamente, ou um template sobre .parameters que se resolva em um. A forma de template é a razão de existir do interruptor: ela permite que uma Release decida a presença de uma entidade preenchendo um parâmetro, de modo que um único Aggregate cubra ambientes que diferem nas partes que implantam — sem que a Release declare nada que o Aggregate não tenha declarado.

O que um interruptor falso remove. A entidade é podada antes de o grafo ser construído, e a poda se propaga em cascata: um componente leva consigo suas próprias arestas uses: e suas Features anexadas, e um módulo leva tudo o que contribuiu — seus componentes, as arestas deles, os anexos deles. Nada do que a entidade podada trouxe é renderizado. O que a poda não alcança é uma referência a ela a partir de algo que sobreviveu, que é o assunto do próximo parágrafo.

Um componente remanescente que ainda aponta para um podado interrompe a compilação. Se api declara uma aresta uses: para redis e redis está desativado, a compilação para em vez de deixar a aresta desaparecer, o que deixaria os valores injetados de api silenciosamente vazios no momento da implantação. Decida qual dos dois pertence a este ambiente: reative o destino, condicione o consumidor ao mesmo parâmetro para que o par saia junto, ou remova a aresta do bloco uses: do consumidor.

Um interruptor escrito precisa se resolver em um booleano, e um valor vazio não é um. O interruptor é lido de forma estrita depois que seu template é resolvido, e um literal que não é interpretado como booleano para a compilação em vez de assumir um valor padrão. O caso a observar é um interruptor que lê um parâmetro sem valor: ele se resolve em nada, e ler esse nada como “presente” implantaria justamente a entidade que você condicionou a esse parâmetro. Por isso, escrever active: sem nada depois não é o mesmo que omitir a chave — apenas um interruptor que ninguém escreveu vale “presente” por padrão. Dê ao parâmetro um default: em spec.parameters para que cada ambiente tenha uma resposta, ou preencha-o na Release. Para tornar uma entidade incondicionalmente presente, remova a chave active: em vez de esvaziá-la. A interrupção é descrita em “An active: toggle does not resolve to true or false (Um interruptor não se resolve em true ou false)” na referência das condições de interrupção.

Um componente desativado continua nomeável a partir de uma Release. Uma Release ainda pode nomeá-lo em um limite, e isso é intencional: desativar um componente é um ato de autoria, e não se espera que a Release que o configura seja reescrita na mesma edição.

Anotações em subsistemas e componentes

Subsistemas e instâncias de componente carregam ambos um campo annotations:. As anotações escritas pelo desenvolvedor na superfície do Aggregate conduzem a cascata de anotações do lado do Aggregate — uma anotação de subsistema se propaga para cada subsistema aninhado e cada componente contido, com sobrescritas nos níveis mais próximos em granularidade por chave. O mapa mappings.features.annotations do Manifest declara os bindings que traduzem chaves de anotação em vinculações sintéticas de Feature em tempo de build. A invariante do Aggregate como superfície de autoria restringe essas anotações ao roteamento pelos caminhos maps.values do binding; um binding que declara apenas caminhos maps.infra é acionado pelo lado da Release, não pelo lado do Aggregate.

Formas dos valores

Cada chave de anotação assume uma de quatro formas, distinguindo “fico em silêncio” de “declaro um valor” — um escalar ou um objeto estruturado — e de “estou fora”:

  • Chave ausente — o escopo não declara nenhum valor para esta anotação. Subsistemas aninhados e componentes contidos herdam qualquer binding de um escopo ancestral.
  • Uma string escalar — um único valor. O binding do Manifest deve declarar exatamente um caminho no total; o escalar é roteado para esse caminho.
  • Um objeto estruturado — um mapa de subchave para subvalor. Cada subchave do objeto é roteada, pelos maps do binding do Manifest, para o campo correspondente do esquema da Feature no pilar declarado.
  • null YAML explícito — o escopo remove de sua subárvore qualquer binding herdado para esta chave. Componentes e subsistemas irmãos mantêm sua herança; apenas o escopo que se exclui perde o binding.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker
components:
api:
type: core/server:1.0.0
# inherits feature.myco/db-pool: "shared-pool"
worker:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
type: core/server:1.0.0
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Valores estruturados para Features com vários campos

Uma Feature com vários campos configuráveis se presta a um valor de anotação estruturado: uma única chave de anotação que carrega valores para vários campos do esquema da Feature em uma só declaração. O lado do Aggregate aciona apenas as subchaves cujo pilar no mapa do binding é values; subchaves roteadas para infra pertencem às anotações do lado da Release.

spec:
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
components:
api:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
db_name: "api-override" # closer-level override at subkey granularity
# read_replicas not listed → inherits 5 from parent
analytics:
type: core/server:1.0.0
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out

Valores estruturados se propagam em cascata com mesclagem profunda por subchave: subchaves dos níveis mais próximos sobrescrevem as do pai; um null explícito em uma subchave suprime a subchave herdada para aquele escopo, enquanto as subchaves irmãs permanecem. Para a explicação completa sobre valores estruturados — composição entre os dois lados com subchaves infra do lado da Release, validação de tipo por subchave, a disciplina de padrão relaxado para campos de esquema sem um type declarado — consulte providers/well-known-annotations.md §“Valores de anotação estruturados”.

Independência por chave

Cada chave de anotação herda, sobrescreve e se exclui de forma independente. Um componente que declara annotations.feature.myco/db-pool: null se exclui apenas dessa chave; as outras chaves herdadas do subsistema que o contém continuam a se propagar para esse componente. Componentes irmãos no mesmo subsistema mantêm seus próprios mapas de anotações de forma independente — a exclusão de um componente não afeta os irmãos.

Anotações de componentes de nível superior

Componentes de nível superior (declarados diretamente em spec.components em vez de dentro de um subsistema) não carregam nenhuma cascata herdada. Seu campo annotations: declara valores diretamente no escopo do componente; a expansão sintetiza vinculações de Feature a partir de cada anotação declarada para a qual o Manifest tem um binding correspondente.

Para a regra de cascata do lado do Aggregate aplicada aos bindings, a partição entre lado e pilar e um exemplo completo que mostra os bindings traduzindo anotações em vinculações sintéticas de Feature, consulte providers/well-known-annotations.md §“Cascata de anotações do lado do Aggregate”.

Padrões de âncoras YAML (bloco defs:)

O esquema do Aggregate aceita um bloco defs: opcional no nível raiz — uma lista de strings YAML usada exclusivamente como suporte para âncoras YAML padrão (&anchor) e referências (*anchor). O conteúdo do bloco nunca é lido pelo compilador; ele existe para que os autores possam declarar definições de âncoras em um só lugar e referenciá-las no restante do Aggregate, mantendo DRY os valores repetidos sem perder o dicionário plano O(1) que o compilador percorre. O mecanismo espelha o bloco defs: equivalente da entidade Manifest.

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &default_log_level "info"
spec:
components:
primary:
type: core/compute/api-server:1.0.0
values:
log_level: *default_log_level
secondary:
type: core/compute/python:1.0.0
values:
log_level: *default_log_level

As âncoras são resolvidas durante o parsing do YAML, então *default_log_level já é a string "info" quando o compilador lê o bloco de valores. O bloco defs: é o lugar convencional das definições de âncoras; o YAML permite declarar âncoras em qualquer lugar, mas reuni-las mantém legível o restante do Aggregate. O bloco é opcional — Aggregates que não precisam de âncoras o omitem por completo.