Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Aggregate

El rol conceptual de la entidad Aggregate (Dominio 1 — el plano declarativo de topología del desarrollador) se describe en architecture/04-entity-taxonomy.md. Los patrones de composición (subsistemas, agregados anidados, convención Zero-Port, Parameter Hoisting) se describen en architecture/06-data-taxonomy-and-composition.md. Esta página trata la superficie de autoría del catálogo para el Aggregate — en concreto, la autoría de módulos Aggregate reutilizables para su distribución a través del catálogo.

Ámbito de Component: el subsistema predeterminado

Un Aggregate organiza los componentes en subsistemas — agrupaciones con nombre para aspectos transversales (un nivel de datos, un nivel perimetral) que llevan su propia cascada de anotaciones. La mayoría de los Aggregates tienen una única agrupación, por lo que no requiere ceremonia.

Ámbito único (el predeterminado). Escribe los componentes directamente en spec.components: y omite el bloque subsystems::

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

El compilador los agrupa en un subsistema default sintetizado. La identidad de los nodos no cambia — api sigue siendo api, nunca default.api — de modo que un Aggregate escrito así es intercambiable con la forma explícita de un solo subsistema, y para direccionarlo (en destinos uses:, en los diagnósticos) se usa la ruta simple spec.components.<name>. El ámbito sintetizado se registra fielmente en la IR exportada (con un marcador de subsistema sintetizado), pero nunca aparece en las rutas que un autor escribe o lee.

Ámbitos múltiples. Cuando los componentes se reparten en grupos transversales distintos, declara subsistemas con nombre en subsystems:. Cada subsistema lleva sus propios componentes y su propia cascada de anotaciones, y puede anidar más subsistemas.

Exclusión mutua. spec.components: y spec.subsystems: se excluyen mutuamente en la raíz del Aggregate — escribe uno u otro, nunca ambos. Un documento que declara ambos se detiene al cargarse con un error de envoltorio. (Un subsistema que un desarrollador llama explícitamente default es un subsistema declarado corriente, direccionado en su ruta cualificada spec.subsystems.default.components.<name> — la omisión del ámbito sintetizado depende de la procedencia, no del nombre.)

Módulos Aggregate reutilizables

Los Aggregates sirven tanto de Aggregate raíz que compila una Release como de módulos reutilizables. Un Aggregate padre puede declarar un Aggregate hijo exactamente igual que un componente, pasándole parameters. Para evitar un acoplamiento estrecho, los Aggregates hijos exponen un contrato exportedComponents:, que establece un nombre de interfaz pública estable. El padre llega a los componentes del módulo solo a través de esta interfaz: un destino uses: es el nombre del módulo, un punto y uno de sus alias exportados, y el compilador conecta la arista con el componente interno que nombra el alias. Un destino que entra en un módulo por cualquier otro nombre — el nombre del componente dentro del módulo, o una ruta hacia un módulo anidado dentro de él — detiene la compilación, nombrando el módulo y los alias que exporta; consulta A uses target names a module’s component the module does not export (Un destino nombra un componente de un módulo que el módulo no exporta).

Por qué una lista exportedComponents: explícita. Los autores de un módulo deciden cuáles de sus componentes forman la interfaz pública y cuáles siguen siendo detalles de implementación. Como un padre solo puede nombrar lo que publica la lista, el interior del módulo puede refactorizarse — un componente renombrado, un componente dividido en dos, un worker sustituido por un servicio gestionado — sin romper ningún padre, siempre que cada nombre publicado siga apuntando a un componente. La lista cuesta una entrada por componente publicado, y un componente puede publicarse con su propio nombre (store: store) cuando ese es el nombre que deben usar quienes lo importan. La misma regla rige dentro de una composición: un módulo llega a un módulo que importa a través de los alias exportados de ese módulo. Una Release puede conectar entre sí dos componentes de un mismo módulo, ya que esa conexión no cruza la interfaz de ningún módulo.

