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

El bloque `assertions:`

Component, Feature, Recipe y FeatureRecipe llevan un campo opcional spec.assertions: — un mapa de reglas con nombre que el compilador evalúa después de la validación del esquema pero antes del renderizado. Cada clave es un identificador de regla que aparece en el mensaje de fallo; cada valor es un cuerpo de plantilla Go. Un único cuerpo de plantilla escrito directamente bajo assertions: no tiene la forma del campo y se rechaza cuando se lee la entidad, por lo que cada regla se escribe bajo un nombre propio. El bloque expresa reglas entre campos que JSON Schema no puede capturar de forma compacta: invariantes que implican varios campos donde ningún campo individual es «el que se valida». Esta página cubre la gramática de autoría, la fase de evaluación, el contexto de la plantilla y el reparto de responsabilidades entre las aserciones de Component / Feature (invariantes arquitectónicos del contrato) y las aserciones de Recipe / FeatureRecipe (invariantes de implementación del proveedor concreto).

Para restricciones por campo (rango, patrón, enum, formato), usa las palabras clave nativas de JSON Schema dentro de schema:. Para predicados personalizados por campo, usa el campo validate: de la forma compacta. Para una forma condicional, usa when:. El campo assertions: los complementa — es el lugar de las verdaderas reglas entre campos.

Dónde aparece el campo

Las cuatro entidades que pueden llevar assertions::

  • Component — invariantes arquitectónicos del contrato del Component.
  • Feature — invariantes arquitectónicos del contrato de la Feature.
  • Recipe — invariantes de implementación del chart o módulo subyacente de la Recipe.
  • FeatureRecipe — invariantes de implementación del mecanismo subyacente de la FeatureRecipe.

El campo es opcional en cada una. Las entidades sin reglas entre campos omiten el campo por completo.

Cuándo se ejecutan las aserciones

Las fases de evaluación de aserciones se sitúan entre la validación del esquema y el renderizado en el pipeline de compilación:

  1. Resolución: validación e interpolación de parámetros, luego validación del esquema frente a schema: / usesSchema: / featuresSchema:.
  2. Construcción de la topología y finalización del grafo: se ensambla el grafo.
  3. Análisis estático: el selector de cada socket uses: se comprueba frente a las etiquetas de los componentes a los que llegan sus conexiones.
  4. Aserciones de Component / Feature evaluadas frente a cada instancia.
  5. Enlace de la Recipe.
  6. Aserciones de Recipe / FeatureRecipe evaluadas frente a la instancia enlazada.
  7. Renderizado: plantillas de mapeo evaluadas, salida producida.

Las dos fases de aserción se ejecutan antes de cualquier renderizado — ningún chart renderizado, ningún archivo Compose generado. Lo único que se pregunta a un proveedor antes de que se ejecuten las aserciones de la Recipe es el nombre que da a los recursos de cada nodo enlazado, que el provides de una Recipe puede leer. Una aserción fallida detiene el build de inmediato con el mensaje de error específico de la aserción; los pasos posteriores no se ejecutan.

La separación entre las dos fases refleja el reparto de responsabilidades: las reglas a nivel de Component se aplican con independencia de qué Recipe se enlace, por lo que se activan antes del enlace; las reglas a nivel de Recipe se aplican dada una elección concreta de Recipe, por lo que se activan después del enlace.

El contexto de plantilla

