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

Pilares de datos

El encuadre conceptual de las cinco palabras clave estructurales del DSL — parameters, values, uses, infra, inject — se encuentra en architecture/06-data-taxonomy-and-composition.md. Esta página cubre la lista canónica de pilares de datos, la semántica de autoría por pilar, la mecánica entre pilares y el vocabulario de valores predeterminados que los autores encuentran en los distintos pilares. La tríada topológica complementaria (provides, inject, uses — palabras clave que conectan las aristas del grafo) está documentada en topology-triad.md; el vocabulario de metadatos distinto de los pilares de datos (etiquetas, anotaciones, campos de la superficie de publicación) se encuentra en labels-and-annotations.md y publishing-surface.md.

Lista canónica de pilares

Las entidades de Aggrega llevan siete pilares de datos con nombre. Cinco participan en el flujo de datos de la IR como estado vivo durante todo el renderizado; dos son transitorios o privados y solo existen en etapas concretas de la compilación.

PilarReside enCiclo de vidaRol
valuesInstancias de componente / vinculación del AggregateVivo durante todo el renderizadoPayload cognitivo escrito por el desarrollador
infraEntradas de componente, vinculación y conexión de la ReleaseVivo durante todo el renderizadoDimensionamiento físico escrito por el operador
providesBloque provides: de la RecipeVivo durante todo el renderizado (pilar derivado — consulta más abajo)Cadenas de salida públicas calculadas por la Recipe que consume la tubería topológica
usesInstancias de componente / funcionalidad del AggregateVivo durante todo el renderizadoAristas topológicas hacia otros componentes / funcionalidades
featuresInstancias de componente del Aggregate + la Release; slots declarados en el featuresSchema de una entidad del catálogo — consulta «Features pillar (Pilar Features)» más abajoVivo durante todo el renderizadoPilar de vinculaciones — una sola forma para cada familia de vinculaciones
parametersRaíces del Aggregate + la ReleaseLegible hasta el final del pipeline, hasta que se completa cada fase de renderizado; accesible para las plantillas de ruta durante el renderizado mediante la concesión asimétrica; los contextos de plantillas de valor consumen los literales posteriores a la interpolación en lugar de .parameters directamenteSlots por entorno que cumple la Release
localsBloque locals: de la RecipePrivado de la Recipe — visible solo dentro de las plantillas propias de la RecipeEstado de cadena calculado que las Recipes derivan en el preámbulo de locals

values / infra / provides / uses / features son los cinco pilares vivos que el contexto de plantilla en tiempo de ejecución expone mediante .values, .infra, .provides, .context.uses y .features, respectivamente. parameters y locals quedan fuera de la lista de pilares vivos — parameters porque no sobrevive a la resolución; locals porque es privado de la Recipe y nunca cruza los límites de las entidades.

Los pilares son señales, no muros: el motor de plantillas permite lecturas entre pilares en cualquier sitio, salvo que las reglas de autocontención lo prohíban explícitamente (un bloque provides: de Recipe y un bloque source: de Recipe que leen .context.inject / .context.uses; documentado en templates/expansion-matrix.md). Los límites de los pilares son disciplina de autoría, no una imposición del lenguaje.

Límites de los pilares y disciplina de autoría

Las lecturas entre pilares desde una plantilla de Recipe no tienen restricciones en cualquier sitio que permita el contexto de plantilla completo. La disciplina de autoría espera que los autores:

  • Lean .values para el payload cognitivo (intención escrita por el desarrollador).
  • Lean .infra para el dimensionamiento físico (dimensionamiento escrito por el operador).
  • Lean .context.uses[].provides.<key> para las cadenas de puntero entre componentes (el flujo de datos de la tríada topológica).
  • Lean .context.inject para la tubería de entrega posterior a la hidratación (ensamblada a partir de las fuentes de inject en component.inject, uses[].inject y las interceptaciones injectMapping de FeatureRecipe).

La disciplina son señales, no muros. Una plantilla de Recipe que lee .infra.replicas para alimentar un campo values: funciona; el motor de plantillas no bloquea la lectura. El encuadre de la arquitectura es que los límites de los pilares describen la intención de autoría — a quién pertenecen los datos — en lugar de una restricción en tiempo de ejecución. Las convenciones coinciden con la división en cuatro dominios: los valores escritos por el desarrollador vienen de .values; el dimensionamiento escrito por el operador viene de .infra; las coordenadas entre componentes vienen de la tubería topológica.

Cuando se necesita un puente deliberado entre pilares — p. ej., el schema: de un Component expone un control orientado al desarrollador que la plantilla valuesMapping: de la Recipe canaliza hacia una salida con forma de infra: del lado de Ops, según vocabulary/inheritance-and-interface.md — la arquitectura trata el puente como una excepción señalizada. Consulta «Cross-pillar mechanics (Mecánica entre pilares)» más abajo.

Values

El pilar values: lleva el payload cognitivo escrito por el desarrollador — los parámetros con la forma de la aplicación que el desarrollador dicta para cada instancia de componente. El schema: del Component declara la forma de los valores; el Aggregate del desarrollador rellena valores concretos por instancia. Este es el dominio del desarrollador.