Reexportar la interfaz de un módulo anidado. Una entrada de exportedComponents: puede apuntar al alias exportado de un subagregado anidado en lugar de a un componente declarado directamente — un módulo que vuelve a publicar parte de un módulo que importa, bajo su propio nombre de interfaz y opcionalmente con un nombre nuevo. Una arista uses: cuyo destino es un alias reexportado de ese tipo se resuelve de forma transitiva a lo largo de la cadena hasta el nodo interno concreto, de modo que un módulo compone módulos más profundos en su propia interfaz pública sin exponer su organización interna, y un consumidor nunca necesita saber a qué profundidad está anidado el destino. La disciplina de la interfaz estable se mantiene en cada salto: cada módulo reexporta solo lo que decide publicar. Un destino reexportado que no se resuelve en ningún nodo interno detiene la compilación de forma explícita, igual que un destino directo colgante, y una cadena de reexportación que se cierra sobre sí misma se rechaza en lugar de seguirse indefinidamente.

Las declaraciones de un módulo se comprueban como las del Aggregate. El documento de un módulo solo se lee cuando se compila la composición que lo importa, y sus declaraciones se comprueban a partir de ese momento, a cualquier profundidad de anidamiento. El bloque inject: propio de un componente del módulo se ajusta a la lista de permitidos spec.inject de su tipo, y a las reglas que prohíben reclamar dos veces una misma clave de entrega y leer una clave que el tipo no publica. Una vinculación escrita en uno de los subsistemas propios del módulo solo puede nombrar un socket que declare su Feature, y lo mismo vale para una vinculación que la Release escribe sobre un componente que aporta un módulo.

Las vinculaciones a subsistemas de un módulo llegan a sus componentes. Una Feature que un módulo vincula a uno de sus propios subsistemas se propaga en cascada a cada componente que el módulo declara bajo ese subsistema, incluidos los subsistemas anidados, exactamente como lo hace una vinculación a un subsistema en el Aggregate — y solo a esos componentes, nunca al componente de un Aggregate importador situado bajo un subsistema del mismo nombre. Se evalúa justo después de las vinculaciones propias del componente, los subsistemas exteriores antes que los interiores. En un campo que ambas escriben, prevalece la vinculación propia del componente con el mismo nombre, y los campos que esta omite conservan los valores del subsistema. Cada componente al que llega la somete al appliesTo de la Feature. Un hallazgo sobre las declaraciones propias de un módulo nombra el módulo y la clave dentro de su documento — .spec.subsystems.<subsystem>.features.<attachment>, por ejemplo — para que la edición se haga en el módulo, donde está la declaración, y no en el Aggregate que lo importa.

Ubicación en el catálogo

Un módulo Aggregate reutilizable se ubica en el directorio de tipo aggregate/, en la ruta que su metadata.name describe, segmento a segmento, con un directorio de versión como hoja:

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

El nombre de un módulo puede llevar un segmento inicial {publisher} que nombra al proveedor o autor — core para la biblioteca estándar, acme para una empresa — y los módulos publicados de la biblioteca estándar se nombran así: core/agenta se ubica en aggregate/core/agenta/1.0.0/aggregate.yaml. Un nombre que es un único token se ubica un nivel menos profundo, en aggregate/{module-name}/{version}/aggregate.yaml. Ambas formas están bien formadas; el nombre es lo que escribe el autor, y el directorio lo refleja. Ese reflejo es una convención del catálogo y no algo que el compilador compruebe — un módulo se encuentra por el nombre que declara, no por dónde está su archivo.

URI de OCI: hub.aggrega.ai/aggregate/{module-name}:{version}, en minúsculas — así, un módulo llamado core/agenta se publica en hub.aggrega.ai/aggregate/core/agenta:1.0.0, y uno llamado db-module en hub.aggrega.ai/aggregate/db-module:1.0.0.

El patrón de módulos