Para las assertions: de Component y Feature, el contexto de plantilla expone el estado resuelto de la instancia:

  • .values — el contenido values del desarrollador.
  • .infra — el contenido infra de Ops (del Aggregate o de la Release).
  • .uses — las conexiones uses: resueltas, cada una ya comprobada frente al selector de su socket, en la forma en que el autor las escribe: indexadas por nombre de socket y, bajo cada socket, por el alias de cada conexión en él — el nombre que el autor dio a la conexión bajo el socket o, para una conexión escrita como entrada de una lista, su destino. La entrada de cada conexión describe la conexión y no lleva nada de lo que su destino publicó. target es el id de instancia del destino resuelto, alias repite el nombre por el que está indexada, y origin_feature está presente cuando la conexión la trazó una vinculación de Feature. Junto a ellos hay tres datos, con los nombres con los que una plantilla de Recipe los lee en la entrada .context.uses.<alias> de la misma conexión, donde template-context-contract.md describe lo que contiene cada uno: labels — las etiquetas del destino, nunca las etiquetas del componente sobre el que se ejecuta la aserción — values, los valores escritos en la conexión, y features, las vinculaciones escritas en la conexión, indexadas por el slot que ocupa cada una. Cada uno de los tres está presente en cada conexión, vacío donde la conexión no lleva ninguno, y una vinculación bajo features tiene la forma que .features da a una vinculación más abajo. Así, .uses.<socket>.<alias>.target lee el destino resuelto de una conexión, .uses.<socket>.<alias>.labels las etiquetas de ese destino, un socket que contiene varias conexiones contiene una entrada para cada una, y una referencia que atraviesa este mapa en busca de un valor publicado por el destino detiene el build, porque la entrada no lleva tal campo.
  • .features — las vinculaciones resueltas, indexadas por el nombre de instancia que el autor dio a cada una. Cada entrada lleva type (el URI de catálogo de la Feature vinculada), resolved_version (la versión enlazada para este build) y values (el contenido de intención del desarrollador propio de la vinculación). Una vinculación escrita en una de las conexiones del componente no está entre ellas, exactamente igual que no está entre las .features de una plantilla de Recipe: se lee bajo su conexión, en .uses.<socket>.<alias>.features.<slot>, con esta misma forma.
  • .metadata — la instancia que se evalúa: su instance_id, su tipo component y su resolved_version, su boundary_path, y aggregate_name, aggregate_version y release_version del build.

Para las assertions: de Recipe y FeatureRecipe, el contexto añade campos específicos de la Recipe:

  • .provides — los valores provides: resueltos del componente que se evalúa, ya calculados en el momento en que se ejecuta la aserción. Los valores publicados de un destino no están en esta superficie; llegan en cambio a un llamador en el contexto de renderizado.
  • .locals — los locals de la Recipe.
  • .recipe.metadata — el name y la version de la Recipe, y su capability.
  • .recipe.source — el puntero de origen de la Recipe.

El acceso a los campos usa la sintaxis estándar de las plantillas Go (.values.architecture, .uses.databases.primary.target); la construcción que detiene el build es {{ fail "message" }} según el contrato Loud Guardrails — una aserción fallida produce un error claro y específico en tiempo de build que nombra el invariante violado.

Esta superficie evalúa con missingkey=error. Una referencia a una clave que el contexto no lleva detiene el build — nombrando la entidad, la instancia, la aserción y la clave ausente — en lugar de renderizarse como nada. Ese rigor es lo que hace fiable una aserción: un predicado cuya referencia se renderizara vacía compararía con nada y pasaría, de modo que un solo error tipográfico retiraría silenciosamente la regla que la aserción se escribió para hacer cumplir. También significa que la referencia desnuda se resuelve antes de que pueda ejecutarse cualquier valor de respaldo, por lo que un campo opcional necesita una forma que tenga en cuenta la presencia; errors/fatal-halts.md recoge la política de claves ausentes de cada superficie y las formas que funcionan con ella.

Leer las conexiones de un socket. La entrada de un socket tiene una sola forma, contenga lo que contenga: una entrada por conexión, bajo su alias. Una aserción lee una conexión por su alias, cuenta o recorre el socket para ver cada conexión en él, y comprueba la clave propia del socket para preguntar si está cableado en absoluto. Dado un componente cuya entrada del Aggregate escribe

uses:
models:
local: { target: llama }
fast: { target: turbo }

estas aserciones la leen de cada manera:

assertions:
# The socket's presence: the socket key alone, however many connections it holds.
models-wired: |
{{- if not (hasKey .uses "models") -}}
{{- fail "wire at least one model to the models socket" -}}
{{- end -}}
# Every connection on the socket: a range visits each one.
every-model-distinct: |
{{- $seen := list -}}
{{- range $alias, $connection := (optional .uses "models" dict) -}}
{{- if has $connection.target $seen -}}
{{- fail (printf "connection %s points at %s, which another models connection already points at" $alias $connection.target) -}}
{{- end -}}
{{- $seen = append $seen $connection.target -}}
{{- end -}}
# One connection, by the alias it was written under; guarded, because the
# connection is optional.
fast-is-not-local: |
{{- with (optional .uses "models" dict) -}}
{{- if and (hasKey . "fast") (hasKey . "local") (eq .fast.target .local.target) -}}
{{- fail (printf "the fast and local connections both point at %s" .local.target) -}}
{{- end -}}
{{- end -}}

Un bucle range recorre las conexiones de un socket en orden alfabético de sus alias — aquí fast antes que local —, no en el orden en que el Aggregate las escribió. Un socket que contiene una sola conexión se lee del mismo modo: .uses.models.local.target lee llama esté o no cableado fast a su lado, y .uses.models.target no direcciona ninguna conexión y detiene el build.

Cada conexión que tiene un componente tiene aquí su propia entrada, porque no hay dos conexiones de un mismo componente que compartan un alias — en un socket o en dos, sea cual sea el documento o la vinculación que trazó cada una. El build rechaza un par así, nombrando ambas conexiones y dónde se escribió cada una, antes de que se ejecute ninguna aserción. Una lista que nombra dos veces un mismo destino es un par así, ya que el alias de una entrada de lista es su destino; también lo es la conexión local propia de un componente junto a la conexión local de una vinculación en el mismo componente.

Leer lo que lleva una conexión. Una regla sobre una conexión puede leer qué es su destino, qué escribió el desarrollador en la conexión y qué está vinculado a ella, de modo que se cumple sea cual sea la Recipe que se enlace. Un Component cuyo socket models declara un valor unauthenticated y un slot credential puede rechazar una conexión a un destino que su catálogo etiqueta como servicio alojado cuando esa conexión no lleva ni una credencial ni el opt-out:

assertions:
hosted-model-needs-a-credential: |
{{- range $alias, $connection := (optional .uses "models" dict) -}}
{{- $hosted := eq (optional $connection.labels "component.aggrega.ai/hosting" "") "managed" -}}
{{- $optedOut := optional $connection.values "unauthenticated" false -}}
{{- if and $hosted (not (hasKey $connection.features "credential")) (not $optedOut) -}}
{{- fail (printf "the models connection %s reaches a hosted model with no credential: attach one under credential, or set unauthenticated: true on the connection" $alias) -}}
{{- end -}}
{{- end -}}

La etiqueta se lee de labels, que son las del destino — el modelo — y nunca las del propio componente; el opt-out se lee de los values de la conexión; y la credencial es un slot bajo las features de la conexión. Cada uno se lee con optional o hasKey, porque un destino puede no llevar tal etiqueta y una conexión tal valor. Lo que significa la etiqueta es la convención del catálogo: el build lleva la cadena y la aserción decide lo que significa.

El .uses de una aserción no es el .context.uses de una plantilla de Recipe, y una referencia escrita para uno no se transfiere al otro. El contexto de renderizado lleva una proyección más rica de las mismas aristas: indexada solo por alias, con el nombre del socket como campo de la entrada, y con los valores publicados de cada destino anidados bajo provides — de modo que una plantilla de Recipe lee .context.uses.<alias>.provides.<name> donde una aserción lee .uses.<socket>.<alias>.target. Los datos que llevan ambas vistas comparten sus nombres pero no sus rutas: .context.uses.<alias>.labels y .uses.<socket>.<alias>.labels son las etiquetas del mismo destino, y values y features leen igualmente la misma conexión en una u otra. Ambas fases de aserción evalúan antes del renderizado, por eso la vista que una aserción tiene de una arista no lleva nada de lo que su destino publicó, y por eso una vinculación sobre ella no lleva ningún provides.

