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

Aggregate

O papel conceptual da entidade Aggregate (Domínio 1 — o modelo declarativo de topologia do programador) está em architecture/04-entity-taxonomy.md. Os padrões de composição (subsistemas, agregados aninhados, Convenção Zero-Port, elevação de parâmetros) estão em architecture/06-data-taxonomy-and-composition.md. Esta página cobre a superfície de autoria do Aggregate no catálogo — especificamente, a autoria de módulos Aggregate reutilizáveis para distribuição em catálogo.

Âmbito do Component: o subsistema predefinido

Um Aggregate organiza os componentes em subsistemas — agrupamentos com nome para preocupações transversais (uma camada de dados, uma camada de periferia) que transportam a sua própria cascata de anotações. A maioria dos Aggregates tem um único agrupamento, pelo que não precisa de cerimónia.

Âmbito único (a predefiniçã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 agrupa-os num subsistema default sintetizado. A identidade dos nós não muda — api continua a ser api, nunca default.api —, pelo que um Aggregate escrito desta forma é intercambiável com a forma explícita de subsistema único, e endereçá-lo (em destinos uses:, em diagnósticos) usa o caminho simples spec.components.<name>. O âmbito sintetizado é registado fielmente no IR exportado (com um marcador de subsistema sintetizado), mas nunca aparece nos caminhos que um autor escreve ou lê.

Vários âmbitos. Quando os componentes se dividem em grupos transversais distintos, declare subsistemas com nome em subsystems:. Cada subsistema transporta os seus próprios componentes e a sua cascata de anotações, e pode aninhar mais subsistemas.

Exclusividade mútua. spec.components: e spec.subsystems: são mutuamente exclusivos na raiz do Aggregate — escreva um ou outro, nunca ambos. Um documento que declare ambos para no carregamento com um erro de envelope. (Um subsistema a que um programador chama explicitamente default é um subsistema declarado comum, endereçado pelo seu caminho qualificado spec.subsystems.default.components.<name> — a omissão do âmbito sintetizado baseia-se na proveniência, não no nome.)

Módulos Aggregate reutilizáveis

Os Aggregates servem tanto como o Aggregate raiz que uma Release compila como módulos reutilizáveis. Um Aggregate pai pode declarar um Aggregate filho exatamente como um componente, passando-lhe parameters. Para evitar um acoplamento forte, os Aggregates filhos expõem um contrato exportedComponents:, que estabelece um nome de interface pública estável. O pai só alcança os componentes do módulo através desta interface: um destino uses: é o nome do módulo, um ponto e um dos seus aliases exportados, e o compilador liga a aresta ao componente interno que o alias nomeia. Um destino que entra num 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 a build, indicando o módulo e os aliases que 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).

Porquê uma lista exportedComponents: explícita. Os autores de um módulo decidem quais dos seus componentes formam a interface pública e quais continuam a ser detalhe de implementação. Como um pai só pode nomear o que a lista publica, o interior do módulo pode ser refatorizado — um componente renomeado, um componente dividido em dois, um worker substituído por um serviço gerido — sem quebrar nenhum pai, desde que cada nome publicado continue a apontar para um componente. A lista custa uma entrada por componente publicado, e um componente pode ser publicado com o seu próprio nome (store: store) quando esse é o nome que os importadores devem usar. A mesma regra aplica-se dentro de uma composição: um módulo alcança um módulo que importa através dos aliases exportados desse módulo. Uma Release pode ligar entre si dois componentes de um mesmo módulo, já que essa ligação não atravessa a interface de nenhum módulo.