Se escribe en:

  • Aggregate components.<id>.values: — payload cognitivo por instancia de componente.
  • Aggregate subsystems.<name>.components.<id>.values: — lo mismo, dentro de componentes agrupados en subsistemas.
  • Aggregate components.<id>.features.<name>.values: y features.<name>.values: de un subsistema — payload de valores de la vinculación, sea cual sea la familia a la que pertenezca la Feature vinculada (los parámetros de consulta al vault de una vinculación de credenciales se escriben aquí como cualquier otro).

Prohibido en:

  • Entidad Release (el esquema de la Release prohíbe un bloque values: en cualquier nivel de anidamiento — el Parameter Hoisting es la vía admitida para la variación por entorno; consulta Parameters más abajo).

Validado por: el bloque values: del schema del Component (y el bloque values: del schema de la Feature para las vinculaciones de Feature), resuelto a JSON Schema 2020-12 al cargar el Component / la Feature según vocabulary/validation-surface.md, capa 2.

Consumido por: las plantillas valuesMapping: de la Recipe mediante .values. El contexto de plantilla completo expone el diccionario de valores resueltos en cada sitio de plantilla del renderizado base.

Infra

El pilar infra: lleva el dimensionamiento físico escrito por el operador — réplicas, solicitudes de recursos, límites de IOPS, fijación de región, clase de máquina. Expresa el dónde y de qué tamaño, complementando el qué y cómo se comporta de los values. Este es el dominio del operador.

Cuatro superficies de autoría

Los autores encuentran infra: en cuatro superficies distintas, cada una con un ámbito diferente y un comportamiento en cascada diferente:

#SuperficieÁmbitoPrecedencia de fusión
1Límite de la Release components.<id>.infra: (spec.components.<id>.infra: en una Release sin límites)Una instancia de componenteEl dimensionamiento propio del componente; ninguna otra superficie lo escribe
2Límite de la Release features.<name>.infra:Una vinculación de ámbito de límite, en cada componente del límiteLa más baja para esa vinculación — la superficie 3 la sobrescribe campo a campo
3Límite de la Release components.<id>.features.<name>.infra:Una vinculación en un componenteSobrescribe la superficie 2 para esa vinculación, campo a campo
4Release components.<id>.uses.<socket>.<alias>.infra:Una conexiónValidado contra el infraSchema del socket; solo llega al renderizado del componente consumidor

La superficie 1 es la más escrita: un operador dimensiona cada componente que coloca la Release. Un límite no lleva ningún infra: propio — el esquema de la Release lo rechaza —, así que el dimensionamiento que comparten varios componentes se escribe en cada uno, o se hereda de una Release padre mediante extends: (más abajo). Las superficies 2 y 3 cubren el dimensionamiento de las vinculaciones de Feature — las Features llevan su propio payload infra, que la FeatureRecipe consume al sintetizar sidecars o recursos por Feature: una vinculación de ámbito de límite se dimensiona una vez, y un componente ajusta un solo campo de ella.

«Infra principalmente localizado» — la regla con excepciones

El objetivo arquitectónico para infra: es local al componente: el dimensionamiento de un componente se aplica a esa instancia de componente y no se extiende a otros componentes. Es el mecanismo que permite a Ops aumentar los IOPS de la base de datos sin afectar a la solicitud de CPU del servidor de API.

La regla: infra: está principalmente localizado en la superficie que lo escribió. Existen excepciones en cascada por diseño:

  • Cascada de anotaciones del límite. Las annotations: de un límite se propagan en cascada a través de los límites anidados hasta los componentes internos (superficie 5 de la matriz de anotaciones en labels-and-annotations.md). Las anotaciones que las Recipes consumen como entrada de enrutamiento se convierten en un alcance indirecto de infra — la anotación a nivel de límite fluye a través de .context.annotations.release hacia la salida renderizada de la Recipe por nodo.
  • Herencia de Release mediante extends:. Una Release que hace extends: de una Release padre hereda las declaraciones infra del padre en cada superficie que las lleva, a menos que la hija las sobrescriba clave por clave. El valor de la hija prevalece clave por clave, hasta el primer valor indivisible — un escalar, una lista, una plantilla —, que se sustituye entero, y una clave que la hija escribe como null se elimina en lugar de establecerse en nada. La herencia cruza deliberadamente el límite de cada Release; para la regla de plegado completa y lo que viaja con ella, consulta entities/release.md.
  • Canalización entre pilares mediante puente de esquema. El schema: de un Component puede exponer un control values: orientado al desarrollador que la plantilla valuesMapping: de la Recipe canaliza hacia la salida del proveedor con forma de infra: (consulta «Cross-pillar mechanics — Schema-bridge cross-pillar piping (Mecánica entre pilares — Canalización entre pilares mediante puente de esquema)» más abajo). En sentido estricto, el valor se origina en values: y fluye hacia la salida renderizada; la cascada es interna a la instancia pero entre pilares.

La localización es la intención de diseño, no un muro que el motor imponga: las cascadas anteriores son excepciones deliberadas, cada una documentada en la superficie que la lleva.

Partición entre lado y pilar para la expansión de Feature guiada por anotaciones. La invariante del Aggregate como superficie de autoría se extiende a la ruta de expansión de Feature guiada por anotaciones: las anotaciones del lado del Aggregate (ámbito de subsistema y de instancia de componente) solo pueden activar subclaves maps.values; las anotaciones del lado de la Release (ámbito de límite y de instancia de componente) solo pueden activar subclaves maps.infra. Un binding de Manifest puede declarar rutas en ambos pilares; cada lado activa solo su subconjunto compatible, y la composición entre lados fusiona las contribuciones campo a campo en el momento de la compilación de la IR. La partición preserva la separación de autoría values-desarrollador / infra-operador en la superficie de anotaciones — la misma separación que values: e infra: imponen en las superficies de vinculación explícita. Consulta providers/well-known-annotations.md §«Side-vs-pillar partition per subkey (Partición entre lado y pilar por subclave)» para la explicación por subclave y el patrón de composición entre lados.

