Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

extends e implements

Ereditarietà tramite extends

Le entità del catalogo (Component, Feature) supportano l’ereditarietà singola tramite la parola chiave extends, che permette agli architetti di piattaforma di costruire entità specializzate sopra una base condivisa. Il deep-merge dell’involucro YAML è comune a entrambi i tipi: i metadati, le etichette e le tabelle strutturali dichiarative dell’entità che estende sovrascrivono le chiavi corrispondenti nella base, e le mappe annidate vengono unite ricorsivamente. I due tipi si separano sui pilastri di dati.

Questa pagina tratta i tipi del catalogo, e non sono gli unici tipi che dichiarano extends. Lo dichiarano anche una Release e un Manifest, ed entrambi sono documenti del lato distribuzione scritti l’uno accanto all’altro anziché entità indicizzate nel catalogo — per cui i loro riferimenti nominano file, non entità del catalogo, e ciò che viene fuso è una superficie di scrittura anziché uno schema. Per questi, vedi entities/release.md e entities/manifest.md.

L’extends di un Component compone la struttura ed eredita i pilastri per intero

Per un Component, extends compone metadata.labels, metadata.annotations, spec.featuresSchema (slot di associazione), spec.usesSchema (socket topologici) e spec.inject (l’allowlist del self-inject, le cui voci si concatenano partendo dalla base, senza duplicati). I tre pilastri di dati — values, infra, provides — non vengono composti. Un Component che estende non scrive alcun contenuto di pilastro: scrive il marcatore letterale schema: inherited e riceve il blocco schema: della base esattamente come la base lo ha scritto, a ogni profondità di una catena.

Lo schema Component pubblicato rende quel marcatore sia obbligatorio sia esclusivo, e rifiuta ogni deviazione da esso al caricamento del documento, con una diagnostica propria per ciascuna: contenuto di pilastro scritto sotto schema: su un Component che dichiara extends:; schema: del tutto omesso in quel caso; e schema: inherited su un Component che non dichiara alcun extends:.

Ne seguono due conseguenze, che tirano in direzioni opposte:

  • L’insieme delle chiavi è fissato dalla base. Un Component che estende non dichiara chiavi di pilastro, quindi non può nascondere, eliminare o ritipizzare una chiave dichiarata dalla base, e non ne aggiunge di proprie. Un’istanza della base e un’istanza di qualunque cosa la estenda vengono validate rispetto allo stesso contratto di pilastro.
  • Il rafforzamento passa ad assertions:. Una specializzazione che deve ammettere meno di quanto ammettono i pilastri ereditati lo esprime come predicato su sé stessa, non come una foglia di schema ristretta. Se una base core/base-server dichiara tls_enabled: { type: boolean, default: true }, una specializzazione che richiede TLS incondizionatamente scrive:
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 regola rifiuta un valore che il blocco di pilastro ereditato accetta, ed è esattamente ciò che qui significa rafforzare. La direzione inversa non ha alcuna espressione: una specializzazione non può allentare un vincolo ereditato, perché non può riformulare la foglia che lo porta. Vedi entities/component.md «Catalog Authoring: Extending Base Components (Authoring del catalogo: estendere i Components di base)» per la tabella di composizione completa e la coppia svolta di base ed estensione.

L’extends di una Feature compone i suoi pilastri

Per una Feature, lo schema: della figlia si compone con quello della base secondo la semantica di composizione di JSON Schema 2020-12, producendo un unico schema unito rispetto al quale viene validata un’istanza scritta. Le Features di credenziali — quelle con l’etichetta feature.aggrega.ai/kind: secret — lo usano per costruire su una base condivisa: una Feature di credenziali figlia estende un genitore per ereditarne lo schema di interrogazione del vault restringendo i vincoli.

Il compilatore non prende posizione sulla direzione di quel cambiamento. La composizione è strutturale, quindi un vincolo della figlia che allarga quello della base si compone senza arrestare la build ed emerge come segnalazione. Nulla lo rifiuta: il vincolo di una base di Feature è un’aspettativa condivisa che gli autori del catalogo mantengono tramite revisione, non un contratto che la piattaforma fa rispettare.

