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

Anotaciones bien conocidas

Los Providers leen anotaciones específicas para configurar un contexto propio de la plataforma — definidas en el límite de una Release o en la entrada de un componente en una Release, o declaradas en el Aggregate sobre un subsistema o una instancia de componente. El propio compilador es agnóstico respecto a los valores de estas anotaciones — los deja pasar como cadenas opacas. Cada proveedor declara qué anotaciones lee, en qué ámbito y qué valor predeterminado se aplica cuando la anotación está ausente. Esa declaración reside en spec.provider.wellKnownAnnotations de un Plugin de renderizado de proveedor, y es deliberadamente estrecha: un proveedor enumera una clave solo donde la lee. Un proveedor que no lee ninguna declara en su lugar spec.provider.readsNoWellKnownAnnotations: true.

La matriz de compatibilidad de este capítulo se genera a partir de esas declaraciones, con la granularidad que tiene la declaración — por proveedor por tipo de entrada, porque un proveedor puede leer una clave cuando sintetiza una unidad de despliegue y no tener forma de leerla cuando renderiza un artefacto copiado localmente. Escribe tomando como referencia la matriz de aquí: una celda dice lo que ese proveedor lee en esa ruta, porque una celda no puede decir nada que el proveedor no haya declarado. Una declaración que nombra un tipo de entrada que el propio contrato de comportamiento de renderizado del proveedor no renderiza se rechaza cuando se lee la entidad Plugin, de modo que las dos afirmaciones no pueden discrepar.

El vocabulario reservado es el conjunto más amplio, y reside en cambio en dos lugares — este capítulo, que nombra cada clave reservada, incluidas las que ningún proveedor lee, y el conjunto de prefijos reservados que comprueba el lint de publicación.

Los invariantes

  1. El compilador nunca interpreta ni valida el valor de una anotación bien conocida del proveedor: lleva la clave y su valor a través de la cascada, y avisa donde un destino no actúa sobre la clave.
  2. Cada proveedor documenta qué anotaciones lee y qué valores predeterminados aplica.
  3. Las anotaciones se aplican de manera uniforme dentro de un límite. Si un valor varía por componente, corresponde a anotaciones a nivel de componente (que prevalecen sobre las anotaciones del límite) o a infra del componente.
  4. Las anotaciones bien conocidas de los Provider nunca duplican las etiquetas de los componentes. Las etiquetas de Component describen qué es un componente. Las anotaciones de límite describen dónde se despliega un componente.
  5. Las Recipes no manejan las anotaciones bien conocidas del proveedor. El proveedor aplica automáticamente el contexto de ubicación (espacio de nombres, prefijo de registro, cuenta de servicio) después de que la Recipe produce su contenido.
  6. El prefijo aggrega.ai/ está reservado para la biblioteca estándar. Las anotaciones empresariales personalizadas usan su propio prefijo.
  7. Las anotaciones a nivel de Component en la Release prevalecen sobre las anotaciones a nivel de límite (fusión profunda, gana el componente). Donde un proveedor ensambla la salida de varios límites en un único artefacto, puede exigir que una anotación se resuelva de manera uniforme entre ellos — el proveedor helm-chart toma el nombre del chart paraguas de aggrega.ai/chart-name y, cuando más de un límite contribuye al mismo chart y resuelven esa anotación en valores distintos, la compilación se detiene nombrando los límites en desacuerdo, porque un chart no puede llevar dos nombres.
  8. Las anotaciones que declara el Aggregate alcanzan las mismas claves por debajo de las de la Release. Una clave declarada en un subsistema o en una instancia de componente — en el propio Aggregate, o en un módulo que importa, donde alcanza los componentes propios del módulo — se aplica al componente siempre que la Release no establezca ningún valor para esa clave; donde la Release establece uno, en el límite o en la entrada del componente, el valor que se aplica es el de la Release. Las anotaciones propias de una entidad del catálogo nunca establecen ninguno. aggrega.ai/chart-name es la excepción al alcance del Aggregate: nombra un ensamblado en lugar de un componente, y se lee de los límites de la Release que contribuyen a él.

La matriz completa de anotaciones

Cómo leer esta matriz

Las seis tablas por categoría de abajo nombran cada anotación del vocabulario reservado aggrega.ai/, lo que controla y lo que hace el proveedor cuando está ausente. Si un proveedor dado aplica una clave dada es una cuestión más fina, porque un proveedor renderiza más de un tipo de entrada — un artefacto copiado localmente (sourced), un Workload que el propio proveedor sintetiza (synthesized) o los artifacts: de una Recipe como salida completa de un nodo (artifacts-only) — y una clave puede leerse en una de esas rutas mientras es inalcanzable en otra. Qué proveedor renderiza qué tipo de entrada se indica en ../../architecture/16-recipe-input-composition.md; lo que aplica cada uno es Compatibilidad por proveedor y tipo de entrada más abajo, que es la declaración autorizada de esta página.

Cada celda de esa cuadrícula lleva uno de tres niveles:

  • Aplicada — el proveedor aplica la clave en este tipo de entrada, y la salida renderizada cambia en consecuencia de forma determinista.
  • Aplicada condicionalmente — el compilador emite una sobrescritura aditiva junto al artefacto de destino en lugar de editar el artefacto, así que que el valor surta efecto depende de que ese artefacto exponga una clave propia que coincida. Eficaz en la práctica, nunca una garantía. Ningún proveedor implementa una celda condicional, y la superficie de declaración no ofrece forma de expresar una, así que la cuadrícula generada más abajo emite solo los otros dos niveles. El nivel se nombra porque la vía existe de verdad para un artefacto copiado localmente, y un vocabulario de dos niveles obligaría a la matriz o bien a afirmar una garantía que no puede dar o bien a negar que la vía exista en absoluto.
  • No aplicada — ningún proveedor aplica la clave en esta ruta: el destino no tiene ahí ninguna ranura de renderizado para ella, así que el mecanismo de ubicación no aporta nada a lo que se renderiza, y la columna Predeterminado de la tabla de la categoría indica lo que obtienes en su lugar. El valor sigue pasando por la compilación como una cadena opaca, intacto. El nivel lleva el nombre del mecanismo y no de la suerte del valor, porque son preguntas distintas y solo la primera es una que una celda puede responder: lo que aplica un proveedor es una propiedad de las ranuras de renderizado de ese destino, que es exactamente lo que indica la declaración detrás de cada celda.