Módulo hijo (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 padre:

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

Cuando un Aggregate se publica en el catálogo como módulo reutilizable, puede llevar metadata.labels en su envoltorio YAML — por ejemplo aggregate.aggrega.ai/tier: infrastructure o aggregate.aggrega.ai/compliance: pci-dss. Estas etiquetas describen la identidad del módulo y se conservan en el documento del módulo tal como se publica; todavía ningún comando las lee. La búsqueda en el catálogo no indexa los Aggregates, y el grafo de compilación no lleva ni las etiquetas de un módulo ni su nombre de catálogo, por lo que una política de gobernanza no puede seleccionar los componentes de un módulo por el módulo del que proceden.

La distinción crítica. Las etiquetas del Aggregate describen la identidad del módulo reutilizable en el catálogo. No se propagan en cascada a los nodos de componente hijos. Las etiquetas de los componentes proceden exclusivamente de la entidad de catálogo Component del Dominio 2. Si un desarrollador importa un módulo etiquetado aggregate.aggrega.ai/tier: infrastructure, los componentes individuales de ese módulo conservan solo sus propias etiquetas definidas en el catálogo (p. ej., component.aggrega.ai/type: stateful-server). La etiqueta del Aggregate nunca se inyecta en el diccionario labels del nodo de la IR.

Consulta architecture/06-data-taxonomy-and-composition.md §6 para el análisis completo de los Aggregates compuestos / el patrón de módulos (incluida la regla de que los Components no tienen subcomponentes), y para el mecanismo de agrupación transversal subsystems. Consulta vocabulary/data-pillars para la superficie de autoría del contrato tipado parameters.

Contratos de parámetros tipados

El bloque spec.parameters: del Aggregate declara el contrato tipado de los parámetros que la Release cumplimenta. Cada slot de parámetro lleva un type declarado, una description opcional, un default opcional, restricciones opcionales del espacio de valores y (para los slots de tipo objeto) una estructura anidada. El compilador valida cada valor suministrado por la Release contra el contrato durante la resolución, antes de que se ejecute la interpolación 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 }}

El entrecomillado de cada referencia es deliberado: es lo que decide el tipo con el que llega el valor elevado. Consulta templates/parameters-context.md.

Vocabulario de los slots de parámetro

El bloque tipado parameters: acepta el vocabulario de la forma compacta: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate y validateMessage (una comprobación personalizada y el mensaje que notifica), items (para arrays), properties (para objetos), valuesType (para mapas de valores tipados) y required: true (marcador por slot). Tres de esas palabras clave toman como valor un contrato en lugar de un ajuste simple — items, valuesType y cada entrada bajo properties — y, en un slot de parámetro, ese contrato anidado se escribe con la misma forma tipada que el slot que lo rodea: valuesType: { type: boolean }, no valuesType: boolean. Antes de la interpolación, el compilador comprueba directamente el mapa de parámetros fusionado contra estas declaraciones: un parámetro que ningún slot declara se rechaza, un slot marcado con required: true que ni la Release rellena ni un default suministra detiene la compilación, y cada valor suministrado se comprueba contra el type declarado de su slot, la pertenencia a su enum, los límites minLength y maxLength, la expresión regular pattern y el format en un slot de cadena, y los límites min y max: el valor de un slot numérico, la longitud de un slot de cadena y el número de elementos de un slot de array. Los slots de objeto y de array son recursivos: cada entrada bajo properties y cada elemento contra items se comprueban de la misma manera, un contrato valuesType rige las claves que properties no nombra, y una clave anidada que ninguna declaración nombra se rechaza. Consulta vocabulary/compact-form-authoring.md para ver el vocabulario completo de palabras clave, incluidos los casos en que un pilar schema: escribe estas palabras clave de otra forma.