Binding di interfaccia tramite implements

Le Recipes e le FeatureRecipes si legano a un’interfaccia di Component o di Feature tramite la parola chiave implements: in cima al loro spec. Il binding dichiara di quale interfaccia del catalogo questa Recipe / FeatureRecipe è l’implementazione concreta, e supporta tre forme di corrispondenza delle versioni:

  • Esatta — implements: core/api-server:1.0.0 — corrisponde a una specifica versione del tipo di Component.
  • Intervallo compatibile con la major — implements: core/api-server:^1.0.0 — corrisponde a qualsiasi versione che soddisfi >=1.0.0, <2.0.0 (compatibile con la major secondo SemVer). Si usa quando una Recipe supporta un intervallo compatibile anziché una singola versione fissata.
  • Senza versione — implements: core/api-server — corrisponde a qualsiasi versione del tipo di Component. Si usa quando una Recipe serve ogni versione del tipo.

implements: non seleziona mai una Recipe: lo fa la mappatura del Manifest. Ciò che la dichiarazione determina è il controllo di coerenza su ogni voce di mappatura — la versione del tipo mappato deve soddisfare l’implements: della Recipe mappata in una delle tre forme, oppure la Recipe deve implementare una base che quel tipo estende — e l’elenco dei candidati offerto dalla diagnostica di mappatura assente e dal completamento dell’editor. Una voce di mappatura la cui Recipe ha un implements: che non corrisponde né al tipo mappato né ad alcuna delle sue basi arresta la build, nominando la mappatura, la Recipe e il suo valore implements:. Dove una chiave components.type raggiunge un’istanza di componente a una versione che la chiave non nomina — ogni istanza, per una chiave scritta senza versione — il controllo viene ripetuto con il tipo proprio di quell’istanza, alla versione con cui la build la compila, e una Recipe che non lo soddisfa arresta la build allo stesso modo, nominando l’istanza.

Il binding implements: è il meccanismo che fa funzionare «lo stesso tipo di Component, Recipes diverse per provider diversi»: un Component core/postgres può avere una Recipe che lo implementa per il provider helm e una Recipe diversa che lo implementa per il provider compose. Ogni Recipe dichiara lo stesso valore implements:, e il Manifest con cui una Release esegue la build mappa il tipo su quella che desidera.

Una Recipe scritta per una base serve tutto ciò che la estende

implements: nomina una base, e una Recipe che ne nomina una è l’implementazione concreta per ogni Component che estende quella base, a qualsiasi profondità della catena. Così una specializzazione costruita con extends non ha bisogno di una Recipe propria — ed è questo che rende economico consumare un wrapper pubblicato: il team che lo pubblica scrive un Component, e i team che lo distribuiscono riutilizzano le Recipes della base su ogni target.

Qui valgono due fatti contemporaneamente, e sono distinti. Un lettore che li fonde in «la specializzazione non ha bisogno di nulla» scrive un Manifest che fallisce, per un motivo che cercherà nel file sbagliato:

  • La Recipe corrisponde. Il controllo di coerenza tra la chiave di tipo di una mappatura del Manifest e l’implements: della Recipe mappata accetta la mappatura quando la Recipe implementa il tipo mappato stesso oppure una qualsiasi base che quel tipo estende. Le tre forme di versione descritte sopra si applicano a una base esattamente come al tipo stesso: una Recipe che dichiara implements: core/base-server:^1.0.0 soddisfa una specializzazione la cui base è alla versione 1.4.0, e non ne soddisfa una la cui base è 2.0.0.
  • Il Manifest mappa comunque il tipo proprio della specializzazione. La selezione della Recipe avviene per chiave di mappatura esatta. Un’istanza di enterprise/labelled-server ha bisogno di una propria voce mappings.components.type; non eredita la voce scritta per core/base-server. Una specializzazione senza una voce propria si arresta con la diagnostica dell’istanza non mappata anche quando la sua base è mappata.

Il costo di scrittura di una specializzazione è quindi una riga di Manifest e nessuna nuova Recipe:

# 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

Quando la catena extends del tipo mappato non può essere percorsa — forma un ciclo, oppure una base che nomina è assente dal catalogo — la build si arresta su quell’errore della catena anziché sulla mappatura, perché una mappatura non può essere giudicata finché la catena da cui dipende non si risolve. Il controllo percorre la catena solo attraverso i Components già presenti su questa macchina — quelli in una directory del catalogo e quelli che la cache locale degli artefatti conserva sotto un pin del lockfile — e non interroga mai un registry, quindi una base conservata solo da un registry conta qui come assente. Recuperarla è il compito di aggrega pull: una base è una dipendenza di tutto ciò che la estende, quindi un pull segue ogni catena extends: che la Release raggiunge, recupera ogni base che nessuna directory del catalogo contiene e la fissa con un pin nel lockfile, dove la trova la build successiva. Il Manifest non ha bisogno di alcuna riga per la base stessa, a meno che un Aggregate non dichiari anche un’istanza della base.

I suggerimenti di Recipe restano più ristretti di questa regola di corrispondenza. L’elenco dei candidati stampato da una diagnostica di mappatura assente, e l’ordinamento che il completamento dell’editor applica a un valore di mappatura, nominano le ricette che implementano il tipo richiesto stesso; non si allargano alle ricette che implementano una delle sue basi.

Per una procedura end-to-end eseguibile — un wrapper pubblicato nel catalogo, l’unica riga di Manifest che lo consuma, la Recipe della base che dà forma al suo output renderizzato, e l’arresto prodotto da un’istanza del wrapper senza una mappatura propria — vedi l’esempio svolto examples/extends-wrapper/.

Consumo delle versioni tra entità

Ogni tipo di entità di Aggrega — Component, Feature, Aggregate, Recipe, FeatureRecipe, Manifest, Release, Plugin, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary — porta un campo obbligatorio metadata.version validato rispetto alla stessa regex SemVer (MAJOR.MINOR.PATCH secondo architecture/02-ecosystem-philosophy.md). Le versioni sono uniformi nella forma; il consumo delle versioni varia per tipo di entità. Alcune versioni partecipano attivamente alla risoluzione; altre sono provenienza descrittiva rispetto alla quale il compilatore non effettua corrispondenze. La tabella seguente copre i tipi che non sono librerie, indicando che cosa fa il compilatore con il campo versione di ciascuna entità e usando la tassonomia di stato a quattro etichette di 10-status.md per classificare ciascun regime di consumo. I quattro tipi di libreria sono fuori dalla tabella perché il loro regime è uniforme e diverso: un consumatore fa riferimento a una libreria per nome nudo, può affermare una soglia minima di versione facoltativa :<version>, e il lockfile per Release possiede la versione risolta e il suo digest del contenuto.

EntitàRegime di consumoStato
ComponentRisoluzione dei riferimenti di tipo; corrispondenza implements: della Recipeavailable — forme esatta, con intervallo caret (^MAJOR.MINOR.PATCH) e senza versione in entrambi (vedi Risoluzione delle versioni e Stato del linguaggio → Corrispondenza delle versioni)
FeatureRisoluzione dei riferimenti di associazione; corrispondenza implements: della FeatureRecipeCome per Component
RecipeRisoluzione dei livelli di mappatura del Manifestavailable — forme esatta, con intervallo caret e senza versione in un valore di mappatura, ciascuna delle quali seleziona la versione più alta che la soddisfa
FeatureRecipeRisoluzione dei livelli di mappatura del ManifestCome per Recipe
AggregateRisoluzione del riferimento aggregates[].type del genitoreavailable — forme esatta, con intervallo caret e senza versione, ciascuna delle quali seleziona la versione più alta che la soddisfa (vedi Risoluzione delle versioni)
PluginSmistamento del Provider tramite recipe.spec.capability → spec.provider.capabilitiesavailable — la capacità nuda seleziona il provider, e un pin su di essa (helm:<version>, helm:^<version>) seleziona quale versione di quel plugin esegue il rendering; l’identità del plugin è il riferimento oci://<repository> privo di digest più metadata.version, e il digest del contenuto è registrato nel lockfile della release rispetto al quale la build verifica i byte scaricati
ManifestProvenienza del grafo IR (manifest_version)available (letto solo per la provenienza; nessun ruolo nello smistamento della risoluzione)
ReleaseProvenienza del grafo IR (release_version) + metadati del template (.metadata.release_version)Come per Manifest