Dos ámbitos, y solo uno de ellos hace del tipo de entrada un eje significativo:

  • Con ámbito de nodo — aggrega.ai/namespace, aggrega.ai/image-registry, aggrega.ai/image-pull-secret, aggrega.ai/service-account y aggrega.ai/kubernetes-version dan forma a la salida renderizada propia de un componente, que produce la ruta que selecciona su tipo de entrada. Estas son las columnas de la cuadrícula.
  • Con ámbito de ensamblado y de referencia — aggrega.ai/chart-name se resuelve una sola vez cuando se ensambla un chart paraguas, y las tres claves aggrega.ai/aws-* se resuelven cuando una referencia cruza un límite. El tipo de entrada no es un eje para ninguna de las dos: el valor se lee en el ensamblado o en la referencia, sea cual sea la forma en que se renderizó cada nodo contribuyente. Tienen su propia tabla en Claves resueltas por ensamblado y por referencia.

Categoría 1 — Ubicación

AnotaciónAplicada porPropósitoPredeterminado
aggrega.ai/namespacehelm (con fuente, sintetizado); compose (con fuente, sintetizado)Espacio de nombres de Kubernetes (helm); nombre de la red de Docker (compose)No se inyecta si está ausente (helm); una red con el nombre de la ruta del archivo compose, compartida por todos los nodos de ese archivo sin la anotación (compose)
aggrega.ai/project-namereservada; ningún proveedor la leeReservada para un nombre de proyecto de Docker Compose—
aggrega.ai/regionreservada; ningún proveedor la leeReservada para una región de nube en el ámbito de ubicación—
aggrega.ai/account-idreservada; ningún proveedor la leeReservada para un identificador de cuenta de nube en el ámbito de ubicación—
aggrega.ai/kubernetes-versionhelm (con fuente)Versión de Kubernetes del clúster en el que se despliega el componente, que un chart renderizado desde la fuente lee como .Capabilities.KubeVersionLa versión para la que renderiza el helm template estándar de la misma release de helm: la de la biblioteca cliente de Kubernetes con la que está construido el proveedor

aggrega.ai/namespace tiene un doble propósito por diseño. Expresa la misma intención de aislamiento lógico — «los recursos de este límite viven en su propio ámbito direccionable» — en la forma nativa de cada destino: un metadata.namespace de Kubernetes para helm, un nombre de red de Docker para compose. Los autores de Recipe establecen una sola anotación; cada proveedor la materializa de forma adecuada para el destino. En el caso de compose, el nombre de la red se resuelve por nodo a partir de la anotación de ese nodo, recurriendo a la ruta del archivo compose cuando el nodo no lleva ninguna anotación — de modo que los límites sin anotación que comparten un archivo compose comparten una red, y es aggrega.ai/namespace lo que los separa. Sea cual sea de los dos el que aporte la identidad, esta se escribe después en los caracteres que acepta un nombre de red de compose — cualquier otro carácter se escribe como secuencia de escape en lugar de sustituirse, de modo que dos identidades que difieran en lo más mínimo quedan en dos redes, y las mayúsculas y minúsculas de la identidad se conservan tal como se escribieron. La referencia del proveedor compose documenta la derivación por completo, incluido cómo leer un nombre codificado y lo que cuesta un cambio de nombre.

aggrega.ai/kubernetes-version indica una propiedad del clúster en el que se despliega un componente, y no dónde dentro de él acaba el componente: las plantillas de chart eligen una versión de API, un campo o todo un mecanismo según la versión para la que se renderizan, y la compilación no tiene ningún clúster al que preguntar. El proveedor helm lee el valor del mismo modo en que helm template --kube-version lee su flag y detiene la compilación ante un valor que no es una versión; cuando no se nombra ninguna, un chart se renderiza para la versión para la que renderiza helm template de la misma release de helm. La referencia del proveedor helm documenta las formas aceptadas y el valor predeterminado.

Categoría 2 — Registro

AnotaciónAplicada porPropósitoPredeterminado
aggrega.ai/image-registryhelm, compose — solo sintetizadoPrefijo de registro para las imágenes de contenedor, aplicado a cada referencia a una imagen de contenedor sintetizadaSin prefijo
aggrega.ai/image-pull-secrethelm — solo sintetizadoNombre de imagePullSecrets de Kubernetes, unido a las entradas existentes del pod sintetizadoNinguno

Categoría 3 — Redes

AnotaciónAplicada porPropósitoPredeterminado
aggrega.ai/cluster-domainreservada; ningún proveedor la leeReservada para un sufijo DNS para el descubrimiento de servicios entre espacios de nombres—
aggrega.ai/ingress-classreservada; ningún proveedor la leeReservada para una IngressClass de Kubernetes en los recursos Ingress—
aggrega.ai/service-meshreservada; ningún proveedor la leeReservada para las anotaciones de inyección de sidecar de la malla—

Categoría 4 — Seguridad

AnotaciónAplicada porPropósitoPredeterminado
aggrega.ai/service-accounthelm — solo sintetizadoServiceAccount de Kubernetes para los Pods sintetizados; prevalece sobre el workload.serviceAccount de la Recipe cuando ambos están definidosEl workload.serviceAccount de la Recipe, o sin definir cuando la Recipe no declara ninguno
aggrega.ai/pod-security-standardreservada; ningún proveedor la leeReservada para un nivel de los Pod Security Standards—
aggrega.ai/iam-rolereservada; ningún proveedor la leeReservada para un rol de identidad de nube enlazado a una carga de trabajo—

Categoría 5 — Empaquetado

AnotaciónAplicada porPropósitoPredeterminado
aggrega.ai/chart-namehelm-chart — por ensambladoNombre del chart paraguasNombre del Aggregate y ruta de ensamblado del paraguas, unidos — consulta Resolución del nombre del chart
aggrega.ai/chart-versionreservada; ningún proveedor la leeReservada para una versión de chart de Helm—
aggrega.ai/stack-namereservada; ningún proveedor la leeReservada para un stack nombrado explícitamente—
aggrega.ai/tf-backendreservada; ningún proveedor la leeReservada para un identificador de backend de estado de Terraform—

Categoría 6 — Destino en la nube