Las palabras clave siguientes también se comprueban en la propia declaración, antes de leer cualquier valor de la Release, de modo que un slot que no podría restringir nada detiene la compilación aunque ninguna Release lo suministre:

  • Los límites de longitud son cero o más. Un minLength o maxLength negativo en la propia declaración de un parámetro lo rechaza el esquema del Aggregate cuando se carga el Aggregate, nombrando el parámetro y la clave. Dentro de un contrato anidado — bajo items, properties o valuesType — un límite de longitud se lee tal como está escrito y no se somete a ese mínimo cuando se carga el Aggregate, así que escríbelo también ahí como cero o más: un minLength negativo no impone nada, y un maxLength negativo rechaza todos los valores.
  • min y max deben acotar algo. En un slot booleano o de objeto, el par no acota nada, por lo que un min o un max escrito ahí se rechaza cuando se carga el Aggregate, nombrando el parámetro y la clave.
  • Un pattern debe compilar. Cada pattern se compila como expresión regular cuando se lee el contrato de parámetros — en el propio slot y dentro de cualquier contrato anidado, a cualquier profundidad — y uno que no compila se rechaza nombrando el parámetro, el pattern y el motivo. El contrato se lee en cada compilación, pull y validación de Release que alcanza el Aggregate, ya sea el propio Aggregate de la Release o un módulo que ese Aggregate importa. La comprobación de valores contrasta después cada valor suministrado con esa misma expresión compilada.
  • Un formato debe ser uno de los que el compilador comprueba. format nombra uno de email, uri, hostname, ipv4, ipv6, uuid, date-time y date, escritos como los escribe JSON Schema. Cualquier otro nombre — una errata como emial, o un nombre que JSON Schema no define, como password — se rechaza cuando se carga el Aggregate, nombrando el parámetro y enumerando los nombres admitidos: en el propio slot, por el esquema del Aggregate, y dentro de un contrato anidado, a cualquier profundidad, cuando se lee el contrato de parámetros. Una cadena suministrada que no tiene el formato nombrado se rechaza después nombrando el parámetro, el valor y el formato. Lo que comprueba cada nombre se describe en vocabulary/compact-form-authoring.md.

Parámetros de tipo objeto y de tipo array

Los slots de parámetro aceptan cualquier tipo que admita la forma compacta, incluidos objetos anidados y 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 }

La Release cumplimenta los parámetros de tipo objeto con YAML estructurado; el compilador valida la estructura contra el esquema declarado antes de la interpolación. Las plantillas que hacen referencia a los campos del objeto usan la sintaxis estándar de plantillas de Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }}, etc.

Validación del contrato de parámetros