Reexportar a interface de um módulo aninhado. Uma entrada 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 o seu próprio nome de interface e, opcionalmente, com um novo nome. Uma aresta uses: que visa um alias reexportado destes resolve transitivamente através da cadeia até ao nó interno concreto, pelo que um módulo compõe módulos mais profundos na sua própria interface pública sem expor a estrutura interna deles, e um consumidor nunca precisa de saber a que profundidade o destino está aninhado. A disciplina de interface estável mantém-se em cada salto: cada módulo reexporta apenas o que escolhe publicar. Um destino reexportado que não resolve para nenhum nó interno para ruidosamente da mesma forma que um destino direto pendente, e uma cadeia de reexportação que se fecha sobre si própria é 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 é compilada a composição que o importa, e as suas declarações são verificadas a partir desse momento, a qualquer profundidade de aninhamento. O bloco inject: próprio de um componente do módulo está sujeito à lista de permissões spec.inject do seu tipo, e às regras que proíbem reivindicar duas vezes a mesma chave de entrega e ler uma chave que o tipo não publica. Uma associação escrita num dos subsistemas próprios do módulo só pode nomear um socket que a sua Feature declare, e o mesmo se aplica a uma associação que a Release escreve sobre um componente fornecido por um módulo.

As associações aos subsistemas de um módulo chegam aos seus componentes. Uma Feature que um módulo associa a um dos seus próprios subsistemas propaga-se em cascata a cada componente que o módulo declara sob esse subsistema, incluindo subsistemas aninhados, exatamente como faz uma associação a um subsistema no Aggregate — e apenas a esses componentes, nunca ao componente de um Aggregate importador sob um subsistema com o mesmo nome. É avaliada logo após as associações próprias do componente, os subsistemas exteriores antes dos interiores. Num campo que ambas escrevem, prevalece a associação própria do componente com o mesmo nome, e os campos que esta omite mantêm os valores do subsistema. Cada componente que alcança sujeita-a ao appliesTo da Feature. Uma constatação sobre as declarações próprias de um módulo indica o módulo e a chave dentro do seu documento — .spec.subsystems.<subsystem>.features.<attachment>, por exemplo — para que a edição seja feita no módulo, onde a declaração se encontra, 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 o seu metadata.name soletra, segmento a segmento, com um diretório de versão na 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

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

URI OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, em minúsculas — pelo que 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ódulo

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

Etiquetas de módulo

Quando um Aggregate é publicado no catálogo como módulo reutilizável, pode ter metadata.labels no seu envelope YAML — por exemplo aggregate.aggrega.ai/tier: infrastructure ou aggregate.aggrega.ai/compliance: pci-dss. Estas etiquetas descrevem a identidade do módulo e são mantidas no documento do módulo tal como publicado; nenhum comando as lê ainda. A pesquisa no catálogo não indexa Aggregates, e o grafo de build não transporta nem as etiquetas de um módulo nem o seu nome de catálogo, pelo que uma política de governação não pode selecionar os componentes de um módulo pelo módulo de onde provêm.

A distinção crítica. As etiquetas do Aggregate descrevem a identidade do módulo reutilizável no catálogo. Não descem em cascata para os nós de componentes filhos. As etiquetas dos componentes vêm exclusivamente da entidade de catálogo Component no Domínio 2. Se um programador importar um módulo etiquetado com aggregate.aggrega.ai/tier: infrastructure, os componentes individuais dentro desse módulo mantêm apenas as suas próprias etiquetas definidas no catálogo (por exemplo, component.aggrega.ai/type: stateful-server). A etiqueta do Aggregate nunca é injetada no dicionário labels do nó IR.

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

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 transporta um type declarado, uma description opcional, um default opcional, restrições opcionais do espaço de valores e (para slots do tipo objeto) estrutura aninhada. O compilador valida cada valor fornecido pela Release em relação ao contrato durante a resolução, antes de correr a interpolação de parâmetros.

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 deliberadas: são elas que decidem o tipo com que o valor elevado chega. Consulte templates/parameters-context.md.

