Arquitectura de Provider
Un proveedor renderiza los tipos de entrada de una Recipe en archivos de manifiesto nativos del proveedor. Cuando una Recipe declara capability: helm, capability: compose o cualquier otro nombre de proveedor, el compilador despacha el renderizado al proveedor que sirve ese nombre. Este capítulo trata cómo se realiza un proveedor como Plugin de renderizado de proveedores, cómo funciona el despacho y el contrato del socket de plugins que vincula el compilador con cada proveedor.
Lo que este capítulo no trata: el modelo de composición de tres tipos de entrada (source: + valuesMapping:, workload:, artifacts: — cada uno acepta contenido en línea o $import:) que una Recipe usa para producir su salida. Ese modelo es transversal a todos los proveedores y se encuentra en ../../architecture/16-recipe-input-composition.md, incluida la Matriz de capacidades por Provider que indica qué tipo de entrada admite cada proveedor.
El Plugin de renderizado de proveedores
El renderizado Provider lo proporciona un Plugin con pluginType: provider. El Plugin de renderizado de proveedores:
- sirve uno o más nombres de proveedor — declarados en
spec.provider.capabilities. El nombre de proveedor que nombra una Recipe (spec.capability: helm) se vincula al Plugin de renderizado de proveedores cuya listaspec.provider.capabilitiesincluye ese nombre. Cuando más de un Plugin sirve el mismo destino, el espacio de trabajo elige entre ellos mediante un enlace de proveedor en.aggrega-config.yaml, resuelto enaggrega pully registrado en el archivo de bloqueo; sin enlace y con exactamente un candidato se usa ese candidato, y sin enlace y con más de un candidato la compilación se detiene de forma visible, nombrando los plugins candidatos. - lleva sus metadatos del socket de proveedor en el mismo bloque —
spec.providercontiene la lista de capacidades anterior junto con el resto de las declaraciones del proveedor.spec.provider.workloadSchemaes una declaración JSON Schema 2020-12 que documenta cómo el tipo Workload, propiedad de la plataforma, se traduce a la salida nativa de este proveedor; el catálogo de la biblioteca estándar la declara en los proveedores que sintetizan, como contrato de traducción documentado.spec.provider.wellKnownAnnotationsenumera las anotaciones de límiteaggrega.ai/que lee el proveedor. La compatibilidad con entradas sintetizadas (workload:) es una propiedad del proveedor, aplicada en tiempo de renderizado — no determinada por la presencia deworkloadSchema.
Consulta ../entities/plugin.md para la superficie de autoría completa, a nivel de campo, de la entidad Plugin, incluido el bloque spec.provider.
Despacho por proveedor
Cada Recipe declara exactamente un capability: al principio de su spec. El compilador lee este campo y despacha el renderizado al proveedor que sirve el nombre. Una Recipe no puede apuntar a varios proveedores a la vez. La composición multiproveedor ocurre a nivel de Release: un límite puede contener componentes de proveedores distintos, y los contribuidores de cada proveedor en la ruta de ensamblado evaluada del límite se ensamblan de forma independiente — un ensamblado por tupla (path, provider).
La ruta de despacho para un solo nodo:
- El compilador resuelve la URI de la Recipe para este nodo mediante la búsqueda de tres niveles del Manifest en la sección de mapeo del proveedor de destino. La agrupación por eje de proveedor del Manifest es lo que hace de «el mismo Component, Recipes distintas para proveedores distintos» un patrón natural.
- El
spec.capabilityde la Recipe resuelta identifica el nombre de proveedor al que despachar. - El compilador vincula el proveedor para ese nombre: resuelve el Plugin de renderizado de proveedores cuya lista
spec.provider.capabilitiesincluye el nombre y renderiza mediante el guest de ese Plugin. El renderizado es solo Wasm — no hay ningún renderizador dentro del host al que recurrir, así que un nombre de proveedor que no se resuelve en ningún Plugin que lo sirva detiene la compilación de forma visible en el momento del enrutamiento. - El proveedor se invoca con el contexto de renderizado por nodo (valores de los pilares, proyecciones
.context.*, los tipos de entrada de la Recipe). - El proveedor devuelve la salida renderizada. El compilador enruta los archivos renderizados al ensamblador por
(path, provider)indexado por eldirectory:evaluado del límite unido alsubDirectory:por componente. Dos límites que se evalúan a la misma ruta con el mismo proveedor comparten un ensamblador — el patrón canónico es un límite padre más dos límites hijos condirectory: "{{ .parent_boundary.directory }}"que confluyen en un único ensamblado fusionado.
Consulta ../entities/manifest.md para la forma de despacho por eje de proveedor del Manifest, y ../entities/recipe.md para la declaración de proveedor único del lado de la Recipe. El modelo de ensamblado por (path, provider) y la lista de variables permitidas de las plantillas de ruta que controla las rutas evaluadas están documentados en ../path-template-variables.md.
El contrato de los plugins Wasm
El renderizado Provider se ejecuta dentro de un sandbox de WebAssembly. El compilador Go es el host; el Plugin de renderizado de proveedores es el guest. Para cada nodo, el compilador entrega al plugin el contexto de renderizado del nodo, y el plugin devuelve los archivos que ha renderizado. Este contrato es uniforme para todos los proveedores:
- Una codificación binaria canónica en ambas direcciones. El compilador codifica el contexto de renderizado — los valores y las vinculaciones del nodo, el
.workloadanalizado, las entradas de artefacto evaluadas, el listado solo de nombres de un.sourceresuelto y los metadatos del límite — como CBOR canónico (RFC 8949 §4.2.1) y lo entrega al plugin. El plugin responde en la misma codificación con la lista de archivos que ha renderizado — cada uno, una ruta relativa a la raíz de salida del nodo y los bytes exactos que deben escribirse allí, opcionalmente con el formato del archivo — junto con cualquier diagnóstico. Cada export del socket, desde renderizar un nodo hasta ensamblar un límite y cablear un enlace entre límites, lleva esta codificación en ambas direcciones, y el kit de desarrollo de plugins de cada lenguaje la decodifica y la codifica para el plugin. Una respuesta que no tenga la forma de salida del export en esta codificación detiene la compilación. El contrato de los plugins documenta la carga útil de cada export. - Sin acceso al sistema de archivos. Los Plugins no pueden leer archivos arbitrarios del sistema de archivos del host. Una fuente que nombra una Recipe — un chart en un registro, un módulo en un repositorio — la resuelve el compilador antes de que se ejecute el plugin; el plugin recibe un listado solo de nombres de ella y pide al compilador los archivos que selecciona mediante una función del host, que responde solo para los archivos bajo la fuente de ese nodo.
- Sin acceso a la red. Los Plugins son deterministas y herméticos, y no abren ninguna conexión propia. Una entrada externa que un plugin necesita mientras renderiza — un esquema remoto al que hacen referencia los valores de un chart — se solicita mediante la función del host para entradas externas del compilador, que responde a partir del contenido que el espacio de trabajo fijó para esa referencia.
- Salida determinista. Con una entrada idéntica y la misma versión del plugin, un plugin debe producir una salida idéntica byte a byte. Este es el contrato que hace que la garantía de salida idéntica byte a byte del compilador se mantenga de extremo a extremo a través de la capa de plugins. Una compilación ejecutada con
--verify-determinismrenderiza cada nodo dos veces y se detiene cuando los dos renderizados de un nodo difieren.
La arquitectura de sockets de plugins en el nivel más amplio de la extensibilidad, incluidos los demás sockets Wasm del pipeline de compilación (los roles de transformación y de veredicto del socket de gobernanza), se encuentra en ../../architecture/14-extensibility.md.
Los proveedores de la biblioteca estándar de Aggrega
Los proveedores helm, helm-chart, compose, terraform y cloudformation forman juntos el conjunto de proveedores de la biblioteca estándar. Cubren los destinos de despliegue habituales sin que los equipos empresariales tengan que crear sus propios proveedores.
helm admite los tres tipos de entrada: procedente de una fuente (un chart de Helm upstream obtenido mediante el SDK de Helm, con la salida del valuesMapping de la Recipe como sobrescrituras del chart), sintetizado (YAML de Kubernetes plano — un objeto controlador elegido por el form del Workload (Deployment, StatefulSet, DaemonSet, Job o CronJob) más Services y PVC — emitido a partir de un Workload analizado) y artefactos (archivos YAML independientes junto a la salida del chart). Consulta la Matriz de capacidades por Provider en ../../architecture/16-recipe-input-composition.md para saber cuáles de los tres tipos acepta.
helm-chart admite el modo procedente de una fuente (composición de chart paraguas: un chart por límite, un subchart por componente) y artifacts: que lo acompañan, en ambas formas de autoría. Aggrega procesa primero como plantilla de Go una entrada artifacts: cargada con $import: y luego la inyecta en el directorio templates/ del chart antes del renderizado; una entrada artifacts: con contenido en línea se evalúa de la misma manera y se coloca en la raíz del subchart, sin procedencia fusionada, donde las propias plantillas del chart la leen mediante .Files.Get / .Files.Glob de Helm. Una Recipe independiente compuesta solo de artefactos no es uno de los tipos que declara, ni tampoco el tipo sintetizado: el chart paraguas orquesta subcharts, mientras que el tipo Workload es un concepto hoja que pertenece a cada subchart (el dominio del proveedor helm).
compose admite procedente de una fuente (carga un archivo compose y fusiona en profundidad la superposición del valuesMapping), sintetizado (emite services: + volumes: + networks: de compose a partir de un Workload analizado para las formas stateless y stateful, con un manejo degradado de volúmenes para persistentTemplate — los PVC por réplica se reducen a un único volumen con nombre compartido, con una advertencia; las formas daemon, scheduled y task no tienen correspondencia en compose y se detienen de forma visible) y artefactos (fragmentos de compose cuyas claves de nivel superior services: / networks: / volumes: / configs: se fusionan en el docker-compose.yaml combinado por límite). Los artefactos pueden acompañar a cualquiera de los otros dos tipos, y una Recipe independiente compuesta solo de artefactos — artifacts: sin source: y sin workload: — también es un tipo que este proveedor declara: sus fragmentos se fusionan con las mismas reglas, de modo que el nodo aporta exactamente lo que declara y no necesita ningún Workload que ocupe el lugar de un cómputo que no tiene.
terraform admite procedente de una fuente (incorpora un módulo de Terraform tal cual y suministra la salida del valuesMapping como argumentos del bloque module de ese componente en la configuración raíz del límite) y artefactos (emite un cuerpo HCL o .tf.json escrito por el autor tal como lo evalúa su plantilla, sin reescribirlo). No ofrece el tipo de entrada sintetizado — no existe una correspondencia fiel entre el tipo Workload de la plataforma y recursos de Terraform arbitrarios. El proveedor emite configuración y nunca ejecuta Terraform; los valores que dependen del tiempo de ejecución permanecen como cadenas de interpolación ${ ... } que el runtime de Terraform resuelve en el momento del apply.
cloudformation renderiza un límite en una única plantilla de stack de AWS CloudFormation, ensamblando los fragmentos de recursos que escriben sus componentes en una única plantilla en JSON puro, exponiendo los provides de cada componente como Outputs del stack y cableando las aristas uses como Fn::GetAtt dentro de un stack y como Fn::ImportValue / Fn::GetStackOutput entre stacks. Admite entradas procedentes de una fuente y de artefactos, y emite configuración sin ejecutar nunca CloudFormation; los valores que solo existen en tiempo de ejecución permanecen como funciones intrínsecas de CloudFormation.
El índice de referencia de Provider te dirige a la página de referencia propia de cada proveedor; qué tipos de entrada acepta cada uno lo responde la matriz de capacidades en ../../architecture/16-recipe-input-composition.md.
Proveedores personalizados
Los equipos empresariales que crean sus propios proveedores siguen el mismo patrón que la biblioteca estándar: crear un Plugin de renderizado de proveedores (pluginType: provider) que declare en spec.provider.capabilities el nombre o los nombres de proveedor que sirve, junto con el resto de sus metadatos spec.provider, y luego publicar el artefacto Wasm que implementa el contrato de renderizado descrito arriba. El compilador trata los proveedores personalizados de forma idéntica a los proveedores de la biblioteca estándar; el despacho por proveedor funciona con el nombre de proveedor que declara la Recipe.
Cómo crear uno está documentado en lugar de aplazado. Crear un proveedor construye de principio a fin un guest de proveedor funcional — el autoinforme describe(), la compilación, la entidad Plugin, la vinculación y un renderizado cuya salida puedes leer. La Guía para desarrolladores de plugins Wasm es la referencia para la entidad y el ciclo de vida de publicación, y el contrato de los plugins documenta las formas de carga útil y de resultado de cada socket. Los guests se escriben en Go, Rust o TypeScript con el kit de desarrollo de plugins.