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

La taxonomía de entidades

La arquitectura de Aggrega se organiza en cuatro dominios, cada uno propiedad de un perfil distinto y que alberga tipos de entidad específicos, más una capa de bibliotecas de nivel 3 — el tercer nivel del modelo de niveles de entidades de la referencia del lenguaje — que contiene contenido reutilizable de esquemas, mapeos, workloads y artefactos. La vista general siguiente muestra cómo se relacionan entre sí los cuatro dominios y las bibliotecas de nivel 3; cada sección que sigue se abre con un diagrama de sus propias entidades, en el que una entidad de otro dominio se dibuja con un contorno discontinuo. Las superficies de autoría detalladas (campos, esquemas, ejemplos) de cada entidad están en el catálogo de entidades de la referencia del lenguaje.

graph TD
    Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
    Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
    Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
    Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
    Libs["<b>Tier 3: Libraries</b>"]

    Intent -->|"requests, attaches"| Catalog
    Intent -->|"binds via"| Routing
    Routing -->|"attaches"| Catalog
    Catalog -->|"resolved to"| Infra
    Routing -->|"resolves, renders via"| Infra
    Catalog -.->|"$ref"| Libs
    Infra -.->|"$import"| Libs

El corpus abarca cuatro dominios más la capa de bibliotecas de nivel 3:

#EntidadDominioRol
1AggregateDominio 1 — Intención del desarrolladorPlano de la topología de la aplicación
2ComponentDominio 2 — Platform CatalogInterfaz abstracta de nodo de cómputo
3FeatureDominio 2 — Platform CatalogRasgo operativo (incluidas las Features de credenciales)
4RecipeDominio 3 — Base de infraestructuraImplementación de un Component, por proveedor
5FeatureRecipeDominio 3 — Base de infraestructuraImplementación de una Feature, por proveedor
6PluginDominio 3 — Base de infraestructuraPlugin WebAssembly direccionado por contenido (renderizado de proveedores, pasos de pipeline, linting)
7ManifestDominio 4 — Enrutamiento y políticasArchivo de bloqueo de dependencias que asigna interfaces a Recipes
8ReleaseDominio 4 — Enrutamiento y políticasEnrutador de despliegue que vincula el Aggregate con el Manifest
9SchemaLibraryNivel 3 — BibliotecasDefiniciones de JSON Schema 2020-12 reutilizables
10MappingLibraryNivel 3 — BibliotecasFragmentos de plantillas Go reutilizables
11WorkloadLibraryNivel 3 — BibliotecasFragmentos de plantillas de Workload reutilizables
12ArtifactLibraryNivel 3 — BibliotecasPaquetes de artefactos con nombre reutilizables

Esa tabla es el conjunto completo de tipos de entidad de autoría: los tipos que un autor declara en un campo kind:. El tipo Workload es contenido propiedad de la plataforma incrustado en la entrada sintetizada de una Recipe, y no una entidad de catálogo independiente (véase el capítulo 16), por lo que está deliberadamente ausente de la tabla anterior.

El Plugin es una entidad de autoría de primera clase — con su propio kind, su propio JSON Schema y su propio directorio de catálogo — propiedad de Platform Ops en el dominio 3. Un Plugin es una referencia direccionada por contenido a un artefacto WebAssembly, que declara el único tipo de socket que implementa. La taxonomía tiene siete miembros: provider (renderiza nodos de la IR en artefactos nativos del proveedor), linter (emite diagnósticos sobre el contenido escrito), pipeline-step (un paso de una feature-recipe-pipeline), governance (desempeña un rol de gobernanza — transformar etiquetas o anotaciones, o devolver un veredicto de aceptación o rechazo sobre el grafo de la IR o sobre los artefactos renderizados), cli (aporta un subcomando aggrega que un operador invoca en la línea de comandos), parser (convierte un texto fuente ajeno en un árbol estructurado canónico) e importer (convierte una fuente ajena de infraestructura o de definición de agentes en borradores de archivos de autoría de Aggrega). Un Plugin de renderizado de proveedor (pluginType: provider) es la unidad que atiende el renderizado de proveedor: declara en spec.provider.capabilities el nombre o los nombres de proveedor que renderiza y lleva el resto de los metadatos de su socket de proveedor en ese mismo bloque spec.provider. El compilador fija y enruta la referencia; el runtime de WebAssembly ejecuta los bytes; el compilador no interpreta lo que hace el plugin — el plugin es el transporte de la inteligencia específica del dominio que vive en WebAssembly. Su superficie de autoría y de metadatos está documentada en language-reference/entities/plugin.md.

Dominio 1: intención del desarrollador (el «qué»)