Provides

El pilar provides: es derivado — lo declara una Recipe, pero a diferencia de values / infra, el desarrollador no lo escribe directamente. Las Recipes calculan las cadenas de salida públicas que consumirá la tubería topológica.

El bloque provides: de una Recipe es un mapa de pares <key>: <template>. Cada plantilla se evalúa contra la superficie autocontenida propia de la Recipe (.values, .infra, .context.instance_id, .context.rendered_name donde el proveedor del nodo informa de uno, y los .locals resueltos del nodo) durante la evaluación de los provides. Las cadenas resultantes se exponen mediante .provides y las consumen los bloques uses[].inject de los llamadores mediante referencias from: "<key>". .locals está disponible porque los locals del nodo se resuelven en el preámbulo de esa etapa, antes que sus provides (consulta Locals más abajo); nombrar una clave que el bloque locals no declara provoca una detención.

Invariante de autocontención. Las plantillas provides: de una Recipe no deben referenciar .context.inject ni .context.uses. La evaluación de los provides ejecuta esas plantillas en cualquier orden — solo se cierran sobre los datos propios del nodo, así que el orden no importa. Las referencias entre nodos acoplarían esa evaluación al orden de iteración topológica, algo que el diseño evita deliberadamente. Consulta templates/expansion-matrix.md, fila 6, para la regla y su justificación.

Por qué provides: es un pilar. Las cadenas de salida son la superficie pública canónica de cada Recipe; los consumidores posteriores (uses[].inject del llamador, bloques injectMapping de FeatureRecipe que leen los provides resueltos del destino mediante .context.uses) tratan el diccionario como un contrato tipado. Nombrar provides: como pilar reconoce su estatus de primera clase junto a values / infra / uses / features. Tratarlo como «un mero detalle interno de la Recipe» subestima su papel como fuente de datos principal de la tubería topológica.

Uses

El pilar uses: es la declaración de aristas topológicas. El bloque uses: de una instancia de componente nombra las aristas en las que participa el componente — los sockets a través de los cuales consume destinos. La gramática completa está documentada en topology-triad.md; esta sección nombra uses: como pilar para completar el panorama.

uses: reside en las instancias de componente del Aggregate + las vinculaciones de funcionalidad; el contexto de plantilla en tiempo de ejecución expone una entrada por cada conexión saliente, indexada por su alias, como .context.uses. La proyección lleva los metadatos resueltos del destino de cada arista (los provides del destino, etiquetas, anotaciones) para que las Recipes de los llamadores puedan leer cadenas de puntero entre componentes en la evaluación de plantillas del renderizado base, y las vinculaciones escritas en esa conexión, en .context.uses.<alias>.features.<slot>.

Pilar Features

features: es el pilar de vinculaciones: una palabra clave, una forma, cada vinculación. Una Feature operativa, una Feature de credenciales y una Feature de identidad se declaran todas aquí bajo el nombre de instancia que elige el autor. El contexto de plantilla en tiempo de ejecución expone las vinculaciones del nodo como .features.<name>, cada una con type, values, infra y los provides resueltos de la vinculación. Una vinculación escrita en una de las conexiones del componente se expone en esa misma forma bajo la conexión, en .context.uses.<alias>.features.<slot>, y nunca bajo .features — así, una Recipe que recorre .features solo encuentra las vinculaciones propias del componente (consulta el contrato del contexto de plantillas).

Una vinculación cuyo nombre de instancia coincide con un slot que la entidad declara en featuresSchema rellena ese slot; cualquier otro nombre de instancia es una vinculación libre. Rellenar un slot es lo que conecta las cuatro superficies que recorre una credencial basada en slots:

SuperficieDónde se escribeRol
Component / Feature featuresSchema:entidad del catálogoDeclara los slots que espera la entidad; por slot, restringe la allowlist de entrega (env / file / blackbox) y, opcionalmente, un selector de etiquetas que el relleno debe satisfacer
Aggregate components.<id>.features.<slot>:Instancia de componente del AggregateRellena el slot con una vinculación; aporta los values: propios de la vinculación y, para un slot transparente, su mapeo inject:
Workload containers.<name>.attachments.<KEY>.from/as:Cuerpo de Workload de la RecipeHace referencia a un slot declarado — o, junto a connection: <alias>, a un slot que declara el socket de esa conexión — y dicta la entrega por contenedor de lo que lo rellenó
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:)la FeatureRecipe enlazadaProduce la salida de la vinculación — un recurso emitido, una reescritura de la entrega, o ambos

El nombre del slot es el identificador determinante en las cuatro: la superficie 1 lo declara, las superficies 2–4 hacen referencia a él, y el flujo de datos va en una sola dirección (declarar → rellenar → referenciar → producir).

Para la lista de comprobación de autoría, consulta examples/04-secrets.md «The secret-delivery checklist (La lista de comprobación de la entrega de secretos)».

Locals