Para la forma más amplia del contexto de plantilla y la semántica de disponibilidad por campo, consulta template-context-contract.md.

Números en esta superficie

Una aserción lee un número escrito por el autor exactamente como lo hace una plantilla de valor — consulta Números en una plantilla de valor:

  • Comparaciones. Las seis comparaciones leen dos números por su valor, sea cual sea el tipo que lleve cada uno: lt .values.replicas 1.5 y eq .values.replicas 3.0 responden aquí como en una plantilla de valor, un 0.1 escrito por el autor es eq a un 0.1 escrito en la aserción, y comparar un número con texto entre comillas detiene el build con las mismas palabras.
  • Vacío. Un 0 escrito por el autor está vacío: falso para if y with, verdadero para empty, y reemplazado por default. Una regla que pregunta si el autor escribió un valor — un 0 incluido — lo pregunta con los helpers de presencia: para un 0 escrito por el autor, hasKey .values "replicas" es verdadero y optional .values "replicas" 1 devuelve 0. Una regla que pregunta si el valor es cero compara: eq .values.replicas 0. Presencia y vacío pone las dos preguntas una al lado de la otra.
  • Impresión. Un número que imprime un mensaje fail se lee como se leería en la salida de una plantilla de valor: un número entero como entero, de modo que printf "%d" imprime sus dígitos, y cualquier otro número en su forma decimal exacta más corta, de modo que un 0.0000001 escrito por el autor se lee 0.0000001.

Aserciones de Component / Feature — invariantes arquitectónicos

Estas expresan reglas que se cumplen sea cual sea la Recipe que enlace el Component. La regla es una propiedad del contrato, no de la implementación.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/datastore/mariadb
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
component.aggrega.ai/category: datastore
spec:
schema:
values:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
secondary:
replicaCount: { type: integer, min: 0, max: 9, default: 0 }
assertions:
# Replication mode requires at least 2 secondary replicas.
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt .values.secondary.replicaCount 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}
# Total node count limit for safe replication coordination.
total-node-count-within-cap: |
{{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}}
{{- if gt $total 9 -}}
{{- fail (printf "total node count must not exceed 9; got %d" $total) -}}
{{- end -}}

Ambas reglas expresan propiedades del contrato de MariaDB. Sea cual sea la Recipe que se enlace — un chart de Bitnami, una alternativa hecha a mano — las reglas se aplican.

El control de espacios en blanco {{- ... -}} importa: las plantillas de aserciones no producen salida, solo efectos secundarios mediante {{ fail }}. El recorte de espacios mantiene vacío el cuerpo de la plantilla renderizada en caso de éxito.

Aserciones de Recipe / FeatureRecipe — invariantes de implementación

Estas expresan reglas que se cumplen para el chart o módulo concreto del que la Recipe obtiene su origen. La regla es una propiedad de la implementación, no del contrato.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: bitnami/datastore/mariadb/k8s
version: 1.0.0
spec:
capability: helm
implements: core/datastore/mariadb:^1.0.0
source:
# Keys this provider defines for itself; a source the build fetches is written as { kind, url, version } instead.
chart: oci://registry-1.docker.io/bitnamicharts/mariadb
version: "20.0.0"
valuesMapping:
$import: BitnamiHelpers#/mappings/MariaDBBitnamiCore
assertions:
# Bitnami chart 20.x requires an explicit ServiceMonitor namespace when
# replication and metrics scraping are both enabled.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}
# ARM-node incompatibility.
arm-rejects-hard-anti-affinity: |
{{- if and (eq .values.primary.podAntiAffinityPreset "hard") (eq .infra.cpu_arch "arm64") -}}
{{- fail "Bitnami MariaDB 20.x is incompatible with ARM nodes when podAntiAffinityPreset=hard; use 'soft' or omit" -}}
{{- end -}}