Primero se comprueba el propio contrato, cuando se lee: son las comprobaciones de límites de longitud y de patterns descritas arriba en «Vocabulario de los slots de parámetro». Después, el compilador ejecuta tres subpasos durante el procesamiento de parámetros:

  1. Relleno de valores por defecto — los slots con default: definido y sin valor suministrado por la Release reciben su valor por defecto. Los parámetros de objeto anidado tienen una semántica de autoría de tres casos para los slots padre omitidos, explícitamente vacíos y parcialmente escritos: omitir el padre rellena los valores por defecto de los hijos, escribir el padre como {} conserva el vacío explícito (suprime los valores por defecto de los hijos), y escribir el padre como un mapa no vacío rellena solo los hijos que la Release no suministró. Consulta templates/parameters-context.md para ver los ejemplos YAML y la guía de decisión «cuándo usar cada forma».
  2. Validación del contrato — cada valor del mapa fusionado, tanto si lo suministró la Release como si lo rellenó un default:, se valida contra las restricciones declaradas de type / enum / min / max / pattern / estructura anidada. Los fallos de validación detienen la compilación con un error claro que nombra el slot infractor, el valor suministrado y la restricción incumplida. Los parámetros obligatorios ausentes sin default: producen una detención similar con el nombre del slot.
  3. Interpolación — el compilador evalúa todo el texto del Aggregate como una plantilla, antes de leerlo como YAML, y sustituye cada referencia {{ .parameters.<slot> }} — normalmente dentro de cadenas values: de componentes / funcionalidades / subagregados — por el valor resuelto; cualquier otro {{ del texto también se lee como sintaxis de plantilla, de modo que un valor que lleva sus propias llaves dobles — la definición exportada de una plataforma de flujos, por ejemplo — escribe cada {{ como {{"{{"}}, como describe Texto que lleva sus propias llaves dobles. Tras esta pasada, las superficies de plantillas de valores consumen literales ya interpolados y no reciben .parameters en su contexto de plantilla.

El mapa de parámetros fusionado se mantiene vivo durante el renderizado para dar soporte a la evaluación de plantillas de ruta. Las plantillas directory: y subDirectory: escritas por el operador en los límites de la Release leen .parameters.<slot> directamente en el momento del renderizado, contra una lista cerrada de valores permitidos; la emisión de rutas necesita vocabulario de región / entorno para la disposición de artefactos por entorno, y la concesión asimétrica mantiene esa responsabilidad del operador dentro de la superficie del operador sin pasar por los values del Aggregate. El mapa sigue siendo legible hasta que se completan todas las fases de renderizado y solo es accesible desde la compilación para la que se resolvió; las recetas que consumen values: escritos por el desarrollador ven las cadenas posteriores a la interpolación, mientras que las plantillas de ruta ven datos .parameters vivos durante el renderizado. Consulta templates/expansion-matrix.md fila 3 para ver la matriz de disponibilidad de las plantillas de ruta y path-template-variables.md para ver la lista de variables permitidas en las plantillas de ruta.

Para la lista de comprobación más amplia del parameter hoisting (declaración en el Aggregate → referencia en los values → cumplimentación en la Release → consumo en la Recipe) y la mecánica entre pilares, consulta vocabulary/data-pillars.md §«Parámetros» y §«La lista de comprobación del parameter hoisting». Para los campos del contexto de plantilla expuestos durante la interpolación y la excepción de las plantillas de ruta, consulta templates/parameters-context.md.

Una arista uses es una llamada que el Aggregate declara

Una arista uses es la declaración del Aggregate de que un componente llama a otro. El compilador canaliza hacia el llamante los valores que publica el destino y no restringe nada: por sí sola, una arista ni admite al llamante ni rechaza a nadie más, y una carga de trabajo que alcanza la dirección del destino sin una arista la alcanza igualmente.

Restringir quién puede llamar a un componente, y a qué puede llamar este, es decisión del operador, tomada por entorno en la Release. Cuando una Release adjunta a un componente la Feature core/caller-allowlist del catálogo de la biblioteca estándar, la compilación escribe una network policy que admite exactamente los componentes cuyas aristas uses apuntan a él, los pods propios de ese componente y los orígenes que nombra el adjunto. Su contraparte de salida, core/egress-allowlist, permite que el componente al que está adjunta alcance solo los componentes a los que apuntan sus propias aristas uses, sus propios pods, el DNS del clúster y los rangos de direcciones que enumera la Release. Una llamada que el Aggregate no declara como arista puede entonces ser rechazada por el clúster en cualquiera de los dos extremos, allí donde su plugin de red aplique las network policies. Así que escribe una arista para cada llamada que hagan tus componentes, incluida una que no inyecte ningún valor: una arista que falta es una llamada que un componente cercado puede rechazar. model-server-caller-allowlist muestra un servidor de modelos accesible solo a través del gateway que tiene delante.

Los adjuntos propios de una conexión: features en una entrada uses

Una conexión que un componente traza en su forma detallada de uses: es una entrada por derecho propio y, junto a target, inject y values, puede llevar adjuntos, bajo features:. Cada uno se indexa por un slot que declara el socket: el Component consumidor enumera, en el featuresSchema del socket, los slots que puede rellenar cada conexión cableada a través de ese socket (consulta Sockets de topología). Así es como un componente mantiene una credencial distinta para cada componente al que llega: un gateway que llama a dos modelos con dos claves, o un agente que presenta su propia clave a un 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 }

Un adjunto en una conexión lleva type (obligatorio), una description opcional y values para la Feature. No lleva uses ni inject: un adjunto en una conexión no se anida, y cómo llega su material al consumidor lo decide la Recipe del componente consumidor, no un bloque inject. Un documento que escriba cualquiera de las dos claves se rechaza al cargarse, nombrando la clave.

Solo los slots que declara el socket. Un adjunto con un nombre que el featuresSchema del socket no enumera detiene la compilación al cargarse, nombrando la conexión, el socket, el componente y los slots que el socket sí declara y, cuando el nombre está a una edición de uno de ellos, ese slot, como la grafía probablemente pretendida. Un slot rellenado queda sujeto después a la propia declaración del slot en cada conexión: un selector que las etiquetas de la Feature no satisfacen detiene la compilación en esta entrada, y un slot required que queda vacío en cualquier conexión la detiene nombrando esa conexión. Un socket que no declara slots no admite adjuntos en sus conexiones, y tampoco un socket ad hoc — uno que el Aggregate cablea sin que el Component lo declare —, ya que no declara ningún slot. Un componente que aporta un submódulo queda sujeto a la misma regla, y el hallazgo apunta al propio documento del submódulo. Consulta A connection carries an attachment under a name its socket declares no slot for (Una conexión lleva un adjunto con un nombre para el que su socket no declara ningún slot).

Una conexión que traza una Feature no lleva ninguno. El bloque uses: propio de una Feature adjunta — en un componente o en un subsistema — se escribe con la misma forma, pero rechaza features: cuando se carga el documento. Una credencial que necesite una conexión así rellena un slot que la Feature declara en su propio featuresSchema, adjunto junto a la Feature; consulta La credencial propia de una Feature.

El nombre que toma el adjunto. Cada adjunto de conexión se convierte en un adjunto del componente consumidor, con el nombre <alias>.<slot>: el alias con el que se escribe la conexión, un punto y el slot; arriba, gpt.credential. El punto es el separador reservado para los nombres que compone el compilador, que ningún alias, slot ni nombre de adjunto de un Aggregate puede contener, de modo que el nombre compuesto nunca coincide con uno escrito en el bloque features: propio del componente; una Release que lo escriba en un componente o en un límite se rechaza (consulta Configuración de conexiones por arista). Es el nombre por el que el nivel por instancia del Manifest indexa el adjunto (consulta Mapeo de URI plano), el nombre con el que lo notifican los diagnósticos y el grafo IR, y el valor que la FeatureRecipe del adjunto lee como .attachment_name (consulta Nombres derivados del adjunto de una conexión).

A partir de ahí se resuelve como cualquier adjunto: el Manifest vincula su tipo de Feature a una FeatureRecipe, sus values se validan contra el esquema de la Feature — un fallo se notifica en la entrada de conexión que los escribió — y su FeatureRecipe renderiza con los values y la infra propios del adjunto. Dos cosas lo distinguen de los adjuntos propios del componente:

  • No está en .features de la Recipe consumidora. Ese pilar lleva solo los adjuntos escritos en el bloque propio del componente, de modo que a una Recipe que busca en .features sus propios adjuntos por tipo nunca se le entrega la credencial de una conexión. Una Recipe lee el adjunto de una conexión desde la propia conexión, en .context.uses.<alias>.features.<slot>, con la forma que lleva .features, incluidos sus provides resueltos (consulta Los adjuntos de una conexión).
  • Llega solo al consumidor. La salida renderizada de un destino es la misma, lleven lo que lleven las conexiones que llegan a él.

La copia del bloque escrito en el grafo. El grafo IR conserva el bloque uses: de cada componente tal como se escribió, y allí un adjunto de conexión mantiene su type y su description y ninguno de sus values. Los valores aparecen una sola vez, en el adjunto que lleva el consumidor, donde se oculta un valor que la Feature declara sensible.

Una Release puede dimensionar con infra un adjunto declarado aquí, o adjuntar uno propio en una conexión a la que llega: consulta Configuración de conexiones por arista.

Desactivar un componente o un módulo: active:

Una instancia de componente y un módulo subagregado aceptan cada uno un interruptor active: que decide si esa entidad forma parte o no de la topología compilada. Si lo omites, la entidad está presente; ese es el valor por defecto y el caso habitual.

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

Escribe directamente un booleano, o una plantilla sobre .parameters que se resuelva en uno. La forma de plantilla es la razón de ser del interruptor: permite que una Release decida la presencia de una entidad cumplimentando un parámetro, de modo que un solo Aggregate cubre entornos que difieren en las piezas que despliegan, sin que la Release declare nada que el Aggregate no haya declarado.

Lo que elimina un interruptor falso. La entidad se poda antes de construir el grafo, y la poda se propaga en cascada: un componente se lleva consigo sus propias aristas uses: y sus Features adjuntas, y un módulo se lleva todo lo que aportó: sus componentes, sus aristas, sus adjuntos. No se renderiza nada de lo que aportó la entidad podada. Lo que la poda no alcanza es una referencia a ella desde algún punto que ha sobrevivido, que es el tema del párrafo siguiente.

Un componente superviviente que aún apunta a uno podado detiene la compilación. Si api declara una arista uses: hacia redis y redis está desactivado, la compilación se detiene en lugar de dejar que la arista desaparezca, lo que dejaría los valores inyectados de api vacíos sin aviso en el momento del despliegue. Decide cuál de los dos corresponde a este entorno: vuelve a activar el destino, condiciona el consumidor al mismo parámetro para que la pareja salga a la vez, o elimina la arista del bloque uses: del consumidor.

Un interruptor escrito debe resolverse en un booleano, y un valor vacío no lo es. El interruptor se lee de forma estricta una vez resuelta su plantilla, y un literal que no se interpreta como booleano detiene la compilación en lugar de tomar un valor por defecto. El caso al que hay que prestar atención es un interruptor que lee un parámetro sin valor: se resuelve en nada, y leer esa nada como «presente» desplegaría precisamente la entidad que condicionaste a ese parámetro. Por eso, escribir active: sin nada detrás no equivale a omitir la clave: solo un interruptor que nadie escribió vale «presente» por defecto. Da al parámetro un default: en spec.parameters para que cada entorno tenga una respuesta, o cumpliméntalo en la Release. Para que una entidad esté presente de forma incondicional, elimina la clave active: en lugar de vaciarla. La detención se describe en «An active: toggle does not resolve to true or false (Un interruptor no se resuelve en true ni en false)» en la referencia de condiciones de detención.

Un componente desactivado sigue pudiendo nombrarse desde una Release. Una Release puede seguir nombrándolo en un límite, y es deliberado: desactivar un componente es un acto de autoría, y no se espera que la Release que lo configura se reescriba en la misma edición.

Anotaciones en subsistemas y componentes

Los subsistemas y las instancias de componente llevan ambos un campo annotations:. Las anotaciones escritas por el desarrollador en la superficie del Aggregate impulsan la cascada de anotaciones del lado del Aggregate — una anotación de subsistema se propaga a cada subsistema anidado y a cada componente contenido, y los niveles más cercanos sobrescriben con granularidad por clave. El mapa mappings.features.annotations del Manifest declara los bindings que traducen las claves de anotación en vinculaciones sintéticas de Feature en tiempo de build. El invariante del Aggregate como superficie de autoría restringe estas anotaciones al enrutamiento a través de las rutas maps.values del binding; un binding que declara solo rutas maps.infra se activa desde el lado de la Release, no desde el lado del Aggregate.

Formas de los valores

Cada clave de anotación adopta una de cuatro formas, que distinguen «guardo silencio» de «declaro un valor» — un escalar o un objeto estructurado — y de «me excluyo»:

  • Clave ausente — el ámbito no declara ningún valor para esta anotación. Los subsistemas anidados y los componentes contenidos heredan cualquier binding de un ámbito ancestro.
  • Una cadena escalar — un único valor. El binding del Manifest debe declarar exactamente una ruta en total; el escalar se enruta a esa ruta.
  • Un objeto estructurado — un mapa de subclave a subvalor. Cada subclave del objeto se enruta, a través de los maps del binding del Manifest, al campo correspondiente del esquema de la Feature en el pilar declarado.
  • null YAML explícito — el ámbito elimina de su subárbol cualquier binding heredado para esta clave. Los componentes y subsistemas hermanos conservan su herencia; solo el ámbito que se excluye pierde el 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 estructurados para Features con varios campos

Una Feature con varios campos configurables se presta a un valor de anotación estructurado: una sola clave de anotación que lleva valores para varios campos del esquema de la Feature en una única declaración. El lado del Aggregate activa solo las subclaves cuyo pilar en el mapa del binding es values; las subclaves que se enrutan a infra corresponden a anotaciones del lado de la 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

Los valores estructurados se propagan en cascada con una fusión profunda por subclave: las subclaves de los niveles más cercanos sobrescriben las del padre; un null explícito en una subclave suprime la subclave heredada para ese ámbito, mientras las subclaves hermanas se mantienen. Para la explicación completa de los valores estructurados — composición entre ambos lados con subclaves infra del lado de la Release, validación de tipos por subclave, la disciplina de valor por defecto relajado para campos de esquema sin un type declarado — consulta providers/well-known-annotations.md §«Valores de anotación estructurados».

Independencia por clave

Cada clave de anotación hereda, sobrescribe y se excluye de forma independiente. Un componente que declara annotations.feature.myco/db-pool: null se excluye solo de esa clave; las demás claves heredadas del subsistema que lo contiene siguen propagándose a ese componente. Los componentes hermanos del mismo subsistema conservan sus propios mapas de anotaciones de forma independiente — la exclusión de un componente no afecta a sus hermanos.

Anotaciones de componentes de nivel superior

Los componentes de nivel superior (declarados directamente bajo spec.components en lugar de dentro de un subsistema) no llevan ninguna cascada heredada. Su campo annotations: declara los valores directamente en el ámbito del componente; la expansión sintetiza vinculaciones de Feature a partir de cada anotación declarada para la que el Manifest tiene un binding coincidente.

Para la regla de cascada del lado del Aggregate aplicada a los bindings, la partición entre lado y pilar, y un ejemplo completo que muestra cómo los bindings traducen anotaciones en vinculaciones sintéticas de Feature, consulta providers/well-known-annotations.md §«Cascada de anotaciones del lado del Aggregate».

Patrones de anclas YAML (bloque defs:)

El esquema del Aggregate acepta un bloque defs: opcional en el nivel raíz — una lista de cadenas YAML que se usa únicamente como soporte para las anclas YAML estándar (&anchor) y las referencias (*anchor). El compilador nunca lee el contenido del bloque; existe para que los autores puedan declarar las definiciones de anclas en un solo lugar y hacer referencia a ellas en el resto del Aggregate, manteniendo DRY los valores repetidos sin perder el diccionario plano O(1) que recorre el compilador. El mecanismo refleja el bloque defs: equivalente de la entidad 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

Las anclas se resuelven durante el análisis YAML, de modo que *default_log_level es la cadena "info" en el momento en que el compilador lee el bloque de valores. El bloque defs: es la ubicación convencional de las definiciones de anclas; YAML permite declarar anclas en cualquier lugar, pero agruparlas mantiene legible el resto del Aggregate. El bloque es opcional — los Aggregates que no necesitan anclas lo omiten por completo.