El pilar locals: es estado privado de la Recipe. Todo el bloque se resuelve en el preámbulo de locals, antes del provides: de ese nodo; las cadenas resultantes son visibles para cada una de las plantillas posteriores propias de la Recipe — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Una plantilla provides: que nombra una clave que el bloque no declara provoca una detención.

Se escribe en: el bloque spec.locals: de la Recipe — un mapa de pares <key>: <template> evaluados contra una superficie autocontenida local al nodo: .context.instance_id, .values, .infra y las entradas del mismo bloque ya resueltas. Nada más está en ella: .provides, .metadata y el resto de .context.* no lo están, y una referencia a cualquiera de ellos provoca una detención.

El orden es determinante. Las entradas se resuelven en el orden escrito y una entrada puede leer una entrada hermana definida por encima de ella, recibiendo su valor resuelto. El encadenamiento solo va hacia abajo — cuando una entrada lee otra, mover la definición por debajo de su lector se rechaza, y el compilador nunca reordena el bloque para que la referencia se resuelva. Una referencia a una entrada posterior provoca una detención que nombra el fallo de orden; una referencia a una clave no declarada provoca una detención que nombra la clave. En una Recipe cuyo source: es un bloque estructurado, ambos fallos se rechazan también mientras se fija el artefacto que nombra, de modo que aggrega pull los informa antes de que cualquier compilación renderice salida. La comprobación lee la ruta a la que se resuelve una referencia en lugar de las pulsaciones, así que alcanza por igual la forma directa, un bloque with .locals, una variable ligada a .locals y el bloque entre paréntesis, (.locals).<key> o ($.locals).<key>. Una escritura que no cubre: una clave alcanzada a través de una función, como index .locals o (default dict .locals).<key>. Una clave ausente alcanzada así no provoca una detención, y renderiza el texto literal <no value> en lugar de nada en absoluto — excepto a través del propio index, que provoca una detención nombrando la clave en cualquier superficie de plantilla cuando el mapa que lee no la contiene.

Visibilidad: privado de la Recipe. No existe un campo .context.uses[].locals — un llamador no puede leer los locals de su destino a través de la arista. Lo que un llamador puede leer es el provides: del destino.