Vocabulário dos slots de parâmetros

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 reporta), 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 definição simples — items, valuesType e cada entrada em properties — e, num slot de parâmetro, esse contrato aninhado é escrito na mesma forma tipada que o slot à sua volta: valuesType: { type: boolean }, e não valuesType: boolean. Antes da interpolação, o compilador verifica o mapa de parâmetros fundido diretamente em relação a estas 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 para a compilação, e cada valor fornecido é verificado em relação ao type declarado do seu slot, à pertença ao seu enum, aos limites minLength e maxLength, à expressão regular pattern e ao format num slot de cadeia, e aos limites min e max — o valor de um slot numérico, o comprimento de um slot de cadeia e o número de elementos 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 é verificado 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 estas palavras-chave de forma diferente.

As palavras-chave abaixo também são verificadas na própria declaração, antes de qualquer valor da Release ser lido, pelo que um slot que não poderia restringir nada para 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 esquema 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 tal como está escrito e não está sujeito a esse mínimo quando o Aggregate é carregado, pelo que deve escrevê-lo também aí como zero ou mais: um minLength negativo não impõe nada, e um maxLength negativo recusa todos os valores.
  • min e max têm de limitar alguma coisa. Num slot booleano ou de objeto, o par não limita nada, pelo que um min ou max aí escrito é recusado quando o Aggregate é carregado, indicando o parâmetro e a chave.
  • Um padrão tem de 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, a qualquer profundidade — e um que não compile é recusado nomeando o parâmetro, o padrão e o motivo. O contrato é lido em cada compilação, pull e validação de Release que chegue ao Aggregate, quer seja o próprio Aggregate da Release quer um módulo que esse Aggregate importa. A verificação de valores compara então cada valor fornecido com essa mesma expressão compilada.
  • Um formato tem de ser um que o compilador verifica. format nomeia um de email, uri, hostname, ipv4, ipv6, uuid, date-time e date, escritos como o JSON Schema os escreve. Qualquer outro nome — um erro de escrita como emial, ou um nome que o JSON Schema não define, como password — é recusado quando o Aggregate é carregado, nomeando o parâmetro e enumerando os nomes suportados: no próprio slot, pelo esquema do Aggregate, e dentro de um contrato aninhado, a qualquer profundidade, quando o contrato de parâmetros é lido. Uma cadeia fornecida que não tenha o formato nomeado é então recusada nomeando o parâmetro, o valor e o formato. O que cada nome verifica está em vocabulary/compact-form-authoring.md.

Parâmetros do tipo objeto e do tipo array

