Esquema de la base de infraestructura de Aggrega (FeatureRecipe)
Referencia generada. No la edites a mano — regenérala a partir del JSON Schema publicado.
ID del esquema: https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json
Definiciones escritas por Ops que asignan una Feature abstracta del catálogo a una implementación concreta y versionada para una capacidad de proveedor. Estrictamente 1:1 con un proveedor físico y una funcionalidad del catálogo.
Consulta la referencia de autoría de la FeatureRecipe para obtener orientación en prosa sobre cómo escribir entidades FeatureRecipe; 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 “FeatureRecipe” | sí | Constante: "FeatureRecipe" |
metadata | object | sí | |
spec | object | sí | El enlace con la capacidad del proveedor, la asignación, el pipeline y la asignación de inyección de una FeatureRecipe. Lleva los mismos tres tipos de entrada que una Recipe (con fuente, sintetizado, artifacts) más el injectMapping exclusivo de la FeatureRecipe; una FeatureRecipe de puro cableado que declara solo capability e implements es válida y no renderiza nada. |
No se permiten propiedades adicionales.
featurerecipe.metadata
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | Al menos 1 carácter de longitud. |
version | string | sí | Versionado semántico estricto de la FeatureRecipe (p. ej., 1.2.5). 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 Release que la 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.
featurerecipe.metadata.maintainers[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
name | string | sí | |
email | string | no | |
url | string | no |
No se permiten propiedades adicionales.
featurerecipe.spec
El enlace con la capacidad del proveedor, la asignación, el pipeline y la asignación de inyección de una FeatureRecipe. Lleva los mismos tres tipos de entrada que una Recipe (con fuente, sintetizado, artifacts) más el injectMapping exclusivo de la FeatureRecipe; una FeatureRecipe de puro cableado que declara solo capability e implements es válida y no renderiza nada.
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
capability | string | sí | La capacidad explícita del proveedor a la que se enlaza esta receta (p. ej., ‘helm’, ‘terraform’, ‘compose’) — el tipo de proveedor que la renderiza. |
implements | string | sí | Declara qué tipo de Feature del catálogo es capaz de implementar esta receta (incluidas las Features de credenciales etiquetadas con feature.aggrega.ai/kind: secret; versión exacta, rango compatible con la versión mayor ’^’ o sin versión). El compilador lo usa para verificar las asignaciones del Manifest y para sugerir candidatos en los diagnósticos y en el autocompletado del editor; nunca resuelve una compilación. La asignación del Manifest es la elección explícita de implementación del usuario, fijada en el archivo de bloqueo de la Release. |
locals | mapa de string | no | El estado privado de Ops. Resultados de cálculo internos disponibles solo dentro de las plantillas de esta FeatureRecipe como ‘.locals.*’. Cada entrada es en sí misma una plantilla Go, evaluada con respecto a un contexto autónomo: ‘.context.instance_id’ (el COMPONENTE ANFITRIÓN para el que se resuelve esta vinculación, que es lo que esa referencia denota en toda superficie de plantilla), ‘.attachment_name’ (la instancia de vinculación que se está resolviendo, y la única vía hacia ese nombre desde un local), los ‘.values’ e ‘.infra’ propios de la vinculación, y las entradas de este mismo bloque resueltas hasta ese momento. Las entradas se resuelven en el orden en que están escritas, y una entrada PUEDE leer una entrada hermana definida ENCIMA de ella, recibiendo el valor resuelto de esa entrada en lugar del texto de su plantilla. El orden del autor forma parte del contrato siempre que una entrada lea otra: mover una definición por debajo de la entrada que la lee rompe la compilación, y el bloque nunca se reordena para que una referencia se resuelva. Una referencia ‘.locals. |
provides | mapa de string | no | La API pública del Desarrollador. Variables de salida contractuales disponibles para la resolución del inject del Invocador aguas abajo. Cuando executionScope es boundary, los provides se evalúan una vez para la vinculación al límite, con respecto al contexto de plantilla con ámbito boundary, y cada componente al que llega la vinculación lee esa única evaluación en ‘.features. |
source | string u object | no | Ruta opcional al código de infraestructura. Acepta una cadena URI o un objeto estructurado abierto. Si se proporciona junto con valuesMapping, el compilador lo renderiza, y los documentos renderizados se suman a la salida de la FeatureRecipe antes de que se ejecuten los pasos de su pipeline. |
valuesMapping | string u object | no | Contenido de la asignación de values con tres modos de autoría mediante despacho según la forma del contenido. Modo 1 (inline): un escalar de cadena de plantilla Go que produce el formato de values que espera el proveedor. Modo 2 (importación de archivo): un mapa YAML de exactamente una clave, $import: ./relative/path.tmpl, que apunta a un archivo de plantilla Go local. Modo 3 (importación de biblioteca): un mapa YAML de exactamente una clave, $import: <Library>#/mappings/<entry>, que hace referencia a una entrada de una MappingLibrary por identidad de nombre simple (la versión la suministra el archivo de bloqueo de cada Release; ningún host de registro aparece en la referencia). En la forma de objeto, $import no debe coincidir con ^oci://; un valor que coincide se rechaza. |
workload | string u object | no | Productor de YAML de Workload con tres modos de autoría mediante despacho según la forma del contenido. Modo 1 (inline): un escalar de cadena de plantilla Go cuya salida se analiza como ‘aggrega.ai/v1beta1 Workload’. Modo 2 (importación de archivo): un mapa YAML de exactamente una clave, $import: ./relative/path.yaml, que apunta a un archivo de plantilla Go local. Modo 3 (importación de biblioteca): un mapa YAML de exactamente una clave, $import: <Library>#/workloads/<entry>, que hace referencia a una entrada de una WorkloadLibrary por identidad de nombre simple (la versión la suministra el archivo de bloqueo de cada Release; ningún host de registro aparece en la referencia). El Provider de destino debe admitir la síntesis de cargas de trabajo; el catálogo de la biblioteca estándar declara workloadSchema en esos proveedores como el contrato documentado. Una FeatureRecipe con workload: enlazada a un proveedor que no puede sintetizar se detiene de forma explícita en tiempo de renderizado. Una carga de trabajo sintetizada de una FeatureRecipe emite sus manifiestos nativos del proveedor en el directorio de salida de la funcionalidad. En la forma de objeto, $import no debe coincidir con ^oci://; un valor que coincide se rechaza. |
artifacts | mapa de string u object | no | Mapa del nombre de entrada a la autoría del contenido del artefacto. El valor de cada entrada lleva uno de tres modos mediante despacho según la forma del contenido. Modo 1 (inline): un escalar de cadena de plantilla Go cuya salida es el cuerpo del artefacto. Modo 2 (importación de archivo): un mapa YAML de exactamente una clave, $import: ./relative/path.yaml, que apunta a un archivo de plantilla Go local. Modo 3 (importación de biblioteca): un mapa YAML de exactamente una clave, $import: <Library>#/artifacts/<entry>, que hace referencia a un bundle de una ArtifactLibrary por identidad de nombre simple (la versión la suministra el archivo de bloqueo de cada Release; ningún host de registro aparece en la referencia). Un bundle se expande en una salida por archivo, cada una anidada bajo la clave de la entrada como <key>/<filename>. La clave nombra la salida de la entrada: la clave de una entrada de modo 1 o 2 es su nombre de archivo de salida, usado tal como está escrito, y el archivo importado de una entrada de modo 2 suministra el contenido sin nombrar la salida, de modo que dos entradas que importan archivos distintos que comparten un nombre son dos salidas distintas. Los recursos auxiliares que emite una FeatureRecipe generadora de recursos (ConfigMap, ServiceMonitor, NetworkPolicy, CRD ExternalSecret, etc.) tienen forma de artefacto; artifacts: es el mecanismo principal de generación de recursos. Las colisiones entre entradas de artefactos, archivos de bundle, salida de la fuente y síntesis de cargas de trabajo detienen la compilación cuando se renderiza el nodo. El bloque artifacts se escribe de forma idéntica en una Recipe y en una FeatureRecipe — los mismos tres modos, la misma regla de clave a salida y el mismo comportamiento ante colisiones — y por eso esa parte de esta descripción se lee igual en ambos tipos; un ejemplo escrito para uno se traslada al otro sin cambios. En la forma de objeto, $import no debe coincidir con ^oci://; un valor que coincide se rechaza. Claves: la clave nombra la salida de la entrada, por lo que está restringida a un único nombre de archivo: comienza con una letra o un dígito y continúa con letras, dígitos, puntos, guiones o guiones bajos. Los puntos después del primer carácter conservan las extensiones que llevan las claves de artefacto (main.tf, template.yaml, serviceaccount.yaml). Una / haría que una clave nombrara una ruta en lugar de un archivo, y un . inicial admitiría .., que nombra una ubicación fuera del directorio de salida — la clase del primer carácter rechaza ambos. Para una importación de biblioteca, la clave nombra el directorio bajo el que se anidan los archivos del bundle, por lo que se aplica la misma restricción. Patrón: ^[A-Za-z0-9][A-Za-z0-9._-]*$. |
omits | object[] | no | Qué excluir de lo que renderiza la fuente de esta FeatureRecipe — para una fuente tomada tal cual que renderiza algo que la Release no debe entregar: un documento que renderiza un chart descargado, como un Secret que contiene una clave que el chart genera de nuevo en cada renderizado, un servicio, un volumen o una configuración que incluye un archivo compose descargado, o un recurso que declara una plantilla de CloudFormation descargada. La mayoría de las FeatureRecipes nunca lo necesitan. Cada entrada nombra una unidad que renderiza la fuente por su tipo, su nombre y, cuando la entrada los indica, su namespace y el subchart del que procede, cada uno en el vocabulario del proveedor que renderiza la fuente — para un chart, un documento por su propio kind y su metadata.name; para un archivo compose, un service, un volume o un config por su clave bajo services:, volumes: o configs:; para una plantilla de CloudFormation, un recurso por su Type y su ID lógico. Ese proveedor excluye cada unidad con la que coincide una entrada, y con qué coincide una entrada, y qué rechaza el proveedor a causa de una entrada, es el contrato documentado propio de ese proveedor. Un proveedor que no puede excluir nada rechaza una FeatureRecipe que declara esta clave antes de que se renderice nada. Solo se filtra lo que renderiza source: — una entrada de workload: o de artifacts: nunca —, por lo que la clave requiere source. Cada valor es una plantilla, evaluada con respecto al contexto con el que se evalúa valuesMapping. El when de una entrada se evalúa primero, y una entrada cuyo when renderiza un valor falsy se descarta. Cada entrada que permanece activa debe excluir algo: una entrada activa que no coincide con nada de lo que renderizó la fuente detiene la compilación, nombrando la entrada. La fuente se sigue renderizando por completo — cada plantilla de un chart se sigue ejecutando, por lo que una plantilla que falla sigue haciendo fallar la compilación — y solo se excluye su salida. La clave se escribe de forma idéntica en una Recipe y en una FeatureRecipe. Al menos 1 entrada. |
injectMapping | string | no | Plantilla Go inline opcional evaluada durante la fase de intercepción previa al renderizado, una vez por cada componente al que llega la vinculación, con respecto al contexto de plantilla de ese componente: lee ‘.context’ y ‘.features’ del componente y ‘.attachment_name’, ‘.values’, ‘.infra’ y ‘.locals’ de la vinculación, diga lo que diga executionScope, y una referencia a ‘.boundary’, que el contexto de ningún componente lleva, detiene la compilación. Produce un diccionario JSON/YAML que el compilador Go fusiona en profundidad de forma nativa sobre el pipe de memoria ‘.context.inject’ del Invocador. Se usa para la mutación del lado del Invocador, sin Wasm, de variables de entorno y contratos de entrega. |
pipeline | object[] | no | Lista secuencial de pasos de pipeline Wasm que se ejecutan después del renderizado sobre el conjunto de documentos renderizados, cada uno de los cuales devuelve parches RFC 6902 y efectos secundarios. |
executionScope | string (enum) | no | Indica si la Generación de recursos de esta FeatureRecipe se ejecuta por componente (el valor predeterminado) o una vez por cada vinculación a un límite. Las FeatureRecipes con ámbito boundary se deduplican por (boundary_path, instancia de FeatureRecipe) y cada plantilla excepto el injectMapping lee un contexto de plantilla con ámbito boundary: los pilares .boundary.* en lugar de los pilares .context.* por componente, cuya referencia detiene la compilación. El injectMapping se ejecuta una vez por cada componente al que llega la vinculación independientemente de executionScope, por lo que lee el contexto de ese componente y nunca .boundary. Valores permitidos: "component", "boundary" Valor predeterminado: "component" |
readsCallerRenderFacts | booleano | no | Declara que las plantillas de esta FeatureRecipe leen lo que renderizaron los Components que se conectan a aquel al que está vinculada: los hechos de renderizado que el proveedor de cada uno de esos invocadores informa sobre su propia salida. Cuando es true y la FeatureRecipe renderiza por componente, cada vinculación suya se renderiza después de que se haya renderizado cada Component de la compilación, en lugar de justo después del Component al que está vinculada, de modo que el renderizado de cada invocador está completo antes de que se evalúe la vinculación. Cuando es false o está ausente, la entrada de ningún invocador en ‘.context.used_by’ lleva hechos de renderizado, la vinculación se renderiza justo después de su Component salvo que readsTargetRenderFacts sea true, y la compilación se detiene ante una plantilla escrita inline en esta FeatureRecipe que lee los hechos de renderizado de un invocador bajo ‘.context.used_by’. Valor predeterminado: false |
readsTargetRenderFacts | booleano | no | Declara que las plantillas de esta FeatureRecipe leen lo que renderizaron los Components a los que está conectado aquel al que está vinculada: los hechos de renderizado que el proveedor de cada uno de esos destinos informa sobre su propia salida, en cada entrada de ‘.context.uses’. Cuando es true y la FeatureRecipe renderiza por componente, cada vinculación suya se renderiza después de que se haya renderizado cada Component de la compilación, en lugar de justo después del Component al que está vinculada, de modo que el renderizado de cada destino está completo antes de que se evalúe la vinculación. Es el mismo renderizado posterior que provoca readsCallerRenderFacts, por lo que establecer cualquiera de las dos claves, o ambas, hace que la vinculación se renderice entonces. Cuando es false o está ausente, ninguna entrada de ‘.context.uses’ lleva hechos de renderizado, la vinculación se renderiza justo después de su Component salvo que readsCallerRenderFacts sea true, y la compilación se detiene ante una plantilla escrita inline en esta FeatureRecipe que lee los hechos de renderizado de un destino bajo ‘.context.uses’. Valor predeterminado: false |
assertions | mapa de string | no | Validación entre campos en tiempo de compilación. Cada entrada es una aserción con nombre: la clave es un identificador de regla estable que aparece en los mensajes de error; el valor es una cadena de plantilla Go con semántica de detención {{ fail "message" }}. Varias aserciones con nombre por entidad se evalúan por instancia en el orden declarado por el autor; la primera aserción que falla detiene la compilación. Las aserciones de FeatureRecipe se evalúan después del enlace de la receta y después de evaluar los provides, antes del renderizado, y expresan invariantes de implementación del chart o módulo concreto que la FeatureRecipe usa como fuente. Contexto de la plantilla: .values / .infra / .uses / .features / .metadata más .provides / .locals / .recipe. El evaluador usa missingkey=error: las referencias a claves no definidas provocan una detención con un diagnóstico no-such-key. Como la referencia simple provoca la detención antes de que pueda ejecutarse cualquier valor alternativo, un default simple no proporciona un valor alternativo para un campo opcional en esta superficie — protege la referencia con hasKey, o usa la función auxiliar optional, que realiza directamente la comprobación de presencia. Leer la clave mediante index tampoco proporciona uno: index provoca una detención ante una clave de mapa que el mapa no contiene, nombrando la clave. |
No se permiten propiedades adicionales.
featurerecipe.spec.omits[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
kind | string | sí | El tipo de la unidad que se excluye, en el vocabulario del proveedor que renderiza la fuente: para un chart, el kind propio de un documento renderizado, como Secret; para un archivo compose, service, volume o config; para una plantilla de CloudFormation, el Type de un recurso, como AWS::S3::Bucket. Nombra un tipo que la fuente renderiza y no tiene relación con el kind: que lleva un source: estructurado. Una plantilla. |
name | string | sí | El nombre de la unidad que se excluye, en el vocabulario del proveedor que renderiza la fuente: para un chart, el metadata.name propio de un documento renderizado; para un archivo compose, la clave de la unidad bajo services:, volumes: o configs:; para una plantilla de CloudFormation, el ID lógico del recurso, su clave bajo Resources. Una plantilla. |
namespace | string | no | El namespace en el que está la unidad que se excluye, cuando la entrada debe coincidir solo con una unidad de ese namespace — para un proveedor cuya salida tiene namespaces, como ocurre con los documentos renderizados de un chart. Si está ausente, o si se renderiza como la cadena vacía, la entrada coincide con una unidad de su tipo y nombre sea cual sea su namespace. Un archivo compose y una plantilla de CloudFormation no tienen namespaces, y sus proveedores rechazan una entrada que nombre uno. Una plantilla. |
subchart | string | no | El subchart del que procede la unidad que se excluye, cuando la entrada debe coincidir solo con la copia que renderiza un subchart — para una fuente ensamblada a partir de fuentes anidadas, como lo está un chart a partir de sus subcharts. Para un chart, el nombre propio del subchart, o el alias que le da la dependencia de su padre, con los nombres de un subchart anidado unidos por / desde el más externo: operator, o operator/webhooks. La entrada coincide entonces con un documento renderizado desde los templates/ o los crds/ propios de ese subchart, y no con uno que renderiza el propio chart ni con uno que renderiza un subchart anidado dentro de él. Si está ausente, o si se renderiza como la cadena vacía, la entrada coincide con una unidad de su tipo y nombre sea cual sea su procedencia. Un chart que no renderiza ningún subchart con ese nombre detiene la compilación, nombrando la entrada. Un archivo compose y una plantilla de CloudFormation no tienen subcharts, y sus proveedores rechazan una entrada que nombre uno. Una plantilla. |
when | string | no | Plantilla Go inline que se evalúa antes de los demás campos de la entrada. Cuando renderiza un valor falsy, la entrada se descarta: sus demás campos no se evalúan, no se excluye nada por su causa y no está obligada a coincidir con nada. Un when vacío o ausente conserva la entrada. La veracidad sigue la convención estándar para la salida de plantillas de tipo booleano: las cadenas true/True/TRUE, cualquier número distinto de cero y cualquier otra cadena no vacía son verdaderos, mientras que false/False/FALSE, la cadena vacía y el cero son falsos. Un when cuyo renderizado falla detiene la compilación. |
No se permiten propiedades adicionales.
featurerecipe.spec.pipeline[]
| Propiedad | Tipo | Obligatoria | Descripción |
|---|---|---|---|
id | string | sí | Un identificador programático para este paso, único entre los pasos de este pipeline: un documento que declara un mismo id en dos de sus pasos se rechaza cuando se lee. Un paso posterior del mismo pipeline lee las salidas de este paso como .steps.<id>.outputs. Patrón: ^[a-zA-Z0-9_]+$. |
plugin | string | sí | La referencia a la entidad Plugin que ejecuta este paso, siempre calificada por el tipo de socket propio del plugin: <pluginType>/<name> con una versión opcional, como en parser/yaml o parser/yaml:1.0.0. La calificación es obligatoria y no una forma entre varias — un name:version sin calificar se rechaza, porque dos sockets pueden contener un plugin con el mismo nombre y la calificación es lo que hace que la entidad pueda resolverse. La compilación resuelve la entidad en su artefacto .wasm direccionado por contenido — localizado a partir de la identidad del plugin y del registro configurado, con su digest fijado en el archivo de bloqueo — y carga los bytes. Aquí no se acepta una simple referencia a un .wasm o a un artefacto. |
function | string | sí | La función Wasm exportada que se invoca. |
with | string | no | Plantilla Go inline que se evalúa como un mapa JSON/YAML que satisface estrictamente el esquema de entrada explícito de este plugin. |
optional | booleano | no | Cuando es true, un fallo de este paso (un trap del guest, un parche dirigido a un documento que no está en el conjunto, un parche mal formado o un diagnóstico con gravedad de detención) se rebaja a una advertencia bien visible: se restaura el conjunto de documentos anterior al paso, se descarta la salida de este paso y el pipeline continúa. Cuando es false o está ausente, cualquier fallo de un paso detiene la compilación después de restaurar el conjunto de documentos anterior al paso. |
when | string | no | Plantilla Go inline que se evalúa al recorrer el pipeline. Cuando renderiza un valor falsy, el paso se salta — una transferencia directa: el conjunto de documentos pasa sin cambios al siguiente paso, sin aportar parches, efectos secundarios ni registro del paso. Un when vacío o ausente siempre ejecuta el paso. La veracidad sigue la convención estándar para la salida de plantillas de tipo booleano: las cadenas true/True/TRUE, cualquier número distinto de cero y cualquier otra cadena no vacía son verdaderos, mientras que false/False/FALSE, la cadena vacía y el cero son falsos. when y optional son independientes: un paso puede declarar ambos. |
No se permiten propiedades adicionales.