Cada regla es específica de la implementación del chart de Bitnami 20.x. Si se enlaza una Recipe de MariaDB distinta — un chart hecho a mano, una implementación alternativa — estas reglas no se aplican. Las reglas a nivel de Component (replication-needs-two-secondaries, total-node-count-within-cap) siguen aplicándose porque son propiedades del contrato.

Por qué las aserciones de Component y de Recipe están separadas

Los dos roles parecen similares (ambos ejecutan detenciones {{ fail }} sobre reglas entre campos), pero el reparto de responsabilidades es fundamental:

  • Las aserciones de Component forman parte del contrato. Cuando el desarrollador escribe architecture: replication con secondary.replicaCount: 1, el build lo rechaza sea cual sea la Recipe que se enlace. Una futura Recipe alternativa no cambia eso.
  • Las aserciones de Recipe forman parte de la implementación. Cuando el arquitecto elige el chart de Bitnami 20.x como Recipe, el chart tiene peculiaridades específicas (el requisito de serviceMonitor.namespace, el error de los nodos ARM). Estas no se aplican a un chart distinto.

Ubicar ambos tipos de regla en el Component entrelazaría el contrato con sus implementaciones: el Component tendría que hacer referencia a su Recipe enlazada para saber qué reglas de implementación hacer cumplir, rompiendo la separación Component-Recipe. Repartir las reglas en su ubicación natural mantiene limpio el modelo de responsabilidades. El coste en tiempo de ejecución de la separación es insignificante; ambas fases se ejecutan antes del renderizado y se detienen con el mismo diagnóstico Loud Guardrails, E0033, que nombra la entidad, la instancia y la regla.

La convención de los mensajes fail

El argumento de {{ fail "..." }} es el error en tiempo de build que ve el usuario. Convenciones:

  • Nombra la restricción — «architecture=replication requires secondary.replicaCount >= 2» (architecture=replication requiere secondary.replicaCount >= 2).
  • Nombra el valor cuando sea pertinente — «total node count must not exceed 9; got 12» (el número total de nodos no debe superar 9; se obtuvo 12).
  • Sugiere la corrección cuando sea posible — «use ‘soft’ or omit the field» (usa ‘soft’ u omite el campo).
  • Evita la jerga — quien lee es el desarrollador que escribió el Aggregate, no el arquitecto que escribió la aserción.

Para mensajes largos o que contienen valores, usa printf:

{{- fail (printf "field %s exceeds limit: got %d, max is %d" .field .value .max) -}}

El compilador presenta el mensaje en el formato de error Loud Guardrails con el nombre de la entidad, la ubicación de la aserción en el código fuente y el mensaje que falla. El diagnóstico es lo bastante específico para que el desarrollador identifique y corrija la causa raíz.

Un valor que un autor declaró sensitive: true se lee <redacted> en ese mensaje dondequiera que el mensaje lo cite, de modo que nombrar en el mensaje el valor de un campo declarado es seguro: el diagnóstico sigue nombrando la regla y el campo, y solo se retiene el valor. Una aserción cuyo resultado depende de lo que contiene un valor así — una comparación con un literal, una prueba de prefijo — informa de que su texto de fallo se retiene en lugar de su mensaje. vocabulary/compact-form-authoring.md «Qué dice un rechazo sobre un valor declarado» contiene la regla completa.

Qué no reemplaza assertions:

assertions: es el lugar de las reglas entre campos. No reemplaza:

  • Las restricciones de JSON Schema dentro de schema: — las reglas por campo (rango, patrón, enum, formato, tipo) pertenecen a las palabras clave nativas de JSON Schema.
  • El campo validate: de la forma compacta — predicados personalizados por campo con alcance de un solo campo. Usa validate: cuando la regla se aplica a un campo concreto; usa assertions: cuando la regla implica varios campos y ningún campo individual es «el que se valida».
  • El campo when: de la forma compacta — forma condicional (si se aplican las restricciones de un subárbol). Usa when: para variaciones de forma; usa assertions: cuando la combinación de valores no es válida de un modo que se expresa mejor como un predicado de forma libre.
  • Comprobaciones en tiempo de ejecución — assertions: se ejecuta solo en tiempo de compilación. Todo lo que dependa del estado del clúster en tiempo de ejecución (IP activas, contenido del vault, estado de los pods en tiempo de ejecución) debe expresarse como cadenas de puntero deterministas (consulta el contrato de pureza AOT).

