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

extends e implements

Herencia mediante extends

Las entidades del catálogo (Component, Feature) admiten herencia simple mediante la palabra clave extends, que permite a los arquitectos de plataforma construir entidades especializadas sobre una base compartida. La fusión profunda del envoltorio YAML es común a ambos tipos: los metadatos, las etiquetas y las tablas estructurales declarativas de la entidad que extiende sobrescriben las claves coincidentes de la base, y los mapas anidados se fusionan recursivamente. Los dos tipos se separan en los pilares de datos.

Esta página trata los tipos del catálogo, y no son los únicos tipos que declaran extends. Una Release y un Manifest también lo declaran, y ambos son documentos del lado del despliegue escritos uno junto al otro en lugar de entidades indexadas en el catálogo — por eso sus referencias nombran archivos, no entidades del catálogo, y lo que se pliega es una superficie de autoría en lugar de un esquema. Para ellos, consulta entities/release.md y entities/manifest.md.

El extends de un Component compone la estructura y hereda los pilares completos

Para un Component, extends compone metadata.labels, metadata.annotations, spec.featuresSchema (slots de vinculación), spec.usesSchema (sockets de topología) y spec.inject (la allowlist del self-inject, cuyas entradas se concatenan empezando por la base y sin duplicados). Los tres pilares de datos — values, infra, provides — no se componen. Un Component que extiende no escribe contenido de pilar: escribe el marcador literal schema: inherited y recibe el bloque schema: de la base exactamente como la base lo escribió, a cualquier profundidad de una cadena.

El esquema Component publicado hace que ese marcador sea a la vez obligatorio y exclusivo, y rechaza cada desviación respecto de él al cargar el documento, con un diagnóstico propio para cada una: contenido de pilar escrito bajo schema: en un Component que declara extends:; schema: omitido por completo en ese caso; y schema: inherited en un Component que no declara ningún extends:.

De ello se derivan dos consecuencias, que tiran en direcciones opuestas:

  • El conjunto de claves lo fija la base. Un Component que extiende no declara claves de pilar, así que no puede ocultar, eliminar ni cambiar el tipo de una que la base declara, y no añade ninguna propia. Una instancia de la base y una instancia de cualquier cosa que la extienda se validan contra el mismo contrato de pilar.
  • El endurecimiento pasa a assertions:. Una especialización que debe admitir menos de lo que admiten los pilares heredados lo expresa como un predicado sobre sí misma, no como una hoja de esquema restringida. Si una base core/base-server declara tls_enabled: { type: boolean, default: true }, una especialización que exige TLS incondicionalmente escribe:
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/tls-only-server
version: 1.0.0
labels:
component.aggrega.ai/type: "server"
spec:
extends: core/base-server
schema: inherited # values, infra and provides are the base's, verbatim
assertions:
tls-is-mandatory: |
{{- if not .values.tls_enabled -}}
{{- fail "this component requires tls_enabled: true" -}}
{{- end -}}

La regla rechaza un valor que el bloque de pilar heredado acepta, que es exactamente lo que significa endurecer aquí. La dirección inversa no tiene expresión alguna: una especialización no puede relajar una restricción heredada, porque no puede reformular la hoja que la lleva. Consulta entities/component.md «Catalog Authoring: Extending Base Components (Autoría del catálogo: extender Components base)» para la tabla de composición completa y el par desarrollado de base y extensión.

El extends de una Feature compone sus pilares

Para una Feature, el schema: de la hija se compone con el de la base según la semántica de composición de JSON Schema 2020-12, lo que produce un único esquema fusionado contra el que se valida una instancia escrita. Las Features de credenciales — las etiquetadas con feature.aggrega.ai/kind: secret — lo usan para construir sobre una base compartida: una Feature de credenciales hija extiende a un padre para heredar su esquema de consulta al vault mientras acota las restricciones.

El compilador no toma posición sobre la dirección de ese cambio. La composición es estructural, así que una restricción de la hija que amplía la de la base se compone sin detener la compilación y aparece como un aviso. Nada la rechaza: la restricción de una base de Feature es una expectativa compartida que los autores del catálogo mantienen mediante revisión, no un contrato que la plataforma haga cumplir.

Enlace de interfaz mediante implements

