Esquema de la Release de Aggrega
Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.
ID del esquema: https://aggrega.ai/schemas/release-v1beta1.schema.json
Consulta la referencia de autoría de la Release para obtener orientación en prosa sobre cómo escribir entidades Release; esta página documenta el esquema estructural que describe esa referencia.
Tipo de nivel superior: object
Propiedades
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sí | Constante: "aggrega.ai/v1beta1" |
kind | const “Release” | sí | Constante: "Release" |
metadata | object | sí | |
spec | object | sí | Lo que la Release enlaza y enruta: el Aggregate y el Manifest que despliega (o una base extends), el cumplimiento de parámetros específico del entorno y los límites hacia los que se enrutan sus componentes. |
No se permiten propiedades adicionales.
release.metadata
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | Al menos 1 carácter de longitud. |
environment | string | sí | |
version | string | sí | Versionado semántico estricto de la release (p. ej., 1.0.0). Patrón: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | no | Qué es esta entidad y para qué sirve, escrito para quien está decidiendo si usarla. Empieza con una frase que nombre la cosa y luego añade lo que un lector necesita para elegirla y usarla correctamente — qué espera de la plataforma en la que despliega, y cualquier cosa sorprendente sobre su comportamiento. Un párrafo corto es la extensión habitual. |
maintainers | object[] | no | Lista de mantenedores responsables de esta entidad. |
license | string | no | Identificador SPDX de la licencia del software que describe esta entidad, como MIT o AGPL-3.0. Registra las condiciones de ese software, no las de este archivo. |
repository | string | no | La URL del repositorio Git donde se encuentran los archivos fuente. |
home | string | no | La URL de la página de inicio, la wiki o la documentación de esta entidad. |
keywords | string[] | no | Una lista de palabras clave descriptivas para facilitar el descubrimiento en la interfaz de usuario. |
No se permiten propiedades adicionales.
release.metadata.maintainers[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | |
email | string | no | |
url | string | no |
No se permiten propiedades adicionales.
release.spec
Lo que la Release enlaza y enruta: el Aggregate y el Manifest que despliega (o una base extends), el cumplimiento de parámetros específico del entorno y los límites hacia los que se enrutan sus componentes.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
aggregate | string | no | Referencia al Aggregate (intención del desarrollador) que despliega esta release. Un token simple se resuelve por identidad — el metadata.name del Aggregate referenciado, buscado en el directorio propio de la Release y después en el catálogo. Un valor que empieza por ’./’ o ’../’ es un archivo local explícito resuelto de forma relativa a la Release (p. ej., ’../shared/app.yaml’ para compartir un mismo Aggregate entre variantes de la release en un subdirectorio). |
manifest | string | no | Referencia al Manifest que resuelve las interfaces abstractas con respecto a las que despliega esta release. Un token simple se resuelve por identidad — el metadata.name del Manifest referenciado, buscado en el directorio propio de la Release. Un valor que empieza por ’./’ o ’../’ es un archivo local explícito resuelto de forma relativa a la Release. Un Manifest está del lado del despliegue y no se indexa en el catálogo, por lo que solo se resuelve desde el directorio de la Release o desde una ruta explícita. |
extends | string | no | Referencia a una Release base cuya superficie de autoría hereda esta Release — su árbol de límites con la infra por componente y las vinculaciones de Feature que cuelgan de él, sus parámetros, sus anotaciones y su puntero al Manifest. El valor es una ruta a un archivo junto a esta Release, que empieza por ’./’ o ’../’; un nombre simple y una coordenada de registro se rechazan ambos, porque una Release está del lado del despliegue y no se indexa en el catálogo. Lo heredado puede reemplazarse clave por clave, hasta el primer valor indivisible — un escalar, una lista, una plantilla —, que se reemplaza entero; una clave escrita como null elimina lo heredado. Ningún campo de metadatos se transmite, por lo que un hijo lleva su propio nombre, su propia versión y su propio entorno. Declarar ‘aggregate’ junto a ‘extends’ lo rechaza este esquema, por lo que un hijo despliega la misma intención del desarrollador que su base; ‘manifest’ sigue siendo opcional y puede sobrescribirse para cambiar el archivo de bloqueo de dependencias. |
parameters | object | no | Contrato de cumplimiento de variables específico del entorno con dos modos de autoría mediante despacho según la forma del contenido. Modo 1 (inline): un mapa YAML que lleva directamente valores de parámetros anidados y estructurados. Modo 2 (importación de archivo): un mapa YAML de exactamente una clave, $import: ./relative/path.yaml, que apunta a un único archivo local que suministra los valores de los parámetros. Una sola fuente en este punto — la superposición en varios archivos corresponde a las cadenas extends: de Release (la Release padre suministra los parámetros base; el hijo extiende + sobrescribe). |
boundaries | mapa de boundary | no | Las cajas lógicas raíz en las que se enrutan los componentes del Aggregate. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
components | mapa de boundary_component | no | Instancias de componente de nivel superior que llevan la infra por componente del operador, para una Release de un único ámbito sin límites con nombre. Mutuamente excluyente con boundaries: declara components para una Release plana o boundaries para un enrutamiento hacia varios destinos, nunca ambos. Cuando se usa components, el compilador sintetiza un límite default que los contiene y emite sus artefactos en dist/ de forma plana. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
No se permiten propiedades adicionales.
Definiciones
boundary_component
Una instancia de componente enrutada a un límite, con dimensionamiento físico y vinculaciones de funcionalidades opcionales.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
description | string | no | Documentación opcional que describe el rol de este componente en este límite de la Release. |
subDirectory | string | no | Sobrescritura de la subruta a nivel de Component, añadida al directorio del límite padre. Si se omite o está vacía tanto en el límite como en el componente, toma por defecto ’{{ .capability }}’; una cadena vacía escrita aquí se lee como omitida. Establécela en ’.’, o en una plantilla que se evalúe como una cadena vacía, para desactivar la generación de subdirectorios. |
annotations | mapa de string u object o null | no | Anotaciones del Operador específicas del Component que sobrescriben, para este componente, las anotaciones a nivel de límite. Se combinan en profundidad sobre las anotaciones del límite (el componente prevalece en caso de colisión de claves; los valores estructurados se combinan por subclave con padres estructurados). Los valores son cadenas, objetos estructurados o null. Se usan para sobrescrituras por componente de las anotaciones bien conocidas del proveedor (p. ej., aggrega.ai/namespace en el proveedor helm). Un null explícito en una clave heredada del límite padre elimina de este componente el enlace heredado (renuncia a una Feature guiada por anotaciones); los componentes hermanos conservan el enlace heredado. |
infra | object | no | Dimensionamiento físico estrictamente local a este componente (p. ej., réplicas, IOPS de disco). |
features | mapa de object | no | Las Features vinculadas a este componente a través de la Release. Para las funcionalidades declaradas también en el Aggregate, solo se proporciona infra (los values provienen del Aggregate). Para las funcionalidades exclusivas de la Release (inyectadas por el Operador), type es obligatorio. Las claves son nombres de instancia de funcionalidad y pueden llevar el URI completo del tipo de funcionalidad (se permiten puntos y barras). La Release NO DEBE proporcionar values para las funcionalidades — este es el dominio del Desarrollador. Claves: una o más letras, dígitos, guiones bajos, puntos, barras o guiones. Patrón: ^[a-zA-Z0-9_./-]+$. |
uses | release_uses_block | no | Superficie de aristas del Operador. Dentro de los sockets declarados por el Arquitecto, la Release puede cablear un socket declarado pero no enlazado a un componente existente (target) y/o suministrar infra por arista. Sin values (rige la prohibición de values: de la Release) y sin creación de cómputo; redirigir una arista declarada por el desarrollador detiene la compilación. |
No se permiten propiedades adicionales.
release_uses_block
Superficie uses por arista escrita en la Release, indexada por socket y luego por alias (refleja la forma de la topología uses del Aggregate). Cada conexión puede establecer target (para crear una arista hacia un socket declarado pero no enlazado, que apunta a un componente existente), infra (configuración del operador por arista, validada frente al infraSchema del socket cuando se resuelve la Release) y features (vinculaciones que llenan las ranuras que declara el socket), en cualquier combinación. values está prohibido (la prohibición de values: de la Release); redirigir una arista declarada por el desarrollador es una salvaguarda bien visible en la compilación.
Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$.
Los valores son map of object.
No se permite ninguna otra clave.
release_connection_attachment
Una vinculación que lleva una entrada de conexión de una Release: la Feature que llena una ranura que declara el socket de la conexión, con el dimensionamiento del operador para ella.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
type | string | no | El URI de la Feature. Obligatorio para una vinculación que solo realiza la Release. Debe coincidir con el type del Aggregate si ambos lo declaran. |
description | string | no | Documentación opcional que explica por qué el Operador vinculó esta funcionalidad a la conexión. |
infra | object | no | Dimensionamiento operativo para esta vinculación, validado por la declaración de esquema de la Feature. |
No se permiten propiedades adicionales.
aggregate_routing
Enruta a este límite los componentes internos de un submódulo Aggregate anidado. Refleja la estructura component/aggregate del límite para la composición recursiva.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
components | mapa de boundary_component | no | Instancias de Component dentro del agregado anidado que se enrutan a este límite. Las claves son el nombre local que cada componente lleva dentro de ese submódulo — ‘main-db’ para el componente al que el mapa components propio de un límite se dirige como ‘data.main-db’ — porque es el único nombre que tiene allí. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
aggregates | mapa de aggregate_routing | no | Más agregados anidados dentro de este subagregado (para la composición de módulos profundamente anidados). Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
No se permiten propiedades adicionales.
boundary
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
description | string | no | Documentación opcional que describe el propósito y el destino físico de este límite (p. ej., ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’). |
directory | string | no | Ruta de salida física para la generación de artefactos de GitOps. Admite variables de plantilla Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Se combina con subDirectory mediante una unión de rutas para producir la ruta final del artefacto. |
subDirectory | string | no | Subruta a nivel de límite añadida a directory. Si se omite o está vacía tanto en el límite como en el componente, toma por defecto ’{{ .capability }}’ para la partición automática de CI/CD; una cadena vacía escrita aquí se lee como omitida. Establécela en ’.’, o en una plantilla que se evalúe como una cadena vacía, para desactivarla. |
syncWave | integer | no | Oleada de despliegue opcional por límite (entero con signo, 0 por defecto). Cada componente de este límite hereda en su nodo la oleada del límite. Se permiten valores negativos (se ejecutan antes que todo lo demás); los valores mayores se ejecutan después de los menores. En K8s y Helm la oleada es lo que ordena el despliegue: se convierte en una anotación argocd.argoproj.io/sync-wave, y en un recurso que el chart ya marca como hook de Helm se convierte además en el helm.sh/hook-weight de ese hook. En compose la oleada se registra como etiqueta del servicio y además ordena los servicios del archivo en el que se renderiza, mediante depends_on entre ellos — así que llega a cada servicio de ese único archivo y a nada fuera de él. En cloudformation la oleada ordena el aprovisionamiento del stack en el que se ensambla el límite: cada recurso de una oleada se declara dependiente de los recursos de la oleada anterior, lo que fija el orden en que se crean y, a la inversa, el orden en que se eliminan. Es solo orden de creación y de eliminación — una plantilla de stack no expresa ninguna noción de que un recurso esté listo, así que nada espera a que uno quede operativo. En terraform la oleada ordena los bloques module de la configuración raíz en la que se ensambla el límite: cada módulo de una oleada se declara dependiente de los módulos de la oleada anterior, lo que fija el orden en que el motor realiza sus acciones. Es solo orden de acciones — una configuración no expresa ninguna noción de que un recurso esté listo, así que nada espera a que uno quede operativo — y el valor también se registra con la procedencia de compilación del nodo. El compilador lleva el mismo valor a cada nodo del límite como el sync_wave de ese nodo, donde el comportamiento por destino se describe de nuevo desde el lado del nodo. Los límites anidados no heredan implícitamente — cada uno declara su propia oleada. |
annotations | mapa de string u object o null | no | Anotaciones del Operador para todo el límite, que se propagan en cascada hasta el contenedor .context.annotations.release. Los valores son cadenas, objetos estructurados o null. Un valor estructurado lleva una configuración por subclave que se combina en profundidad con los padres estructurados (por subclave, prevalece el hijo) y fluye por la expansión de Feature guiada por anotaciones; solo los valores escalares aparecen en el contexto de renderizado. Un null explícito en una clave heredada de un límite padre elimina el enlace heredado del conjunto efectivo de anotaciones de este límite (renuncia a una Feature guiada por anotaciones), lo que se propaga a cada componente enrutado a este límite salvo que una sobrescritura más profunda vuelva a introducir el enlace. |
features | mapa de object | no | Funcionalidades para todo el límite aplicadas a todos los componentes anidados (p. ej., una malla de seguridad predeterminada). El bloque uses de una funcionalidad se proyecta sobre cada componente del límite, declarando una dependencia compartida una sola vez en el límite en lugar de repetirla en cada componente. Las claves son nombres de instancia de funcionalidad y pueden llevar el URI completo del tipo de funcionalidad (se permiten puntos y barras). Claves: una o más letras, dígitos, guiones bajos, puntos, barras o guiones. Patrón: ^[a-zA-Z0-9_./-]+$. |
boundaries | mapa de boundary | no | Límites lógicos anidados (p. ej., namespaces dentro de un clúster). Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
components | mapa de boundary_component | no | Qué componentes del Aggregate se colocan en este límite. Las claves son nombres de instancia de componente; el componente de un subagregado se direcciona por su ruta calificada con puntos (p. ej., ‘data.main-db’ — el nombre de la instancia de agregado, un punto, el nombre del componente). Claves: una o más letras, dígitos, guiones bajos, puntos o guiones. Patrón: ^[a-zA-Z0-9_.-]+$. |
aggregates | mapa de aggregate_routing | no | Enruta a este límite los componentes de los submódulos Aggregate anidados. Las claves son nombres de instancia de agregado que coinciden con el mapa spec.aggregates del Aggregate. Todas las instancias de agregado deben colocarse en exactamente un límite si hay límites definidos. Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$. |
No se permiten propiedades adicionales.
uses_block
La topología estructural - propiedad del Desarrollador. Declara aristas de red lógicas y dependencias.
Claves: una o más letras, dígitos, guiones bajos o guiones. No se permite un punto. Patrón: ^[a-zA-Z0-9_-]+$.
Los valores son string[] or map of object.
No se permite ninguna otra clave.
inject_block
Enrutamiento agnóstico de la inyección en una conexión. Asigna variables locales a las claves provides del destino. Cada mecanismo de entrega (env, file, arg o personalizado) se escribe como un array de entradas {in, from} — ‘from’ explícito para referencias a provides. Un mecanismo personalizado puede tener cualquier nombre excepto all: una plantilla lee todos los mecanismos fusionados en una sola vista en .context.inject.all, por lo que un mecanismo con ese nombre quedaría oculto por ella, y nombrar uno detiene el build.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
env | inject_delivery | no | Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’. En una Release cada entrada está en una conexión, por lo que ‘from’ se resuelve frente a los provides del destino y una entrada que lleva ‘value’ se rechaza. |
file | inject_delivery | no | Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’. En una Release cada entrada está en una conexión, por lo que ‘from’ se resuelve frente a los provides del destino y una entrada que lleva ‘value’ se rechaza. |
arg | inject_delivery | no | Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’. En una Release cada entrada está en una conexión, por lo que ‘from’ se resuelve frente a los provides del destino y una entrada que lleva ‘value’ se rechaza. |
inject_delivery
Un único mecanismo de entrega, escrito como un array de entradas. Cada entrada lleva un ‘in’ (identificador local — nombre de variable de entorno, ruta de archivo, flag de argumento o clave personalizada específica del mecanismo) más exactamente uno de ‘from’ (una clave provides que resolver) o ‘value’. En una Release cada entrada está en una conexión, por lo que ‘from’ se resuelve frente a los provides del destino y una entrada que lleva ‘value’ se rechaza.
Tipo: object[]