Ejemplos prácticos

Mínimo — una sola regla arquitectónica

spec:
assertions:
replication-needs-two-secondaries: |
{{- if and (eq .values.architecture "replication") (lt .values.secondary.replicaCount 2) -}}
{{- fail "replication requires secondary.replicaCount >= 2" -}}
{{- end -}}

Tamaño medio — contrato de Component con varias reglas

spec:
assertions:
# Replication minimum.
replication-needs-two-secondaries: |
{{- if eq .values.architecture "replication" -}}
{{- if lt .values.secondary.replicaCount 2 -}}
{{- fail "architecture=replication requires secondary.replicaCount >= 2" -}}
{{- end -}}
{{- end -}}
# Total node limit.
total-node-count-within-cap: |
{{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}}
{{- if gt $total 9 -}}
{{- fail (printf "total node count exceeds 9: got %d (primary=%d, secondary=%d)"
$total .values.primary.replicaCount .values.secondary.replicaCount) -}}
{{- end -}}
# A ServiceMonitor scrapes the metrics exporter, so it needs one.
service-monitor-needs-metrics: |
{{- if and .values.metrics.serviceMonitor.enabled (not .values.metrics.enabled) -}}
{{- fail "metrics.serviceMonitor.enabled=true requires metrics.enabled=true" -}}
{{- end -}}

Producción — Recipe con reglas de implementación

spec:
assertions:
# Bitnami 20.x: serviceMonitor namespace requirement.
service-monitor-namespace-required: |
{{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}}
{{- if not .values.metrics.serviceMonitor.namespace -}}
{{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}}
{{- end -}}
{{- end -}}
# TLS certificate consistency.
tls-needs-both-certificate-files: |
{{- if .values.tls.enabled -}}
{{- if not (and .values.tls.certFilename .values.tls.certKeyFilename) -}}
{{- fail "tls.enabled=true requires both tls.certFilename and tls.certKeyFilename" -}}
{{- end -}}
{{- end -}}
# Replication-mode storage class consistency.
replication-needs-one-storage-class: |
{{- if eq .values.architecture "replication" -}}
{{- $primaryClass := .values.primary.persistence.storageClass -}}
{{- $secondaryClass := .values.secondary.persistence.storageClass -}}
{{- if and $primaryClass $secondaryClass (ne $primaryClass $secondaryClass) -}}
{{- fail "replication mode requires primary and secondary to use the same storageClass" -}}
{{- end -}}
{{- end -}}

Integración con herramientas

  • aggrega build evalúa las aserciones entre la validación del esquema y el renderizado; una aserción fallida detiene el build con el mensaje {{ fail }} de la aserción.
  • aggrega validate aplica la misma corrección antes del renderizado sin escribir artefactos — para una Recipe cuyo origen no se obtiene, ejecuta el pipeline de compilación real en torno a un Aggregate, un Manifest y una Release mínimos sintetizados, de modo que una plantilla de aserción mal formada o una aserción que hace referencia a un campo desconocido aflora como un error de corrección; las aserciones de una Recipe cuyo origen se obtiene las evalúa un build. Una aserción que allí llama a fail se informa como una advertencia que lleva su mensaje, y la comprobación pasa: la Release sintetizada contiene marcadores de posición y valores predeterminados en lugar de los valores que establece una Release real, de modo que el veredicto sobre la aserción se deja a un build — consulta una aserción fallida es una advertencia. (aggrega lint cubre las convenciones de publicación, no la corrección de las aserciones.)
  • Los IDE con soporte para plantillas Sprig resaltan las referencias .values.X; la documentación al pasar el puntero remite a la definición del esquema cuando la integración con el IDE está configurada.