graph LR
    classDef ext stroke-dasharray:5 4;

    A["Aggregate<br/>The 'What'"]
    CC["Component"]:::ext
    CapC["Feature"]:::ext
    EB["Release"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    A -->|"Binds via"| EB
  • Rol: el desarrollador. Se centra exclusivamente en la arquitectura de IA, los bucles cognitivos y los requisitos de supervivencia de la aplicación. No necesita conocer CEL, OPA ni los puertos físicos.
  • 1. Aggregate: el plano declarativo basado en mapas de la topología de la aplicación. Tanto si actúa como Aggregate raíz que construye una Release como si es un módulo parametrizado y reutilizable, define components lógicos y adjunta, bajo features, las Features cuyo comportamiento es intención de la aplicación, con sus values; una Feature cuyas entradas son todas operativas la adjunta en cambio el operador en la Release (véase el dominio 4). Una credencial se solicita en esa misma superficie de adjunción features, mediante una Feature de credenciales: no hay un bloque separado para ello. Define requisitos de capacidad abstractos mediante parameters (contratos tipados escritos en el vocabulario de la forma compacta) y el estado de la carga útil mediante values. Las instancias de Component admiten un campo description opcional para la documentación y la representación en Studio. Promueve la convención «Zero-Port» (abstraer los puertos de red salvo que el código existente los requiera explícitamente), sin plataforma de destino ni namespace codificados de forma fija.

Dominio 2: Platform Catalog (las «interfaces e inteligencia»)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release"]:::ext
    CC["Component<br/>The Compute Interface"]
    CapC["Feature<br/>The Operational Trait"]
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -.->|"Requests"| CC
    A -.->|"Attaches"| CapC
    EB -.->|"Attaches"| CapC
    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
  • Rol: el Platform Architect. El «programador» de la plataforma. Sitúa cada componente en la ontología operativa, escribe las políticas programables (mutadores y validadores Wasm) y establece las etiquetas semánticas de duck typing.
  • 2. Component: la interfaz abstracta de un nodo de cómputo. Declara su forma base mediante la ontología de nube operativa (p. ej., component.aggrega.ai/type: server) y superpone su identidad cognitiva mediante etiquetas de duck typing (p. ej., model.aggrega.ai/capability: generative). Declara ranuras de credenciales mediante featuresSchema (obligatorias/opcionales, caja negra/transparentes) y usa schema: (JSON Schema 2020-12, normalmente escrito con la notación abreviada de la forma compacta) para validar estrictamente el bloque values opaco del desarrollador.
  • 3. Feature: un rasgo operativo modular (p. ej., enmascaramiento de datos, enrutamiento DNS, gestión de secretos). Usa selectores de etiquetas appliesTo para vincularse dinámicamente a etiquetas semánticas específicas. Al igual que los Components, declara ranuras de credenciales mediante featuresSchema para imponer el aprovisionamiento de claves de API. Lo fundamental es que usa metadata.annotations para marcar explícitamente elementos en el grafo IR plano, lo que indica a los validadores de políticas Wasm y a los plugins de renderizado posteriores cómo manejar la carga útil de configuración de la Feature.
    • Features de credenciales: la plataforma unifica la gestión de credenciales en la entidad Feature: una Feature con la etiqueta feature.aggrega.ai/kind: secret es una feature de credenciales, que define una interfaz de consulta hacia un almacén de secretos (p. ej., AWS Secrets Manager, HashiCorp Vault). Se adjunta bajo features: como cualquier otra Feature, en la misma superficie y con la misma forma; la etiqueta es un metadato que el catálogo lleva para describir lo que produce la adjunción, y ninguna rama del compilador la lee. No existe un kind separado de almacén de secretos ni de recipe de secretos: una FeatureRecipe de credenciales tiene la misma forma que cualquier otra FeatureRecipe, la pipeline de obtención y entrega es la misma para ambas y el contrato de entrega inject (env, file, arg) es compartido. Una entidad, una palabra clave de adjunción, una ruta de ejecución de modificadores a lo largo del renderizado; y las credenciales se asignan bajo features.type en el Manifest.

La ontología como etiqueta. La ontología de nube operativa se declara en metadata.labels["component.aggrega.ai/type"] en lugar de como un campo spec.type de nivel superior. Esta elección permite que el motor de selectores de etiquetas del compilador apunte directamente a los valores de la ontología: una Feature declara appliesTo: "component.aggrega.ai/type in (server, worker)" para adjuntarse dinámicamente a cada componente server o worker sin ninguna lógica Go nueva en el compilador central. La misma maquinaria de selectores se aplica a cada etiqueta de Aggrega, de modo que una Feature, un selector de socket o una asignación de límites de una Release lee la clave de etiqueta propia de un catálogo exactamente igual que lee esta.

component.aggrega.ai/type es la clave de Aggrega, y su conjunto de valores es cerrado: el esquema publicado del Component enumera las primitivas, y un documento que lleve cualquier otro valor se rechaza al cargarse, con E0215 nombrando la etiqueta y enumerando lo que acepta. Un catálogo que necesita una clasificación que Aggrega no define añade su propia clave de etiqueta junto a ella (el esquema del Component acepta cualquier clave de etiqueta adicional con un valor de cadena), de modo que un eje nuevo cuesta una clave propia y ninguna versión nueva del compilador, mientras que la clave reservada mantiene un único significado en todas partes. Eso es lo que hace que una Feature escrita contra component.aggrega.ai/type in (stateful-server) funcione con Components de autores que nunca se conocieron.

Dominio 3: base de infraestructura (las «implementaciones»)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    ENV["Manifest"]:::ext
    EB["Release"]:::ext
    CD["Recipe<br/>The Implementation"]
    CapD["FeatureRecipe<br/>The Binding"]
    T["Plugin<br/>The Wasm Plugin"]

    CC -.->|"Resolved to"| CD
    CapC -.->|"Resolved to"| CapD
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
    EB -->|"Renders via"| T
  • Rol: el ingeniero de infraestructura / Ops. Es responsable de la realidad física, la asignación de puertos de red y la lógica de plantillas.
  • 4. Recipe: la plantilla de traducción multiproveedor (p. ej., Helm o Docker Compose). Establece un contrato de API estricto 1:1 con el componente del catálogo mediante la palabra clave implements. La Recipe asigna los .values del desarrollador al formato físico. Codifica de forma fija los puertos de red físicos (p. ej., 5432) y lee los provides del destino a través de la tubería .context.uses, cumpliendo el contrato de inyección sin codificar de forma fija los nombres de las bases de datos.
  • 5. FeatureRecipe: asigna explícitamente una Feature a una implementación de infraestructura concreta mediante la palabra clave implements. Exige una capacidad del proveedor de destino en capability (p. ej., helm, compose). Como la plataforma unifica la gestión de credenciales en la entidad Feature, las FeatureRecipes manejan tanto funcionalidades operativas (enmascaramiento de datos, enrutamiento DNS, inyección de sidecars) como funcionalidades de credenciales (generación de CRD de bóvedas, montaje de volúmenes de secretos). Para cubrir todo este espectro, admite tres bloques de ejecución distintos:
    1. pipeline: un array secuencial de plugins WebAssembly (Wasm) para la mutación del Workload tras el renderizado (p. ej., inyectar un sidecar de Envoy mediante JSONPatch o montar un volumen de secretos).
    2. source y valuesMapping, workload, artifacts: los mismos tres tipos de entrada que lleva una Recipe; se usan para la generación de recursos y permiten a Ops renderizar plantillas estáticas de forma nativa (p. ej., generar una nueva CRD HTTPRoute o una CRD ExternalSecret) junto al componente base.
    3. injectMapping (interceptación previa al renderizado): un bloque de plantilla Go nativo que se ejecuta antes de que se renderice la Recipe base. Genera un diccionario JSON que el compilador fusiona de forma nativa y profunda sobre la tubería de memoria .context.inject del llamador, lo que permite la mutación de variables de entorno y cadenas de conexión en el lado del llamador, sin Wasm.
    • El patrón de FeatureRecipe de credenciales: cuando una FeatureRecipe implementa una Feature de credenciales (etiquetada con feature.aggrega.ai/kind: secret), se aplica el principio estándar del Plugin en dos partes: la pipeline encadena un plugin Fetcher (que genera la CRD específica de la bóveda) seguido de un plugin Injector (que monta el secreto en el contenedor de destino). La separación Fetcher/Injector maximiza la reutilización: pasar de AWS Secrets Manager a HashiCorp Vault solo requiere sustituir el plugin Fetcher; el Injector permanece idéntico.
  • 6. Plugin: el plugin WebAssembly direccionado por contenido. Un Plugin de renderizado de proveedor (pluginType: provider) es la unidad que convierte los tipos de entrada de una Recipe en el formato de archivo final serializado como cadena: declara en spec.provider.capabilities el nombre o los nombres de proveedor a los que sirve (p. ej., helm), anuncia una exportación render_node a la que el compilador despacha y lleva el resto de los metadatos de su socket de proveedor (workloadSchema, wellKnownAnnotations) en ese mismo bloque spec.provider. Los demás tipos de socket que puede declarar un Plugin son pipeline-step, linter, governance, cli, parser e importer. El compilador enruta la referencia fijada; el runtime de WebAssembly ejecuta los bytes.

Dominio 4: enrutamiento y políticas (el «pegamento»)

graph TD
    classDef ext stroke-dasharray:5 4;

    A["Aggregate"]:::ext
    EB["Release<br/>The Deployment Router"]
    ENV["Manifest<br/>The Dependency Lockfile"]
    CapC["Feature"]:::ext
    T["Plugin"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext

    A -->|"Binds via"| EB
    EB -.->|"Attaches"| CapC
    EB -->|"Uses"| ENV
    EB -->|"Renders via"| T
    ENV -->|"Resolves Interfaces to"| CD
    ENV -->|"Resolves Interfaces to"| CapD
  • Rol: el Platform Operator / DevOps.
  • 7. Manifest: el archivo de bloqueo de dependencias. Usa una asignación plana de URI: un diccionario components.type asigna los tipos de componentes del catálogo a URI de Recipe, y un diccionario features.type asigna los tipos de Feature a URI de FeatureRecipe. La resolución es una búsqueda directa de URI en el archivo de bloqueo y el catálogo; la determinación de la capacidad se deriva del campo spec.capability de cada Recipe resuelta en el momento de la compilación. Tras la resolución, cada entidad debe tener una asignación o el compilador se detiene. Para mantener un ecosistema DRY, los Manifests admiten un patrón de composición al estilo de Kustomize mediante la palabra clave extends, lo que permite que los manifiestos específicos de un entorno (como local o staging) hereden limpiamente de un manifiesto base global y solo declaren sus sobrescrituras específicas.
  • 8. Release: el enrutador. Vincula un aggregate con un manifest y asigna los componentes a límites físicos (p. ej., aws-eks-production). Para mantener un flujo de trabajo DRY, las Releases admiten herencia mediante la palabra clave extends, lo que permite que las releases específicas de un entorno hereden limpiamente de una release base global. Cumple el contrato abstracto del aggregate 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. Para proteger el Aggregate como fuente única de verdad, el esquema de la Release prohíbe mecánicamente un bloque values:: Ops no puede declarar values sobre ningún Component ni Feature desde una Release. La variación por entorno de los valores orientados al desarrollador fluye mediante el Parameter Hoisting: el desarrollador expone un campo tipado parameters.* en el Aggregate, la plantilla values del Component lo referencia y la Release proporciona el parámetro para su entorno. Los valores renderizados difieren entre entornos mientras el Aggregate, la superficie de autoría que determina qué valores existen y cómo fluyen, sigue siendo la fuente única de verdad. Consulta la restricción 4, «La Release no puede sobrescribir los valores del desarrollador», en Restricciones arquitectónicas y patrones recomendados para ver la prohibición a nivel de esquema enunciada explícitamente. Lo fundamental es que, para evitar Releases no rastreables que «mutan el aggregate», cuando una Release usa extends, el esquema de la Release rechaza la declaración de un aggregate (la restricción del esquema no permite declarar aggregate cuando se usa extends). La release hija debe corresponder exactamente a la misma intención del desarrollador que su release padre. El manifest, en cambio, pasa a ser opcional, lo que habilita el «enlace tardío»: Ops puede heredar toda la topología física pero sustituir quirúrgicamente el archivo de bloqueo de dependencias.
    • Adjunción de Feature: la Release también adjunta Features, bajo features en un límite o en un solo componente. Una Feature cuyas entradas son todas operativas la adjunta directamente, con su type y su infra; una Feature que adjuntó el Aggregate la dimensiona, escribiendo el infra de esa adjunción bajo el mismo nombre.

Por qué separar el Manifest de la Release. Separar el archivo de bloqueo de software (Manifest) del enrutador de despliegue (Release) permite una forma que ninguna de las dos entidades podría producir por sí sola: DevOps despliega una sola aplicación en varios enrutadores de despliegue regionales (distintas Releases que apuntan a distintas regiones de nube, todas haciendo referencia al mismo Manifest) sin duplicar los enlaces de Recipe entre entornos. Cada Release regional lleva su disposición de límites y sus parámetros específicos del entorno mientras consume el mismo archivo de bloqueo de software que proporciona el Manifest. El escalado multirregión se deriva de la separación de dominios, no de la duplicación del Manifest.

Nivel 3: bibliotecas (reutilización del catálogo)

graph LR
    classDef ext stroke-dasharray:5 4;

    CC["Component"]:::ext
    CapC["Feature"]:::ext
    CD["Recipe"]:::ext
    CapD["FeatureRecipe"]:::ext
    SL["SchemaLibrary<br/>JSON Schema definitions"]
    ML["MappingLibrary<br/>Go template fragments"]
    WL["WorkloadLibrary<br/>Workload template fragments"]
    AL["ArtifactLibrary<br/>Named artifact bundles"]

    CC -.->|"$ref"| SL
    CapC -.->|"$ref"| SL
    CD -.->|"valuesMapping $import"| ML
    CapD -.->|"$import"| ML
    CD -.->|"workload $import"| WL
    CD -.->|"artifacts $import"| AL
    CapD -.->|"$import"| AL
  • Rol: el Platform Architect (el mismo perfil que en el dominio 2), pero el rol solo entra en juego cuando el contenido del catálogo crece lo suficiente como para beneficiarse de la reutilización de esquemas entre un Component y otro o de la reutilización entre una Recipe y otra de plantillas, formas de workload o paquetes de artefactos. Los autores individuales y los catálogos pequeños funcionan sin ninguna entidad de nivel 3.
  • 9. SchemaLibrary: definiciones de JSON Schema 2020-12 reutilizables. Una biblioteca declara esquemas con nombre en spec.schemas: y ayudantes parametrizados opcionales en spec.templates: (con declaraciones $params: y referencias $instantiate: para la reutilización paramétrica). Las entidades del catálogo consumen las entradas de la biblioteca mediante la palabra clave estándar de JSON Schema $ref:, que apunta a la entrada de la biblioteca por identidad con la forma sin host <library>#/schemas/<name> (la versión procede del archivo de bloqueo, no de la referencia). Nombres en PascalCase, distribución mediante OCI, versión fijada en el archivo de bloqueo. Opcional, para catálogos que necesitan reutilizar esquemas entre un Component y otro: formas comunes como PodResources, PersistenceSpec, NodePool, MetricsServiceMonitor se repiten en cada Component de almacén de datos y en cada Component de workload, y las entradas de una SchemaLibrary eliminan esa repetición de la definición de cada Component.
  • 10. MappingLibrary: fragmentos de plantillas Go reutilizables. Una biblioteca declara plantillas con nombre en spec.mappings:. Las Recipes y las FeatureRecipes consumen las entradas de la biblioteca por identidad mediante valuesMapping: { $import: <library>#/mappings/<name> }. Un único modo de autoría (solo plantillas Go); no existe una ruta de autoría paralela en Jsonnet. Opcional, para catálogos que necesitan reutilizar mapeos entre una Recipe y otra: patrones comunes como la lógica de los helpers de los charts de Bitnami o los patrones compartidos de plantillas de pod se repiten en cada Recipe de almacén de datos que apunta al mismo proveedor, y las entradas de una MappingLibrary eliminan esa repetición de la definición de cada Recipe.
  • 11. WorkloadLibrary: fragmentos de plantillas de Workload reutilizables. Una biblioteca declara entradas de workload con nombre en spec.workloads:. Una Recipe consume una entrada por identidad mediante workload: { $import: <library>#/workloads/<entry> }, y el cuerpo importado se valida contra el esquema de Workload propiedad de la plataforma exactamente igual que un bloque workload: en línea, de modo que un workload importado de una biblioteca se renderiza de forma idéntica al equivalente en línea. Un único modo de autoría (solo plantillas Go). Opcional, para catálogos que necesitan reutilizar workloads entre una Recipe y otra, cuando varias Recipes comparten una misma forma de despliegue y solo difieren en sus valores.
  • 12. ArtifactLibrary: paquetes de artefactos con nombre reutilizables. Una biblioteca declara paquetes con nombre en spec.artifacts:; cada paquete agrupa los archivos de salida que van juntos (por ejemplo, una CRD, su RBAC y un ConfigMap) y se importa como una sola unidad. Las Recipes y las FeatureRecipes consumen un paquete por identidad mediante artifacts.<name>: { $import: <library>#/artifacts/<name> }. Un único modo de autoría (solo plantillas Go). Opcional, para catálogos que necesitan reutilizar artefactos entre una Recipe y otra, cuando el mismo conjunto de recursos auxiliares acompaña a muchas Recipes.

Cada biblioteca se publica mediante OCI, se fija en el archivo de bloqueo (las secciones schema_libraries:, mapping_libraries:, workload_libraries: y artifact_libraries:) y aparece en la interfaz del Hub con conocimiento de sus consumidores (qué Components hacen referencia a qué entradas de biblioteca; qué Recipes consumen qué entradas de biblioteca).