AnotaciónAplicada porPropósitoPredeterminado
aggrega.ai/aws-accountcloudformation — por referencia entre límitesCuenta de AWS en la que se despliega el stack (límite)Misma cuenta — una referencia entre stacks se resuelve mediante la importación de una exportación de stack de la misma cuenta
aggrega.ai/aws-regioncloudformation — por referencia entre límitesRegión de AWS en la que se despliega el stack (límite)Misma región — una referencia entre stacks se resuelve mediante la importación de una exportación de stack de la misma región
aggrega.ai/aws-assume-role-arncloudformation — por referencia entre límitesARN del rol de IAM que asume una lectura de stack entre cuentas para alcanzar los valores exportados de un stack homólogoNo se proporciona ningún rol en una referencia entre cuentas

Cada límite de CloudFormation se renderiza en un único stack. Cuando una arista uses cruza de un límite a otro, el proveedor cloudformation necesita saber dónde reside el stack homólogo para dar forma a la referencia: dos stacks en la misma cuenta y región intercambian valores mediante una exportación y una importación de stack; un homólogo en una cuenta o región distinta necesita una lectura de salidas de stack entre cuentas, opcionalmente bajo un rol asumido. Estas anotaciones llevan ese contexto de ubicación. Cada una se lee en el momento en que el proveedor da forma a dicha referencia, y se resuelve en ese momento mediante la cascada de anotaciones ordinaria — un valor establecido en el componente prevalece sobre un valor establecido en el límite, y un valor que establece la Release prevalece sobre uno que declara el Aggregate. Un valor a nivel de límite es, por tanto, la forma habitual de expresarlas, no la única. Son cadenas de puntero escalares opacas — el proveedor las canaliza hacia la referencia que construye y nunca las resuelve contra el estado real de AWS; la cuenta, la región y el rol los proporciona la Release o se declaran en el Aggregate, y el entorno de ejecución resuelve la lectura física final. Cuando todas las anotaciones están ausentes, el proveedor trata al homólogo como de la misma cuenta y la misma región y no proporciona ningún rol.

Compatibilidad por proveedor y tipo de entrada

Las claves con ámbito de nodo, por proveedor y por tipo de entrada. Los encabezados de columna omiten el prefijo aggrega.ai/ que lleva cada clave. applied y — llevan los niveles definidos arriba, donde — significa no aplicada; n/a significa que el proveedor no renderiza ese tipo de entrada en absoluto, de modo que ahí no existe ninguna ruta en la que la clave pueda aplicarse o dejar de aplicarse.

ProviderTipo de entradanamespaceimage-registryimage-pull-secretservice-accountkubernetes-version
helmsourcedapplied———applied
helmsynthesizedappliedappliedappliedapplied—
helmartifacts-only—————
composesourcedapplied————
composesynthesizedappliedapplied———
composeartifacts-only—————
helm-chartsourced—————
helm-chartsynthesizedn/an/an/an/an/a
helm-chartartifacts-onlyn/an/an/an/an/a
terraformsourced—————
terraformsynthesizedn/an/an/an/an/a
terraformartifacts-only—————
cloudformationsourced—————
cloudformationsynthesizedn/an/an/an/an/a
cloudformationartifacts-only—————

Cada proveedor distribuido con el compilador tiene filas aquí, incluido uno que no lee ninguna anotación de ubicación — un conjunto de filas vacío sería indistinguible de un proveedor que nadie ha descrito todavía. Un proveedor suministrado por separado declara lo que lee de la misma manera y no figura aquí, porque una página publicada no puede enumerar proveedores que nunca ha visto.

Una Recipe puede declarar más de un tipo de entrada a la vez — un workload: con artifacts: junto a él, por ejemplo. Lee la cuadrícula por tipo: la salida sintetizada de un nodo así es la fila synthesized, y sus archivos de artefactos son el caso de los artefactos. La fila artifacts-only es el tipo de entrada en el que una Recipe declara artifacts: y nada más.

No tienes que consultar la cuadrícula para averiguarlo. Establecer una clave que el destino de uno de tus renderizados no lee en ninguno de los tipos de entrada de ese renderizado produce una advertencia que nombra la clave, el destino y cada tipo de entrada que declara ese renderizado, de modo que una celda en la que caíste por accidente se anuncia en el momento en que compilas, en lugar de esperar a que se te ocurra mirar aquí:

warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it

En un renderizado que declara más de un tipo de entrada, la advertencia trata de ese renderizado en su conjunto, no de una de sus mitades. Como los tipos se componen por adición, un destino que lee la clave en cualquiera de ellos la aplica efectivamente, y la salida de ese renderizado lleva el resultado — así que no se emite ninguna advertencia. Una advertencia aparece solo cuando ninguno de los tipos que declara ese renderizado aplica la clave, y los nombra a todos:

warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored it

Así, un workload: junto a un source: basta para que aggrega.ai/service-account surta efecto en ese nodo, y la compilación no dice nada al respecto — que es el informe honesto, porque el valor alcanza la mitad sintetizada y aparece en los manifiestos emitidos.

Lee la cuadrícula por renderizado, no por componente. Una funcionalidad vinculada a un nodo genera sus recursos mediante el destino que nombra su propia FeatureRecipe, en los tipos de entrada que declara esa FeatureRecipe — así que acaba en su propia fila de esta cuadrícula, que no tiene por qué ser la fila en la que acaba su componente anfitrión. Un componente que sintetiza su Workload mientras una funcionalidad vinculada aporta artifacts: junto a él lee la fila synthesized para los manifiestos propios del componente y la fila artifacts-only para los archivos de la vinculación, y una clave aplicada en la primera puede no aplicarse en la segunda. La advertencia sigue la misma división y te informa de cada una por separado, porque son archivos distintos. Una funcionalidad vinculada a un límite en lugar de a un componente con nombre lee la cuadrícula de la misma manera.