Casos de uso:

  • Calcular cadenas de puntero internas de la Recipe (p. ej., secret_target_admin_password: "redis-auth", el sufijo del nombre de un Secret) que consumen tanto el valuesMapping: como el provides: de la Recipe, y que una FeatureRecipe de credenciales vinculada al mismo componente lee como .locals.secret_target_admin_password — las plantillas de una vinculación ven los locals resueltos de la Recipe anfitriona fusionados con los propios de la vinculación. En el destino helm, cada una de ellas escribe el nombre completo como {{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}: el nombre renderizado es el nombre del componente escrito con los caracteres que admite un nombre de Kubernetes, y un local no puede leerlo, así que el local lleva el sufijo y cada lector une ambos.
  • Aplicar DRY a valores calculados repetidos dentro de una Recipe (un nombre de host calculado una vez, referenciado desde varios campos valuesMapping:).
  • Valores intermedios para lógica de plantillas compleja que sería ilegible en línea.

provides: y locals: — cara pública frente a cara privada

Los dos pilares del lado de la Recipe llevan una separación deliberada de visibilidad que los autores deberían tener presente:

  • provides: es la cara pública. Cada clave es la superficie canónica de la tubería topológica — los bloques uses[].inject de los llamadores posteriores las consumen mediante referencias from: "<key>". El diccionario provides: es un contrato tipado del que dependen los llamadores; renombrar o eliminar una clave es un cambio incompatible para cada Recipe cuyas declaraciones uses[].inject hagan referencia a ella.
  • locals: es la cara privada. Cada clave es estado interno de la Recipe visible solo dentro de las plantillas posteriores propias de la Recipe. Ningún llamador puede leer los locals de una Recipe; los nombres en locals: no forman parte de ninguna interfaz publicada y renombrarlos es una refactorización interna de la Recipe sin efecto posterior.

Los dos también están ordenados: locals: se resuelve primero, así que provides: puede leer .locals pero locals: no puede leer .provides. Publicar el valor de un local mediante provides: significa, por tanto, añadir una entrada provides que lee el local — la expresión permanece en un solo lugar.

La separación es deliberada, conforme a la separación arquitectónica entre los internos de la Recipe (privados) y la interfaz de la Recipe (pública). Los autores que tratan provides: y locals: como un único espacio de nombres pierden la distinción de visibilidad y se arriesgan a exponer estado interno a través de la tubería topológica — cada clave declarada en provides: pasa a formar parte de la superficie contractual de la Recipe, lo pretendiera o no el autor. El objetivo de la disciplina: declarar primero una clave en locals:; promoverla a provides: solo cuando un llamador posterior realmente la necesite.

La visibilidad la fija el pilar en el que se declara una clave: no existe un marcador de visibilidad por clave, así que un valor a la vez privado y publicado es una entrada locals: más una entrada provides: que la lee.

Parameters

Tanto el esquema Aggregate como el esquema Release llevan un diccionario parameters en su raíz. Los desarrolladores declaran las claves que espera el Aggregate; Ops rellena los valores desde archivos de Release específicos de cada entorno. Este desacoplamiento es el mecanismo de la promoción GitOps: un único Aggregate.yaml inmutable avanza por los entornos Dev, Staging y Production, y la Release de cada entorno aporta sus propios valores de parámetros.

aggregate.yaml
spec:
parameters:
corp_db_name:
type: string
required: true
env_workers:
type: integer
required: true
region:
type: string
required: true
enable_debug:
type: boolean
required: true
components:
my-backend:
type: core/python-worker:1.0.0
values:
workers: {{ .parameters.env_workers }}
region: "{{ .parameters.region }}"
# release-prod.yaml — inline parameter values
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
corp_db_name: "enterprise_data"
env_workers: 10
region: "eu-west-1"
enable_debug: false

Para flujos de CI/CD que mantienen los valores de los parámetros en un archivo aparte (p. ej., un .yaml por entorno versionado junto a la Release), la Release usa la forma $import:: parameters: { $import: ./prod-values.yaml }. El contenido del archivo sustituye el mapa en línea en la superficie de la Release. La ruta se resuelve desde el directorio que contiene la Release, sea cual sea el lugar desde el que se ejecute un comando, y debe llevar a un archivo dentro del espacio de trabajo — o, para una Release indicada fuera del espacio de trabajo, dentro del directorio que la contiene. La superposición de varios archivos (combinar un archivo base con una capa específica del entorno) se expresa mediante cadenas extends: de Release — la Release padre aporta los parámetros base; la Release hija extiende y sobrescribe clave por clave.

Ciclo de vida de los parámetros. El compilador resuelve los parámetros en tres fases. (1) Relleno de valores predeterminados — los slots con default: definido y sin valor de la Release reciben su valor predeterminado. (2) Validación del contrato de parámetros — el contrato tipado parameters: valida cada valor contra sus restricciones declaradas type / enum / min / max / pattern, incluido un valor predeterminado rellenado, de modo que un valor predeterminado que incumple su propio contrato detiene la compilación. (3) Interpolación — el compilador evalúa todo el texto del Aggregate como una plantilla y sustituye cada referencia {{ .parameters.<slot> }} por el valor resuelto. El mapa fusionado sigue siendo legible durante el renderizado, de modo que las plantillas de ruta (límite de la Release directory: / subDirectory:) pueden leer .parameters.<slot> directamente, contra la allowlist cerrada documentada en ../path-template-variables.md. Las superficies de plantillas de valor (Recipe valuesMapping, FeatureRecipe injectMapping / provides / pipeline.with, cuerpos de Workload) NO reciben .parameters en su contexto de plantilla — consumen los valores resueltos escritos en las cadenas values: circundantes por la interpolación de la fase 3.

La lista de comprobación de la elevación de parámetros

Cada valor que varía entre entornos pasa en secuencia por cuatro puntos de contacto de autoría. El modelo mental que llevan los autores: para cualquier valor que varíe entre Dev / Staging / Production, espera tocar el Aggregate (declarar), la plantilla de values (referenciar), la Release (cumplir) y la plantilla de la Recipe (consumir).

PasoSuperficieAcción
1Aggregate spec.parameters.<name>Declara el parámetro como parte del contrato de autoría tipado del Aggregate. Cada slot de parámetro lleva un type declarado (string, integer, number, boolean, array, object), una description opcional, un default opcional, restricciones opcionales del espacio de valores (enum, min, max, pattern, minLength, maxLength) y una estructura anidada opcional para los slots de tipo objeto. El contrato valida cada valor que aporta la Release antes de la interpolación.
2Plantilla values: del Component dentro del mismo AggregateHaz referencia al parámetro mediante {{ .parameters.<name> }} desde dentro del bloque values: de cualquier componente (o funcionalidad, o subagregado) que lo consuma. La referencia es una expresión de plantilla de Go — el compilador la evalúa durante la fase de interpolación de la resolución.
3Release spec.parameters.<name> (en línea o parameters: { $import: ./path.yaml })Cumple el parámetro con el valor específico del entorno en la superficie de la Release. Los archivos de Release por entorno aportan valores distintos para la misma clave de parámetro sin modificar el Aggregate.
4Plantilla valuesMapping: de la RecipeConsume el valor resuelto mediante {{ .values.<key> }} — la Recipe es una superficie de plantilla de valor; su contexto de plantilla no lleva .parameters directamente. La variación por entorno llega a la Recipe a través del diccionario values: posterior a la interpolación que escribe la fase de interpolación anterior. (Las plantillas de ruta en los límites de la Release son la excepción: leen .parameters.<slot> directamente durante el renderizado según la concesión asimétrica.)

Los cuatro puntos de contacto son secuenciales y determinantes: omitir la declaración en el Aggregate deja a la Release sin slot que cumplir; omitir la referencia en los values deja a la Recipe sin valor que consumir; omitir el cumplimiento en la Release deja el parámetro vacío. El compilador valida la cadena durante la resolución (validación del contrato de parámetros contra la declaración tipada parameters:, luego interpolación en las cadenas values: circundantes, luego validación con JSON Schema del diccionario values: resultante contra el schema: del Component o de la Feature); las discrepancias aparecen como una violación del contrato de parámetros (detectada contra la declaración tipada parameters:), un error de plantilla sin rellenar (detectado en la interpolación) o una violación de restricción de JSON Schema contra el esquema values: (detectada en la validación de esquema).

El patrón es el mecanismo canónico de la promoción GitOps: un único Aggregate inmutable avanza por los entornos y la Release de cada entorno aporta sus propios valores de parámetros. Todo valor por entorno que un autor quiera variar pertenece a la cadena de parámetros en lugar de incrustarse directamente en el Aggregate.

Semántica de fusión de extends: por pilar

Cuando una entidad del catálogo declara extends: y el compilador recorre la cadena de herencia, el contenido de cada pilar se fusiona según reglas específicas del pilar. La semántica difiere entre pilares; la tabla siguiente es la referencia canónica por pilar.

PilarComportamiento de fusión en una cadena extends:
values (JSON Schema 2020-12)En una cadena de Feature, los esquemas se componen mediante la composición de JSON Schema 2020-12. Un Component que extiende no escribe contenido de pilar y recibe el bloque de su base exactamente como la base lo escribió, a cualquier profundidad de una cadena.
infra (fragmento de JSON Schema 2020-12)Igual que values — compuesto en una cadena de Feature, heredado entero por un Component que extiende.
provides (mapa de plantillas de la Recipe)Sustitución superficial de primer nivel: la clave hija sustituye por completo a la clave padre del mismo nombre; las claves hermanas se conservan del padre. Las plantillas no se componen; la plantilla de la hija es dueña por completo de su slot.
uses (usesSchema)Superposición de la entrada completa por socket, por nombre de socket. Una hija añade sockets que su base no declara, y un socket que redeclara con un nombre existente sustituye esa entrada por completo — sus esquemas de valor e infra y su selector juntos. Las entradas de socket no se componen, y nada compara un selector redeclarado con el de la base.
features (esquema por slot de featuresSchema)Superposición de la entrada completa por slot, por nombre de slot, en los mismos términos que usesSchema. Una hija añade slots libremente; un slot que redeclara sustituye por completo la entrada de la base en lugar de componerse con ella.
locals (mapa de plantillas de la Recipe)Sustitución superficial de primer nivel — igual que provides.
parameters (mapa raíz del Aggregate)Un Aggregate no tiene campo extends:, así que ninguna cadena de Aggregate fusiona parámetros. En una cadena extends: de Release, un parámetro con valor de mapa se fusiona en profundidad con prevalencia de la clave hija, uno con valor escalar lo sustituye la hija, y una clave que la hija escribe como null se elimina.

El patrón general depende del tipo y de la superficie. Los pilares validados por esquema de una Feature se componen bajo JSON Schema 2020-12. Los pilares de un Component que extiende se heredan enteros — no escribe ninguno, así que su contrato es exactamente el de su base, y una restricción de la base no puede por tanto relajarse, por construcción. Las superficies de forma fija — usesSchema y featuresSchema — se superponen por nombre en ambos tipos: una hija añade entradas, y una entrada que redeclara sustituye por completo la de la base. Los pilares escritos como plantillas usan sustitución superficial por clave, lo que da a la hija la plena propiedad de cualquier slot de plantilla que declare.

Un Component que extiende endurece una restricción mediante assertions: en lugar de mediante un pilar — un predicado que añade, evaluado junto a los que hereda. Consulta inheritance-and-interface.md para ese mecanismo.

Para el mecanismo de herencia en sí, consulta inheritance-and-interface.md «Inheritance via extends (Herencia mediante extends)», que cubre los tipos del catálogo. Una Release no es una entidad del catálogo y se pliega según su propia regla; esa regla está en entities/release.md «Composite Release and extends: inheritance (Release compuesta y herencia mediante extends:)».

Mecánica entre pilares

El encuadre de señales permite lecturas entre pilares en todas partes, salvo en las superficies de autocontención documentadas. Los patrones siguientes formalizan mecánicas habituales entre pilares; se documenta un síntoma de autoría problemática para que los autores reconozcan la contrapartida.

Canalización entre pilares mediante puente de esquema — señalizado, no amurallado

Los límites de los pilares son disciplina de autoría: la arquitectura señaliza qué va dónde (values: para la intención cognitiva del desarrollador, infra: para el dimensionamiento físico de Ops, provides: para las cadenas emitidas por la Recipe, etc.) y el revisor del catálogo hace cumplir la convención. El propio motor de plantillas permite lecturas entre pilares, salvo que las reglas de autocontención documentadas las prohíban (el provides: de una Recipe no ve .context.inject; el provides: de ámbito de límite de una FeatureRecipe no ve los campos por consumidor). Los muros de los pilares son señales, no imposiciones.

Una excepción señalizada canónica: el schema: de un Component puede declarar un control values: orientado al desarrollador que la plantilla valuesMapping: de la Recipe canaliza hacia la salida renderizada con forma de infra:. El desarrollador dicta la intención mediante un campo values: tipado; la plantilla de la Recipe canaliza el valor resultante hacia la capa de infraestructura del proveedor sin que el desarrollador escriba código de infraestructura. Un ejemplo desarrollado:

# Component schema declares a developer-facing dial in values
spec:
schema:
values:
required_iops: { type: integer, min: 100 }
# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knob
valuesMapping:
iops_limit: "{{ .values.required_iops }}"

El puente está documentado en inheritance-and-interface.md con ejemplos desarrollados. La intención arquitectónica (un control entre pilares declarado que la Recipe canaliza) tiene una sola dirección — values: del lado del desarrollador que fluyen hacia la salida renderizada del lado de Ops — y se materializa en las plantillas de mapeo de la Recipe, no en el propio esquema del Component. El límite de los pilares sigue señalizado: el desarrollador ve values:, la Recipe ve tanto values: como infra:, y la salida renderizada los combina.

Acumulador inject entre pilares

La tubería .context.inject es el punto de fusión de tres fuentes que abarcan varios pilares:

  1. Self-inject a nivel de Component (component.inject) — obtiene cadenas de los values y los provides propios del componente.
  2. Uses-inject (uses[].inject) — obtiene cadenas de los provides del destino.
  3. Interceptaciones injectMapping: de la FeatureRecipe — obtienen cadenas de cualquiera de las fuentes anteriores, más el payload infra: propio de la FeatureRecipe.

Cuando se ejecuta el renderizado base, .context.inject.<mechanism>.<key> ya ha acumulado entradas de las tres fuentes. El acumulador es entre pilares por construcción — las entradas que se originan en values, provides e infra fluyen todas hacia el mismo mapa .context.inject. Las Recipes que consumen .context.inject ven el estado posterior a la fusión sin necesidad de saber qué pilar aportó cada entrada.

Para la gramática de inject y las reglas de colisión, consulta topology-triad.md.

Duplicación de restricciones entre pilares

Un campo que vive en dos pilares con capas de validación diferentes puede llevar restricciones duplicadas. El ejemplo canónico: un número de puerto declarado en el usesSchema de un Component (validado con JSON Schema, rango min: 1, max: 65535) y el mismo número de puerto consumido en el campo services.<name>.ports.<port> de un Workload, para el cual el spec.provider.workloadSchema del plugin de renderizado del proveedor puede añadir una regla min: 1024 para puertos no privilegiados. El spec.provider.workloadSchema de un Plugin de renderizado del proveedor documenta cómo el proveedor traduce un Workload y marca al proveedor como capaz de sintetizar uno; no valida nada. Todo cuerpo de Workload se valida contra el esquema Workload de la plataforma, sea cual sea el proveedor, así que una restricción escrita solo en un workloadSchema — una regla de puerto min: 1024, por ejemplo — no se aplica; para rechazar un valor así, pon la restricción en el esquema del Component o en una aserción.

Vinculación de Feature / aislamiento de pilares del Component

Una vinculación de Feature no escribe en los pilares del Component padre. Cada Feature vinculada lleva su propio payload de pilar (su propio bloque values: y su propio bloque infra:). La FeatureRecipe que sintetiza los recursos de la Feature lee su propio payload de pilar con independencia del del Component. El aislamiento es de las entradas: lo que una vinculación lee es suyo, sea cual sea el destino de lo que escribe. Donde el proveedor del destino escribe documentos separados, la salida renderizada de la vinculación se sitúa junto a la del Component, en un directorio propio; donde el proveedor reúne los contribuyentes de un límite en un único documento, la vinculación contribuye a ese documento igual que el Component, y cada recurso sigue llevando la identidad propia de la vinculación, de modo que sigue siendo legible qué vino de dónde.

Dos consecuencias para los autores:

  • Un ajuste values: en una vinculación de Feature no aparece en .values de la plantilla valuesMapping: del Component. El Component solo ve sus propios valores.
  • El payload infra: de una Feature no fluye hacia el infra: del Component. Cada Feature vinculada tiene su propio dimensionamiento físico, acotado a los recursos de la Feature.

El aislamiento es explícito según la separación de responsabilidades de la arquitectura: las Features son contribuyentes independientes superpuestos a los Components mediante el modelo de cebolla de 5 niveles. Para las superficies de vinculación y su orden, consulta labels-and-annotations.md «Feature attachment — five surfaces (Vinculación de Feature — cinco superficies)».

El mismo nombre de propiedad en ambos pilares

Un Component o una Feature cuyo spec.schema.values: y cuyo spec.schema.infra: declaran el mismo nombre de propiedad — en la raíz, a cualquier profundidad de anidamiento, o en ambos casos — es un síntoma frecuente de autoría problemática. Los dos pilares son espacios de nombres separados por diseño (el compilador acepta el solapamiento), así que el esquema se valida y la salida renderizada está bien formada. El síntoma es cognitivo: lectores y autores de plantillas tropiezan con la fricción «¿qué pilar contiene el foo que estoy leyendo?» cada vez que recorren el esquema o escriben una plantilla basada en él.

# Smell — both pillars declare `mode`. A reader of the schema or a
# template against the Feature has to disambiguate every reference.
spec:
schema:
values:
mode: { type: string }
infra:
mode: { type: string }

Los autores con un solapamiento intencionado tienen un motivo real para conservar ambos — p. ej., un mode que significa «modo operativo de la aplicación» en values ("debug" / "production") y «modo de topología del despliegue» en infra ("standalone" / "clustered") lleva semánticas distintas, y los nombres coinciden por casualidad. Los autores con un solapamiento accidental (el caso más común) renombran una de las entradas.

Una segunda forma intencionada es un único dato que cualquiera de los dos autores puede aportar. Las Features de credenciales de la biblioteca estándar que llevan el localizador de un llamador — core/referenced-secret, core/referenced-secret-set, core/secret-value y core/secret-provided — lo declaran en ambos pilares con un mismo nombre y una misma forma, de modo que el desarrollador lo escribe en values o el operador en infra, y la aserción propia de cada Feature rechaza una vinculación que lo escriba en ambos o en ninguno. El aviso descrito más abajo nombra esas cuatro en cada carga que las alcanza; para ellas informa del contrato, no de un descuido.

La carga del catálogo emite un aviso notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) por cada propiedad del mismo nombre cuyo solapamiento se resuelve en una hoja terminal en al menos un lado. Las propiedades del mismo nombre que existen como espacios de nombres organizativos compartidos (ambos pilares llevan un objeto llamado ingress con subpropiedades disjuntas) no generan advertencia; solo se informa del solapamiento de hojas. La advertencia es un aviso — la compilación continúa.

