Etiquetas y anotaciones
Las entidades de Aggrega llevan dos mecanismos de metadatos estructuralmente similares — metadata.labels y metadata.annotations — además de campos portadores de anotaciones repartidos entre las superficies de cascada por límites y las de vinculación de funcionalidades. Seis superficies distintas escriben o llevan contenido de anotaciones/etiquetas, cada una con reglas de cascada distintas, consumidores distintos y convenciones de prefijo distintas. Esta página documenta las superficies en un solo lugar, define los tres contenedores semánticos que expone el contexto de plantilla en tiempo de ejecución, nombra la disciplina de prefijos que los autores deberían seguir y documenta las cinco superficies de vinculación de Feature una al lado de otra para que sean visibles junto al vocabulario más amplio de etiquetas/anotaciones.
Las seis superficies portadoras de anotaciones y de etiquetas
Los autores encuentran etiquetas y anotaciones en seis superficies distintas. Cada una tiene un ámbito distinto, una regla de cascada distinta y un consumidor distinto.
| # | Superficie | Ámbito | Regla de cascada | Consumidor principal |
|---|---|---|---|---|
| 1 | metadata.labels de la entidad de catálogo | Identidad por entidad (Component, Feature, Aggregate) | No se propaga en cascada a las instancias; se lleva en la propia entidad de catálogo | aggrega search -l para Components y Features; las etiquetas de un Aggregate se llevan en su documento y ningún comando las lee |
| 2 | metadata.labels del Component (intrínsecas) | Propiedades por instancia de Component (component.aggrega.ai/type, etc.) | Se propaga en cascada al .context.labels por nodo del IR tras las mutaciones de label-transform | Coincidencia de selectores (declaraciones selector: de usesSchema, llevadas como x-aggrega-selector: en el JSON Schema sintetizado), lógica de plantillas de la Recipe |
| 3 | metadata.annotations del Component | Rasgos por instancia de Component escritos por el arquitecto | Se propaga en cascada al contenedor .context.annotations.catalog por nodo del IR | roles de veredicto de gobernanza (políticas de rasgos intrínsecos), lógica de plantillas de la Recipe |
| 4 | annotations: de Aggregate / subsistema | Metadatos cognitivos del lado del Aggregate | Se propaga en cascada al contenedor .context.annotations.aggregate por nodo del IR | valuesMapping: de la Recipe para el enrutamiento cognitivo |
| 5 | Límite de la Release annotations: | Metadatos físicos del lado de Ops, incluidas las anotaciones conocidas aggrega.ai/* | Se propaga en cascada al contenedor .context.annotations.release por nodo del IR | Providers (helm lee aggrega.ai/namespace; compose deriva el nombre de la red de la misma clave); injectMapping: de la FeatureRecipe para el enrutamiento entre límites |
| 6 | Enlaces features.annotations del Manifest | Enlace clave de anotación → tipo de Feature con enrutamiento de subclaves agrupado por pilar (maps.infra / maps.values) para la vinculación de Feature guiada por anotaciones | La subfase de expansión de anotaciones de la resolución recorre los límites de la Release (de fuera hacia dentro) y los subsistemas del Aggregate (de fuera hacia dentro); se aplican la sobrescritura por componente y la exclusión con null del valor completo / por subclave; la aplicación de lado frente a pilar determina qué pilar se activa por cada lado de autoría | Expansión de Feature guiada por anotaciones (vinculaciones de Feature sintéticas, registradas en el grafo IR con origin: annotation) |
Las superficies 4 y 5 comparten una forma YAML (un mapa annotations: en el límite en cascada) pero se propagan a contenedores distintos del IR — la distinción entre contenedores es la regla determinante que expone el tiempo de ejecución. La superficie 6 está estructuralmente separada: vive en la entidad Manifest en lugar de en el contenido de Aggregate / Release, y su consumo está condicionado por la pasada de expansión guiada por anotaciones.
La semántica de tres contenedores de .context.annotations.*
Cuando el renderizador evalúa una plantilla de Recipe, el campo por nodo .context.annotations lleva tres contenedores con nombre. Cada contenedor es un mapa plano string → string indexado por nombre de anotación; el contenedor determina quién escribió la anotación y cuál es su intención.
.context.annotations.release— anotaciones del límite de la Release (Superficie 5). Sirven para gobernar las realidades físicas; los renderizadores las enrutan a camposinfra:cuando corresponde. Las anotaciones conocidasaggrega.ai/*residen en este contenedor..context.annotations.catalog— anotaciones de los metadatos del Component (Superficie 3). Rasgos intrínsecos inmutables escritos por el arquitecto; consumidos principalmente por los plugins de políticas Wasm..context.annotations.aggregate— anotaciones de los subsistemas del Aggregate (Superficie 4). Metadatos cognitivos; los renderizadores las enrutan a payloadsvalues:cuando corresponde.
La separación en tres contenedores es un contrato social
El compilador no impone los límites entre los contenedores. Los tres contenedores comparten una forma plana string → string; la plantilla de una Recipe puede leer los tres, y nada impide que una anotación del límite de la Release se interprete como un campo de metadatos cognitivos o que una anotación del catálogo se enrute a infra:. La separación es disciplina de autoría, no una garantía del compilador.
El objetivo de la disciplina — lo que los contenedores pretenden expresar:
- release = «dónde se ejecuta este componente, gobernado por Ops»
- catalog = «qué es este componente, escrito por el arquitecto»
- aggregate = «qué hace este componente, escrito por el desarrollador»
Cuando los autores respetan la separación, las herramientas posteriores pueden leer el contenedor adecuado para la cuestión adecuada. Cuando los autores la infringen (p. ej., poniendo metadatos cognitivos en anotaciones release porque el archivo de la Release resulta cómodo), el tiempo de ejecución sigue funcionando, pero la intención del contenedor se desdibuja.
Socket de linter — señalar lecturas entre contenedores
Un plugin de linter (aviso fuera de banda; consulta plugins/plugin-contract.md para el criterio de ubicación) puede señalar las lecturas entre contenedores en las que la plantilla de una Recipe toma datos de un contenedor cuya intención no coincide con el campo que se enruta. El criterio:
- Leer
.context.annotations.releasepara rellenar un campovalues:— señalar (los metadatos cognitivos deberían venir del contenedoraggregate). - Leer
.context.annotations.aggregatepara rellenar un campoinfra:— señalar (los metadatos físicos deberían venir del contenedorrelease). - Leer
.context.annotations.catalogpara rellenarvalues:oinfra:— normalmente solo un aviso (las anotaciones del catálogo son rasgos intrínsecos; enrutarlas a pilares es inusual pero no siempre incorrecto).
El linter de publicación no tiene ninguna regla para este criterio, y la compilación no lo comprueba; un plugin de linter propio puede hacerlo, a través del socket de linter que ejecuta aggrega lint. La disciplina la mantienen los revisores y los autores que siguen la convención sobre la intención de los contenedores.
Disciplina de prefijos
Las claves de anotación y de etiqueta siguen una forma uniforme <namespace>/<name>. Las familias de prefijos de abajo indican quién escribe claves bajo cada una y cómo se mantiene cada una — un prefijo está reservado, y una compilación se detiene cuando un enlace del Manifest o una etiqueta de salida de una Recipe reclama una nueva clave dentro de él; el resto son convención del catálogo, sin nada que rechace una clave. La diferencia entre ambos es si una compilación se detiene, así que lee la columna central antes que las demás.
| Prefijo | Quién escribe claves aquí | Cómo se mantiene | Propósito | Ejemplos |
|---|---|---|---|---|
aggrega.ai/ | Solo la plataforma Aggrega | Reservado, e impuesto. La plataforma define las claves aquí, y tú escribes las que define — aggrega.ai/namespace en un límite de la Release, por ejemplo. Reclamar una clave nueva dentro del prefijo provoca una detención: un enlace features.annotations del Manifest bajo el prefijo desnudo, y del mismo modo una clave de etiqueta de salida de una Recipe bajo él en outputLabels: o outputComponentLabels:. Una anotación escrita bajo él que la plataforma no define no se rechaza: la compilación la transporta, y donde está en una Release, un destino que no actúa sobre ella lo indica con una advertencia. Consulta errors/fatal-halts.md «A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Un enlace de anotación del Manifest reclama el prefijo reservado)» y «An output-label key uses a reserved namespace (Una clave de etiqueta de salida usa un espacio de nombres reservado)». | Anotaciones nativas de la plataforma consumidas directamente por el proveedor | aggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment |
feature.aggrega.ai/ | Biblioteca estándar oficial | Convención. Nada rechaza una clave aquí; el vocabulario es de la biblioteca estándar por acuerdo y no por una comprobación. | Atajos de anotación de Feature enlazados en features.annotations del Manifest | feature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking |
component.aggrega.ai/ | Biblioteca estándar oficial | Convención. Nada rechaza una clave aquí. | Etiquetas de rasgos intrínsecos del Component (aquí reside la clave de selector component.aggrega.ai/type) | component.aggrega.ai/type |
aggregate.aggrega.ai/ | Biblioteca estándar oficial | Convención. Nada rechaza una clave aquí. | Etiquetas de identidad a nivel de módulo del Aggregate | aggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance |
<role>.aggrega.ai/ | Biblioteca estándar oficial, y las empresas en sus propios catálogos | Convención. Nada rechaza una clave aquí. | Etiquetas de capacidad — las dimensiones de comportamiento sobre las que discrimina un selector usesSchema o el appliesTo de una Feature. El <role> nombra la cuestión a la que pertenece la dimensión: o bien un rol de componente, o bien una cuestión transversal que comparten varios roles. | model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring |
<any-other-domain>/ | Empresa / comunidad | Abierto. Escribe bajo un dominio que controles. | Anotaciones y etiquetas personalizadas | acme.com/billing-tier, corp/cost-center |
Los autores que escriben anotaciones personalizadas usan un dominio que controlan (normalmente al estilo DNS inverso). Escribir directamente bajo aggrega.ai/ (sin un subprefijo) está reservado para la plataforma; los enlaces features.annotations del Manifest tampoco pueden enlazar claves directamente bajo aggrega.ai/ — consulta entities/manifest.md «aggrega.ai/ Prefix Reservation (Reserva del prefijo aggrega.ai/)».
Nombrar un prefijo de capacidad
Una clave de capacidad es <role>.aggrega.ai/<dimension>, y el <role> es la parte que requiere criterio. Tres reglas lo rigen, y la primera es la que más a menudo se aplica al revés.
- Nombra la cuestión, no el tipo de componente que resulta portarla primero. Cuando una dimensión describe algo que comparten varios tipos de componente, el prefijo nombra la cuestión compartida para que el siguiente tipo que la adquiera reutilice el vocabulario en lugar de inventar uno paralelo.
component.aggrega.ai/hostinges una cuestión — quién opera el recurso subyacente — y describe una base de datos y una API de modelo con las mismas palabras;dataplane.aggrega.ai/*nombra una posición en la ruta del tráfico, de modo que un proxy, un gateway de entrada y una service mesh se describen igual. Una dimensión realmente específica de un rol toma el nombre de ese rol, como hacemodel.aggrega.ai/capability. - Una sola palabra en minúsculas, sin guion, en el prefijo. El guion pertenece a la mitad
<dimension>, donde un compuesto se lee con naturalidad (request-mirroring,data-class,upstream-licensing). - Una dimensión se añade cuando un selector la necesita, y cada valor que declara tiene un componente que lo porta. Cada palabra aquí es una que un autor de catálogo debe aprender y que un autor de Feature puede encontrarse, así que una dimensión se gana su lugar discriminando algo por lo que un
usesSchemao unappliesTopregunta realmente. Un valor que ningún componente porta es peor que uno ausente: un selector que lo nombra se analiza, no coincide con nada y no informa de nada — así que un valor que el catálogo no puede demostrar se deja fuera del vocabulario hasta que un componente lo porte. Una clave cuyo valor es una declaración de una organización sobre cómo usa sus propios componentes, en lugar de una propiedad del producto, es la excepción, ycompliance.aggrega.ai/data-classes ese caso: qué clase tienen los datos de un componente depende de cómo una organización usa el componente, así que ningún Component de la biblioteca estándar porta ninguno de sus valores y ningún socket ni Feature de la biblioteca estándar selecciona por ellos. La clave y sus valores se declaran para que los Components propios de una organización y las políticas que esta vincula compartan una sola grafía; un selector o una política que nombra un valor solo coincide en un catálogo cuyos Components lo portan. policy-data-class-route muestra uno de esos Component y la política que lo lee.
Una reserva y una clave definida por la plataforma no son lo mismo
La reserva recae sobre la raíz aggrega.ai/ desnuda. Cada espacio de nombres <scope>.aggrega.ai/ por debajo de ella es un espacio de claves propio que la plataforma no posee, y eso es lo que mantiene extensible el vocabulario del catálogo: un catálogo empresarial puede escribir acme.aggrega.ai/team sin disputar nada de lo que estampa la compilación.
Algunas claves dentro de esos espacios de nombres abiertos están, no obstante, definidas por la plataforma y leídas por la compilación, y eso no hace reservado su espacio de nombres:
component.aggrega.ai/typees obligatoria en losmetadata.labelsde cada Component y toma uno de un conjunto fijo de valores. Los selectores hacen coincidencia con ella; el compilador no se bifurca según el valor que contiene.features.aggrega.ai/requiredType.<label>, escrita en losmetadata.annotationsde un Component, declara que debe vincularse una Feature del tipo nombrado. La compilación comprueba ese mandato frente al conjunto final de vinculaciones de cada nodo y se detiene donde nada lo satisface — consultaerrors/fatal-halts.md«Required feature not attached (Funcionalidad obligatoria no vinculada)». Fíjate en el plural:features.aggrega.ai/es un espacio de nombres propio, distinto del singularfeature.aggrega.ai/de la tabla anterior, que lleva los atajos de enlace del Manifest.
Lee la diferencia así: un prefijo reservado rechaza una clave que intentas definir dentro de él, mientras que una clave definida por la plataforma es una única clave con nombre que la compilación conoce, situada en un espacio de nombres en el que por lo demás eres libre de escribir. Cualquier otra clave bajo component.aggrega.ai/, features.aggrega.ai/ y el resto son metadatos que la compilación transporta sin interpretarlos.
Una de esas claves en los metadata.annotations de un Component la lee el linter de publicación estándar en lugar de la compilación: observability.aggrega.ai/metrics-credential indica cómo se autentican las métricas del producto — none, se sirven sin credencial; target-key, exigen la clave que el Component exige a cada llamador; separate-token, exigen un token propio. La compilación la transporta como cualquier otra anotación. El linter la lee para decidir si la credencial de una conexión de scrape se compara con la clave de llamador del destino, y exige que concuerde con la clave provides metrics_credential_required que el Component declara — consulta «The discipline rules (Las reglas de disciplina)» en cli/aggrega-lint.md.
Etiquetas de procedencia emitidas en la salida renderizada
Además de las anotaciones entrantes que consumen los proveedores, Aggrega también emite etiquetas de procedencia en cada manifiesto de Kubernetes que renderiza el proveedor helm y en cada servicio compose emitido, y el proveedor helm-chart escribe el mismo conjunto, tal como lo escribe el proveedor helm, en cada artefacto que carga con $import:. El conjunto de etiquetas permite a las herramientas posteriores (paneles de costes, pilas de observabilidad, controladores GitOps) atribuir los recursos en tiempo de ejecución al contenido del catálogo que los produjo. Las plantillas propias de un subchart de helm-chart se copian tal como las escribió su autor, así que llevan las etiquetas que ese autor haya escrito.
El conjunto que emiten los proveedores helm y compose — en helm, tres de las claves se escriben como anotaciones en lugar de etiquetas, como indica la tabla:
| Etiqueta | Origen | ¿Se emite siempre? |
|---|---|---|
app.kubernetes.io/name | Identidad del Component — el nombre que escribiste o, para un componente que aporta un Aggregate importado, su nombre cualificado con el separador de módulo escrito explícitamente (ver más abajo); o, para un recurso que emite una FeatureRecipe, el identificador derivado para esa vinculación | Sí en los manifiestos de Kubernetes; no se emite en los servicios compose (la etiqueta estándar es específica de K8s) |
aggrega.ai/component-id | Identidad del Component — el nombre que escribiste o, para un componente que aporta un Aggregate importado, su nombre cualificado con el separador de módulo escrito explícitamente (ver más abajo); o, para un recurso que emite una FeatureRecipe, el identificador derivado para esa vinculación | Sí |
aggrega.ai/recipe-uri | <recipe-name>:<recipe-version> de la Recipe productora (o de la FeatureRecipe productora para los recursos emitidos por una FR) | Cuando la entidad productora tiene definidos tanto el nombre como la versión; una anotación en helm |
aggrega.ai/boundary-path | Ruta del límite a la que se enrutó el componente | Cuando la ruta del límite no está vacía; una anotación en helm |
aggrega.ai/aggregate-name | metadata.name del Aggregate | Cuando está definido |
aggrega.ai/compiler-version | Versión del compilador estampada en tiempo de compilación | Cuando está definido |
aggrega.ai/provider | El proveedor que renderizó el recurso (helm, helm-chart, compose) | Sí |
aggrega.ai/provider-version | La versión de ese proveedor | Sí |
aggrega.ai/environment | metadata.environment de la Release | Sí — toda Release lo declara |
aggrega.ai/sync-wave | Entero syncWave por límite, el orden en que una herramienta GitOps aplica los recursos | Cuando no es cero; una anotación en helm, junto a argocd.argoproj.io/sync-wave |
El nombre del agregado, el entorno, la versión del compilador y el nombre y la versión del proveedor son cadenas que tú o la compilación eligieron, y ninguna de ellas está sujeta a las reglas de Kubernetes para valores de etiqueta en el lugar donde se escribe. En helm, cada una de esas etiquetas lleva el valor tal como se escribió cuando 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 — y, en caso contrario, el valor reescrito en uno válido, con el valor literal añadido como anotación bajo la misma clave: 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 que ya cumple no añade ninguna anotación. Compose lleva el valor literal como etiqueta. La regla de reescritura se indica en providers/well-known-annotations.md «Etiquetas de procedencia emitidas por los proveedores».
Para los recursos que emite una FeatureRecipe, el valor 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, ya sea que sintetice una carga de trabajo, emita un conjunto de artefactos independiente o renderice un chart o un fragmento proporcionado por su autor. Así, una consulta que selecciona por identidad los recursos de una vinculación los devuelve todos, y ninguno de ellos es indistinguible de un recurso que el propio componente anfitrión emitió. Cómo se construye el valor depende de dónde esté vinculada la Feature; en cualquier caso, el resultado es una cadena de etiqueta de Kubernetes válida.
Para un componente que aporta un Aggregate importado, la identidad es el nombre cualificado de ese componente con el separador que une el módulo al componente escrito explícitamente — data-layer.main-db se estampa como data-layer-zdmain-db — porque un punto no es un carácter que un nombre de recurso o una dirección del clúster puedan llevar con seguridad. Un nombre que escribiste sin ningún separador se estampa byte a byte.
La identidad dice a qué pertenece un recurso. Esa es una pregunta distinta de cómo se llama un recurso, y para una de las entregas las dos tienen respuestas distintas:
- Cuando una FeatureRecipe sintetiza una carga de trabajo, Aggrega construye esos recursos por sí mismo, así que también los nombra según la identidad: la identidad llega a su
metadata.name, a sus etiquetas de selector y a sus nombres de archivo emitidos, además de a sus etiquetas. Es un nombre dentro del clúster y no solo una etiqueta. - Cuando una FeatureRecipe entrega un chart o un fragmento que escribió su autor, los nombres pertenecen a quien lo escribió. El nombre de release de Helm con el que se renderizan esas plantillas — y el prefijo de los archivos que emite ese renderizado — siguen siendo los del componente anfitrión. Los charts suelen nombrar sus recursos según el nombre de release, así que cambiarlo renombraría recursos que el propio chart declara, en un clúster donde ya están desplegados, por una razón que no tiene nada que ver con el chart. Las etiquetas siguen llevando la identidad propia de la vinculación, que es lo que mantiene localizables los recursos de la vinculación.
- Cuando la Feature está vinculada a un límite, no hay ningún componente anfitrión cuyo nombre pueda servir de sustituto, así que allí la identidad compuesta es la base de los nombres además de la etiqueta.
En cualquier caso, el valor se compone a partir de las partes que escribiste, unidas por --, detrás de un inicio fijo que indica de cuál de los dos se trata. Hay dos inicios en uso, y una identidad de componente que escribas no puede empezar por ninguno de ellos — que es lo que impide que un nombre que escribiste y un nombre que compuso Aggrega se confundan nunca entre sí.
Cuando la Feature está vinculada a un componente, las partes son un inicio fijo cfr, la identidad del componente al que está vinculada la Feature y la clave bajo la que está vinculada. Una Feature vinculada al componente api bajo mon da cfr--api--mon. El componente anfitrión forma parte del valor porque un mismo nombre de Feature vinculado a varios componentes emite un conjunto de recursos separado en cada uno, y cada conjunto necesita una identidad propia: vincular mon tanto a api como a worker da cfr--api--mon y cfr--worker--mon en lugar de un único valor para ambos. Una vinculación llamada exactamente como el componente que la aloja da un valor distinto del propio de ese componente por la misma razón — mon vinculada a mon da cfr--mon--mon.
Cuando la Feature está vinculada a un límite — el servicio gateway compose-bridge es el ejemplo canónico —, las partes son un inicio fijo bfr, luego cada segmento de la ruta del límite empezando por el más externo, y luego el nombre bajo el que está vinculada la Feature. Una Feature llamada gateway en un límite en bridge da bfr--bridge--gateway; la misma Feature en un límite en prod/eu da bfr--prod--eu--gateway.
Un carácter que el valor no puede llevar se escribe explícitamente en lugar de sustituirse, y como el valor es un nombre dentro del clúster además de una etiqueta, se limita a los caracteres que admite todo tipo de nombre de recurso de Kubernetes: letras minúsculas, dígitos y el guion. Así, un guion que escribiste sigue siendo un guion, una letra minúscula o un dígito se queda como está, y cualquier otra cosa — incluida una letra mayúscula, que el valor de una etiqueta admite y un nombre de recurso rechaza — se convierte en un escape corto: una vinculación llamada my_zone aporta my-zuzone, y un componente myApi con una vinculación worker da cfr--my-zx000041pi--worker. Ese valor escapado es aquel por el que los recursos de la vinculación se etiquetan y se seleccionan en cada destino, aquel según el cual se nombran una carga de trabajo que sintetiza la vinculación y sus archivos, y aquel del que se deriva el nombre de release de una vinculación a un límite. Una mayúscula es el único carácter que la regla de nombres de recurso añade a lo que una etiqueta por sí sola habría escrito explícitamente, así que un valor compuesto cuyas partes no contienen ninguna — cfr--api--mon, bfr--prod--eu--gateway — es el valor que una etiqueta por sí sola llevaría. Por tanto, dos vinculaciones que puedes distinguir dan dos valores — sea cual sea el nombre que les diste y por profundo que esté el límite — porque -- es una secuencia que ninguna parte escrita puede contener, de modo que mover la división entre las partes cambia el valor en lugar de colisionar con él.
Cuánto puede medir un valor compuesto es la respuesta del destino y no un número que guarde Aggrega: se pregunta al destino para el que se renderizan los recursos, y el valor se acorta hasta que ese destino lo acepta. El valor de una etiqueta de Kubernetes lleva como máximo 63 caracteres, y un nombre de release de Helm derivado de la misma identidad está acotado aún más, así que la misma vinculación puede quedar más corta bajo un destino que bajo otro. Un valor que cabe se emite exactamente tal como se compuso, que es el caso ordinario y el caso de toda vinculación del catálogo de la biblioteca estándar. Uno que no cabe se acorta: cada parte conserva su comienzo, y se añade un resumen de diez caracteres de toda la identidad detrás de un marcador que ningún nombre que puedas escribir produce — así un valor acortado es reconocible como tal y nunca puede leerse como un valor que cabía. Por tanto, una vinculación gateway profundamente anidada puede renderizarse como bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. Es muy improbable que dos valores acortados coincidan, y si ocurre, una compilación se detiene en lugar de dejar que dos de ellos compartan un nombre.
Consulta errors/fatal-halts.md «The same name is derived more than once inside the output (El mismo nombre se deriva más de una vez dentro de la salida)» para saber qué pares provocan una detención y cómo separarlos.
El valor aggrega.ai/recipe-uri de un recurso emitido por una FR corresponde al name:version propio de la FeatureRecipe, no a la identidad de la Recipe que la consume — así las herramientas posteriores que leen recipe-uri para identificar la entidad productora obtienen la procedencia correcta tanto para la salida emitida por componentes como para la emitida por FR.
Para los detalles de emisión de cada proveedor (dónde caen las etiquetas en la salida renderizada y cómo las serializa cada proveedor), consulta providers/well-known-annotations.md «Provenance labels emitted by providers (Etiquetas de procedencia emitidas por los proveedores)».
Etiquetas de salida declaradas por la Recipe
Junto al conjunto de procedencia que pertenece al compilador, el autor de una Recipe puede declarar sus propias etiquetas para estamparlas en la salida renderizada de la Recipe, mediante Recipe.spec.outputLabels:. Estas viajan por el mismo carril de emisión que las etiquetas de procedencia — se fusionan en el mismo conjunto de etiquetas y llegan a donde llegue la procedencia —, pero pertenecen al autor y no al compilador. El uso previsto es un rasgo de realización: una propiedad de cómo una Recipe concreta realiza un componente (por ejemplo, hosting: managed frente a hosting: self-hosted para una Recipe de servicio gestionado frente a una Recipe de chart autoalojado del mismo tipo de componente), expuesta en la salida para que las herramientas de costes, políticas e inventario puedan consultarla.
Los espacios de nombres aggrega.ai/ y app.kubernetes.io/ están reservados para el conjunto de procedencia; una clave bajo cualquiera de los dos prefijos se rechaza al cargar — en outputLabels: y en outputComponentLabels:, el bloque complementario que nombra una clave de etiqueta del componente y estampa el valor que el propio componente declara. Por tanto, un conjunto de etiquetas de salida validado es siempre disjunto de las claves de procedencia, así que ambos nunca colisionan en la salida fusionada. La prueba es la raíz desnuda: una clave con ámbito como component.aggrega.ai/hosting está en un espacio de nombres propio y puede escribirse literalmente o promoverse. La exposición por proveedor (objeto de helm y pod-template en la síntesis; objeto en el renderizado desde fuente y en los artefactos; etiquetas de servicio de compose; tags por recurso de terraform en los cuerpos de artefacto .tf.json) coincide con la ubicación de la procedencia, y está documentada por completo en la página de la entidad Recipe en «The outputLabels: field (El campo outputLabels:)» y «The outputComponentLabels: field (El campo outputComponentLabels:)».
Vinculación de Feature — cinco superficies
Las Features se vinculan a los Components mediante cinco superficies de autoría distintas, cada una con un ámbito, un usuario previsto y una precedencia de ordenación diferentes dentro del modelo de cebolla de 5 niveles. La ordenación completa de las vinculaciones y el propio modelo de cebolla están documentados en architecture/10-compilation-pipeline.md; la tabla siguiente enumera las cinco superficies una junto a otra.
| Nivel | Superficie | Escrito por | Ámbito | Regla de cascada |
|---|---|---|---|---|
| 1 | Bloque features: de un componente del Aggregate | Desarrollador | Por instancia de componente (granular) | Ninguna — directa del autor |
| 2 | Bloque features: de un subsistema del Aggregate | Desarrollador | Ámbito del subsistema (transversal dentro del Aggregate) | Se propaga en cascada a cada componente del subsistema |
| 3 | components.<id>.features del límite de la Release | Ops | Por instancia de componente (granular, lado de Ops) | Ninguna — directa del autor |
| 4 | Bloque features: del límite de la Release | Ops | Ámbito del límite (transversal dentro del límite) | Se propaga en cascada a cada componente del límite |
| 5 | Expansión de features.annotations del Manifest | Operador de plataforma | Guiada por anotaciones (vinculación sintética) | Se propaga en cascada a través del árbol de límites (lado de la Release) o del árbol de subsistemas (lado del Aggregate); se aplican la sobrescritura por componente y la exclusión por subclave mediante null |
Las cinco superficies se acumulan; una vinculación presente en cualquier superficie contribuye al conjunto de funcionalidades resuelto del Component. Cuando el mismo nombre de instancia de Feature aparece en más de una superficie, las contribuciones se fusionan en una sola vinculación en lugar de reemplazarse entre sí, y una discrepancia de tipo entre ellas detiene la compilación con un error feature-merge-conflict.
Las cinco superficies son deliberadas según la separación de responsabilidades de la arquitectura — desarrollador (niveles 1-2), Ops (niveles 3-4), operador de plataforma (nivel 5) — y no redundantes. Los autores eligen la superficie que corresponde a quién es dueño de la vinculación y en qué ámbito.
Qué etiquetas deciden si una Feature se aplica
Una Feature declara dónde puede vincularse con spec.appliesTo y spec.appliesToAnyOf, y la compilación juzga esa declaración frente a las etiquetas finalizadas del nodo en el que recae la vinculación. Vincular una Feature a un nodo que esas etiquetas no satisfacen detiene la compilación; una Feature que no declara ninguna de las dos superficies no establece ningún requisito y se aplica en cualquier parte.
El conjunto de etiquetas finalizado se ensambla en dos pasos, y ninguno de ellos es el que los autores suponen con más frecuencia.
- Un nodo toma sus etiquetas de la entidad de catálogo Component que nombra su
type:. Son una propiedad del tipo de componente, no de la instancia: el Aggregate no puede etiquetar una instancia de componente, y la Release tampoco. Losmetadata.labelspropios de un Aggregate describen el Aggregate como un módulo reutilizable y no se propagan en cascada a los componentes que contiene. Así, dos instancias de un mismo tipo llevan etiquetas idénticas, y cambiar cuáles son las etiquetas de un nodo significa cambiar el tipo al que apunta — o cambiar la entidad de ese tipo. - Una vinculación
label-transformpuede después reescribirlas. Cuando la configuración del espacio de trabajo vincula un plugin de gobernanza en el rollabel-transform, este se ejecuta durante la construcción de la topología y puede añadir, cambiar o eliminar etiquetas de nodo antes de que nada se juzgue frente a ellas. No puede tocar nada más, así que las etiquetas son la única parte de un nodo que puede mover — y son exactamente la parte de la que depende la aplicabilidad.
Una propuesta hecha a partir de las etiquetas que declara un único documento es, por tanto, una aproximación, no una predicción. Leer los metadata.labels de una entidad Component te dice con qué empieza un nodo de ese tipo, lo cual es la respuesta correcta con la frecuencia suficiente para ser útil y es incorrecto de dos formas concretas: un documento que simplemente comparte el nombre de un nodo es un sujeto distinto con etiquetas distintas, y una vinculación label-transform puede mover el conjunto por debajo de cualquier documento. Las herramientas que ofrecen sugerencias de vinculación solo a partir del código fuente trabajan con esa aproximación; el juicio que emite una compilación es sobre el conjunto finalizado.
Precedencia de los adjuntos
Cuando dos contribuciones aportan el mismo campo de la misma vinculación, cuatro reglas deciden cuál lleva la salida renderizada. Se aplican en este orden, y el orden es lo que hace predecible el resultado:
- Origen. Una contribución escrita explícitamente prevalece sobre una guiada por anotaciones, sea cual sea el ámbito en el que se declaró cada una. Escribir un campo en un bloque
features:es la forma en que un autor sobrescribe lo que una anotación habría aportado, y una anotación nunca desplaza silenciosamente algo escrito a mano. El compilador registra la anotación suprimida junto al valor ganador y la notifica como un aviso, de modo que la sobrescritura es visible en lugar de misteriosa. - Propiedad de los pilares. Cada dominio llena su propio pilar: las superficies del Aggregate aportan
values, las superficies de la Release aportaninfra. Como los dos lados nunca escriben el mismo pilar, una contribución del desarrollador y una contribución del operador no pueden disputarse el mismo campo — no hay ninguna cuestión de precedencia entre desarrollador y operador que responder. - Autoridad de la composición. Una declaración en el Aggregate que estás desplegando prevalece sobre una declaración dentro de un Aggregate que este compone, incluso cuando el Aggregate compuesto declaró en el ámbito más estrecho. La composición sigue siendo determinante: un módulo no puede imponerse al Aggregate que lo consume simplemente eligiendo un ámbito más estrecho.
- Especificidad. Dentro de un mismo nivel de autoría y un mismo pilar, el ámbito más estrecho refina el más amplio, campo por campo. Una vinculación con ámbito de componente sobrescribe una vinculación a nivel de subsistema o de límite con el mismo nombre de instancia — pero solo para los campos que realmente menciona. Los campos que el ámbito más estrecho omite conservan los valores del ámbito más amplio, de modo que una vinculación compartida puede aportar la configuración común mientras un solo componente ajusta uno de sus campos. Dos contribuciones en el mismo ámbito se resuelven por el orden del autor, y gana la posterior, que es lo que permite que un subsistema interior refine uno exterior y que un límite más profundo refine uno menos profundo.
La precedencia gobierna los valores de los campos. No reordena la evaluación: la secuencia en la que el compilador pliega las superficies, y en la que ejecuta el injectMapping previo al renderizado de cada vinculación, es la secuencia fija de cinco niveles documentada en architecture/10-compilation-pipeline.md. El bloque inject escrito de una vinculación sigue esa secuencia de evaluación en lugar de la clasificación de ámbitos anterior, de modo que una vinculación nunca lleva dos ordenaciones en competencia.
Qué tipos llevan metadata.labels y metadata.annotations
metadata.labels está en Component, Feature, Aggregate y los cuatro tipos de biblioteca; metadata.annotations en los mismos tipos excepto Aggregate. Manifest, Release, Recipe, FeatureRecipe y Plugin no llevan ninguno de los dos.
Resumen de la cascada
Las reglas de cascada en las seis superficies, tal como las evalúa el compilador:
- Las etiquetas de las entidades de catálogo (Superficie 1) permanecen en la entidad de catálogo. No fluyen hacia las instancias; los consumidores las leen inspeccionando directamente el contenido del catálogo.
- Los
metadata.labelsdel Component (Superficie 2) fluyen al.context.labelspor nodo después del paso opcionallabel-transformdurante la construcción de la topología. - Los
metadata.annotationsdel Component (Superficie 3) fluyen al contenedor por nodo.context.annotations.catalog. - Las
annotations:del Aggregate / del subsistema (Superficie 4) se propagan en cascada por la jerarquía de subsistemas, acumulándose desde los subsistemas exteriores hacia dentro, en el contenedor por nodo.context.annotations.aggregate. - Las
annotations:del límite de la Release (Superficie 5) se propagan en cascada por la jerarquía de límites, desde los límites exteriores hacia dentro, en el contenedor por nodo.context.annotations.release. - Las
features.annotationsdel Manifest (Superficie 6) no se propagan en cascada directamente a los datos de IR por nodo; la subfase de expansión guiada por anotaciones de la resolución consume los enlaces para sintetizar vinculaciones de Feature por nodo, que el grafo de IR (--ir-graph) registra conorigin: annotation. Las vinculaciones sintéticas son estructuralmente indistinguibles de las explícitas aguas abajo de la resolución, salvo por esa procedencia — consultaproviders/well-known-annotations.mdpara la explicación completa de la expansión yarchitecture/13-catalog-and-registry.md§«Annotation-driven Feature expansion (expansión de Feature guiada por anotaciones)» para la mecánica en la carga del catálogo y en tiempo de inspección.
Para el diseño canónico de las anotaciones en cascada, consulta architecture/06-data-taxonomy-and-composition.md §2 (Flujo 5).
Referencias cruzadas
templates/template-context-contract.md— vista en tiempo de ejecución de.context.labelsy de los tres contenedores.context.annotations.*.providers/well-known-annotations.md— matriz de anotaciones del límite por proveedor y asimetría en la emisión de etiquetas de procedencia.entities/manifest.md— la superficie de enlacefeatures.annotationsdel Manifest (Superficie 6).vocabulary/publishing-surface.md— vocabulario de metadatos uniforme que complementa las etiquetas/anotaciones en el lado de la publicación.plugins/plugin-contract.md— el criterio de ubicación del socket de linter para las comprobaciones de aviso sobre lecturas entre contenedores.architecture/06-data-taxonomy-and-composition.md— diseño canónico de las anotaciones en cascada.architecture/10-compilation-pipeline.md— modelo de cebolla de 5 niveles que ordena la vinculación de Feature.