El valor sigue pasando intacto — la compilación no se detiene, porque un límite que abarca componentes en destinos heterogéneos siempre tendrá algún renderizado que no puede actuar sobre una clave dada, y eso es una Release ordinaria y no un error. Una anotación de límite se propaga en cascada, así que una línea escrita produce una advertencia por cada renderizado que no puede actuar sobre ella, y así es como ves qué partes de tu salida se ven afectadas. Pertenece a la clase unsupported-field y se silencia con el indicador de esa clase; Advertencias tiene el detalle. Dos restricciones que conviene conocer: solo se comprueban las claves con el prefijo aggrega.ai/ simple, ya que una clave con subprefijo es tu propio vocabulario, y un proveedor que no declara ninguna afirmación de compatibilidad no produce ninguna advertencia, porque no hay nada con lo que comparar lo que escribiste. Un proveedor que declara que no lee ninguna de estas claves no es silencioso de esa manera: readsNoWellKnownAnnotations: true en su entidad Plugin es una afirmación que no cubre ninguna clave, así que cada clave con prefijo simple que alcanza uno de sus renderizados provoca la advertencia. El proveedor terraform lo declara.

Por qué un artefacto copiado localmente aplica menos claves. Una anotación con ámbito de nodo se aplica donde el proveedor tiene una ranura de renderizado para ella. Cuando el proveedor sintetiza él mismo la unidad de despliegue, es dueño de cada campo del resultado, así que un prefijo de registro, un pull secret y una cuenta de servicio tienen todos un lugar donde ir. Un artefacto copiado localmente — un chart de Helm, un archivo compose, un módulo de Terraform — lleva en cambio su propia interfaz de configuración, y el compilador no lee esa interfaz, por lo que no puede saber a cuál de las claves propias del artefacto correspondería un prefijo de registro o una cuenta de servicio. La ubicación que controla la llamada de renderizado circundante se sigue aplicando, por eso aggrega.ai/namespace se aplica a un chart renderizado desde la fuente. La ubicación que supondría decidir dónde, dentro del artefacto de otra persona, corresponde un valor no se aplica, y un autor la proporciona mediante los valores propios de ese artefacto. Por eso las filas con fuente son escasas donde las filas sintetizadas están llenas, y es la forma que cabe esperar de cualquier clave añadida más adelante.

Claves resueltas por ensamblado y por referencia

Cuatro de las claves incluidas no tienen ámbito de nodo, por lo que quedan fuera de la cuadrícula de arriba en lugar de integrarse en ella: el tipo de entrada no es un eje significativo para ellas, y dar a cada una una fila por tipo de entrada repetiría una sola celda tres veces e implicaría una distinción que no existe. Cada una declara el ámbito de límite, y la tabla de abajo se genera a partir de esas declaraciones.

AnotaciónAplicada porPropósitoPredeterminado
aggrega.ai/chart-namehelm-chartNombre del chart paraguas de Helm ensamblado.Se usan el nombre del Aggregate y la ruta de ensamblado del paraguas — su directorio de salida bajo dist/, como boundaries/data/helm-chart —, cada uno codificado, y se unen.
aggrega.ai/aws-accountcloudformationLa cuenta de AWS en la que se despliega el stack (límite). Una referencia entre límites la lee para decidir si un stack homólogo está en la misma cuenta.El homólogo se trata como de la misma cuenta, y una referencia entre stacks se resuelve mediante la importación de una exportación de stack de la misma cuenta en lugar de una lectura de salidas de stack entre cuentas.
aggrega.ai/aws-regioncloudformationLa región de AWS en la que se despliega el stack (límite). Una referencia entre límites la lee para decidir si un stack homólogo está en la misma región.El homólogo se trata como de la misma región, y una referencia entre stacks se resuelve mediante la importación de una exportación de stack de la misma región.
aggrega.ai/aws-assume-role-arncloudformationEl ARN del rol de IAM que asume una lectura de stack entre cuentas para alcanzar los valores exportados de un stack homólogo.No se proporciona ningún rol, y una referencia entre cuentas no lleva ningún assume-role.

Cuándo se resuelve cada una, algo que la propia declaración no lleva. aggrega.ai/chart-name se resuelve una sola vez por ensamblado de chart paraguas, a partir de la cascada de anotaciones del límite; cada contribuyente a un mismo ensamblado debe resolverla al mismo valor, y un desacuerdo detiene la compilación nombrando los límites. Las tres claves aggrega.ai/aws-* se resuelven por referencia entre límites con precedencia del componente sobre el límite, así que un valor del componente prevalece sobre un valor del límite; la categoría 6 de arriba describe la referencia a la que da forma cada una.

Nombres reservados que ningún proveedor lee

Once claves de la matriz de arriba están marcadas como reservada; ningún proveedor la lee: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name y aggrega.ai/tf-backend.

Establecer una de ellas en una Release o en un Aggregate no tiene ningún efecto en la salida renderizada. Ningún proveedor las lee, y no se aplica ningún valor predeterminado en su lugar — en particular, no se aplica ningún sufijo DNS para aggrega.ai/cluster-domain, así que una Recipe que necesita un dominio de clúster debe proporcionarlo como un valor ordinario en lugar de depender de esta anotación. Un autor de Recipe que necesita uno de estos comportamientos lo expresa como un valor de la Recipe o un campo infra del componente.

Ningún proveedor declara estas once. El wellKnownAnnotations de un proveedor enumera solo lo que lee, así que ninguna de las once aparece ahí — quien abre el Plugin helm, helm-chart, compose o cloudformation ve las claves que funcionan y nada más. Ese es el sentido de la declaración estrecha: una clave declarada es una clave que funciona, y el ámbito junto a ella dice en qué ruta.

Dos de los nombres reservados están cerca de claves activas y no son intercambiables con ellas. aggrega.ai/region y aggrega.ai/account-id nombran una región y una cuenta en el ámbito de ubicación y no llegan a ningún proveedor; las claves que lee el proveedor cloudformation son aggrega.ai/aws-region y aggrega.ai/aws-account, en el espacio de nombres de la nube, en la categoría 6. Cuando te refieras al contexto de ubicación entre stacks de CloudFormation, escribe la forma aws- — el par sin prefijo se reserva frente a colisiones, no está conectado a nada. Otros dos nombres reservados están cubiertos por otras superficies en lugar de por una anotación: aggrega.ai/stack-name está reservado, mientras que el nombre del stack en el que se renderiza un límite cloudformation se deriva de forma determinista de la identidad de la release y del límite; y el rol de identidad de nube de una carga de trabajo se proporciona como un campo ordinario establecido por el operador en la Feature que emite el enlace, no mediante aggrega.ai/iam-role.