Regimi di risoluzione del catalogo (Component, Feature, Aggregate, Plugin). Un riferimento a uno di questi tipi — il type di un componente, il type di un’associazione di funzionalità, l’aggregates[].type di un’importazione di sotto-aggregato, il plugin di un passo della pipeline — si risolve secondo la regola che Risoluzione delle versioni insegna: un riferimento esatto, con intervallo caret o senza versione seleziona la versione più alta che lo soddisfa tra quelle che il catalogo contiene, e il pull, la build, una validazione, l’editor e gli strumenti rivolti all’assistente applicano allo stesso modo quell’unica regola. Per un Component o una Feature, la corrispondenza implements: legge le stesse tre forme dalla direzione opposta — una versione concreta del tipo rispetto alla forma che una Recipe o una FeatureRecipe dichiara — come il controllo di coerenza descritto più avanti, non come una selezione. Lo smistamento verso il plugin di rendering del Provider usa una forma più semplice: cerca per nome la recipe.spec.capability nuda tra le spec.provider.capabilities del plugin di rendering del provider, e un pin di versione scritto sulla capacità seleziona quale versione di quel plugin esegue il rendering, arrestandosi quando nessuna versione lo soddisfa.

Risoluzione dei livelli di mappatura del Manifest. Il meccanismo di risoluzione piatto mappings.{components,features} del Manifest (con i livelli name e type, il nome che prevale sul tipo, e il tipo con versione che prevale sul tipo senza versione) è documentato in entities/manifest.md. Il resolver consuma quelle mappature: la selezione di Recipe e FeatureRecipe è una ricerca diretta del valore di mappatura nel lockfile e nel catalogo, e un componente o un’associazione il cui tipo non ha alcuna mappatura arresta la build. spec.implements non seleziona una Recipe — è il controllo di coerenza al caricamento su una mappatura che l’autore ha già scritto, e la fonte dell’elenco dei candidati offerto dalla diagnostica di mappatura assente e dal completamento dell’editor. Lo smistamento delle capacità procede poi dal campo spec.capability della Recipe risolta, non dalla forma strutturale del Manifest.

Regimi di provenienza descrittiva (Manifest, Release). Il metadata.version del Manifest e il metadata.version della Release vengono letti quando il compilatore popola la provenienza, e compaiono nel blocco di provenienza del grafo IR come manifest_version e release_version; nessuna etichetta sull’output renderizzato porta né l’uno né l’altro. I template vedono inoltre la versione della Release esposta come .metadata.release_version. Nessuna delle due versioni viene confrontata con la versione di un’altra entità per lo smistamento della risoluzione; sono pura provenienza.

Leggere la tabella. La classificazione a quattro etichette distingue «il campo versione è accettato dallo schema ed esiste sull’entità» (sempre vero — regex SemVer uniforme) da «il compilatore effettua la corrispondenza con questa versione durante la risoluzione» (varia per entità).

Convogliamento tra pilastri tramite ponte di schema: collegare l’intento all’infrastruttura

Aggrega esprime una forte separazione delle responsabilità tra il Dominio 1 e il Dominio 4: lo sviluppatore scrive la logica cognitiva nel blocco values, mentre l’operatore detta il dimensionamento fisico nel blocco infra. Lo schema Aggregate.yaml impone un corollario concreto: la parola chiave infra è assente dalle istanze di componente dell’Aggregate e dalle loro associazioni features e, combinata con additionalProperties: false, viene rifiutata dalla validazione dello schema. Gli sviluppatori non dovrebbero dettare il dimensionamento fisico all’interno dell’intento dello sviluppatore; quando un valore specifico si adatta al caso dell’applicazione (per es., una porta fissata nel codice o un numero specifico di CPU), l’architetto può esporlo esplicitamente nella dichiarazione schema: del Component e il valore fluisce attraverso values.

