Feature
El papel conceptual de la entidad Feature (el rasgo operativo modular del Dominio 2) se describe en architecture/04-entity-taxonomy.md. La distinción entre Features operativas y Features de credenciales (las etiquetadas con feature.aggrega.ai/kind: secret) se describe en architecture/08-credential-model.md. El vocabulario de etiquetas semánticas que usan los selectores de Feature está en entities/component. Esta página trata la superficie de autoría del catálogo de Feature.
Ubicación en el catálogo
A diferencia de los Components (que usan URI de tres segmentos con subdirectorios por categoría), las Features se organizan de forma plana: un directorio por Feature bajo su publicador, que contiene un directorio por versión.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...URI OCI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (p. ej., hub.aggrega.ai/feature/core/data-masking:1.0.0).
Contrato de autoría
Las Features declaran:
metadata.labels: usafeature.aggrega.ai/kind: secretpara marcar una Feature como Feature de credenciales. La etiqueta es metadato descriptivo para el autor, para el sitio del catálogo y para los selectores de etiquetas; ninguna rama del compilador la lee, y lo que produce un acoplamiento lo decide la FeatureRecipe a la que el Manifest asigna su tipo, no la etiqueta. Una Feature de credenciales y una Feature ordinaria se acoplan del mismo modo, en la misma superficie de acoplamiento, en cualquier ámbito. La familia de credenciales de la biblioteca estándar se divide por resultado:core/secret-valueentrega un valor en la tubería de inyección;core/referenced-secretnombra un recurso secreto referenciable (un Secret de Kubernetes, un secreto de AWS Secrets Manager, una entrada de Vault), creado por la salida de su FeatureRecipe o ya existente, y declara un contrato de salidaschema.provides—name(el localizador del recurso, neutral respecto al provider) ykey(el campo de datos dentro de él) — que un consumidor lee como.features.<slot>.provides.<key>para referenciar el recurso sin volver a derivar su nombre;core/referenced-secret-setmaterializa un recurso que contiene un conjunto de claves de datos proporcionado por quien llama y publica solo el localizador, para un consumidor cuyo destino ya conoce los nombres de clave que lee;core/secret-providedexpone el valor de un secreto preexistente;core/generated-secretno produce nada, porque el motor de destino genera y gestiona la credencial por sí mismo, así que no declara nivaluesniprovidesy sus FeatureRecipes son puro cableado que no renderiza ningún byte. Dos ejes separan a los miembros: quién aporta el material — un autor lo escribe o indica dónde obtenerlo, o el motor de destino lo posee por completo, como concore/generated-secret— y qué produce el acoplamiento: un valor inyectado, un recurso referenciable o nada renderizado en absoluto. Cada miembro es par de los demás en la misma superficie de acoplamiento, de modo que un slot de credenciales siempre está vinculado y lo que varía entre Releases es qué lo vincula. Una Feature de credenciales que declara un contratoschema.providesobliga a cada FeatureRecipe que la implementa a publicar esas claves — de lo contrario la build se detiene — y elselectorde un slot defeaturesSchemaapunta al miembro de la familia que necesita.usesSchema(opcional): declara los sockets topológicos que la Feature puede consumir (p. ej., el socketpath/keyde una Feature de credenciales que apunta a un vault). Consulta architecture/13-catalog-and-registry.md §2 para el mecanismo de Split Schema.schema: valida los bloquesvalueseinfradel acoplamiento de la Feature — la intención cognitiva que el desarrollador configura en cada acoplamiento en el Aggregate (losvaluesson el dominio del desarrollador, y el esquema de la Release prohíbevalues:en los acoplamientos de Feature) y la capacidad que el operador decide por entorno en la Release (infra). Un campo que declara undefault:se valida contra él y además se rellena en el pilar renderizado cuando nadie lo escribe; consulta Ámbito de la Feature y forma de autoría. Acepta JSON Schema 2020-12 expresado en la abreviatura YAML de forma compacta (la predeterminada; consultavocabulary/compact-form-authoring.md) o en YAML de JSON Schema completo, con$ref:entre documentos hacia entradas de SchemaLibrary para formas compartidas (consultavocabulary/cross-document-ref.md). Una hoja que contiene material secreto declarasensitive: true— las Features de credenciales de la biblioteca estándar marcan la hoja que contiene el material y dejan deliberadamente sin marcar los localizadores que publican, ya que un nombre de recurso y una clave de datos son ambos públicos. La palabra clave, y el límite de lo que logra declararla, están envocabulary/compact-form-authoring.md«Declarar una hoja como sensible».featuresSchema(opcional): declara los slots de acoplamiento que la Feature necesita para su propio funcionamiento — una Feature declara slots exactamente como lo hace un Component, de modo que una Feature que a su vez necesita una credencial (la clave de API de una Feature sidecar de Datadog, por ejemplo) nombra el punto de vinculación en lugar de recurrir a los slots del Component anfitrión. Consulta La credencial propia de una Feature para ver una Feature que declara su propio slot y una FeatureRecipe que lee lo que lo llena. Cada slot acepta los mismos campos que un slotfeaturesSchemade un Component, con la misma semántica — incluido unselectoropcional (un selector de etiquetas al estilo de Kubernetes que restringe qué Feature puede llenar el slot, el análogo para slots de un selector de socketusesSchema; un llenado cuyas etiquetas no lo satisfacen detiene la build, y el selector se evalúa contra las etiquetas de la Feature acoplada y nada más), unsensitiveopcional (que declara que lo que vincule el slot maneja material secreto — una afirmación sobre el punto de vinculación y no sobre un llenado concreto) y la misma apertura: declarar un slot nunca prohíbe un acoplamiento bajo un nombre que ningún slot declara. La tabla completa de campos, la declaración de sensibilidad a nivel de slot y en qué se diferencia de la de una hoja del esquema, y las dos formas en que se despliega una entidad que declara slots están en entities/component.md «Slots de acoplamiento».appliesTo/appliesToAnyOf: selectores de etiquetas que controlan a qué Components puede acoplarse la Feature. Los evalúa el motor nativo de coincidencia de etiquetas del compilador durante la etapa de análisis estático. Consulta Acoplamiento basado en etiquetas más abajo y architecture/13-catalog-and-registry.md §2 «Selectores al estilo de Kubernetes» para la referencia de la sintaxis de selectores.interoperability(opcional): un bloque anidado que contieneconflictsWith— las Features junto a las cuales esta Feature no puede alcanzar un componente. La build se detiene antes del renderizado cuando un componente termina llevando ambas, sea cual sea el ámbito en que se acopló cada una. Consulta El bloqueinteroperabilitymás abajo para la explicación completa.
El renderizado estructural de una Feature está ligado a su FeatureRecipe correspondiente, que asigna la interfaz de la Feature a una implementación de infraestructura concreta.
Acoplamiento basado en etiquetas
Los dos selectores applies del esquema de la Feature controlan a qué Components se acopla la Feature, evaluados por el motor nativo de coincidencia de etiquetas del compilador durante la etapa de análisis estático:
appliesTo— una cadena de selector de etiquetas al estilo de Kubernetes; la superficie de composición AND. Todos los requisitos separados por comas deben cumplirse, con el vocabulario completo de operadores:key=value,key!=value,key in (v1, v2),key notin (v1, v2),keysolo (etiqueta presente),!key(etiqueta ausente). Una Feature que declaraappliesTo: "datastore.aggrega.ai/engine=vector"solo se acopla a Components etiquetados con ese par clave-valor exacto;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"expresa «cualquier server o worker que no contenga datos restringidos» en una única cadena de selector.appliesToAnyOf— la superficie de composición OR. Una lista de elementos de selector en la que basta con que coincida un solo elemento. Cada elemento es o bien un selector en forma de cadena (la misma gramática queappliesTo; los requisitos dentro de la cadena se combinan con AND) o bien un mapa clave-valor plano para coincidencias solo por igualdad. Se usa cuando una Feature encaja en varias formas de componente no relacionadas — por ejemplo, una Feature de observabilidad que se aplica a{ component.aggrega.ai/type: worker }O a{ component.aggrega.ai/type: task }sin forzar a ambas en una única cadena de selector.
Sin la forma any-of, los arquitectos tendrían que duplicar el mismo YAML de Feature para cada forma de componente no relacionada en la que encaja la Feature. Las dos formas se componen: una Feature puede declarar ambas, y los resultados se combinan con AND entre las formas — la cadena appliesTo debe cumplirse y al menos un elemento de appliesToAnyOf debe coincidir. Un selector omitido o vacío no declara ninguna restricción y coincide con cualquier conjunto de etiquetas.
Una cadena de selector se lee frente a las seis formas cada vez que se evalúa un acoplamiento de la Feature, y un requisito fuera de ellas detiene la build en lugar de leerse como otro selector: un requisito vacío (una coma inicial, final o duplicada, o una cadena solo de separadores), una clave que contiene espacios en blanco o cualquiera de =, !, (, ) y la coma, y un conjunto in ( o notin ( que no está cerrado. Eso es lo que detecta los errores que de otro modo seleccionarían silenciosamente lo contrario de lo que se pretendía: appliesTo: "!tier=frontend", escrito para mantener una Feature fuera de los frontends, se rechaza porque ! nombra una clave de etiqueta y nada más — tier!=frontend es la forma de excluir un valor — y tier in frontend se rechaza en favor de tier in (frontend). Un valor es el texto que sigue a su operador, contenga los caracteres que contenga, así que tier==frontend pide una etiqueta cuyo valor sea =frontend. La detención nombra la Feature, su selector y el requisito que no se pudo leer. Una Feature que nada acopla nunca se evalúa, así que un selector mal formado en ella no se informa hasta que un acoplamiento la nombra.
Consulta architecture/13-catalog-and-registry.md §2 «Selectores al estilo de Kubernetes» para la referencia de la sintaxis de selectores — la gramática que acepta un selector de Feature es la misma que aceptan los selectores de socket usesSchema, la forma de cadena que los usuarios de Kubernetes conocen de kubectl get -l.
El bloque interoperability
El esquema de la Feature declara un bloque spec.interoperability opcional que contiene un único control: con qué otras Features puede coexistir esta Feature en un componente.
interoperability.conflictsWith — una lista de las Features mutuamente excluyentes con la Feature que se define, cada una escrita del modo en que el type de un acoplamiento nombra una Feature. Impide generar configuraciones incompatibles — acoplar al mismo componente tanto una malla solo TCP como un proxy compatible con HTTP, por ejemplo.
La build se detiene antes de renderizar nada cuando un componente termina llevando esta Feature y una Feature que nombra su lista. Lo que cuenta es el alcance: un acoplamiento alcanza el componente en el que está escrito, y cada componente dentro del subsistema o del límite en el que está escrito, incluidos los límites anidados; un acoplamiento escrito en una entrada de componente de la Release, o producido por la expansión dirigida por anotaciones, alcanza su componente del mismo modo. Así, un conflicto declarado detiene la build cuando las dos Features están acopladas al mismo componente, cuando una está en un límite y la otra en un componente dentro de él, cuando una está en un límite exterior y la otra en un límite anidado dentro de él que contiene un componente, y cuando una está en un subsistema y la otra en un componente de ese subsistema. Dos Features acopladas a límites hermanos que no comparten ningún componente nunca se encuentran, y un límite que no contiene ningún componente no alcanza nada — ninguno de los dos casos detiene la build.
- Basta con una declaración. La build se detiene cuando la lista de cualquiera de las dos Feature nombra a la otra; la segunda Feature no tiene que incluir a la primera en su lista.
- Nombres, sean cuales sean las versiones. Cada entrada y el tipo de cada acoplamiento se comparan sin ninguna versión, de modo que una entrada
core/fixed-replica-controllercoincide con un acoplamiento decore/fixed-replica-controller:2.0.0, y una entrada que lleva una versión coincide con todas las versiones de la Feature que nombra. - Solo lee nombres. El compilador compara los nombres que declaró el autor de la Feature con las Features que lleva un componente — el mismo tipo de evaluación que
appliesTo, sobre datos que escribió el autor. Si dos Features son incompatibles es juicio del autor, y la lista es donde queda registrado.
La detención nombra la Feature cuya lista nombra a la otra, cada lugar en que se acopló cada una de las dos — en el componente del Aggregate, en un subsistema, en un límite de la Release con su ruta, en una entrada de componente de la Release, o mediante la expansión dirigida por anotaciones de una anotación nombrada — y el componente en que se encuentran. Un par que se encuentra en varios componentes se informa una vez por cada uno. Consulta errors/fatal-halts.md para el mensaje.
Ejemplo:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerEsta Feature solo se acopla a Components de tipo server y declara incompatibilidad con otra Feature que controla réplicas: una build en la que cualquier componente termina llevando ambas se detiene antes del renderizado. Una FeatureRecipe que necesita el nombre del componente al que está acoplada — para apuntar un autoscaler a su destino, por ejemplo — lo lee de su contexto de plantilla y lo escribe allí donde su salida lo necesite: .context.instance_id es la identidad del componente, y .context.rendered_name es el nombre que el propio provider del componente da a los recursos que renderiza para él, que es el que se usa para apuntar a un recurso — con helm, el nombre del Deployment que emite una carga de trabajo sintetizada, y el nombre de release a partir del cual un chart construye sus propios nombres.
Herencia mediante extends
Una Feature puede declarar spec.extends: <feature-name> apuntando a una Feature base cuya superficie de autoría hereda. La referencia nombra la base por su metadata.name, no por la coordenada de registro con la que se publica la Feature, y admite las mismas tres formas de versión que toda referencia de catálogo: sin versión (core/queue) para la versión disponible más alta, exacta (core/queue:1.0.0) o un rango caret (core/queue:^1.0.0). El compilador recorre la cadena de padres al cargar el catálogo, valida que la cadena sea acíclica y luego fusiona las specs de los padres en el hijo para producir una única Feature resuelta. Los campos escritos por el hijo tienen prioridad en caso de colisión de claves; los metadata.labels y metadata.annotations del padre, los selectores appliesTo / appliesToAnyOf, el bloque interoperability, usesSchema, featuresSchema y las declaraciones de JSON Schema 2020-12 en schema se fusionan automáticamente hacia abajo. Cualquier otro campo de metadata es el del hijo tal cual, de modo que la identidad y la procedencia nunca se heredan.
Qué hereda el metadata: de una Feature. labels y annotations se fusionan clave por clave a lo largo de la cadena, primero la base, y el valor de la Feature que extiende prevalece en una clave compartida — la misma regla que siguen los Components. El resto de metadata: no se transmite: name, version, description, maintainers, license, repository, home y keywords son los propios de la Feature que extiende, exactamente como se escribieron.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }El core/kafka-queue fusionado hereda appliesTo del padre, hereda las propiedades values.qos e infra.partition_count, y añade values.compression_codec encima. Un hijo que declara explícitamente appliesTo sustituye por completo el selector del padre (la fusión de selectores de etiquetas no es profunda — el selector del hijo reemplaza al del padre). El schema.values.qos de un hijo sustituye la declaración del padre para esa propiedad.
Cómo hereda cada parte de la superficie de acoplamiento. Las dos formas de selector se heredan de forma independiente entre sí, porque se componen en lugar de reemplazarse: cada forma presente debe cumplirse — la cadena appliesTo debe coincidir, y al menos un elemento de appliesToAnyOf debe coincidir — mientras que una forma ausente no restringe nada. Así, una Feature puede tomar el selector AND de su base mientras declara un conjunto OR propio. El bloque interoperability se hereda campo a campo — un hijo que declara el bloque sin una lista conflictsWith sigue llevando la lista que declaró su base, mientras que un hijo que declara su propio conflictsWith reemplaza la lista de la base en lugar de añadirse a ella. Una Feature que no declara ninguno de los tres se acopla exactamente donde se acopla su base.
La herencia es fusión de esquemas, no vinculación de interfaces. Una cadena extends: de Feature produce una única Feature resuelta, no una familia polimórfica. La URI de la Feature base de la cadena no es lo que referencia el campo feature: de una vinculación del Manifest — los Manifests vinculan por la URI de la Feature hoja, y el esquema resuelto incluye las propiedades heredadas. El contrato de Feature que una FeatureRecipe implements: es igualmente la URI hoja; las FeatureRecipes no recorren la cadena de herencia.
aggrega pull obtiene la base. Una Feature base es una dependencia de cada Release que adjunta una Feature que la extiende, la nombre o no cualquier otra cosa. aggrega pull sigue cada extends: hasta el final de la cadena, obtiene del registro una base que ningún directorio de catálogo contiene y registra cada base en el lockfile de la Release, referenciada desde el spec.extends de la Feature que la nombra; una compilación lee la base desde allí.
Modos de error. Una cadena extends: cíclica, y un padre que ninguna entidad del catálogo proporciona, detienen la build, nombrando la Feature desde la que empezó la resolución, la Feature cuya línea extends: hay que abrir y la referencia que declara. Los mensajes están en Cyclic extends on Components or Features (extends cíclico en Components o Features) y An extends: chain cannot be assembled (No se puede ensamblar una cadena).
Para el vocabulario más amplio de herencia / interfaz entre Components, Features y Features de credenciales, consulta vocabulary/inheritance-and-interface.md.
Componibilidad: el contrato social de la pureza
La convención de la biblioteca estándar es una Feature, una función interna — un sidecar de observabilidad es una Feature de observabilidad; un sidecar de proxy de red es una Feature de proxy de red; no se combinan en un único compuesto con dos responsabilidades no relacionadas. La convención mantiene las Features individuales componibles, versionadas de forma independiente y acoplables de forma independiente.
El compilador Go central no impone esta convención. Las definiciones de Feature con responsabilidades mezcladas son sintácticamente válidas y compilan sin problemas. La aplicación es opcional:
- Las empresas que crean catálogos internos pueden escribir un plugin de linter personalizado que inspeccione las definiciones de Feature en CI/CD y advierta cuando las etiquetas
appliesTode una sola Feature abarcan dominios de capacidad no relacionados. - Un autor de Feature que registra, en
interoperability.conflictsWith, que dos Features se solaparían opta por una comprobación en tiempo de build: el compilador se detiene allí donde las dos alcanzan un mismo componente. Compara los nombres declarados y nada más, así que impone la declaración que escribió un autor y no la convención de pureza en sí.
Las Features de código abierto de la biblioteca estándar siguen la convención de pureza por disciplina de autoría; los catálogos empresariales son libres de desviarse cuando un compuesto estrechamente acoplado encaja realmente en el modelo de despliegue.
Qué justifica una Feature, y dónde va el ajuste propio de un producto
Una Feature es una vinculación: aporta algo que el desarrollador o el operador vincula deliberadamente — recursos, un paso de pipeline, cableado — y la convención de la biblioteca estándar es que pueda ser respetada por al menos dos productos independientes. Esa segunda mitad es la prueba que hay que aplicar antes de crear una, porque la portabilidad es lo que promete la palabra vinculación. Una vinculación dice que la capacidad viaja: vincúlala a un componente, vincúlala a otro, y la realización de cada producto la respeta en sus propios términos.
Una capacidad que solo tiene un producto en el campo es un ajuste propio de ese producto y no una Feature. Corresponde como valor escrito en la superficie propia de ese producto, que el autor que lo decide establece en su propio pilar y lee junto a todo lo demás que configura el mismo producto. Publicarla en cambio como Feature ofrece una portabilidad que ningún otro producto puede ofrecer: la vinculación nombra un solo producto por construcción, de modo que un autor que la vincula al siguiente producto al que recurre se encuentra con un build que se detiene nombrando el tipo, y la Feature ha enseñado una capacidad que nunca tuvo.
La prueba cuenta productos en el campo, no componentes de este catálogo, cada uno leído en su propia referencia de configuración actual. Dos productos independientes que implementan una capacidad la hacen portable, se distribuyan aquí cuantos se distribuyan, de modo que una Feature puede declararse antes de que nada en el catálogo la realice — vincularla entonces detiene el build nombrando el tipo — y cada realización que se distribuye es una FeatureRecipe para un solo producto, que respeta la vinculación de la forma en que ese producto la configure.
El anclaje de certificados upstream es el caso práctico. Un pin es un control sobre qué clave puede presentar un upstream: aceptar solo un certificado cuya clave pública coincida con una que proporciona la Release. Es una aserción distinta de exigir que el certificado de un upstream se encadene a un ancla de confianza que proporciona la Release, y distinta a su vez de afirmar lo que dice el sujeto de un certificado — ambas establecen lo que un certificado debe decir, mientras que un pin establece qué clave debe ser. Varios gateways de aquí pueden verificar contra un ancla, y por eso dataplane.aggrega.ai/upstream-tls: trust-anchor es un valor con el que un selector puede coincidir. El anclaje es una capacidad separada, y al menos dos productos independientes la implementan para las conexiones que abren hacia un upstream: Tyk toma la clave pública del upstream en formato PEM, y Envoy toma un hash de ella. Por tanto es una Feature, core/upstream-key-pinning, cuyo selector nombra dataplane.aggrega.ai/upstream-pinning: public-key, y lo que este catálogo realiza se responde producto por producto: core/gateway/tyk lleva el valor y una FeatureRecipe para cada uno de sus destinos, mientras que los gateways de aquí que integran Envoy exponen su ajuste de pin solo para los certificados que presentan los clientes, o no lo exponen en absoluto, de modo que no llevan ningún valor y una vinculación a ellos se detiene en el selector. Un pin restringe lo que un upstream puede presentar; es un control, no una garantía de que la conexión sea sólida en lo demás.
Dos límites de la prueba, y el segundo es la mitad que más fácilmente se omite:
- Es disciplina de autoría, no una comprobación del compilador. Una Feature que declara opciones que ningún producto implementa supera por igual la validación del esquema, el linter de publicación y un renderizado — el compilador no interpreta lo que promete una Feature. El juicio queda en manos del autor del catálogo.
- Que un producto no pueda respetar una opción no es motivo para eliminar esa opción. Donde dos o más productos ofrecen una capacidad bajo nombres que se agrupan, la capacidad es portable y la Feature la conserva; el producto que no puede respetarla la rechaza. Una Feature reducida a lo que todos los productos admiten casi no tiene nada que decir.
Ámbito de la Feature y forma de autoría
El spec.schema de una Feature define las formas values: e infra: propias de la Feature — la intención cognitiva que el desarrollador configura por cada vinculación de la Feature en el Aggregate (values), distinta de las cifras de capacidad que el operador decide por entorno (infra). Los pilares de la Feature viven en sus propios espacios de nombres y se validan de forma independiente de los pilares del Component anfitrión. Cuando el desarrollador vincula una Feature autoscaler a un Component web-server en el Aggregate, el Aggregate lleva los values: del Component (forma del anfitrión) más los values: de la Feature (la forma de la intención de escalado — qué métrica impulsa el escalado); las cifras de capacidad orientadas al operador (min_replicas / max_replicas) fluyen a través del bloque infra: de la Release en la vinculación de la Feature.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10El schema: de la Feature valida los bloques values: e infra: propios de la vinculación de la Feature. El schema: del Component valida los propios del Component. Ambos se evalúan de forma independiente en la etapa de análisis estático; un pilar de la vinculación que no coincide con el schema: de la Feature detiene el build con un error circunscrito al punto de vinculación de la Feature, no al Component anfitrión. Lo que se valida es la configuración efectiva de la vinculación — el resultado de componer cada ámbito que la configuró —, de modo que se detecta un valor que se hace conforme en un ámbito y luego se sobrescribe con algo ilegal en uno más estrecho.
Los valores predeterminados declarados se materializan en los pilares renderizados de la vinculación. Además de la validación, un default: declarado en un campo values o infra de una Feature se rellena en el pilar renderizado de esa vinculación en tiempo de build para cada clave que nadie escribió — así, una plantilla de FeatureRecipe que lee {{ .infra.tier }} recibe el valor declarado en el esquema en lugar de uno vacío. Los valores proporcionados por el autor siempre prevalecen, y un valor predeterminado rellena solo las claves que estos omiten: una vinculación que escribe una clave del esquema de la Feature sigue recibiendo los valores predeterminados declarados para las demás claves de ese esquema, y un objeto anidado escrito en parte conserva lo que se escribió y gana los hermanos que no se escribieron.
Conviene conocer tres propiedades del relleno al escribir:
- Un valor predeterminado nunca desplaza un valor que haya proporcionado algún ámbito. Donde una Feature está vinculada en más de un ámbito — un límite de Release y uno de sus componentes, por ejemplo —, prevalece el valor del ámbito más estrecho y el valor predeterminado rellena solo lo que ningún ámbito escribió.
- Un valor predeterminado rellena una vinculación; nunca crea una. Declarar valores predeterminados en una Feature que nada vincula no aporta nada a la salida, de modo que el esquema de una Feature no puede añadir configuración que ningún autor haya pedido.
- Una vinculación declarada en un límite de Release en lugar de en un único componente rellena solo
infra, porque esa superficie no lleva ningún bloquevalues:que rellenar.
Como la materialización usa la misma resolución de esquema que la validación, un valor predeterminado declarado en una Feature padre llega a las vinculaciones de un hijo extends:, y los valores predeterminados alcanzados mediante un $ref: entre documentos hacia una SchemaLibrary también se materializan. Los valores predeterminados declarados solo dentro de una referencia local dentro del documento #/$defs/, o bajo una rama allOf / oneOf / anyOf, no se materializan.
Conviene enunciar claramente una consecuencia, porque la validación por sí sola no la revelará: un campo required: que también lleva un default: queda satisfecho por ese valor predeterminado, así que omitirlo es legal — y el valor con el que la comprobación dio su aprobación es el valor que lleva la salida renderizada.
El contexto de plantillas del compilador expone el estado de la instancia de la Feature a la FeatureRecipe asociada a través del campo .features.<alias> (que contiene .type, .resolved_version, .labels, .values, .infra y .provides por vinculación). Las plantillas dentro de la FeatureRecipe leen los values: propios de la Feature mediante .values.<field> en el ámbito de plantilla propio de la FeatureRecipe; los values: del Component anfitrión no son directamente visibles para las plantillas de la FeatureRecipe a menos que la Feature declare explícitamente un socket uses: hacia el Component anfitrión.
Esta separación de ámbitos hace que las Features sean componibles: una Feature autoscaler no depende del Component al que se vincula; su schema: describe la intención de autoescalado sea cual sea el anfitrión. Los values: del Component anfitrión son asunto del anfitrión; los values: de la Feature son asunto de la Feature; los dos pilares se componen sin filtrar nombres de campo a través del límite.
Destinos de los bindings de anotaciones
Una Feature no declara ella misma bindings de anotaciones; los lleva el mapa mappings.features.annotations del Manifest. Una Feature participa indirectamente en la relación de binding como destino del enrutamiento: cada binding nombra un tipo de Feature mediante su campo feature:, y las listas maps.infra y maps.values del binding declaran rutas con puntos hacia las propiedades spec.schema.infra.<path> y spec.schema.values.<path> de la Feature nombrada.
Al cargar el catálogo, el compilador verifica que cada ruta con puntos de las listas maps de un binding corresponda a una propiedad que el spec.schema de la Feature de destino declara realmente en el pilar nombrado. Un binding que enruta hacia una ruta que el esquema de la Feature no declara detiene la carga del catálogo con un OPS_ERROR claro, que nombra el binding, la Feature de destino y el pilar y la ruta por los que enrutó — el binding está escrito en el Manifest, que es el documento del operador. Por tanto, los autores de esquemas saben que cualquier propiedad que declaren bajo spec.schema.values.<path> o spec.schema.infra.<path> es alcanzable como destino de binding; a la inversa, cualquier propiedad por la que enrute un binding del Manifest debe existir en el esquema de la Feature de destino.
Cuando una anotación del lado del Aggregate o del lado de la Release coincide con un binding, el compilador sintetiza una vinculación de Feature cuyas cargas de pilar enrutan el valor de la anotación hacia las rutas nombradas. La vinculación sintetizada es estructuralmente indistinguible de una vinculación de Feature explícita declarada por el autor en el mismo punto; el renderizado posterior, la validación y el contexto de plantillas de la FeatureRecipe consumen ambas formas de manera uniforme. Para la forma del binding, la partición entre lado y pilar y la disciplina por la que prevalece la vinculación explícita, consulta entities/manifest.md §«Bindings de Feature impulsados por anotaciones». Para la regla de cascada del lado del Aggregate y un ejemplo de autoría, consulta providers/well-known-annotations.md §«Cascada de anotaciones del lado del Aggregate».
El bloque assertions:
Feature.spec.assertions: es un mapa opcional de reglas con nombre que expresan invariantes arquitectónicos del contrato de la Feature — reglas entre campos sobre los values: de la Feature y el estado resuelto del Component vinculado. Cada clave es un identificador de regla que aparece en el mensaje de error; cada valor es el cuerpo de una plantilla Go. El compilador las evalúa después de la validación del esquema y antes de que se renderice la FeatureRecipe asociada, en el orden en que están escritas, y la primera regla que falla detiene el build con el mensaje de error propio de esa regla.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Al igual que las aserciones de Component, las aserciones de Feature expresan invariantes a nivel de contrato — propiedades que la vinculación de la Feature debe cumplir independientemente de qué FeatureRecipe implemente el renderizado. Para reglas entre campos que dependen de la implementación concreta (un requisito de un plugin Wasm, una peculiaridad de un chart), usa en su lugar el campo assertions: de la FeatureRecipe. Para la gramática de autoría completa, el contexto de plantillas y el reparto de responsabilidades entre las aserciones de Feature y las de FeatureRecipe, consulta templates/assertions-block.md.