Los nombres siguen reservados, y siguen listados aquí, porque el prefijo aggrega.ai/ está reservado: un catálogo empresarial no debe reutilizar una de estas claves con un significado propio, porque la plataforma reserva la clave para un significado suyo. Esta matriz y el conjunto de prefijos reservados que comprueba el lint de publicación son juntos el registro de reservas, y ambos se mantienen en el mismo conjunto de nombres mediante una comprobación que lee los dos y falla cuando divergen. Escribir una de las once, por tanto, ni hace fallar la validación ni activa la regla «no uses el prefijo aggrega.ai/ simple» — simplemente no tiene ningún efecto.

La versión del chart paraguas que emite un límite helm-chart es siempre 0.1.0; es un valor fijo y no un valor predeterminado de aggrega.ai/chart-version.

Nota: los enlaces features.annotations del Manifest que usan el prefijo aggrega.ai/ se rechazan en el momento de la carga; el prefijo está reservado exclusivamente para las anotaciones bien conocidas de proveedor documentadas en este capítulo. Los autores de enlaces de Feature dirigidos por anotaciones usan feature.aggrega.ai/ para los atajos de la biblioteca estándar o un dominio personalizado para los atajos empresariales.

Nota: un null explícito en una anotación de Release elimina el enlace heredado del límite o del componente que sobrescribe (exclusión voluntaria de una Feature dirigida por anotaciones). Los componentes hermanos del mismo límite que no se excluyeron conservan el enlace heredado; las claves ausentes siguen heredando de la cascada principal como de costumbre.

Anotaciones escritas en el catálogo que lee el compilador

Todo lo anterior es una anotación de proveedor: escrita en la Release o declarada en el Aggregate, transmitida por el compilador como una cadena opaca, leída por un proveedor. Un segundo vocabulario, mucho más pequeño, funciona en sentido contrario — escrito por el Arquitecto en los metadata.annotations propios de una entidad del catálogo, leído por el compilador y nunca visto por un proveedor. El invariante 1 de arriba trata del vocabulario de los proveedores y no se extiende a estas; el compilador lee exactamente las claves enumeradas aquí y ninguna otra.

Estas claves se sitúan bajo un subprefijo <scope>.aggrega.ai/, no bajo el prefijo aggrega.ai/ simple, así que quedan fuera del registro de reservas que lleva la matriz de arriba y fuera de la regla de prefijos reservados que el lint de publicación aplica a las claves con prefijo simple.

AnotaciónEscrita enLeída porPropósito
features.aggrega.ai/requiredType.<label>metadata.annotations del Componentel compilador, sobre el grafo finalizadoDeclara un mandato de presencia: cada instancia de este Component debe llevar al menos una vinculación cuyo tipo sea igual al valor de la anotación. <label> es un sufijo elegido por el autor que nombra el requisito en el diagnóstico; no es un nombre de ranura y nada lo desreferencia. Repite la clave con etiquetas diferentes para declarar varios mandatos.

El mandato se satisface con una vinculación en cualquier ámbito — un bloque features: a nivel de componente o de subsistema, un bloque de la Release a nivel de límite o de componente, o una expansión dirigida por anotaciones — porque comprueba el conjunto final de vinculaciones de la instancia y no de dónde procede cada vinculación. Un mandato no satisfecho detiene la compilación nombrando la etiqueta y el tipo requerido; un valor que no es un URI de tipo de Feature, o una clave sin etiqueta después del prefijo, se detiene con un diagnóstico distinto de declaración mal formada. El tratamiento completo de la escritura, y en qué se diferencia un mandato de una ranura featuresSchema, está en entities/component.md «Obligaciones de presencia».

Etiquetas de procedencia emitidas por los proveedores

Las anotaciones anteriores fluyen hacia la compilación — la Release o el Aggregate las escriben, los proveedores las consumen. Los Providers también emiten un conjunto paralelo de etiquetas hacia fuera de la compilación, adjuntándolas a la salida renderizada para que las herramientas posteriores puedan atribuir los recursos en tiempo de ejecución al contenido del catálogo que los produjo. Estas etiquetas de procedencia no se escriben en la Release; se derivan del propio estado de la compilación (identidad de la Recipe, ruta del límite, nombre del agregado, entorno, sync wave, versión del compilador) y el proveedor las emite en el momento del renderizado.

El conjunto que emiten los proveedores, adjuntado a cada manifiesto de Kubernetes que renderiza el proveedor helm, a cada artefacto cargado mediante $import: que el proveedor helm-chart añade a un subchart, y a cada servicio emitido por compose — las plantillas propias de un subchart de helm-chart se copian tal como las escribió su autor, así que llevan lo que ese autor haya escrito:

EtiquetaOrigenEmisión
app.kubernetes.io/nameID del nodo (o, para un recurso que emite una FeatureRecipe, el identificador derivado para esa vinculación — ver más abajo)Solo helm y helm-chart — etiqueta estándar de Kubernetes, no se emite en los servicios de compose
aggrega.ai/component-idID del nodo (o, para un recurso que emite una FeatureRecipe, el identificador derivado para esa vinculación — ver más abajo)Los tres proveedores
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> de la Recipe productora (o de la FeatureRecipe productora para los recursos emitidos por una FR)Los tres proveedores, cuando la entidad productora tiene definidos tanto el nombre como la versión; una anotación en helm y helm-chart
aggrega.ai/boundary-pathRuta del límite a la que se enrutó el componenteLos tres proveedores, cuando la ruta del límite no está vacía; una anotación en helm y helm-chart
aggrega.ai/aggregate-namemetadata.name del AggregateLos tres proveedores, cuando está definido
aggrega.ai/compiler-versionVersión del compilador estampada en tiempo de compilaciónLos tres proveedores, cuando está definido
aggrega.ai/providerEl proveedor que renderizó el recursoLos tres proveedores
aggrega.ai/provider-versionLa versión de ese proveedorLos tres proveedores
aggrega.ai/environmentmetadata.environment de la ReleaseLos tres proveedores — toda Release lo declara
aggrega.ai/sync-waveEntero syncWave por límiteLos tres proveedores, cuando es distinto de cero; una anotación en helm y helm-chart