Las Recipes y las FeatureRecipes se enlazan a una interfaz de Component o de Feature mediante la palabra clave implements: al principio de su spec. El enlace declara de qué interfaz del catálogo es esta Recipe / FeatureRecipe la implementación concreta, y admite tres formas de coincidencia de versiones:

  • Exacta — implements: core/api-server:1.0.0 — coincide con una versión concreta del tipo de Component.
  • Rango compatible con la versión mayor — implements: core/api-server:^1.0.0 — coincide con cualquier versión que cumpla >=1.0.0, <2.0.0 (compatible con la versión mayor según SemVer). Se usa cuando una Recipe admite un rango compatible en lugar de una única versión fijada.
  • Sin versión — implements: core/api-server — coincide con cualquier versión del tipo de Component. Se usa cuando una Recipe sirve a todas las versiones del tipo.

implements: nunca selecciona una Recipe: lo hace el mapeo del Manifest. Lo que la declaración determina es la comprobación de coherencia de cada entrada de mapeo — la versión del tipo mapeado debe cumplir el implements: de la Recipe mapeada en una de las tres formas, o la Recipe debe implementar una base que ese tipo extiende — y la lista de candidatos que ofrecen el diagnóstico de mapeo ausente y el autocompletado del editor. Una entrada de mapeo cuya Recipe tiene un implements: que no coincide ni con el tipo mapeado ni con ninguna de sus bases detiene la compilación, nombrando el mapeo, la Recipe y su valor implements:. Donde una clave components.type alcanza una instancia de componente en una versión que la clave no nombra — todas las instancias, para una clave escrita sin versión —, la comprobación se vuelve a hacer con el tipo propio de esa instancia, en la versión con la que la compilación la trata, y una Recipe que no la cumple detiene la compilación del mismo modo, nombrando la instancia.

El enlace implements: es el mecanismo que hace funcionar «el mismo tipo de Component, Recipes distintas para proveedores distintos»: un Component core/postgres puede tener una Recipe que lo implementa para el proveedor helm y otra Recipe distinta que lo implementa para el proveedor compose. Cada Recipe declara el mismo valor implements:, y el Manifest con el que se compila una Release mapea el tipo a la que esta quiere.

Una Recipe escrita para una base sirve a todo lo que la extiende

implements: nombra una base, y una Recipe que nombra una es la implementación concreta para cada Component que extiende esa base, a cualquier profundidad de la cadena. Así, una especialización construida con extends no necesita una Recipe propia — y eso es lo que hace que un wrapper publicado sea barato de consumir: el equipo que lo publica escribe un Component, y los equipos que lo despliegan reutilizan las Recipes de la base en cada destino.

Aquí se cumplen dos hechos a la vez, y son distintos. Un lector que los reduce a «la especialización no necesita nada» escribe un Manifest que falla, por una razón que buscará en el archivo equivocado:

  • La Recipe coincide. La comprobación de coherencia entre la clave de tipo de un mapeo del Manifest y el implements: de la Recipe mapeada acepta el mapeo cuando la Recipe implementa el propio tipo mapeado o cualquier base que ese tipo extiende. Las tres formas de versión anteriores se aplican a una base exactamente igual que al propio tipo: una Recipe que declara implements: core/base-server:^1.0.0 cumple una especialización cuya base está en la versión 1.4.0, y no cumple una cuya base está en 2.0.0.
  • El Manifest sigue mapeando el tipo propio de la especialización. La selección de la Recipe se hace por clave de mapeo exacta. Una instancia de enterprise/labelled-server necesita su propia entrada mappings.components.type; no hereda la entrada escrita para core/base-server. Una especialización sin entrada propia se detiene con el diagnóstico de instancia sin mapear aunque su base esté mapeada.

El coste de autoría de una especialización es, por tanto, una línea de Manifest y ninguna Recipe nueva:

# The wrapper extends core/base-server and authors no pillars.
# core/helm/base-server declares: implements: core/base-server
spec:
mappings:
components:
type:
enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0

