Visión general de la referencia de entidades
El vocabulario de escritura de Aggrega comprende Aggregate, Component, Feature, Recipe, FeatureRecipe, Plugin, Manifest, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary y ArtifactLibrary, además del tipo Workload, propiedad de la plataforma, incrustado en la entrada sintetizada de una Recipe. Cada entidad es un documento YAML conforme a un JSON Schema; cada campo, palabra clave y referencia entre entidades que describe esta referencia forma parte de ese contrato de escritura.
Este conjunto de capítulos cubre la superficie de escritura: qué campos acepta cada entidad, qué significa cada campo para el autor y cómo interactúan los campos entre entidades (el implements: de una Recipe que nombra el Component que implementa, el puntero manifest: de una Release a un Manifest, containers.<name>.attachments de un Workload que hace referencia a slots declarados en el featuresSchema del Component). El papel conceptual de cada entidad — por qué la taxonomía tiene la forma que tiene, qué dominio es dueño de qué entidad, cómo los cuatro dominios separan las responsabilidades de escritura — se describe en ../architecture/04-entity-taxonomy.md. El papel arquitectónico del tipo Workload como uno de los tres tipos de entrada de una Recipe se describe en ../architecture/16-recipe-input-composition.md.
Cómo está organizada esta referencia
Dos superficies documentan el vocabulario de escritura, y responden a preguntas distintas.
Cada tipo enumerado arriba tiene una referencia de esquema generada. Esas páginas se generan a partir de los esquemas que publica el propio compilador, y schema/README.md indexa el conjunto completo: tipos de entidad, formatos de transmisión de los plugins y archivos del espacio de trabajo por igual. Recurre a la referencia de esquema para responder a «qué puede contener este documento»: cada campo, su tipo, si es obligatorio y las restricciones que impone el envelope.
Las páginas siguientes son las guías de escritura. Están escritas a mano para enseñar lo que el esquema no puede: para qué sirve un tipo, cómo interactúan sus campos con otros tipos, qué forma de escritura conviene en cada situación y las convenciones que sigue el catálogo de la biblioteca estándar. Recurre a una guía de escritura para responder a «cómo escribo uno, y por qué tiene esta forma».
Referencia por entidad
- Aggregate — el artefacto de intención declarativa del desarrollador. Declara los componentes, su topología mediante
uses, los contratos de parámetros para la variación por entorno y los attachments de Feature. - Component — entidad de catálogo escrita por el Platform Architect que define un tipo de componente reutilizable. Declara sus esquemas
valueseinfra(cada uno una declaración JSON Schema 2020-12 en forma compacta o completa), su contrato de salidaprovides, su contrato de aristas entrantesusesSchemay los slots de credenciales mediantefeaturesSchema. - Feature — entidad de catálogo escrita por el Platform Architect para una responsabilidad transversal (sidecar de monitorización, enmascaramiento de datos, política de enrutamiento). Declara sus esquemas
valueseinfra(cada uno una declaración JSON Schema 2020-12), los selectores de attachmentappliesToy las restricciones de interoperabilidad. - Recipe — traducción escrita por Ops de un Component a un provider específico. Compone tres tipos de entrada (
source:+valuesMapping:,workload:,artifacts:— cada uno acepta contenido en línea o$import:según el vocabulario unificado de importación de archivos) más un bloqueprovidesque forma el contrato de inyección hacia el llamador. - FeatureRecipe — traducción escrita por Ops de una Feature a un provider específico. Usa el mismo contrato de tres tipos de entrada que la Recipe, más un
injectMappingque intercepta el pipe de inject para reescribir variables del lado del llamador. - Plugin — plugin WebAssembly direccionado por contenido. Declara el único tipo de socket que implementa —
provider,linter,pipeline-step,governance,cli,parseroimporter—, su versión de ABI y las capacidades que sirve ese tipo de socket. Un Plugin de renderizado de providers (pluginType: provider) declara el nombre o los nombres de provider que sirve enspec.provider.capabilitiesy lleva los metadatos de su socket de provider —workloadSchemaywellKnownAnnotations— en ese mismo bloquespec.provider. - Manifest — tabla de mapeo por proyecto. Vincula los tipos abstractos Component y Feature con URI concretos de Recipe y FeatureRecipe, bajo
componentsyfeatures, con un orden de búsquedaname>typecon versión >typesin versión. - Release — enrutador de despliegue por entorno. Vincula un Aggregate con un Manifest, asigna los componentes a límites físicos, proporciona los valores de parámetros por entorno y adjunta las Features gestionadas por Ops.
Entidades de biblioteca
Los cuatro tipos de biblioteca son de nivel 3: entidades de reutilización opcionales. Un catálogo declara una cuando el mismo contenido se repite en sus entidades, y prescinde de ellas en caso contrario. Cada una contiene un único tipo de contenido, y el fragmento de una referencia (#/schemas/, #/mappings/, #/workloads/, #/artifacts/) indica a qué biblioteca se dirige una referencia.
- SchemaLibrary — definiciones JSON Schema 2020-12 reutilizables más helpers parametrizados opcionales, referenciados desde los esquemas de un Component o de una Feature mediante
$ref: <Library>#/schemas/<name>. - MappingLibrary — fragmentos de plantillas Go reutilizables, importados en el
valuesMapping:de una Recipe o de una FeatureRecipe mediante$import: <Library>#/mappings/<name>. - WorkloadLibrary — contenido Workload reutilizable, importado en el
workload:de una Recipe o de una FeatureRecipe mediante$import: <Library>#/workloads/<name>. - ArtifactLibrary — paquetes reutilizables de archivos de salida auxiliares, importados en los
artifacts:de una Recipe o de una FeatureRecipe mediante$import: <Library>#/artifacts/<name>. Un paquete es la unidad de reutilización: una importación se expande en una salida por cada archivo del paquete.
Tipos propiedad de la plataforma
- Workload — tipo del compilador propiedad de la plataforma (no una entidad de catálogo escrita por el usuario). Se incrusta en el campo
workload:de una Recipe (en línea o mediante$import:); describe la forma de despliegue que el provider sintetiza en manifiestos nativos del provider.