Los valores de aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider y aggrega.ai/provider-version provienen de cadenas que la compilación no somete a las reglas de Kubernetes para los valores de etiqueta — un Aggregate llamado imported/flow, un entorno llamado eu/prod, la versión (devel) de una compilación de desarrollo. En helm y helm-chart, cada una de estas etiquetas lleva su valor tal como está escrito cuando el valor ya es un valor de etiqueta válido: letras, dígitos, -, _ y ., una letra o un dígito en ambos extremos, como máximo 63 caracteres. En caso contrario, la etiqueta lleva el valor reescrito en esa forma — cualquier otro carácter pasa a ser -, las secuencias de - se reducen a uno, los extremos se recortan hasta una letra o un dígito y el resultado se trunca a 63 caracteres como máximo — y el valor literal se añade como anotación bajo la misma clave. Por tanto, un Aggregate llamado imported/flow recibe la etiqueta aggrega.ai/aggregate-name: imported-flow y la anotación aggrega.ai/aggregate-name: imported/flow; un valor sin ningún carácter que una etiqueta conserve lo lleva solo la anotación. Un selector compara el valor de la etiqueta tal como aparece en la salida renderizada, y las herramientas que necesitan el nombre exacto leen la anotación cuando existe. Compose, cuyos valores de etiqueta no tienen restricciones, lleva el valor literal como etiqueta.

Notas de emisión por proveedor

  • helm — las etiquetas van a metadata.labels en cada recurso de Kubernetes renderizado (Deployment, Service, PVC, etc.), y las claves que el valor de una etiqueta no puede llevar — aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave y el valor literal de cualquier etiqueta reescrita como se describe arriba — a metadata.annotations. Las rutas del modo con fuente (renderizado mediante el SDK de Helm con inyección de etiquetas posterior al renderizado), del modo sintetizado (síntesis de la carga de trabajo) y de artifacts: producen el mismo conjunto.
  • helm-chart — las mismas etiquetas y anotaciones van a cada artefacto cargado mediante $import: que el proveedor añade a los templates/ de un subchart. Las plantillas propias del chart de origen, y un artefacto de contenido en línea colocado en la raíz del subchart, no llevan ninguna de ellas — ver helm-chart.md.
  • compose — las etiquetas van a services.<name>.labels en cada servicio de compose emitido. El modo con fuente (inyección de etiquetas posterior a la fusión sobre el documento fusionado de base + valuesMapping) y el modo sintetizado (síntesis de la carga de trabajo que establece directamente el bloque de etiquetas del servicio) producen ambos el mismo conjunto. La etiqueta app.kubernetes.io/name, específica de Kubernetes, se omite de la salida de compose.

Para los recursos que emite una FeatureRecipe, el valor de aggrega.ai/component-id se construye a partir de la vinculación y no del nombre del componente anfitrión — para cada forma en que una FeatureRecipe puede entregar esos recursos, de modo que los recursos de una vinculación nunca son indistinguibles por etiqueta de los del propio componente anfitrión. Que esa identidad sea también aquello por lo que esos recursos reciben su nombre depende de la entrega: una carga de trabajo que Aggrega sintetiza recibe el nombre de la identidad, mientras que un chart o un fragmento que proporcionó el autor de la vinculación conserva el nombre de release de Helm y el prefijo del archivo de salida del componente anfitrión, porque las plantillas propias del autor se renderizan con ese nombre. Cómo se compone el valor — los dos comienzos posibles, las partes y su unión con --, cómo se escribe explícitamente un carácter que una etiqueta no puede llevar, cómo se acorta un valor demasiado largo para su destino, y de qué nombres es y no es la base — no depende del proveedor, así que se indica una sola vez en vocabulary/labels-and-annotations.md «Etiquetas de procedencia emitidas en la salida renderizada» en lugar de repetirse aquí. Esta página se ocupa de la otra mitad: dónde van las etiquetas en la salida renderizada de cada proveedor.

La clave aggrega.ai/recipe-uri se resuelve en el name:version propio de la FeatureRecipe, no en la identidad de la Recipe que la consume — las herramientas posteriores que leen la etiqueta para identificar la entidad productora obtienen la procedencia correcta tanto para la salida emitida por los componentes como para la emitida por las FR.

Anotaciones sync-wave

La clave aggrega.ai/sync-wave anterior va emparejada con una anotación sync-wave que las herramientas posteriores leen para ordenar lo que aplican. En compose la clave es una etiqueta, que expone el valor de la oleada a las consultas por selector; en helm y helm-chart es una anotación, y la anotación emparejada muestra el valor donde cada herramienta lo lee por convención.

AnotaciónEmisiónConsumida por
argocd.argoproj.io/sync-wavehelm, en cada recurso de Kubernetes que renderiza, y helm-chart, en cada artefacto cargado mediante $import: — donde syncWave es distinto de cero en el límite contribuyenteOrdenación sync-wave de ArgoCD
helm.sh/hook-weightSolo helm, en los manifiestos generados por las plantillas del chart que ya llevan una anotación helm.sh/hook cuando syncWave es distinto de ceroOrdenación por hook-weight de Helm dentro de una fase de hook

La emisión de helm.sh/hook-weight depende de la ruta

Una sutileza que conviene señalar a los autores de charts: helm.sh/hook-weight solo se emite en los manifiestos renderizados por la ruta de plantillas del chart — el directorio templates/ del chart renderizado mediante el SDK de Helm. Los Manifests producidos por la ruta de artefactos — en el proveedor helm cada entrada del bloque artifacts: de la Recipe, de contenido en línea o cargada mediante $import:, y en helm-chart una entrada cargada mediante $import: — llevan la anotación argocd.argoproj.io/sync-wave y el conjunto completo de etiquetas de procedencia, pero no reciben helm.sh/hook-weight — ni siquiera cuando el artefacto lleva una anotación helm.sh/hook.

La distinción es estructural: helm.sh/hook y helm.sh/hook-weight son primitivas de ordenación del runtime de Helm que se aplican a los recursos de hook generados por las plantillas del chart. Los artefactos del autor de la Recipe son recursos adicionales declarados en la capa de la Recipe; de forma predeterminada no participan en el ciclo de vida de los hooks de Helm.