Cuando la cadena extends del tipo mapeado no puede recorrerse — forma un bucle, o una base que nombra está ausente del catálogo —, la compilación se detiene en ese fallo de la cadena en lugar de en el mapeo, porque un mapeo no puede juzgarse hasta que se resuelve la cadena de la que depende. La comprobación recorre la cadena solo a través de los Components que ya están en esta máquina — los de un directorio de catálogo y los que la caché local de artefactos guarda bajo un pin del lockfile — y nunca consulta un registro, así que una base que solo guarda un registro cuenta aquí como ausente. Obtenerla es lo que hace aggrega pull: una base es una dependencia de todo lo que la extiende, así que un pull sigue cada cadena extends: que alcanza la Release, obtiene cada base que no guarda ningún directorio de catálogo y la fija en el lockfile, donde la encuentra la compilación siguiente. El Manifest no necesita ninguna línea para la propia base, salvo que un Aggregate también declare una instancia de la base.

Las sugerencias de Recipe siguen siendo más estrechas que esta regla de coincidencia. La lista de candidatos que imprime un diagnóstico de mapeo ausente, y el orden que el autocompletado del editor aplica a un valor de mapeo, nombran las recetas que implementan el propio tipo solicitado; no se amplían a las recetas que implementan una de sus bases.

Para un recorrido completo ejecutable — un wrapper publicado en el catálogo, la única línea de Manifest que lo consume, la Recipe de la base que da forma a su salida renderizada, y la detención que produce una instancia del wrapper sin mapeo propio —, consulta el ejemplo desarrollado examples/extends-wrapper/.

Consumo de versiones entre entidades

Cada tipo de entidad de Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — lleva un campo obligatorio metadata.version validado contra la misma regex SemVer (MAJOR.MINOR.PATCH según architecture/02-ecosystem-philosophy.md). Las versiones son uniformes en su forma; el consumo de las versiones varía según el tipo de entidad. Algunas versiones participan activamente en la resolución; otras son procedencia descriptiva con la que el compilador no hace coincidencias. La tabla siguiente cubre los tipos que no son bibliotecas, indicando qué hace el compilador con el campo de versión de cada entidad y usando la taxonomía de estado de cuatro etiquetas de 10-status.md para clasificar cada régimen de consumo. Los cuatro tipos de biblioteca quedan fuera de la tabla porque su régimen es uniforme y distinto: un consumidor hace referencia a una biblioteca por su nombre simple, puede afirmar un mínimo de versión opcional :<version>, y el lockfile de cada Release es dueño de la versión resuelta y de su digest de contenido.

EntidadRégimen de consumoEstado
ComponentResolución de referencias de tipo; coincidencia de implements: de la Recipeavailable — formas exacta, de rango caret (^MAJOR.MINOR.PATCH) y sin versión en ambos casos (consulta Resolución de versiones y Estado del lenguaje → Coincidencia de versiones)
FeatureResolución de referencias de vinculación; coincidencia de implements: de la FeatureRecipeIgual que Component
RecipeResolución de niveles de mapeo del Manifestavailable — formas exacta, de rango caret y sin versión en un valor de mapeo, cada una de las cuales selecciona la versión más alta que la cumple
FeatureRecipeResolución de niveles de mapeo del ManifestIgual que Recipe
AggregateResolución de la referencia aggregates[].type del padreavailable — formas exacta, de rango caret y sin versión, cada una de las cuales selecciona la versión más alta que la cumple (consulta Resolución de versiones)
PluginDespacho al Provider mediante recipe.spec.capability → spec.provider.capabilitiesavailable — la capacidad simple selecciona el proveedor, y un pin sobre ella (helm:<version>, helm:^<version>) selecciona qué versión de ese plugin renderiza; la identidad del plugin es la referencia oci://<repository> sin digest más metadata.version, y el digest de contenido se registra en el lockfile de la release contra el que la compilación verifica los bytes descargados
ManifestProcedencia del grafo IR (manifest_version)available (se lee solo para la procedencia; sin papel en el despacho de la resolución)
ReleaseProcedencia del grafo IR (release_version) + metadatos de plantilla (.metadata.release_version)Igual que Manifest