Per i casi in cui uno specifico vincolo infrastrutturale è parte intrinseca del contratto di un componente — un database di trading ad alto throughput che deve avere 10.000 IOPS provisionate, un carico di lavoro di ML che deve girare esattamente su 4 GPU — gli architetti di piattaforma espongono il vincolo tramite un Component costruito ad hoc usando il pattern del convogliamento tra pilastri tramite ponte di schema.

Il pattern del ponte di schema per i componenti consapevoli dell’infrastruttura. Il Component espone la specifica manopola infrastrutturale all’interno del blocco values dello sviluppatore tramite la sua dichiarazione schema:, e il template valuesMapping: della Recipe legata convoglia il valore nell’output renderizzato con la forma di infra:. Il risultato è un ponte tipizzato tra intento cognitivo e dimensionamento fisico: lo sviluppatore detta il vincolo hardware tramite un campo validato, e il vincolo fluisce verso Ops senza che nessuna delle due parti scriva codice infrastrutturale grezzo. La manopola è una chiave di pilastro, quindi è dichiarata sul Component il cui contratto la possiede — un Component che fa extends: di una base non dichiara chiavi di pilastro e quindi non può introdurne una.

# 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

Scalabilità multi-ambiente (il requisito del sollevamento dei parametri). Per scalare questo vincolo hardware tra gli ambienti GitOps (Dev vs. Prod) senza modificare l’Aggregate.yaml dello sviluppatore, lo sviluppatore solleva il valore nel contratto tipizzato parameters. Ops soddisfa lo specifico requisito di IOPS tramite file Release specifici per ambiente. L’ordine di esecuzione del compilatore protegge il flusso: la validazione del contratto dei parametri viene eseguita durante la risoluzione; l’interpolazione risolve il parametro nella stringa values: circostante; il template valuesMapping: della Recipe convoglia il valore risolto nell’output renderizzato.

1. L’intento dello sviluppatore (astrarre la manopola). Lo sviluppatore sa di dover controllare le IOPS, ma astrae il numero esplicito al livello dell’ambiente tramite il contratto tipizzato 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. Le Releases GitOps (soddisfacimento da parte di Ops). Ops soddisfa il contratto parameters in file Release specifici per ambiente. Il contratto tipizzato valida ogni valore fornito dalla Release prima che venga eseguita l’interpolazione.

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

L’ordine di compilazione. Questo meccanismo è protetto dall’ordine di esecuzione rigoroso del compilatore durante la risoluzione:

  1. Validazione del contratto dei parametri. Ogni valore di parametro fornito dalla Release viene validato rispetto alla dichiarazione tipizzata parameters: dell’Aggregate. Un valore Prod di 25000 è valido (entro min: 1000, max: 100000); un valore di 500 provocherebbe un arresto con un errore chiaro.
  2. Interpolazione. Il compilatore legge i valori dei parametri della Release Prod e interpola 25000 nella stringa YAML dell’Aggregate in values.required_iops. La mappa dei parametri unita resta attiva durante il rendering, così le superfici dei template di percorso possono leggere .parameters.<slot> direttamente; le superfici dei template di valore consumano il letterale post-interpolazione già scritto nel blocco values: dell’Aggregate. La mappa resta leggibile finché ogni fase di rendering non è completata, ed è raggiungibile solo dalla compilazione per cui è stata risolta.
  3. Validazione dello schema. La dichiarazione schema: del Component valida il dizionario values: risultante; values.required_iops: 25000 soddisfa il min: 1000, max: 100000 dello schema.
  4. Rendering di valuesMapping della Recipe. Il template valuesMapping: della Recipe legata convoglia values.required_iops nell’output con la forma di infra del provider (iops: 25000). Il plugin Wasm del provider genera la configurazione fisica corretta del database. Lo sviluppatore ottiene il suo controllo esplicito sull’hardware, Ops ottiene la sua scalabilità specifica per ambiente, e l’Aggregate resta agnostico rispetto alle capacità.