Si necesitas la ordenación por hook-weight de Helm en un recurso de hook, escribe el recurso como plantilla de chart bajo el directorio source: de una Recipe que renderiza el proveedor helm, en lugar de como entrada de artifacts:; las plantillas de un subchart de helm-chart se copian tal como se escribieron y no reciben ninguna de las dos anotaciones. La plantilla del chart recibirá tanto argocd.argoproj.io/sync-wave como helm.sh/hook-weight, coincidentes con el valor syncWave del límite contribuyente.

Ejemplos de autoría

Ubicación y configuración del registro a nivel de límite:

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
aggrega.ai/image-registry: registry.corp.com
aggrega.ai/image-pull-secret: corp-registry-creds
components:
api: {}
worker: {}

Sobrescritura por componente (el componente prevalece sobre el límite en la misma clave de anotación):

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
components:
api: {}
legacy-thing:
annotations:
aggrega.ai/namespace: legacy-east # override — this component deploys elsewhere

Cascada de anotaciones del lado del Aggregate

Las anotaciones también residen en la superficie de autoría del Aggregate — en el ámbito del subsistema (spec.subsystems.<name>.annotations) y en el ámbito de la instancia de componente (spec.subsystems.<name>.components.<name>.annotations o spec.components.<name>.annotations para los componentes de nivel superior). La cascada del lado del Aggregate hace descender las anotaciones escritas por el desarrollador a lo largo del árbol de subsistemas hasta los componentes contenidos.

La regla de la cascada

Una anotación a nivel de subsistema se propaga a cada subsistema anidado y a cada componente contenido en el subárbol del subsistema. Las anotaciones de un nivel más cercano prevalecen sobre las de un nivel más externo con granularidad por clave: una anotación a nivel de componente prevalece sobre cualquier anotación heredada a nivel de subsistema para la misma clave, sin afectar a las claves hermanas ni a los componentes hermanos.

Una clave de anotación en un ámbito se encuentra en uno de tres estados:

  • 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.
  • Un valor de cadena — el ámbito declara un valor. Los subsistemas anidados y los componentes contenidos heredan este valor, salvo que declaren su propio valor o renuncien a él.
  • null de YAML explícito — el ámbito elimina de su subárbol cualquier enlace heredado para esta clave. Los componentes hermanos y los subsistemas hermanos conservan su herencia independiente; solo el subárbol del ámbito que renuncia pierde el enlace.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # propagates to api and worker
components:
api:
# inherits feature.myco/db-pool: "shared-pool"
worker:
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Anotaciones de los Provider declaradas en el Aggregate

Las claves de la matriz anterior también descienden en cascada a través del Aggregate, y un proveedor aplica lo que la cascada deja en cada componente. El aggrega.ai/namespace de un subsistema ubica cada componente que hay por debajo de él; el valor propio de una instancia de componente ubica en cambio ese componente. Un módulo que el Aggregate importa lleva su propia cascada: sus subsistemas e instancias de componente alcanzan los componentes propios del módulo, y nada de lo que declara el Aggregate importador llega al interior de un módulo.

La Release se sitúa por encima del Aggregate en cada clave. Donde la Release establece una clave para un componente — en su límite o en la entrada propia del componente —, se aplica el valor de la Release; donde no establece ninguno, el del Aggregate. Los dos lados se superponen clave por clave, de modo que una Release que solo establece aggrega.ai/namespace deja en vigor un aggrega.ai/image-registry que declaró el Aggregate.

Un null explícito en la Release retira solo el valor propio de la Release. Una entrada de componente que escribe aggrega.ai/namespace: null elimina el espacio de nombres que el límite de su Release le habría asignado, y el componente toma entonces el valor que declara su Aggregate — o ninguno, donde el Aggregate tampoco declara ninguno. Una Release no puede eliminar un valor que el Aggregate declara; solo puede establecer uno propio por encima.

# Aggregate
spec:
subsystems:
billing:
annotations:
aggrega.ai/namespace: billing # api and worker render into billing
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0
annotations:
aggrega.ai/namespace: billing-batch # worker renders into billing-batch
# Release
spec:
boundaries:
production:
components:
api:
annotations:
aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing
worker: {}

aggrega.ai/chart-name es la única clave fuera de este alcance: nombra un chart paraguas ensamblado a partir de varios componentes, así que se lee de los límites de la Release que contribuyen a ese chart, nunca de las anotaciones de un componente.

Una plantilla de Recipe o de FeatureRecipe lee los contenedores de anotaciones por nombre — .context.annotations.aggregate, .context.annotations.release y .context.annotations.catalog contienen cada uno lo que escribió ese lado —, de modo que una plantilla que lee una clave de ubicación de un contenedor solo ve el valor de ese lado.

La partición entre lado y pilar

La invariante del Aggregate como superficie de autoría restringe las anotaciones del lado del Aggregate al pilar de valores. Un enlace de anotación de un Manifest declara rutas de enrutamiento bajo maps.infra (enrutamiento del lado de la Release) o bajo maps.values (enrutamiento del lado del Aggregate); una anotación del lado del Aggregate cuyo enlace declara solo rutas bajo maps.infra detiene la compilación con un diagnóstico claro que nombra la clave de la anotación, el pilar enrutado y el lado de autoría. La regla simétrica se aplica al lado de la Release: las anotaciones del lado de la Release solo pueden enrutar a través de maps.infra; una anotación del lado de la Release contra un enlace solo de valores provoca el error paralelo. Cada diagnóstico se clasifica en el dominio del documento en el que se escribió el valor de la anotación — [DEVELOPER_ERROR] desde un Aggregate, [OPS_ERROR] desde una Release —, de modo que la cabecera nombra la superficie que hay que abrir.

Los enlaces que declaran rutas en ambos pilares enrutan en cada pasada el subconjunto compatible con el lado: una anotación del lado del Aggregate activa solo las rutas del pilar de valores, y una anotación del lado de la Release activa solo las rutas del pilar infra. La composición entre lados — values desde el Aggregate, infra desde la Release — produce una vinculación de Feature por cada par (Component, Feature) con ambos pilares completados y una procedencia por hoja que registra qué lado aportó cada hoja.

Ejemplo de autoría — una anotación de subsistema se enruta a values

# Manifest binding
spec:
mappings:
features:
type:
core/db-pool: db-pool-helm:1.0.0
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- pool # routes to values.pool
# Aggregate
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool"
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0

