Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

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 values e infra (cada uno una declaración JSON Schema 2020-12 en forma compacta o completa), su contrato de salida provides, su contrato de aristas entrantes usesSchema y los slots de credenciales mediante featuresSchema.
  • 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 values e infra (cada uno una declaración JSON Schema 2020-12), los selectores de attachment appliesTo y 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 bloque provides que 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 injectMapping que 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, parser o importer —, 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 en spec.provider.capabilities y lleva los metadatos de su socket de provider — workloadSchema y wellKnownAnnotations — en ese mismo bloque spec.provider.
  • Manifest — tabla de mapeo por proyecto. Vincula los tipos abstractos Component y Feature con URI concretos de Recipe y FeatureRecipe, bajo components y features, con un orden de búsqueda name > type con versión > type sin 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.