Niveles de validación de los pilares

Los pilares llevan validación en tres niveles. Cada nivel cubre un aspecto distinto; el mismo campo puede ser validado por más de un nivel (consulta «Cross-pillar constraint duplication (Duplicación de restricciones entre pilares)» más arriba).

NivelQué validaDónde se ejecuta
1 — Envoltorio de JSON SchemaForma estructural (qué claves están presentes, si los tipos coinciden con las declaraciones de los campos)Resolución, en cada carga de archivo
2 — Esquema por pilar (schema / featuresSchema / usesSchema)Contenido tipado por pilar, validado como JSON Schema 2020-12Resolución, una vez superado el envoltorio
3 — control de capacidades del proveedorContenido del Workload condicionado por la capacidad de modo sintetizado del proveedor enlazado, documentada por el spec.provider.workloadSchema del plugin de renderizado del proveedorRenderizado base, después de que se resuelva valuesMapping

Para la tabla de formas de error de cuatro capas y los prefijos de error por capa, consulta validation-surface.md.

Mecanismos de valores predeterminados

Los valores predeterminados aparecen en el corpus mediante varios mecanismos distintos. Los autores encuentran la palabra «default» en más de cinco contextos; la tabla siguiente es la referencia canónica sobre qué mecanismo produce un valor cuando el autor deja un campo vacío.

