Release
El papel conceptual de la entidad Release (Dominio 4 — el enrutador de despliegue que enlaza un Aggregate con un Manifest y asigna los componentes a límites físicos) se encuentra en architecture/04-entity-taxonomy.md. El mecanismo de secuenciación temporal (syncWave por límite), el Dynamic Addressing Polyfill y el patrón Parameter Hoisting se encuentran en architecture/12-day-two-lifecycles.md. Esta página cubre la superficie de autoría de la Release.
El papel de la Release
La Release enlaza un aggregate con un manifest y asigna los componentes a límites físicos de despliegue (p. ej., aws-eks-production). Es el único punto de entrada para la compilación: aggrega build --release release.yaml.
La Release cumple el contrato abstracto del agregado inyectando las realidades físicas estrictamente en el bloque parameters, e inyecta el dimensionamiento físico (como CPU o puertos) mediante el espacio de nombres paralelo infra.
Toda Release declara un campo manifest: que nombra su Manifest (salvo que la Release use extends:, que hereda el puntero al manifiesto del padre). La CLI aggrega build lee este campo directamente; no existe ningún flag de CLI --manifest, de modo que la especificación de dependencias permanece confirmada en Git junto a la propia Release, lo que hace auditable el historial de despliegues a través del propio historial de Git de la Release.
Los campos aggregate: y manifest: se resuelven por identidad o por archivo con ruta relativa, del mismo modo en que el resto del lenguaje resuelve las referencias — nunca como una raíz de nombre de archivo relativa a la Release. Un valor ./ o ../ es un archivo local explícito, leído directamente en relación con la Release. Un token sin más es una identidad — el metadata.name de la entidad referenciada. Una identidad manifest: se resuelve examinando el directorio propio de la Release (un Manifest es configuración de operador del lado del despliegue, por lo que no tiene nivel de catálogo ni de registro). Una identidad aggregate: se resuelve a través de la cascada completa — el directorio de la Release, luego el catálogo, luego el registro —, de modo que una Release puede nombrar un Aggregate publicado por identidad y el mismo módulo publicado se resuelve tanto si es el spec.aggregate de nivel superior de una Release como si es un subagregado dentro de otro Aggregate. Este modelo de identidad o ruta permite que un Aggregate compartido respalde muchas variantes de Release sin acoplar la referencia a un nombre de archivo, y que un Aggregate publicado se despliegue directamente por nombre.
Una ruta permanece dentro del espacio de trabajo. Un valor ./ o ../ nombra un archivo que contiene el espacio de trabajo, y lo mismo ocurre con cualquier otra ruta que escriba una Release — su extends: y un $import: de parámetros, más abajo. Una ruta que sale del espacio de trabajo tal como está escrita, o que un enlace simbólico en el camino saca de él, se rechaza antes de que se lea nada del archivo que nombra. Para desplegar un Aggregate que se guarda fuera del espacio de trabajo, nómbralo por identidad e indica el directorio que lo contiene como directorio de catálogo en la configuración del espacio de trabajo; un Manifest, una Release que nombra un extends: y un archivo de parámetros se leen junto a la Release y nunca se buscan por nombre, así que se guardan dentro del espacio de trabajo. Una Release que nombras en la línea de comandos, o que nombra la configuración del espacio de trabajo, fuera del espacio de trabajo es una raíz propia: cada ruta que escribe — y cada ruta que escribe una Release a la que lleva su cadena extends: — debe llevar a un archivo dentro del directorio que contiene esa Release, y una ruta que sale de ese directorio, o que un enlace saca de él, se rechaza de la misma manera. Guarda lo que nombra una Release así junto a ella, o compílala en el espacio de trabajo que contiene a ambas. Consulta errors/fatal-halts.md §«A reference to another file leads out of the directory it must stay inside (Una referencia a otro archivo sale del directorio dentro del cual debe permanecer)».
La Release dicta el destino de los artefactos compilados; el despacho a los proveedores corresponde al Manifest al que apunta la Release (consulta Manifest frente a Release: separación de responsabilidades para el reparto de roles).
Metadatos de entorno
Todo bloque de metadatos de una Release acepta un campo environment: — una cadena libre que identifica el entorno en el que se despliega la Release (valores típicos: production, staging, dev). El campo es informativo: no lleva ninguna enumeración, ningún patrón a nivel de esquema ni ninguna validación entre entidades más allá de type: string. El compilador emite su valor como la etiqueta aggrega.ai/environment en cada manifiesto de Kubernetes que renderiza el proveedor helm, junto al resto del conjunto de etiquetas de procedencia de Aggrega — tal como está escrito cuando es un valor de etiqueta de Kubernetes válido y, en caso contrario, reescrito en un valor válido, con el valor exacto llevado en la anotación aggrega.ai/environment (así, eu/prod recibe la etiqueta eu-prod); el proveedor helm-chart añade las mismas etiquetas a cada artefacto cargado mediante $import: que coloca en un subchart, mientras que las plantillas propias del subchart llevan lo que escribió su autor. El proveedor compose lleva el mismo valor como la etiqueta aggrega.ai/environment en cada servicio que emite.
Cinco patrones prácticos guían la escritura de environment::
-
Atribución de costos OTel/FinOps. Los paneles de costos en la nube (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) filtran los pods de Kubernetes por entorno mediante etiquetas. La etiqueta
aggrega.ai/environment: productionllega a las etiquetas de los pods mediante la inyección de etiquetas del proveedor Helm; los informes de costos agrupan el gasto poraggrega.ai/environmentsin etiquetado manual por recurso. -
Filtrado de trazas y registros OTel. Los paneles de observabilidad (Datadog, New Relic, Honeycomb, Grafana Tempo) filtran la telemetría por etiqueta de entorno.
aggrega.ai/environment: stagingpermite a los operadores limitar las consultas de registros y las búsquedas de trazas a staging sin filtrar por convenciones de namespace o nombres de charts — una única etiqueta canónica en toda la superficie renderizada. -
Selección por operadores de Kubernetes. Los controladores GitOps (ArgoCD, Flux) y los operadores de políticas (Kyverno, OPA Gatekeeper) a veces filtran los recursos por etiqueta de entorno para aplicar políticas específicas de un entorno (por ejemplo, «los recursos exclusivos de producción requieren una etiqueta approved-image-source»). La etiqueta
aggrega.ai/environmentproporciona un selector estable, distinto de las convenciones de namespace o de los patrones de nomenclatura. -
Diferenciación de producción multirregión. Un equipo que ejecuta una Release
production-us-eastjunto a una Releaseproduction-eu-west— ambas conmetadata.environment: production— obtiene la misma etiquetaaggrega.ai/environment: productionen todas las regiones. Combinado con una etiqueta de región aparte, esto permite consolidar costos entre regiones («gasto total de producción») y desglosarlos por región. -
Delimitación del cumplimiento normativo. La recopilación de evidencias SOC 2, PCI e HIPAA se delimita por entorno (auditoría solo de producción, etc.). La etiqueta
aggrega.ai/environmentla consumen las herramientas de recopilación de evidencias de cumplimiento (Vanta, Drata) para filtrar los recursos por alcance de auditoría.
El esquema exige environment: en cada Release; el valor es informativo, y el compilador solo lo lee para escribir la etiqueta aggrega.ai/environment.
Restricciones a nivel de esquema
Dos garantías estructurales protegen el Aggregate como fuente única de verdad:
values:está prohibido. Para proteger el Aggregate como fuente única de verdad, el esquema de la Release prohíbe mecánicamente un bloquevalues:— el operador no puede declararvaluessobre ningún Component ni Feature desde una Release. La prohibición se extiende a las aristasuses: una entradausespor arista de una Release llevainfray las vinculaciones que escribe sobre la conexión, y estas también llevaninfra— nuncavalues(los valores por arista orientados al desarrollador, y los valores de una vinculación sobre una conexión, permanecen en el Aggregate). La variación por entorno de los valores orientados al desarrollador fluye mediante el Parameter Hoisting: el desarrollador expone un campo tipadoparameters.*en el Aggregate, la plantillavaluesdel Component lo referencia y la Release proporciona el parámetro para su entorno. Consulta architecture/06-data-taxonomy-and-composition.md §8 Restricción 4 para ver la prohibición a nivel de esquema enunciada explícitamente. La superficie de aristasusesde la Release — lo que puede configurar y cablear — se documenta en Configuración de conexión por arista más abajo.extends+aggregate:se rechaza. Para evitar Releases no rastreables que «mutan el aggregate», cuando una Release usaextends, el esquema de la Release rechaza la declaración de un punteroaggregate. La release hija debe corresponder exactamente a la misma intención del desarrollador que su release padre. Elmanifest, en cambio, pasa a ser opcional, lo que habilita el «enlace tardío» — el operador puede heredar toda la topología física pero sustituir quirúrgicamente el Manifest.
El bloque parameters:
Una Release cumple el contrato tipado de parámetros que declara el Aggregate. spec.parameters: es la superficie de autoría — un mapa YAML cuyas claves coinciden con las declaraciones parameters.* del Aggregate y cuyos valores proporcionan el cumplimiento por entorno.
# Aggregate declares the typed contractapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: my-app version: 1.0.0spec: parameters: db_size: { type: string, required: true } timeout_seconds: { type: integer, default: 30 } region: { type: string, enum: [us-east-1, eu-west-1], required: true }# Release fulfills the contract for this environmentapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest parameters: db_size: "100Gi" timeout_seconds: 60 region: "us-east-1"Cada valor pasa la comprobación del esquema declarado por el Aggregate en la capa del contrato de parámetros, y la compilación se detiene cuando una Release omite un parámetro obligatorio (E0165, parameter-missing) o proporciona un valor que el contrato de su slot rechaza (E0164, parameter-contract-violation). Los parámetros declarados con un default: reciben el valor predeterminado cuando la Release omite el slot; el contrato tipado es el único vocabulario de autoría.
Dos modos de autoría — selección según la forma del contenido. parameters: acepta un mapa YAML en línea (modo 1, mostrado arriba) o una única clave $import: que apunta a un archivo local (modo 2):
spec: aggregate: my-app manifest: prod-manifest parameters: $import: ./prod-parameters.yamlUna ruta $import: relativa se resuelve desde el directorio que contiene la Release que la escribe, sea cual sea el lugar desde donde se ejecute un comando, de modo que la línea de comandos y el editor leen el mismo archivo; una ruta absoluta nombra su propio lugar, y cualquiera de las dos 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. Los dos modos son mutuamente excluyentes en este punto, y solo se puede importar un único archivo. La superposición de parámetros en varios archivos corresponde a las cadenas extends: de Release: la Release padre aporta un conjunto base de parámetros y la hija extiende y sobrescribe por entorno. Consulta Release compuesta / herencia extends: más abajo para ver el patrón.
Separación entre parámetros e infra. Los parámetros llevan la intención cognitiva del desarrollador expresada como slots tipados que declara el Aggregate; la Release los cumple. infra: en la Release lleva el dimensionamiento físico del operador (número de réplicas, límites de CPU/memoria, clases de almacenamiento) asociado a componentes concretos o a vinculaciones de Feature. Los parámetros fluyen a las plantillas values: del Aggregate mediante .parameters.X; infra: fluye a la plantilla valuesMapping: de la Recipe mediante .infra.X. Consulta architecture/06-data-taxonomy-and-composition.md §3 para la taxonomía de los pilares de datos y templates/parameters-context.md para el ciclo de vida de los parámetros a lo largo del pipeline.
Límites y ámbito predeterminado
Una Release agrupa los componentes en límites — unidades físicas de despliegue, cada una con su propio directorio de salida y su propia cascada de anotaciones. El caso de un único límite es el habitual, por lo que no requiere ceremonia.
Ámbito único (el predeterminado). Escribe los componentes directamente bajo spec.components: y omite el bloque boundaries:. El compilador los integra en un límite default sintetizado cuya salida es plana — los artefactos quedan directamente bajo dist/ (por proveedor, mediante el valor predeterminado seguro de subDirectory descrito más abajo: dist/compose/, dist/helm/, …), sin ningún segmento con el nombre del límite en la ruta. Es el despliegue más sencillo: aggrega build sobre un destino Compose plano o de un solo clúster sin nombrar límites.
spec: aggregate: aggregate manifest: manifest components: db: infra: engine_version: "11.4" web: infra: port: 8080Varios ámbitos. Cuando una Release abarca más de una agrupación física — clústeres, regiones o sync waves separados — declara límites con nombre bajo boundaries:. Cada límite lleva su propio directory:, su propia cascada de anotaciones y su propio syncWave:, y los componentes se direccionan dentro de su límite.
Exclusión mutua. spec.components: y spec.boundaries: se excluyen mutuamente en la raíz de la Release — una Release escribe uno u otro, nunca ambos. Un documento que declara ambos se detiene al cargarse con un error de envoltorio. La superficie components de nivel superior lleva la misma forma por componente, del lado del operador, que llevan los components de un límite (infra:, annotations:, uses:).
Un límite declarado llamado default. La salida plana es una propiedad del límite predeterminado sintetizado, no del nombre. Un límite llamado default que una Release declara explícitamente bajo boundaries: es un límite con nombre corriente: su salida sigue su directory: (que de forma predeterminada es dist/boundaries/default/), exactamente como cualquier otro límite declarado.
Consulta architecture/06-data-taxonomy-and-composition.md §7 para el patrón del ámbito predeterminado.
Segregación espacial y rutas de salida
Cada límite declara un directory físico de salida para sus artefactos compilados; los componentes dentro de un límite pueden sobrescribirlo mediante un subDirectory por componente. El compilador calcula la ruta final del artefacto uniéndolos, en forma separada por barras en todas las plataformas: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).
- Un directorio, una grafía. La ruta evaluada se limpia una sola vez, de modo que
out/a,out//a,./out/ayout/a/son un mismo directorio. Los límites cuyas rutas, una vez limpias, llevan al mismo directorio y que se renderizan mediante el mismo proveedor se ensamblan juntos, exactamente como los límites escritos con rutas idénticas. - La ruta permanece bajo la raíz de salida. Una ruta que sale de la raíz de salida (
..,../escape,a/../..), una absoluta, o una que no nombra ningún directorio — vacía, o que tras la limpieza queda en la propia raíz de salida — detiene la compilación antes de que se escriba nada. El mensaje nombra la Release, el límite, el campo erróneo (directory:osubDirectory:) y el valor al que se evaluó, ya que ese valor suele ser el resultado de una plantilla. - Valor predeterminado seguro. Si
subDirectoryse omite o está vacío, el compilador aplica automáticamentesubDirectory: "{{ .capability }}"— los artefactos de cada capacidad de renderizado (Helm, Helm-chart, Compose, Terraform, CloudFormation) acaban en su propia subcarpeta, lo que evita colisiones de artefactos mezclados en las herramientas de CI/CD posteriores. UnsubDirectory: ""escrito explícitamente se lee exactamente como uno omitido, así que también recibe este valor predeterminado. - Anulación plana. Para desactivar por completo los subdirectorios (todos los artefactos directamente bajo
directory), establecesubDirectory: ".". Una plantillasubDirectoryque se evalúa como una cadena vacía —"{{ .parameters.sub }}"consubestablecido en"", por ejemplo — también los desactiva. - Variables de plantilla.
directoryse evalúa con{{ .capability }},{{ .boundary_name }},{{ .parameters.X }},{{ .manifest.recipe_name }}y{{ .parent_boundary.* }}para los datos en cascada de un límite contenedor.subDirectoryse evalúa con el mismo conjunto más{{ .component_id }}(solo en anulaciones por componente). El compilador evalúa las plantillas de ruta conmissingkey=error— hacer referencia a una variable no declarada detiene la compilación con un diagnóstico preciso. Consulta variables de plantillas de ruta para la matriz por contexto y las reglas de cascada del límite padre.
Las anotaciones de límite descienden en cascada a cada componente contenido; infra permanece estrictamente localizado en el componente al que se dirige. El mapa recursivo boundaries permite un anidamiento arbitrario (límite dentro de límite dentro de límite), mientras los invariantes de la cascada de anotaciones y del infra local se mantienen en cada nivel.
Ejemplo práctico:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: spatial-release version: 1.0.0 environment: productionspec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" # Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`. annotations: "aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations components: api-server: infra: { replicas: 5 } # Strictly local aws-rds: # Scenario B: Bespoke Enterprise Naming. subDirectory: provisioning postgres-db: # Scenario C: The Flat Directory Override. subDirectory: "." # not "", which takes the defaultLas anotaciones propagadas en cascada por este mecanismo aparecen en las plantillas de Recipe posteriores mediante .context.annotations.release; consulta Autoría de una Recipe y la matriz de expansión de plantillas para ver cómo las consumen los renderizadores.
Valores de anotación estructurados. Cuando un binding del Manifest declara varias rutas de enrutamiento del pilar infra para una misma clave de anotación, el valor de la anotación del lado de la Release puede ser un objeto estructurado que lleva valores para varios campos del esquema de una Feature en una sola declaración:
boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100 components: api: annotations: feature.myco/db-pool: max_connections: 200 # closer-level override # pool_size not listed → inherits 20 from boundaryLos valores estructurados descienden en cascada con una fusión profunda por subclave; las subclaves del nivel más cercano sobrescriben las del padre. Un null por subclave excluye una subclave mientras las subclaves hermanas se mantienen. El lado de la Release solo aplica las subclaves cuyo pilar en el mapa de binding es infra; las subclaves que se enrutan a values corresponden a las anotaciones del lado del Aggregate. Para la explicación completa de los valores estructurados — composición entre ambos lados, validación de tipo por subclave, la disciplina de los valores predeterminados relajados — consulta providers/well-known-annotations.md §«Valores de anotación estructurados».
Anotaciones conocidas. Además de las claves ad hoc, la biblioteca estándar de Aggrega define un conjunto de anotaciones conocidas bajo los espacios de nombres aggrega.ai/ y feature.aggrega.ai/, agrupadas en las categorías de ubicación, redes, seguridad y observabilidad. Quienes añadan anotaciones a un límite de una Release deberían consultar providers/well-known-annotations.md para la matriz completa y las reglas de consumo por proveedor — la página documenta qué proveedores aplican cada clave conocida y qué comportamiento emiten cuando la clave está presente.
Configuración de conexión por arista
Un componente de un límite puede llevar un bloque uses: que configura o cablea las aristas de la topología dentro de los sockets que declara el usesSchema de catálogo del Component. Es la superficie por conexión del operador, acotada para que el desarrollador conserve la propiedad de la arquitectura que escribió:
- Configurar una arista existente. Establece
infrapor arista en una arista que el desarrollador ya declaró. La entrada nombra el alias del desarrollador y proporcionainfra; nombra el mismo destino que cableó el desarrollador u omite el destino. Elinfrase valida contra elinfraSchemadel socket. - Cablear un socket sin enlazar. Crea una arista hacia un socket que el
usesSchemadel Component declara pero que el desarrollador dejó sin cablear, apuntando a un componente existente. La arista creada también puede llevarinfrapor arista. - Vincular sobre una conexión. Coloca las vinculaciones bajo
features:de la entrada, indexadas por un slot que el socket declara en sufeaturesSchema— los mismos slots que llena la entrada de conexión del desarrollador. Cada una llevatype, unadescriptionopcional einfra, y nuncavalues. Bajo un slot que el desarrollador ya llenó en la misma conexión, la entrada dimensiona esa vinculación: escribe soloinfra, ya que el tipo y los valores vienen del Aggregate (untypeescrito aquí debe coincidir con el del Aggregate, o la compilación se detiene en esta entrada, nombrando ambos). Bajo un slot que el desarrollador dejó vacío, la vinculación es propia de la Release ytypees obligatorio. En ambos casos el llenado se somete alselectordel slot y cuenta para un slotrequired, exactamente como el del desarrollador.
La superficie es crear-sin-redirigir: una Release puede añadir una arista hacia un socket sin enlazar, pero no puede redirigir una arista que el desarrollador ya declaró. Una entrada por arista que nombra un destino distinto del de la arista del desarrollador detiene la compilación; una entrada que nombra el mismo destino (o lo omite) configura esa arista. La Release tampoco puede declarar values sobre una arista o sobre una vinculación que escribe allí (los valores orientados al desarrollador permanecen en el Aggregate), enlazar un socket que el usesSchema no declara, ni apuntar una arista a un componente que no existe — cada uno es una detención fatal. También lo es una entrada que establece infra o features sobre una conexión que no existe una vez trazadas todas las aristas, salvo que el componente consumidor esté desactivado con active: false. Consulta errors/fatal-halts.md §«Al construir la topología».
Otras tres detenciones mantienen las vinculaciones de una conexión en su conexión:
- Un nombre para el que el socket no declara ningún slot detiene la compilación, exactamente como en la entrada de conexión del Aggregate, en esta entrada de la Release, nombrando los slots que declara el socket y aquellos de los que el nombre dista una sola edición.
- Una vinculación que solo hace la Release, escrita sin
type, detiene la compilación en la entrada de conexión, nombrando el slot. Una vinculación que hace la Release no llevavalues, así que se ajusta a una Feature cuyosvaluesno exigen nada; una cuyo esquema exige un valor se detiene por el valor que falta en la misma entrada. Las Features de credenciales de la biblioteca estándar que llevan el localizador de quien llama no exigen ninguno envalues: cada una lo admite también eninfra(ver más abajo). - El nombre compuesto escrito en cualquier lugar que no sea la conexión detiene la compilación. Una vinculación de conexión se convierte en una vinculación del componente consumidor llamada
<alias>.<slot>(consulta la entrada de conexión del Aggregate), y tanto las clavesfeatures:propias de una entrada de componente como las de un límite admiten un punto. Una entrada de componente que escribe ese nombre, o un límite que lo escribe de modo que alcance un componente cuya conexión lo lleva — un componente colocado en ese límite o en uno anidado dentro de él, incluidos los de un submódulo enrutado — detiene la compilación nombrando ambas grafías, una vez por cada componente que alcanza. El slot de un socket se llena en cada conexión y nunca mediante una vinculación que desciende en cascada desde un ámbito más amplio.
spec: components: router: uses: models: # Size the attachment the Aggregate declared on the "gpt" connection: infra only. gpt: features: credential: infra: { rotation: hourly } # Attach on a connection the developer left without one: the type is required. plain: features: credential: type: core/generated-secretUna credencial sobre una conexión que cablea la Release nombra su secreto en infra. Una conexión que cablea la Release no tiene entrada en el Aggregate, así que nada allí escribe los values de la credencial, y la Release no escribe values en ningún lugar. Por eso, cada Feature de credenciales de la biblioteca estándar que lleva el localizador de quien llama — core/referenced-secret, core/referenced-secret-set, core/secret-value y core/secret-provided — lo admite en infra además de en values: origin, o entries para core/referenced-secret-set, con la misma forma y la misma declaración sensitive: true en ambos pilares. Cada realización lee el pilar que lo lleve.
spec: components: router: uses: models: gpt: target: gpt # wire the socket the developer left unbound features: credential: type: core/referenced-secret infra: origin: openai-team-a # the secret the operator namesEl localizador se escribe en exactamente un pilar por vinculación. Una vinculación que lo lleva en ambos — los values del Aggregate y el infra de la Release para el mismo slot — o en ninguno se detiene en la aserción propia de la Feature (E0033), nombrando la Feature, la vinculación y el componente, e indicando cuál de los dos casos fue. La regla pertenece a las entidades de catálogo de esas Features, no al compilador, que evalúa su aserción como evalúa la de cualquier Feature. Los campos distintos del localizador conservan su pilar: key sigue siendo una hoja de values, así que una vinculación que solo hace la Release lee la clave de datos predeterminada de la Feature, value. La prohibición de values: no cambia — el localizador del operador es infra.
core/secret-provided es la que no encaja en una conexión: publica su valor para que lo entregue el propio bloque inject: de la vinculación, y la vinculación de una conexión no lleva bloque inject: en ninguno de los dos documentos, así que en una conexión ningún bloque inject: lo entrega. Usa allí core/referenced-secret o core/secret-value.
spec: aggregate: spatial-app manifest: prod-manifest boundaries: eu-prod: components: api-server: uses: databases: # Configure the developer-declared edge "primary": add per-edge infra. # The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget. primary: infra: { storage_class: fast-ssd } caches: # Wire an edge into the declared-but-unbound "caches" socket to an existing component. main: target: redis-prod infra: { storage_class: standard }El infra por arista resuelto fluye al contexto de renderizado del componente consumidor en .context.uses.<alias>.infra.<key>; nunca aparece en el contexto del componente destino, de modo que la salida renderizada de un destino es invariante respecto a los consumidores que configuran aristas hacia él. Una vinculación sobre una conexión también llega al componente consumidor, como una de sus vinculaciones: su infra se fusiona con los values del Aggregate para el mismo slot, y su FeatureRecipe renderiza a partir de ambos. La Recipe del componente consumidor la lee bajo su conexión, en .context.uses.<alias>.features.<slot>, y su Workload la entrega nombrando la conexión junto al slot — consulta Entregar una credencial que lleva una conexión.
El campo aggregates: — enrutar submódulos anidados a los límites
Cuando el Aggregate declara submódulos anidados mediante spec.aggregates:, la Release decide en qué límite aterrizan los componentes de cada submódulo declarando aggregates: junto a components: dentro del límite de destino:
# Aggregate declares two sub-aggregatesapiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: platform version: 1.0.0spec: aggregates: finance: type: finance-module:1.2.0 analytics: type: analytics-module:2.0.0 components: gateway: type: core/ingress---# Release routes each sub-aggregate into a specific boundaryapiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: platform manifest: prod-manifest boundaries: eu-prod: directory: "deploy/eu-prod" aggregates: finance: {} components: gateway: {} us-prod: directory: "deploy/us-prod" aggregates: analytics: {}Coloca cada subagregado listado en Aggregate.spec.aggregates: en exactamente un límite.
El enrutamiento coloca componentes. Cada componente de un submódulo enrutado aterriza en el límite que lo enruta y toma de él directory, subDirectory, syncWave y la cascada de anotaciones — el mismo contexto que recibe un componente nombrado directamente bajo components:, incluida la procedencia aggrega.ai/boundary-path estampada en los artefactos emitidos. Enrutar un submódulo y direccionar cada uno de sus componentes mediante su ruta con puntos cualificada con un cuerpo vacío producen, por tanto, artefactos idénticos; el enrutamiento es la forma más breve de expresarlo, y la única de expresarlo sin conocer el contenido del submódulo.
Un componente pertenece a exactamente un límite, y la compilación se detiene cuando un documento coloca uno dos veces — el mismo submódulo enrutado a dos límites, un submódulo enrutado a un límite mientras uno de sus componentes se nombra en otro, o un componente nombrado tanto directamente como a través de una entrada de enrutamiento. El diagnóstico nombra ambos sitios, porque cuál conservar es decisión del autor. Enrutar un submódulo a un límite y nombrar uno de sus componentes bajo ese mismo límite no es un conflicto: el enrutamiento coloca el componente y la entrada nombrada lo configura.
Un subagregado que la Release no coloca en ninguna parte detiene la compilación. La colocación se lee a través de ambas grafías, así que la compilación se detiene solo cuando ninguna alcanza el submódulo: ningún límite lo enruta bajo aggregates: y ningún límite nombra alguno de sus componentes bajo components: mediante la ruta con puntos cualificada. Cualquiera de las dos grafías por sí sola lo coloca, y un submódulo cuyos componentes se nombran todos individualmente no necesita entrada de enrutamiento. La corrección corresponde al bloque aggregates: del Aggregate que importó el submódulo — el Aggregate que la Release despliega, para uno que importa directamente, y el propio documento del submódulo importador, para uno anidado. El diagnóstico nombra esa entrada por la clave con la que la escribe el documento importador, de modo que, para un submódulo anidado, se lee como el nombre local y no como la ruta con puntos.
Dos casos deliberadamente no detienen la compilación. Un submódulo que no aporta componentes no tiene nada que colocar. Un submódulo cuyo interruptor active: se resuelve en false nunca se compuso, así que ninguno de sus componentes existe para ser colocado.
La colocación parcial no activa esta regla: un submódulo queda colocado en cuanto cualquiera de sus componentes alcanza un límite, así que nombrar uno de ellos satisface al submódulo. De ello no se sigue que el resto pueda omitirse. Entonces nada coloca a cada componente que el límite no nombró, y la regla de componentes que sigue lo informa en su propia clave — así que un submódulo colocado en parte detiene la compilación una vez por cada componente que dejó atrás, no en el submódulo. Las dos grafías que colocan un submódulo entero en una línea son la entrada de enrutamiento y nombrar cada componente; cualquier cosa entre ambas coloca lo que nombra y nada más.
Un componente que la Release no coloca en ninguna parte también detiene la compilación, un nivel más adentro. La regla anterior pregunta si un submódulo alcanzó un límite; esta pregunta lo mismo de cada componente que contiene la composición. Un componente alcanza un límite al ser nombrado bajo los components: de ese límite, o al encontrarse dentro de un submódulo que un límite enruta hacia él. Uno que no alcanza ninguna de las dos cosas se renderiza fuera de todo límite que declara la Release, tomando su directory, subDirectory, syncWave, cascada de anotaciones e infra: por componente de ninguna parte — así que la compilación se detiene y nombra el componente en lugar de emitir artefactos que la configuración de límites nunca alcanzó.
Las dos reglas se reparten el terreno preguntando por el submódulo del componente, no solo por si tiene uno. Un componente de un submódulo que la Release no colocó en ninguna parte queda a cargo de la regla de submódulos, que informa ese único error de autoría una vez en la entrada aggregates: en lugar de una vez por cada componente que contiene el módulo. Un componente de un submódulo que la Release colocó en parte corresponde a esta regla, porque la regla de submódulos lee ese módulo como colocado y no dice nada sobre él — así que cada componente que el límite no nombró se informa aquí, en su propia clave dentro del documento que lo declara. Colocar un submódulo en parte, por tanto, nombra exactamente lo que querías nombrar, y te avisa de cada componente que no nombraste.
Y una entrada de límite que nombra un componente que el Aggregate desplegado no contiene detiene la compilación. Las dos reglas anteriores leen la colocación desde el lado del componente — ¿algo lo colocó? Esta la lee desde el lado de la Release: ¿se resuelve el nombre? Una entrada que no se resuelve en nada no coloca nada, de modo que su subDirectory, sus anotaciones, su infra: por componente y sus uses: configuran un componente que no existe, y la compilación se detiene en lugar de emitir un despliegue que la entrada nunca alcanzó. Se comprueban ambas grafías: un nombre bajo los components: de un límite se lee como el id que lleva el componente una vez completada la composición, y un nombre bajo los components: de una entrada de enrutamiento se lee como el nombre local que lleva dentro de ese submódulo. El diagnóstico informa el id al que se dirigió la entrada, que en la grafía enrutada no es el nombre que figura en el archivo — el archivo escribe la mitad local y el submódulo aporta su prefijo.
Un nombre se rechaza por no resolverse en nada y nunca por su forma: un nombre con puntos es normal, porque un componente un módulo más adentro lleva el prefijo de ese módulo. Un componente cuyo interruptor active: se resuelve en false sigue siendo nombrable — desactivar un componente no requiere editar la Release que lo configura.
Un subsistema no aporta nada a la ruta cualificada, así que un límite direcciona un componente por su nombre simple, sea cual sea la forma en que el Aggregate lo agrupe. Solo la composición de submódulos cualifica un id. Un componente del Aggregate desplegado es store tanto si el autor lo escribió en el nivel superior como dentro de un subsistema llamado data; un componente un módulo más adentro es data.store, y ese data es el prefijo del módulo y no el de ningún subsistema. Así, una entrada de límite escrita data.store para un componente situado en un subsistema llamado data no direcciona nada: la propia entrada detiene la compilación según la regla anterior, y el componente al que iba destinada tampoco alcanza ningún límite. Corregir la entrada a store resuelve ambas cosas.
Colocar un submódulo requiere, por tanto, boundaries:. La forma de ámbito único no tiene superficie de enrutamiento — aggregates: es una clave de un límite, no de spec: — y el mapa components: de nivel superior solo acepta nombres no cualificados, así que una Release que despliega un Aggregate que importa submódulos declara boundaries:.
Enrutamiento recursivo. aggregates: es recursivo — cada entrada bajo los aggregates: de un límite puede declarar a su vez un mapa aggregates: anidado para una composición de módulos profundamente anidada.
Bloque de enrutamiento por agregado. Una entrada de enrutamiento acepta exactamente dos claves y nada más: components:, para configurar componentes individuales de ese submódulo, y un aggregates: anidado para los módulos anidados a mayor profundidad. annotations: pertenece al límite, y el infra: por componente pertenece a una entrada bajo los propios components: de la entrada de enrutamiento.
Dentro de una entrada de enrutamiento, un componente se identifica por el nombre que lleva dentro de su submódulo — consumer, no data.consumer — porque es el único nombre que tiene allí. La ruta con puntos cualificada es la forma en que el mapa components: de un límite direcciona el mismo componente; las dos grafías no son intercambiables, y una entrada de enrutamiento rechaza una clave con puntos.
boundaries: eu-prod: directory: "deploy/eu-prod" annotations: aggrega.ai/namespace: "finance-zone" aggregates: finance: components: ledger: # the component's name inside the finance module infra: replicas: 3 aggregates: reporting: {} # a module nested inside financeLos componentes y las Features propios del subagregado no se vuelven a declarar en la Release — la Release los enruta en lugar de repetirlos, y nombra uno solo para configurarlo.
Secuenciación temporal — syncWave por límite
Cada límite de la Release declara opcionalmente un campo entero syncWave:, que da al operador un control explícito sobre el orden de despliegue sin tocar el Aggregate del desarrollador. El número de oleada es una propiedad del propio límite; cada componente contenido en el subárbol del límite hereda el valor de oleada de su límite cuando se emiten los artefactos.
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release version: 1.0.0 environment: productionspec: aggregate: my-app manifest: prod-manifest boundaries: infra: directory: "deploy/infra" syncWave: 0 components: core-vpc: {} postgres-db: {} migrations: directory: "deploy/migrations" syncWave: 1 components: db-migration-task: {} apps: directory: "deploy/apps" syncWave: 2 components: web-server: {} ai-agent: {}Semántica del valor de oleada. syncWave: es un entero con signo (positivo, cero o negativo). El valor predeterminado cuando se omite el campo es 0. Los valores de oleada no se heredan de un límite padre — cada límite que quiera una oleada distinta de la predeterminada la declara explícitamente. Los Components no pueden sobrescribir la oleada de su límite (la oleada es una propiedad de la unidad espacial, no de los componentes individuales).
Emisión por proveedor. El compilador emite el valor de oleada del límite en la salida renderizada, en la forma nativa del proveedor. Tres de las formas se desarrollan a continuación; lo que hace la oleada en cada proveedor de la biblioteca estándar, terraform incluido, se recoge en una tabla en providers/reference-matrix.md «Qué hace la syncWave de un límite en cada proveedor».
- Kubernetes (proveedor helm / helm-chart). Cuando la oleada no es
0, cada recurso de Kubernetes que el proveedor helm renderiza para el límite lleva la anotación estándar de GitOpsargocd.argoproj.io/sync-wave: "<N>"; los hooks de Helm llevan además la anotaciónhelm.sh/hook-weight: "<N>", de modo que el mismo valor de oleada dirige el propio orden pre/post-install de Helm. ArgoCD lee la anotación sync-wave y Helm lee el peso de un hook, y cada uno ordena la aplicación de los recursos en consecuencia. El proveedor helm-chart copia las plantillas de un chart de origen tal como las escribió su autor, así que los recursos propios de un subchart llevan la oleada solo donde esas plantillas la escriben; un artefacto cargado mediante$import:que el proveedor añade llevaargocd.argoproj.io/sync-wavey ningúnhelm.sh/hook-weight(consultaproviders/helm-chart.md). - Compose. Cada servicio del archivo compose en el que se renderiza un límite espera, mediante
depends_on, a los servicios de la oleada inmediatamente anterior que contribuyeron al mismo archivo — condicionado a la salud del destino cuando el destino declara unhealthcheck, y a su arranque cuando no lo declara. Así, la oleada ordena los servicios de un archivo y nada fuera de él: los límites que se renderizan en archivosdocker-compose.yamlseparados son proyectos compose separados, y secuenciarlos es responsabilidad del operador. Las aristasuses:siguen expresando el orden por arista junto a la oleada. Consultaproviders/compose.md. - CloudFormation. Cada recurso de la plantilla de stack ensamblada depende, mediante
DependsOn, de los recursos de la oleada inmediatamente anterior que contribuyeron al mismo stack — de modo que la oleada fija el orden en que se crean los recursos y, a la inversa, el orden en que se eliminan. No es un orden por disponibilidad: una plantilla de stack no tiene noción de que un recurso esté listo para dar servicio. ElDependsOnpropio de un fragmento se amplía en lugar de reemplazarse. Los Components que se ensamblan en un stack distinto quedan fuera de alcance, y secuenciar dos stacks es responsabilidad del operador. Consultaproviders/cloudformation.md.
Unidad de autoría de oleadas frente a unidad desplegable. El límite es la unidad en la que se escriben las oleadas. La unidad desplegable es la ruta de ensamblado en la que se emiten los componentes — por defecto 1:1 con el límite, pero dos límites hermanos que comparten un directory: se funden en una única salida ensamblada (un Chart.yaml, un docker-compose.yaml). Cuando eso ocurre, la salida ensamblada puede contener recursos de varias oleadas; una Application de ArgoCD que la lee ordena, dentro de la Application, cada recurso según la anotación sync-wave que lleva ese recurso — en helm, cada recurso renderizado para una oleada distinta de cero, y en helm-chart, solo un artefacto cargado mediante $import:, mientras que las plantillas propias de un subchart llevan lo que escribió su autor. La secuenciación entre Applications a través de rutas es responsabilidad de la CI del operador.
Casos de uso. El orden por oleadas importa siempre que el arranque de un límite depende de que otro haya terminado antes. Patrón canónico: un límite infra en la oleada 0 (VPC + base de datos), un límite migrations en la oleada 1 (job de migración del esquema) y un límite apps en la oleada 2 (la aplicación que consume el esquema migrado). Sin oleadas explícitas, los tres se despliegan a la vez y la aplicación entra en un bucle de fallos mientras espera a que termine la migración.
Para el marco arquitectónico completo — el modelo de ejecución en DAG, la justificación de situar la secuenciación temporal en la Release en lugar de en el Aggregate, y la distinción entre unidad de autoría de oleadas y unidad desplegable — consulta architecture/12-day-two-lifecycles.md §1.
Vinculación de Feature
La Release puede vincular Features tanto en el ámbito del límite (política amplia) como en el ámbito de un componente concreto (selección precisa), con una ejecución que sigue el modelo de cebolla de 5 niveles definido en architecture/10-compilation-pipeline.md. Las Features declaradas en la Release aportan type, infra y uses; no pueden declarar values (consulta Restricciones a nivel de esquema más arriba).
Una Feature vinculada a un límite se identifica por un nombre de instancia que eliges tú, y ese nombre no puede ser . ni ... En un proveedor que da a cada contribuyente un directorio propio — terraform, bajo modules/, y helm-chart, bajo charts/ —, los archivos de una Feature a nivel de límite se escriben en un directorio que lleva solo el nombre de la instancia, y ninguno de esos dos nombres es un directorio propio: la compilación se detiene y nombra la Release, el límite y la instancia. Un nombre que simplemente contiene puntos, como audit.v2, es un nombre normal.
features: es la única superficie de vinculación de la Release, en ambos ámbitos — como lo es la del Aggregate. Una credencial es una Feature que lleva la etiqueta feature.aggrega.ai/kind: secret, así que una credencial vinculada por el operador se vincula bajo features: como cualquier otra Feature, y nombra su secreto en infra exactamente como lo hace una en una conexión (consulta Configuración de conexión por arista) — en un componente que el Aggregate dejó sin ninguna, o como el dimensionamiento de una vinculación que el Aggregate declaró sin nombrar un secreto. No existe una segunda palabra clave de vinculación en ningún ámbito; un documento que declara una se rechaza al cargarse con un error de envelope que nombra la propiedad inesperada.
Una funcionalidad vinculada a todo un límite puede llevar un bloque uses:, y ese bloque se proyecta sobre cada componente enrutado al límite: cada componente obtiene una arista de dependencia hacia los destinos que nombra la funcionalidad y recibe por inyección los provides de esos destinos. Esto expresa una dependencia compartida una sola vez en el límite — «cada componente de este límite se comunica con la caché / el colector / el bus de mensajes compartido» — en lugar de repetir la misma arista uses: en cada componente. Una vinculación de Feature a nivel de subsistema en el Aggregate proyecta su uses: del mismo modo sobre los componentes del subsistema. uses es una declaración de cableado de la topología, no un valor, así que está permitida en la Release. La proyección es independiente del ámbito de ejecución de la Feature vinculada: una Feature cuya FeatureRecipe se renderiza una vez por límite sigue proyectando su uses: por componente, mientras que el propio recurso compartido se renderiza una vez.
Una funcionalidad vinculada a un único componente lleva el mismo bloque uses: y cablea la misma arista desde ese único componente: el componente obtiene una arista de dependencia hacia cada destino nombrado, recibe por inyección los provides de esos destinos, y la arista registra la vinculación como su origen exactamente como lo hace la forma para todo el límite. Las dos son una misma declaración con dos amplitudes — vincular en el límite para cablear cada componente de él, vincular en un componente para cablear ese — y la elección entre ambas es una cuestión de alcance, nunca de lo que hace el cableado. Ninguna crea cómputo: el destino debe nombrar ya un componente que el Aggregate declaró, y uno que no lo haga detiene la compilación. Una conexión que traza una Feature no lleva vinculaciones propias: su entrada acepta target e inject, y una clave features: en ella se rechaza cuando se carga la Release.
boundaries: cluster: directory: ./dist/cluster components: api: features: shared_backend: type: core/shared-backend uses: backend: primary: target: db # a component of the assembled graph inject: env: - in: DB_HOST from: host # db's `host` provides reaches api as DB_HOST db: {}Cómo se escribe un destino. Un destino de arista nombra un componente del grafo ensamblado, así que se escribe con la ruta con puntos cualificada — data.store, no store — siempre que el destino pertenezca a un submódulo enrutado. Esto se mantiene incluso donde la propia vinculación está bajo una entrada de enrutamiento, cuyas claves components: son locales al módulo: la clave dice en qué componente está la vinculación y el destino dice a qué componente llega la arista, y solo el segundo es un nombre válido en todo el grafo. Un destino escrito con un nombre local al módulo no coincide con ningún componente y detiene la compilación con el mismo diagnóstico que produce cualquier arista colgante.
Release compuesta y herencia mediante extends:
Una Release puede declarar spec.extends: apuntando a una Release base de la que hereda la superficie de autoría.
La referencia es una ruta a un archivo junto a la Release que la declara — ./base-release.yaml, o ../shared/base-release.yaml. Una Release pertenece al lado del despliegue y no está indexada en el catálogo, por lo que una referencia extends: nunca se resuelve a través del catálogo. La ruta relativa es la única forma que acepta: una referencia escrita como coordenada de registro se rechaza, y también un nombre simple, cada una con la forma de ruta relativa indicada en el diagnóstico. El extends: de un Manifest es el vecino cercano que se lee de otra manera — acepta una ruta relativa o el metadata.name simple de un Manifest junto a la Release —, por lo que las dos formas no son intercambiables, y un nombre simple que se resolvería en un Manifest no se resuelve aquí. Cada eslabón de una cadena se lee de la misma manera: una Release padre guardada en otro directorio nombra a su propia Release padre mediante una ruta junto a sí misma, dondequiera que esté la Release que nombraste, exactamente como su $import: de parámetros se resuelve junto a ella. La ruta debe llevar a una Release dentro del workspace, como debe hacerlo toda ruta que escribe una Release — o, para una Release nombrada fuera del workspace, dentro del directorio que contiene esa Release, al que está sujeto cada eslabón de su cadena: una ruta que sale subiendo, o que un eslabón saca fuera, se rechaza antes de que se lea el archivo que nombra.
El compilador sigue la cadena cuando se carga la Release — rechazando una cadena que vuelve a un archivo que ya está en ella, una que supera la cota de profundidad y una referencia que no nombra nada — y luego reduce la cadena a una única Release resuelta.
Lo que heredas, puedes reemplazarlo clave por clave. Tu valor prevalece, hasta el fondo, hasta que llegas a un valor que es una sola cosa indivisible — un escalar, una lista, una plantilla — que tomas o reemplazas entero. Eliminas algo heredado escribiéndolo como null. Es la misma regla que siguen un Component, una Feature y un Manifest que extienden, así que un autor que ha conocido uno los ha conocido todos.
Aplicado a una Release: los boundaries se componen por nombre de límite y un límite por clave, los components por nombre de componente, infra en profundidad, las features por nombre de instancia y luego por pilar; los uses de un componente por socket y luego por conexión, donde un target que escribe el hijo reemplaza al heredado, el infra de la conexión se compone clave por clave, y sus features se componen por slot y luego por pilar según la misma regla que siguen las features propias de un componente; directory, subDirectory, syncWave y los punteros al Aggregate y al Manifest son escalares que reemplazan.
Dos cosas no se transmiten:
- Identidad y procedencia. No se hereda ningún campo
metadata.metadata.environmentes el que hay que conocer: es obligatorio en toda Release y es propio de cada Release por naturaleza, por lo que un hijo renderiza con su propio entorno en sus etiquetas de procedencia en lugar del de su padre. - El puntero al Aggregate se hereda en lugar de poder sobrescribirse. El hijo no puede declarar
aggregate:— el esquema rechazaextends:yaggregate:en un mismo documento —, por lo que un hijo despliega la misma intención del desarrollador que su base.
El hijo puede omitir manifest:, heredando el de su base, o sobrescribirlo para el Late Binding.
Una sola forma de enrutamiento a lo largo de la cadena. boundaries: y components: son mutuamente excluyentes dentro de una misma Release, y eso también se cumple a lo largo de una cadena: una base que declara límites con nombre junto con un hijo que declara componentes de nivel superior se rechaza, y el diagnóstico nombra ambos archivos y ambas claves. Elige una forma de enrutamiento y úsala hasta el fondo.
El patrón puente para el desarrollo local. El caso de uso canónico es un desarrollador que ejecuta localmente el Aggregate de producción de su equipo sin hacer un fork del Aggregate ni duplicar la topología de límites. El equipo publica una Release de producción; una Release local la extiende con extends: y sobrescribe solo el puntero al Manifest, cambiando las Recipes orientadas a la nube por equivalentes locales:
# production Release (committed; the source of truth for prod deployments)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: prod-release environment: production version: "1.0.0"spec: aggregate: my-app manifest: prod-manifest parameters: region: us-east-1 db_size: 100Gi out_dir: prod boundaries: prod: # A directory is a TEMPLATE, not a fixed path. Writing it against a # parameter is what lets a child render somewhere else without # restating the boundary topology. directory: deploy/{{ .parameters.out_dir }} components: api: { infra: { replicas: 5 } } db: {}
---# Local Release (developer-side; inherits everything, swaps the Manifest)apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: local-release environment: local version: "1.0.0"spec: extends: ./prod-release.yaml manifest: local-manifest # surgically overrides for local parameters: region: dev-local db_size: 1Gi out_dir: local # the inherited directory resolves here insteadlocal-release hereda de su base la topología de límites, las vinculaciones de Feature y las sobrescrituras de componentes; el desarrollador mantiene un único local-release.yaml y ejecuta aggrega build --release local-release.yaml sin duplicar ninguna configuración de producción.
Escribe directory: en función de un parámetro. Como un directorio se hereda como cualquier otro escalar, un hijo que hereda un directorio sin ninguna variable de plantilla renderiza en la misma ruta en la que renderiza su base, y ninguna opción de línea de comandos lo redirige. Eso es legítimo cuando es lo que pretendías — cambiar solo las Recipes para comparar su salida, por ejemplo —, por lo que la compilación lo informa y continúa en lugar de rechazarlo. Escribir el directorio en función de un parámetro, como arriba, mantiene la topología en un solo lugar y aun así envía la salida de cada Release a un lugar propio.
Estratificación de parámetros en varios archivos. La herencia de Release es el lugar para la estratificación de parámetros en varios archivos. Una Release base aporta el conjunto común de parámetros; los hijos por entorno extienden la base con extends: y sobrescriben los slots que difieren:
# base-release.yaml — common parametersspec: aggregate: my-app parameters: timeout_seconds: 30 feature_flags: { dark_mode: true }
---# prod-release.yamlspec: extends: ./base-release.yaml manifest: prod-manifest parameters: feature_flags: { dark_mode: false } # override one nested key
---# staging-release.yamlspec: extends: ./base-release.yaml manifest: staging-manifestCada hijo ve los parámetros heredados de su base combinados con los suyos. Los parámetros con valor de mapa se combinan en profundidad y prevalece la clave del hijo; los parámetros con valor escalar los reemplaza el hijo; una clave que un hijo escribe como null se elimina en lugar de establecerse en nada.
Una base puede importar sus parámetros y un hijo puede aun así sobrescribir claves individuales. Los dos modos de autoría descritos arriba en parameters: — en línea, o un único $import: — son una regla sobre un documento, no sobre una cadena: cada Release de la cadena declara un modo u otro, y la importación de cada una se resuelve respecto al directorio que contiene esa Release antes de reducir la cadena. Así, una base que importa un archivo compartido y un hijo que escribe algunas claves en línea se componen por clave, exactamente como lo harían dos bloques en línea:
# base-release.yaml — parameters arrive from a shared file beside itspec: aggregate: my-app parameters: $import: ./shared-params.yaml # tier: prod, region: eu
---# local-release.yaml — overrides one key, inherits the restspec: extends: ./base-release.yaml manifest: local-manifest parameters: tier: local # region stays eu, from the imported fileModos de error. Las cadenas extends: cíclicas, los punteros a padres que faltan y las declaraciones aggregate: del lado del hijo detienen la carga del workspace con diagnósticos explícitos que nombran la Release infractora y la violación a nivel de esquema. Consulta errors/fatal-halts.md para la forma de los mensajes de cada error.