Tras la expansión de anotaciones, tanto api como worker llevan una vinculación sintética de la Feature feature.myco/db-pool cuyo campo values.pool vale "shared-pool". El grafo de la compilación (aggrega validate --release <release> --ir-graph) registra cada hoja con origin: annotation, side: aggregate y annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.

Valores de anotación estructurados

Una Feature con varios campos configurables invita a usar una única clave de anotación que lleve valores para varios de ellos a la vez. La forma de anotación estructurada permite que una clave enrute hacia varias rutas del enlace en una sola declaración:

# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)
boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100

El enlace del Manifest declara el enrutamiento de las cuatro subclaves en listas maps: agrupadas por pilar:

# Manifest
spec:
mappings:
features:
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- db_name
- read_replicas
infra:
- pool_size
- max_connections

La forma del valor de la anotación es una de tres:

  • Cadena escalar — un único valor. El enlace debe declarar exactamente una ruta en total; el escalar se enruta a esa ruta.
  • Objeto estructurado — un mapa de subclave a subvalor. La ruta de cada subclave debe aparecer en la lista maps.infra o maps.values del enlace; el subvalor se enruta al campo del esquema de la Feature nombrado, en el pilar declarado.
  • null de YAML explícito — renuncia por completo al enlace heredado para este ámbito de la cascada.

Cada subclave dentro de un valor estructurado se resuelve de forma independiente con respecto a la lista maps del enlace. Una subclave ausente tanto de maps.infra como de maps.values detiene la compilación con un error claro que nombra la subclave problemática y las rutas declaradas.

Fusión en cascada de valores estructurados

Las anotaciones estructuradas descienden en cascada con una fusión profunda por subclave. La anotación de un ámbito hijo de la cascada se fusiona con la anotación del padre subclave por subclave; el nivel más cercano prevalece sobre el padre con granularidad de subclave:

subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "data-default"
read_replicas: 3
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-override" # overrides parent at this subkey only
# read_replicas not listed → inherits 3 from parent
analytics:
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out: removes inherited subkey
# db_name not listed → inherits "data-default" from parent

Anotaciones efectivas tras la cascada:

  • Component api: { db_name: "api-override", read_replicas: 3 }
  • Component analytics: { db_name: "data-default" } — read_replicas excluida por renuncia en este ámbito

Un nivel hijo de la cascada cuyo valor es un escalar (frente a un padre estructurado) reemplaza por completo en lugar de fusionarse. Las discrepancias de forma entre niveles de la cascada se resuelven a favor del valor del nivel más cercano; el compilador no avisa ante una discrepancia de forma.

null en el valor completo frente a null por subclave

La cascada ofrece dos mecanismos de renuncia con granularidades distintas:

# Whole-value null — opts out wholesale at this scope
components:
api:
annotations:
feature.myco/db-pool: null

Todo el enlace de la anotación se suprime en este componente; no se sintetiza ninguna vinculación sintética de Feature a partir de esta clave de anotación en este ámbito. Los componentes hermanos conservan su enlace heredado.

# Per-subkey null — opts out just one subkey
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-db"
read_replicas: null

La anotación sigue contribuyendo en este ámbito, pero la subclave read_replicas se suprime. Las demás subclaves (declaradas en este ámbito o heredadas de los niveles padre de la cascada) se mantienen.

Orientación para la autoría: usa null en el valor completo para desactivar en un ámbito una vinculación de Feature impulsada por anotaciones. Usa null por subclave cuando quieras conservar la mayor parte de la contribución de una anotación pero suprimir uno o varios campos concretos.

Partición entre lado y pilar por subclave

La invariante del Aggregate como superficie de autoría se aplica por subclave cuando el valor de una anotación es estructurado. El pilar de cada subclave (según la declaración maps del enlace) debe ser compatible con el lado de autoría:

  • Una anotación del lado del Aggregate solo puede llevar subclaves que se enruten a maps.values.
  • Una anotación del lado de la Release solo puede llevar subclaves que se enruten a maps.infra.

Una subclave que se enruta a un pilar incompatible detiene la compilación con un error claro que cita la subclave y el pilar concretos. La cadena de errores reúne todas las subclaves incompatibles por anotación antes de detenerse — los operadores ven todos los problemas en un solo ciclo de compilación en lugar de ir corrigiendo y recompilando una y otra vez.

Validación de tipos por subclave

El valor en tiempo de ejecución de cada subclave se valida contra el tipo declarado en el spec.schema de la Feature de destino, en el pilar enrutado. Los tipos declarados admitidos son string, integer, number, boolean, object, array, null. Un subvalor cuyo tipo YAML no coincide con el tipo declarado del esquema detiene la compilación con un error claro que nombra la subclave, el tipo real y el tipo declarado.

La coincidencia de tipos es estricta — sin coerción. Una cadena "20" frente a un campo del esquema de tipo entero detiene la compilación; los autores declaran correctamente los tipos en el esquema de la Feature o usan anotaciones escalares que pasan como cadenas.

Palanca de autoría para una validación estricta. Las propiedades sin un type declarado en el spec.schema de la Feature aceptan cualquier forma del valor en tiempo de ejecución, incluidos los mapas anidados. Cuando el esquema no declara una restricción, la compilación no inventa ninguna. Los autores que quieren una validación estricta de tipos por subclave declaran type en cada propiedad de spec.schema. La capa de renderizado de la FeatureRecipe, más adelante, maneja cualquier forma que lleve la contribución de la anotación.

Composición entre lados

Cuando tanto una anotación del lado del Aggregate (subclaves values) como una anotación del lado de la Release (subclaves infra) apuntan a la misma vinculación de Feature en el mismo Component, la compilación fusiona las contribuciones en una única vinculación de Feature con ambos pilares completados. La procedencia por hoja registra el origen de cada subclave — la vinculación sintetizada lleva values.db_name atribuido al punto de autoría del Aggregate e infra.pool_size atribuido al punto de autoría de la Release.

El patrón de composición entre lados es la forma de autoría canónica para las Features con campos mixtos de intención del desarrollador y de dimensionamiento por parte del operador: el Aggregate declara las decisiones cognitivas (qué base de datos, cuántas réplicas a nivel de aplicación); la Release declara el dimensionamiento físico (qué tamaño tiene el pool, cuántas conexiones a nivel de infraestructura). Un único enlace del Manifest los une con un solo conjunto de declaraciones maps.