#MecanismoDónde se escribeDisparador
1default: de JSON Schema (forma compacta { default: <value> })schema: de Component / Feature, parameters: del AggregateEl campo se valida con el valor predeterminado cuando el desarrollador omite la clave. Para los parámetros del Aggregate, la fusión de parámetros rellena el valor predeterminado declarado antes de que se ejecute la validación del contrato (consulta templates/parameters-context.md).
2Plantilla Go optional .X `Y` <fallback>valuesMapping: de la Recipe, cuerpo del Workload, plantillas de FeatureRecipe, el evaluador de asercionesValor de respaldo sensible a la presencia — devuelve <fallback> solo cuando la clave está ausente del mapa; un cero / vacío / false escrito en la clave devuelve ese valor escrito. La forma canónica, del lado de Aggrega, del respaldo para campos ausentes. Consulta templates/sprig-functions.md.
3Plantilla Go | default <expr>valuesMapping: de la Recipe, cuerpo del Workload, plantillas de FeatureRecipePipeline en línea que se activa ante lo «vacío» (la comprobación de vacuidad de Sprig — cero, cadena vacía, false, nil). Confunde la ausencia en el mapa con la presencia de un valor cero/vacío/false. Adecuada para una semántica de sobrescritura por punto de llamada (el respaldo del binding difiere del valor predeterminado del campo a nivel de esquema) cuando la confusión es aceptable. No es adecuada como respaldo para campos ausentes cuando un cero / vacío / false escrito es una intención legítima — en ese caso usa optional (mecanismo 2).
4Función default de Sprig ({{ default <expr> .field }})Igual que 3Forma de función del mecanismo 3, con la misma confusión de vacuidad.
5Respaldo en locals: de la RecipePlantilla locals: de la RecipeUna entrada de locals calcula una cadena portadora de un valor predeterminado que consume el resto de la Recipe