Regímenes de resolución del catálogo (Component, Feature, Aggregate, Plugin). Una referencia a uno de estos tipos — el type de un componente, el type de una vinculación de funcionalidad, el aggregates[].type de una importación de subagregado, el plugin de un paso de pipeline — se resuelve según la regla que enseña Resolución de versiones: una referencia exacta, de rango caret o sin versión selecciona la versión más alta que la cumple entre las que guarda el catálogo, y el pull, la compilación, una validación, el editor y las herramientas orientadas al asistente aplican esa única regla por igual. Para un Component o una Feature, la coincidencia de implements: lee las mismas tres formas desde la dirección contraria — una versión concreta del tipo frente a la forma que declara una Recipe o una FeatureRecipe — como la comprobación de coherencia descrita más abajo, no como una selección. El despacho al plugin de renderizado del Provider usa una forma más sencilla: busca por nombre la recipe.spec.capability simple entre las spec.provider.capabilities del plugin de renderizado del proveedor, y un pin de versión escrito sobre la capacidad selecciona qué versión de ese plugin renderiza, deteniéndose cuando ninguna versión lo cumple.

Resolución de niveles de mapeo del Manifest. El mecanismo de resolución plano mappings.{components,features} del Manifest (con los niveles name y type, el nombre prevalece sobre el tipo, y el tipo con versión prevalece sobre el tipo sin versión) está documentado en entities/manifest.md. El resolutor consume esos mapeos: la selección de Recipe y de FeatureRecipe es una búsqueda directa del valor de mapeo en el lockfile y el catálogo, y un componente o una vinculación cuyo tipo no tiene mapeo detiene la compilación. spec.implements no selecciona una Recipe — es la comprobación de coherencia en tiempo de carga sobre un mapeo que el autor ya escribió, y la fuente de la lista de candidatos que ofrecen el diagnóstico de mapeo ausente y el autocompletado del editor. El despacho de capacidades parte después del campo spec.capability de la Recipe resuelta, no de la forma estructural del Manifest.

Regímenes de procedencia descriptiva (Manifest, Release). El metadata.version del Manifest y el metadata.version de la Release se leen cuando el compilador rellena la procedencia, y aparecen en el bloque de procedencia del grafo IR como manifest_version y release_version; ninguna etiqueta de la salida renderizada lleva ninguno de los dos. Las plantillas también ven la versión de la Release expuesta como .metadata.release_version. Ninguna de las dos versiones se compara con la versión de otra entidad para el despacho de la resolución; son pura procedencia.

Cómo leer la tabla. La clasificación de cuatro etiquetas distingue «el campo de versión es aceptado por el esquema y existe en la entidad» (siempre cierto — regex SemVer uniforme) de «el compilador hace coincidir contra esta versión durante la resolución» (varía según la entidad).

Canalización entre pilares mediante puente de esquema: conectar la intención con la infraestructura

Aggrega expresa una fuerte separación de responsabilidades entre el Dominio 1 y el Dominio 4: el desarrollador escribe la lógica cognitiva en el bloque values, mientras que el operador dicta el dimensionamiento físico en el bloque infra. El esquema Aggregate.yaml impone un corolario concreto: la palabra clave infra está ausente de las instancias de componente del Aggregate y de sus vinculaciones features y, combinada con additionalProperties: false, la validación del esquema la rechaza. Los desarrolladores no deberían dictar el dimensionamiento físico dentro de la intención del desarrollador; cuando un valor concreto encaja con el caso de la aplicación (p. ej., un puerto fijado en el código o un número concreto de CPU), el arquitecto puede exponerlo explícitamente en la declaración schema: del Component y el valor fluye a través de values.

Para los casos en que una restricción de infraestructura concreta es parte intrínseca del contrato de un componente — una base de datos de trading de alto rendimiento que debe tener 10.000 IOPS aprovisionadas, una carga de trabajo de ML que debe ejecutarse exactamente en 4 GPU —, los arquitectos de plataforma exponen la restricción mediante un Component creado a tal efecto usando el patrón de canalización entre pilares mediante puente de esquema.

El patrón de puente de esquema para componentes conscientes de la infraestructura. El Component expone el control de infraestructura concreto dentro del bloque values del desarrollador mediante su declaración schema:, y la plantilla valuesMapping: de la Recipe enlazada canaliza el valor hacia la salida renderizada con forma de infra:. El resultado es un puente tipado entre la intención cognitiva y el dimensionamiento físico: el desarrollador dicta la restricción de hardware mediante un campo validado, y la restricción fluye hacia Ops sin que ninguna de las dos partes escriba código de infraestructura en bruto. El control es una clave de pilar, así que se declara en el Component cuyo contrato lo posee — un Component que hace extends: de una base no declara claves de pilar y por tanto no puede introducir ninguna.