Os slots de parâmetros aceitam qualquer tipo que a forma compacta suporte, 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 os parâmetros do tipo objeto com YAML estruturado; o compilador valida a estrutura em relação ao esquema 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 padrões em «Vocabulário dos slots de parâmetros», acima. O compilador executa depois três subpassos durante o processamento dos parâmetros:

  1. Preenchimento de predefinições — os slots com default: definido e sem valor fornecido pela Release recebem a sua predefinição. Os parâmetros de objetos aninhados têm uma semântica de autoria com três casos para slots pai omitidos, explicitamente vazios e parcialmente escritos: omitir o pai preenche as predefinições dos filhos, escrever o pai como {} preserva o vazio explícito (suprime as predefinições 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 YAML e o guia de decisão «quando usar cada forma».
  2. Validação do contrato — cada valor do mapa fundido, quer tenha sido fornecido pela Release quer preenchido por um default:, é validado em relação às restrições declaradas de type / enum / min / max / pattern / estrutura aninhada. As falhas de validação param a compilação com um erro claro que nomeia o slot infrator, o valor fornecido e a restrição violada. Os parâmetros obrigatórios em falta sem default: produzem uma paragem semelhante com o nome do slot.
  3. Interpolação — o compilador avalia todo o texto do Aggregate como um template, antes de o ler como YAML, e substitui cada referência {{ .parameters.<slot> }} — normalmente dentro de cadeias values: de componentes / funcionalidades / subagregados — pelo valor resolvido; qualquer outro {{ no texto também é lido como sintaxe de template, pelo que um valor que transporte chavetas duplas próprias — a definição exportada de uma plataforma de fluxos, por exemplo — escreve cada {{ como {{"{{"}}, como descreve Texto que transporta as suas próprias chavetas duplas. Após esta passagem, as superfícies de templates de valores consomem literais já interpolados e não recebem .parameters no seu contexto de template.

O mapa de parâmetros fundido mantém-se vivo durante a renderização para suportar a avaliação de templates de caminhos. Os templates directory: e subDirectory: escritos pelo operador nas fronteiras da Release leem .parameters.<slot> diretamente no momento da renderização, em relação a uma lista de permissões fechada; a emissão de caminhos precisa de vocabulário de região / ambiente para a disposição dos artefactos por ambiente, e a concessão assimétrica mantém essa preocupação do operador dentro da superfície do operador sem passar pelos values do Aggregate. O mapa continua legível até todas as fases de renderização terem terminado e só é acessível a partir da compilação para a qual foi resolvido; as receitas que consomem values: escritos pelo programador veem as cadeias pós-interpolação, enquanto os templates de caminhos veem dados .parameters vivos durante a renderização. Consulte templates/expansion-matrix.md linha 3 para a matriz de disponibilidade dos templates de caminhos e path-template-variables.md para a lista de permissões de variáveis dos templates de caminhos.

Para a lista de verificação mais ampla da elevação de parâmetros (declaração no Aggregate → referência nos values → preenchimento na Release → consumo na Recipe) e para a mecânica entre pilares, consulte vocabulary/data-pillars.md §«Parâmetros» e §«A lista de verificação da elevação de parâmetros». Para os campos do contexto de template expostos durante a interpolação e a exceção dos templates de caminhos, consulte templates/parameters-context.md.

Uma aresta uses é uma chamada que o Aggregate declara

Uma aresta uses é a afirmação do Aggregate de que um componente chama outro. O compilador encaminha os valores que o destino publica para quem chama e não restringe nada: por si só, uma aresta nem admite quem chama nem recusa mais ninguém, e uma carga de trabalho que chegue ao endereço do destino sem uma aresta chega lá na mesma.

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

Os anexos próprios de uma ligação: features numa entrada uses

Uma ligação que um componente estabelece na sua forma verbosa de uses: é uma entrada própria e, ao lado de target, inject e values, pode transportar anexos, em features:. Cada um é identificado por um slot que o socket declara: o Component consumidor enumera, no featuresSchema do socket, os slots que cada ligação estabelecida através desse socket pode preencher (consulte Sockets de topologia). É assim que um componente detém uma credencial diferente para cada componente a que chega — 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 numa ligação transporta type (obrigatório), uma description opcional e values para a Feature. Não transporta uses nem inject: um anexo numa ligação não se aninha, e a forma como o seu material chega ao consumidor cabe à Recipe do componente consumidor decidir, e não a um bloco inject. Um documento que escreva qualquer um deles é recusado quando é carregado, nomeando a chave.

Apenas os slots que o socket declara. Um anexo com um nome que o featuresSchema do socket não enumera para a compilação quando é carregado, nomeando a ligação, o socket, o componente e os slots que o socket efetivamente declara — e, quando o nome está a uma edição de um deles, esse slot, como a grafia provavelmente pretendida. Um slot preenchido fica então sujeito à própria declaração do slot em cada ligação: um selector que as etiquetas da Feature não satisfazem para nesta entrada, e um slot required deixado vazio em qualquer ligação para nomeando essa ligação. Um socket que não declara nenhum slot não admite nenhum anexo nas suas ligações, e o mesmo acontece com um socket ad hoc — um que o Aggregate liga sem que o Component o declare —, uma vez que não declara slot nenhum. Um componente que um submódulo contribui está sujeito à mesma regra, e a constatação aponta para dentro do próprio documento do submódulo. Consulte A connection carries an attachment under a name its socket declares no slot for (Uma ligação transporta um anexo com um nome para o qual o seu socket não declara nenhum slot).

Uma ligação que uma Feature estabelece não transporta nenhum. O próprio bloco uses: de uma Feature anexada — num componente ou num subsistema — é escrito com a mesma forma, mas recusa features: quando o documento é carregado. Uma credencial de que uma ligação dessas precise preenche um slot que a Feature declara no 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 ligação torna-se um anexo do componente consumidor, com o nome <alias>.<slot> — o alias sob o qual a ligação está 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 num Aggregate pode conter, pelo que o nome composto nunca é igual a um escrito no próprio bloco features: do componente; uma Release que o escreva num componente ou numa fronteira é recusada (consulte Configuração de ligações por aresta). É o nome pelo qual o nível por instância do Manifest identifica o anexo (consulte Mapeamento plano de URI), o nome sob o qual os diagnósticos e o grafo IR o reportam, e o valor que a FeatureRecipe do anexo lê como .attachment_name (consulte Nomes derivados do anexo de uma ligação).

A partir daí, resolve como qualquer anexo: o Manifest associa o seu tipo de Feature a uma FeatureRecipe, os seus values são validados em relação ao esquema da Feature — uma falha é reportada na entrada de ligação que os escreveu — e a sua FeatureRecipe renderiza com os próprios values e infra do anexo. Há duas coisas que o distinguem dos anexos próprios do componente:

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

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

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

Desativar um componente ou um 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 sequer parte da topologia compilada. Omita-o e a entidade está presente; essa é a predefinição e o caso normal.

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 resolva para um. A forma de template é a razão pela qual o interruptor existe: permite a uma Release decidir a presença de uma entidade preenchendo um parâmetro, pelo que um único Aggregate cobre ambientes que diferem nas peças 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 propaga-se em cascata: um componente leva consigo as suas próprias arestas uses: e as suas Features anexadas, e um módulo leva tudo o que contribuiu — os seus componentes, as suas arestas, os seus anexos. Nada do que a entidade podada trouxe é renderizado. Aquilo a que a poda não chega é uma referência a ela a partir de algo que sobreviveu, que é o assunto do parágrafo seguinte.

Um componente sobrevivente que ainda aponta para um podado para a compilação. Se api declarar uma aresta uses: para redis e redis estiver 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: volte a ativar o destino, condicione o consumidor ao mesmo parâmetro para que o par saia em conjunto, ou retire a aresta do bloco uses: do consumidor.

Um interruptor que é escrito tem de resolver para um booleano, e um valor vazio não é um. O interruptor é lido de forma estrita depois de o seu template ser resolvido, e um literal que não seja analisável como booleano para a compilação em vez de assumir qualquer predefinição. O caso a vigiar é um interruptor que lê um parâmetro que não tem valor: resolve para nada, e ler nada como «presente» implantaria precisamente a entidade que condicionou a esse parâmetro. Por isso, escrever active: sem nada a seguir não é o mesmo que omitir a chave — só um interruptor que ninguém escreveu assume por predefinição a presença. Dê ao parâmetro um default: em spec.parameters para que todos os ambientes tenham uma resposta, ou preencha-o na Release. Para tornar uma entidade incondicionalmente presente, remova a chave active: em vez de a esvaziar. A paragem é descrita em «An active: toggle does not resolve to true or false (Um interruptor não resolve para verdadeiro ou falso)» na referência das condições de paragem.

Um componente desativado continua a poder ser nomeado a partir de uma Release. Uma Release pode ainda nomeá-lo numa fronteira, e isso é deliberado: 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

Tanto os subsistemas como as instâncias de componentes transportam um campo annotations:. As anotações escritas pelo programador na superfície do Aggregate conduzem a cascata de anotações do lado do Aggregate — uma anotação de subsistema propaga-se a todos os subsistemas aninhados e a todos os componentes contidos, com substituições ao nível mais próximo com granularidade por chave. O mapa mappings.features.annotations do Manifest declara as associações que traduzem chaves de anotação em anexos de Feature sintéticos no momento da compilação. O invariante do Aggregate como superfície de autoria restringe estas anotações ao encaminhamento através dos caminhos maps.values da associação; uma associação que declara apenas caminhos maps.infra dispara a partir do lado da Release, não do lado do Aggregate.

Formas dos valores

Cada chave de anotação toma uma de quatro formas, distinguindo «fico em silêncio» de «declaro um valor» — um escalar ou um objeto estruturado — e de «excluo-me»:

  • Chave ausente — o âmbito não declara nenhum valor para esta anotação. Os subsistemas aninhados e os componentes contidos herdam qualquer associação de um âmbito antecessor.
  • Uma cadeia escalar — um único valor. A associação do Manifest tem de declarar exatamente um caminho no total; o escalar é encaminhado para esse caminho.
  • Um objeto estruturado — um mapa de subchave para subvalor. Cada subchave do objeto é encaminhada através dos maps da associação do Manifest para o campo correspondente do esquema da Feature no pilar declarado.
  • null YAML explícito — o âmbito remove da sua subárvore qualquer associação herdada para esta chave. Os componentes irmãos e os subsistemas irmãos mantêm a sua herança; só o âmbito que se exclui perde a associação.
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 presta-se a um valor de anotação estruturado: uma chave de anotação que transporta valores para vários campos do esquema da Feature numa só declaração. O lado do Aggregate dispara apenas as subchaves cujo pilar do mapa de associação é values; as subchaves encaminhadas 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

Os valores estruturados propagam-se em cascata com fusão profunda por subchave: as subchaves de nível mais próximo substituem as subchaves do pai; um null explícito numa subchave suprime a subchave herdada para esse âmbito, enquanto as subchaves irmãs se mantêm. Para o ensino completo sobre valores estruturados — composição entre lados com subchaves de infra do lado da Release, validação de tipos por subchave, a disciplina de predefinição relaxada para campos de esquema sem type declarado —, consulte providers/well-known-annotations.md §«Valores de anotação estruturados».

Independência por chave

Cada chave de anotação herda, substitui e exclui-se de forma independente. Um componente que declare annotations.feature.myco/db-pool: null exclui-se apenas dessa chave; as outras chaves herdadas do subsistema envolvente continuam a propagar-se a esse componente. Os componentes irmãos no mesmo subsistema mantêm os 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

Os componentes de nível superior (declarados diretamente em spec.components e não dentro de um subsistema) não transportam nenhuma cascata herdada. O seu campo annotations: declara valores diretamente no âmbito do componente; a expansão sintetiza anexos de Feature a partir de cada anotação declarada para a qual o Manifest tem uma associação correspondente.

Para a regra de cascata do lado do Aggregate aplicada às associações, a partição entre lado e pilar, e um exemplo completo que mostra as associações a traduzir anotações em anexos de Feature sintéticos, 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 ao nível da raiz — uma lista de cadeias YAML usada apenas como anfitrião para âncoras YAML padrão (&anchor) e referências (*anchor). O conteúdo do bloco nunca é lido pelo compilador; existe para que os autores possam declarar definições de âncoras num único lugar e referenciá-las no resto do Aggregate, mantendo os valores repetidos DRY sem perder o dicionário plano O(1) que o compilador percorre. O mecanismo espelha o bloco defs: equivalente na 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 resolvem no momento da análise do YAML, pelo que *default_log_level é a cadeia "info" quando o compilador lê o bloco de valores. O bloco defs: é o lugar convencional para as definições de âncoras; o YAML permite declarar âncoras em qualquer lado, mas agrupá-las mantém o resto do Aggregate legível. O bloco é opcional — os Aggregates que não precisam de âncoras omitem-no por completo.