Recomendaciones de ubicación. Cuando un valor predeterminado forma parte realmente del contrato del tipo (p. ej., «este puerto es 5432 de forma predeterminada salvo que el desarrollador lo sobrescriba»), el default: de JSON Schema (mecanismo 1) es el canónico — el autocompletado del IDE muestra el valor predeterminado; las herramientas de validación lo respetan; el contrato viaja con la entidad de catálogo Component / Feature O con la declaración del parámetro del Aggregate. Cuando una plantilla de Recipe necesita un respaldo para una clave de mapa opcional, el helper optional (mecanismo 2) es la forma canónica del respaldo para campos ausentes — distingue un cero / vacío / false escrito de la ausencia. El | default de la plantilla Go (mecanismo 3) se reserva para el caso de sobrescritura por punto de llamada en el que la confusión entre valores ausentes y falsy es aceptable; recurre a él solo cuando la semántica de sobrescritura sea la intención explícita.

Referencias cruzadas

  • inheritance-and-interface.md — mecanismo extends:, enlace de interfaz implements:, canalización entre pilares mediante puente de esquema.
  • topology-triad.md — mecánica topológica de provides, inject, uses.
  • labels-and-annotations.md — vocabulario de metadatos del lado del contenido, distinto de los pilares de datos (la lista canónica de pilares de arriba no incluye etiquetas / anotaciones / campos de publicación — esos son vocabulario de metadatos).
  • publishing-surface.md — vocabulario de metadatos del lado de la publicación, distinto de los pilares de datos.
  • validation-surface.md — cuatro capas de validación de esquema, incluidos los tres niveles de validación de pilares de arriba.
  • templates/expansion-matrix.md — disponibilidad por sitio de plantilla de las lecturas entre pilares + reglas de autocontención en provides: y source: de la Recipe.
  • examples/04-secrets.md — la lista de comprobación de la entrega de secretos en seis puntos de contacto.
  • architecture/06-data-taxonomy-and-composition.md — encuadre conceptual canónico de las cinco palabras clave estructurales del DSL.