# Domain 2: The Platform Catalog (the schema-bridge Component)
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/high-perf-postgres
version: 1.0.0
labels:
component.aggrega.ai/type: "stateful-server"
spec:
schema:
values:
# Expose the dial safely to the Developer with a typed contract.
required_iops: { type: integer, min: 1000, max: 100000, required: true }
infra:
# Operator-owned sizing the Recipe below reads alongside the dial.
storage: { size: { type: string, default: 100Gi } }
compute: { instance_class: { type: string, default: db.m5.large } }
# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: aws-rds-high-perf-postgres
version: 1.0.0
spec:
implements: core/high-perf-postgres:^1.0.0
capability: terraform
source: ./modules/rds
valuesMapping: |
# The Recipe pipes the developer's values.required_iops into the provider's infra-side knob.
iops: {{ .values.required_iops }}
allocated_storage: "{{ .infra.storage.size }}"
instance_class: "{{ .infra.compute.instance_class }}"
# Domain 1: The Developer Intent (remains capability-agnostic)
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: 10000 # Developer dictates the hardware constraint safely

Escalado multientorno (el requisito de elevación de parámetros). Para escalar esta restricción de hardware entre entornos GitOps (Dev frente a Prod) sin modificar el Aggregate.yaml del desarrollador, el desarrollador eleva el valor al contrato tipado parameters. Ops cumple el requisito concreto de IOPS mediante archivos Release específicos de cada entorno. El orden de ejecución del compilador protege el flujo: la validación del contrato de parámetros se ejecuta en la resolución; la interpolación resuelve el parámetro en la cadena values: circundante; la plantilla valuesMapping: de la Recipe canaliza el valor resuelto hacia la salida renderizada.

1. La intención del desarrollador (abstraer el control). El desarrollador sabe que necesita controlar las IOPS, pero abstrae el número explícito al nivel del entorno mediante el contrato tipado parameters.

spec:
parameters:
env_iops:
type: integer
min: 1000
max: 100000
description: Provisioned IOPS for the trading-db instance
components:
trading-db:
type: core/high-perf-postgres:1.0.0
values:
required_iops: {{ .parameters.env_iops }} # Hoisted to the environment

2. Las Releases de GitOps (cumplimiento por parte de Ops). Ops cumple el contrato parameters en archivos Release específicos de cada entorno. El contrato tipado valida cada valor que aporta la Release antes de que se ejecute la interpolación.

  • Entorno Dev (release-dev.yaml): env_iops: 1000
  • Entorno Prod (release-prod.yaml): env_iops: 25000

El orden de compilación. Este mecanismo está protegido por el orden de ejecución estricto del compilador en la resolución:

  1. Validación del contrato de parámetros. Cada valor de parámetro que aporta la Release se valida contra la declaración tipada parameters: del Aggregate. Un valor de Prod de 25000 es válido (dentro de min: 1000, max: 100000); un valor de 500 provocaría una detención con un error claro.
  2. Interpolación. El compilador lee los valores de parámetros de la Release de Prod e interpola 25000 en la cadena YAML del Aggregate en values.required_iops. El mapa de parámetros fusionado se mantiene vivo durante el renderizado para que las superficies de plantillas de ruta puedan leer .parameters.<slot> directamente; las superficies de plantillas de valor consumen el literal posterior a la interpolación ya escrito en el bloque values: del Aggregate. El mapa sigue siendo legible hasta que se completa cada fase de renderizado, y solo es accesible desde la compilación para la que se resolvió.
  3. Validación de esquema. La declaración schema: del Component valida el diccionario values: resultante; values.required_iops: 25000 cumple el min: 1000, max: 100000 del esquema.
  4. Renderizado del valuesMapping de la Recipe. La plantilla valuesMapping: de la Recipe enlazada canaliza values.required_iops hacia la salida con forma de infra del proveedor (iops: 25000). El plugin Wasm del proveedor genera la configuración física correcta de la base de datos. El desarrollador obtiene su control explícito del hardware, Ops obtiene su escalado específico de cada entorno, y el Aggregate sigue siendo agnóstico respecto a las capacidades.