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

Etichette e annotazioni

Le entità di Aggrega portano due meccanismi di metadati strutturalmente simili — metadata.labels e metadata.annotations — più campi portatori di annotazioni sparsi tra le superfici a cascata sui confini e quelle di associazione di funzionalità. Sei superfici distinte scrivono o portano contenuto di annotazioni/etichette, ciascuna con regole di cascata diverse, consumatori diversi e convenzioni di prefisso diverse. Questa pagina documenta le superfici in un unico posto, definisce i tre contenitori semantici che il contesto dei template a runtime espone, indica la disciplina dei prefissi che gli autori dovrebbero seguire e documenta le cinque superfici di associazione di Feature affiancate, così da renderle visibili accanto al più ampio vocabolario di etichette/annotazioni.

Le sei superfici portatrici di annotazioni e di etichette

Gli autori incontrano etichette e annotazioni su sei superfici distinte. Ciascuna ha un ambito diverso, una regola di cascata diversa e un consumatore diverso.

#SuperficieAmbitoRegola di cascataConsumatore principale
1metadata.labels dell’entità del catalogoIdentità per entità (Component, Feature, Aggregate)Non si propaga a cascata alle istanze; portato sull’entità del catalogo stessaaggrega search -l per Components e Features; le etichette di un Aggregate sono portate sul suo documento e nessun comando le legge
2metadata.labels del Component (intrinseche)Proprietà per istanza di Component (component.aggrega.ai/type ecc.)Si propaga a cascata nel .context.labels per nodo dell’IR dopo le mutazioni label-transformCorrispondenza dei selettori (dichiarazioni selector: di usesSchema, portate come x-aggrega-selector: nel JSON Schema sintetizzato), logica dei template della Recipe
3metadata.annotations del ComponentTratti per istanza di Component scritti dall’architettoSi propaga a cascata nel contenitore .context.annotations.catalog per nodo dell’IRruoli di verdetto della governance (policy sui tratti intrinseci), logica dei template della Recipe
4annotations: di Aggregate / sottosistemaMetadati cognitivi lato AggregateSi propaga a cascata nel contenitore .context.annotations.aggregate per nodo dell’IRvaluesMapping: della Recipe per l’instradamento cognitivo
5Confine della Release annotations:Metadati fisici lato Ops, incluse le annotazioni ben note aggrega.ai/*Si propaga a cascata nel contenitore .context.annotations.release per nodo dell’IRProviders (helm legge aggrega.ai/namespace; compose deriva il nome della rete dalla stessa chiave); injectMapping: della FeatureRecipe per l’instradamento tra confini
6Binding features.annotations del ManifestBinding chiave di annotazione → tipo di Feature con instradamento delle sottochiavi raggruppate per pilastro (maps.infra / maps.values) per l’associazione di Feature guidata dalle annotazioniLa sotto-fase di espansione delle annotazioni della risoluzione percorre i confini della Release (dall’esterno verso l’interno) e i sottosistemi dell’Aggregate (dall’esterno verso l’interno); si applicano l’override per componente e l’opt-out con null sull’intero valore / per sottochiave; il controllo lato-contro-pilastro determina quale pilastro scatta per ciascun lato di scritturaEspansione delle Feature guidata dalle annotazioni (associazioni di Feature sintetiche, registrate nel grafo IR con origin: annotation)

Le superfici 4 e 5 condividono una forma YAML (una mappa annotations: sul confine a cascata) ma si propagano in contenitori distinti dell’IR — la distinzione tra contenitori è la regola portante che il runtime espone. La superficie 6 è strutturalmente separata: vive sull’entità Manifest anziché sul contenuto di Aggregate / Release, e il suo consumo è subordinato al passaggio di espansione guidato dalle annotazioni.

La semantica a tre contenitori di .context.annotations.*

Quando il renderer valuta un template della Recipe, il campo per nodo .context.annotations porta tre contenitori con nome. Ogni contenitore è una mappa piatta string → string indicizzata per nome dell’annotazione; il contenitore determina chi ha scritto l’annotazione e qual è il suo intento.

  • .context.annotations.release — annotazioni del confine della Release (Superficie 5). Servono a governare le realtà fisiche; i renderer le instradano nei campi infra: dove opportuno. Le annotazioni ben note aggrega.ai/* risiedono in questo contenitore.
  • .context.annotations.catalog — annotazioni dei metadati del Component (Superficie 3). Tratti intrinseci immutabili scritti dall’architetto; consumati principalmente dai plugin di policy Wasm.
  • .context.annotations.aggregate — annotazioni dei sottosistemi dell’Aggregate (Superficie 4). Metadati cognitivi; i renderer le instradano nei payload values: dove opportuno.

La separazione a tre contenitori è un contratto sociale

Il compilatore non impone i confini tra i contenitori. I tre contenitori condividono una forma piatta string → string; il template di una Recipe può leggerli tutti e tre, e nulla impedisce che un’annotazione del confine della Release venga interpretata come un campo di metadati cognitivi o che un’annotazione del catalogo venga instradata in infra:. La separazione è disciplina di scrittura, non una garanzia del compilatore.

L’obiettivo della disciplina — ciò che i contenitori sono pensati per esprimere:

  • release = «dove viene eseguito questo componente, governato da Ops»
  • catalog = «che cosa è questo componente, scritto dall’architetto»
  • aggregate = «che cosa fa questo componente, scritto dallo sviluppatore»

Quando gli autori rispettano la separazione, gli strumenti a valle possono leggere il contenitore giusto per l’aspetto giusto. Quando gli autori la violano (per es. mettendo metadati cognitivi nelle annotazioni release perché il file della Release è comodo), il runtime funziona comunque, ma l’intento del contenitore si confonde.

Socket del linter — segnalare le letture tra contenitori

Un plugin linter (segnalazione fuori banda; vedi plugins/plugin-contract.md per il criterio di collocazione) può segnalare le letture tra contenitori in cui il template di una Recipe attinge da un contenitore il cui intento non corrisponde al campo instradato. Il criterio:

  • Leggere .context.annotations.release per popolare un campo values: — segnalare (i metadati cognitivi dovrebbero provenire dal contenitore aggregate).
  • Leggere .context.annotations.aggregate per popolare un campo infra: — segnalare (i metadati fisici dovrebbero provenire dal contenitore release).
  • Leggere .context.annotations.catalog per popolare values: o infra: — di norma solo una segnalazione (le annotazioni del catalogo sono tratti intrinseci; instradarle nei pilastri è insolito ma non sempre sbagliato).

Il linter di pubblicazione non ha alcuna regola per questo criterio e la build non lo controlla; può farlo un tuo plugin linter, attraverso il socket del linter che aggrega lint esegue. La disciplina è mantenuta dai revisori e dagli autori che seguono la convenzione sull’intento dei contenitori.

Disciplina dei prefissi

Le chiavi delle annotazioni e delle etichette seguono una forma uniforme <namespace>/<name>. Le famiglie di prefissi qui sotto dicono chi scrive le chiavi sotto ciascuna e come ciascuna viene mantenuta — un prefisso è riservato, e una build si arresta dove un binding del Manifest o un’etichetta di output di una Recipe rivendica una nuova chiave al suo interno; le altre sono convenzione del catalogo, senza nulla che rifiuti una chiave. La differenza tra i due casi è se una build si arresta, quindi leggi la colonna centrale prima delle altre.

PrefissoChi scrive le chiavi quiCome viene mantenutoScopoEsempi
aggrega.ai/Solo la piattaforma AggregaRiservato, e imposto. La piattaforma definisce le chiavi qui, e tu scrivi quelle che definisce — aggrega.ai/namespace su un confine della Release, per esempio. Rivendicare una nuova chiave all’interno del prefisso provoca un arresto: un binding features.annotations del Manifest sotto il prefisso nudo, e allo stesso modo una chiave di etichetta di output di una Recipe sotto di esso in outputLabels: o outputComponentLabels:. Un’annotazione scritta sotto di esso che la piattaforma non definisce non viene rifiutata: la build la porta, e dove si trova su una Release, un target che non agisce su di essa lo segnala con un avviso. Vedi errors/fatal-halts.md «A Manifest annotation binding claims the reserved aggrega.ai/ prefix (Un binding di annotazione del Manifest rivendica il prefisso riservato)» e «An output-label key uses a reserved namespace (Una chiave di etichetta di output usa un namespace riservato)».Annotazioni native della piattaforma consumate direttamente dal provideraggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment
feature.aggrega.ai/Libreria standard ufficialeConvenzione. Nulla rifiuta una chiave qui; il vocabolario appartiene alla libreria standard per accordo anziché per un controllo.Scorciatoie di annotazione delle Feature legate in features.annotations del Manifestfeature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking
component.aggrega.ai/Libreria standard ufficialeConvenzione. Nulla rifiuta una chiave qui.Etichette dei tratti intrinseci del Component (qui risiede la chiave di selettore component.aggrega.ai/type)component.aggrega.ai/type
aggregate.aggrega.ai/Libreria standard ufficialeConvenzione. Nulla rifiuta una chiave qui.Etichette di identità a livello di modulo dell’Aggregateaggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance
<role>.aggrega.ai/Libreria standard ufficiale, e le aziende nei propri cataloghiConvenzione. Nulla rifiuta una chiave qui.Etichette di capacità — le dimensioni comportamentali su cui discrimina un selettore usesSchema o l’appliesTo di una Feature. Il <role> nomina l’aspetto a cui appartiene la dimensione: un ruolo di componente, oppure un aspetto trasversale condiviso da più ruoli.model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring
<any-other-domain>/Enterprise / communityAperto. Scrivi sotto un dominio che controlli.Annotazioni ed etichette personalizzateacme.com/billing-tier, corp/cost-center

Gli autori che scrivono annotazioni personalizzate usano un dominio che controllano (tipicamente in stile DNS inverso). Scrivere direttamente sotto aggrega.ai/ (senza un sottoprefisso) è riservato alla piattaforma; nemmeno i binding features.annotations del Manifest possono legare chiavi direttamente sotto aggrega.ai/ — vedi entities/manifest.md «aggrega.ai/ Prefix Reservation (Riserva del prefisso aggrega.ai/)».

Nominare un prefisso di capacità

Una chiave di capacità è <role>.aggrega.ai/<dimension>, e il <role> è la parte che richiede giudizio. Tre regole la governano, e la prima è quella più spesso applicata al contrario.

  • Nomina l’aspetto, non il tipo di componente che per primo si trova a portarlo. Dove una dimensione descrive qualcosa che più tipi di componente condividono, il prefisso nomina l’aspetto condiviso, così il tipo successivo che lo acquisisce riusa il vocabolario anziché inventarne uno parallelo. component.aggrega.ai/hosting è un aspetto — chi gestisce la risorsa sottostante — e descrive un database e un’API di modello con le stesse parole; dataplane.aggrega.ai/* nomina una posizione sul percorso del traffico, così un proxy, un gateway di ingresso e un service mesh si descrivono allo stesso modo. Una dimensione davvero specifica di un ruolo prende il nome di quel ruolo, come fa model.aggrega.ai/capability.
  • Una sola parola minuscola, senza trattino, nel prefisso. Il trattino appartiene alla metà <dimension>, dove un composto si legge in modo naturale (request-mirroring, data-class, upstream-licensing).
  • Una dimensione viene aggiunta quando un selettore ne ha bisogno, e ogni valore che dichiara ha un componente che lo porta. Ogni parola qui è una che un autore del catalogo deve imparare e che un autore di Feature può incontrare, quindi una dimensione si guadagna il posto discriminando qualcosa che un usesSchema o un appliesTo chiede davvero. Un valore che nessun componente porta è peggio di uno assente: un selettore che lo nomina viene analizzato, non corrisponde a nulla e non segnala nulla — quindi un valore che il catalogo non può dimostrare resta fuori dal vocabolario finché un componente non lo porta. Una chiave il cui valore è una dichiarazione di un’organizzazione su come usa i propri componenti, anziché una proprietà del prodotto, è l’eccezione, e compliance.aggrega.ai/data-class è quel caso: quale classe abbiano i dati di un componente dipende da come un’organizzazione usa il componente, quindi nessun Component della libreria standard porta alcuno dei suoi valori e nessun socket o Feature della libreria standard seleziona su di essi. La chiave e i suoi valori sono dichiarati affinché i Components di un’organizzazione e le policy che essa associa condividano un’unica grafia; un selettore o una policy che nomina un valore trova corrispondenza solo in un catalogo i cui Components lo portano. policy-data-class-route mostra uno di tali Component e la policy che lo legge.

Una riserva e una chiave definita dalla piattaforma non sono la stessa cosa

La riserva riguarda la radice aggrega.ai/ nuda. Ogni namespace <scope>.aggrega.ai/ sotto di essa è uno spazio di chiavi a sé stante che la piattaforma non possiede, ed è questo che mantiene estensibile il vocabolario del catalogo: un catalogo aziendale può scrivere acme.aggrega.ai/team senza contendere nulla di ciò che la build appone.

Alcune chiavi all’interno di quei namespace aperti sono tuttavia definite dalla piattaforma e lette dalla build, e ciò non rende riservato il loro namespace:

  • component.aggrega.ai/type è obbligatoria nei metadata.labels di ogni Component e assume uno di un insieme fisso di valori. I selettori fanno corrispondenza su di essa; il compilatore non si dirama in base al valore che contiene.
  • features.aggrega.ai/requiredType.<label>, scritta nei metadata.annotations di un Component, dichiara che una Feature del tipo indicato deve essere associata. La build controlla l’obbligo rispetto all’insieme finale di associazioni di ogni nodo e si arresta dove nulla lo soddisfa — vedi errors/fatal-halts.md «Required feature not attached (Funzionalità richiesta non associata)». Nota il plurale: features.aggrega.ai/ è un namespace a sé stante, distinto dal singolare feature.aggrega.ai/ nella tabella sopra, che porta le scorciatoie di binding del Manifest.

Leggi la differenza così: un prefisso riservato rifiuta una chiave che provi a definire al suo interno, mentre una chiave definita dalla piattaforma è una singola chiave con nome che la build conosce, collocata in un namespace in cui per il resto sei libero di scrivere. Ogni altra chiave sotto component.aggrega.ai/, features.aggrega.ai/ e gli altri è un metadato che la build porta senza interpretarlo.

Una di queste chiavi nei metadata.annotations di un Component viene letta dal linter di pubblicazione standard anziché dalla build: observability.aggrega.ai/metrics-credential indica come si autenticano le metriche del prodotto — none, sono servite senza alcuna credenziale; target-key, richiedono la chiave che il Component esige da ogni chiamante; separate-token, richiedono un token proprio. La build la porta come qualsiasi altra annotazione. Il linter la legge per decidere se la credenziale di una connessione di scrape viene confrontata con la chiave dei chiamanti del target, e richiede che concordi con la chiave provides metrics_credential_required che il Component dichiara — vedi «The discipline rules (Le regole di disciplina)» in cli/aggrega-lint.md.

Etichette di provenienza emesse sull’output renderizzato

Oltre alle annotazioni in ingresso che i provider consumano, Aggrega emette anche etichette di provenienza su ogni manifest Kubernetes che il provider helm renderizza e su ogni servizio compose emesso, e il provider helm-chart scrive lo stesso insieme, come lo scrive il provider helm, su ogni artefatto che carica con $import:. L’insieme di etichette permette agli strumenti a valle (dashboard dei costi, stack di osservabilità, controller GitOps) di ricondurre le risorse a runtime al contenuto del catalogo che le ha prodotte. I template propri di un sub-chart helm-chart vengono copiati così come il loro autore li ha scritti, quindi portano qualunque etichetta quell’autore abbia scritto.

L’insieme che emettono i provider helm e compose — su helm, tre delle chiavi sono scritte come annotazioni anziché come etichette, come indica la tabella:

EtichettaOrigineSempre emessa?
app.kubernetes.io/nameIdentità del Component — il nome che hai scritto, oppure, per un componente fornito da un Aggregate importato, il suo nome qualificato con il separatore di modulo scritto per esteso (vedi sotto); oppure, per una risorsa emessa da una FeatureRecipe, l’identificatore derivato per quell’associazioneSì sui manifest Kubernetes; non emessa sui servizi compose (l’etichetta standard è specifica di K8s)
aggrega.ai/component-idIdentità del Component — il nome che hai scritto, oppure, per un componente fornito da un Aggregate importato, il suo nome qualificato con il separatore di modulo scritto per esteso (vedi sotto); oppure, per una risorsa emessa da una FeatureRecipe, l’identificatore derivato per quell’associazioneSì
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> della Recipe produttrice (o della FeatureRecipe produttrice per le risorse emesse da una FR)Quando l’entità produttrice ha impostati sia il nome sia la versione; un’annotazione su helm
aggrega.ai/boundary-pathPercorso del confine in cui è stato instradato il componenteQuando il percorso del confine non è vuoto; un’annotazione su helm
aggrega.ai/aggregate-namemetadata.name dell’AggregateQuando è impostato
aggrega.ai/compiler-versionVersione del compilatore impressa al momento della buildQuando è impostato
aggrega.ai/providerIl provider che ha renderizzato la risorsa (helm, helm-chart, compose)Sì
aggrega.ai/provider-versionLa versione di quel providerSì
aggrega.ai/environmentmetadata.environment della ReleaseSì — ogni Release lo dichiara
aggrega.ai/sync-waveIntero syncWave per confine, l’ordine in cui uno strumento GitOps applica le risorseQuando è diverso da zero; un’annotazione su helm, accanto a argocd.argoproj.io/sync-wave

Il nome dell’aggregato, l’ambiente, la versione del compilatore e il nome e la versione del provider sono stringhe scelte da te o dalla build, e nessuna di esse è vincolata alle regole di Kubernetes sui valori delle etichette nel punto in cui viene scritta. Su helm ciascuna di queste etichette porta il valore così come è scritto quando è già un valore di etichetta valido — lettere, cifre, -, _ e ., una lettera o una cifra a entrambe le estremità, al massimo 63 caratteri — e altrimenti il valore riscritto in modo da esserlo, con il valore letterale aggiunto come annotazione sotto la stessa chiave: un Aggregate chiamato imported/flow riceve l’etichetta aggrega.ai/aggregate-name: imported-flow e l’annotazione aggrega.ai/aggregate-name: imported/flow. Un valore già conforme non aggiunge alcuna annotazione. Compose porta il valore letterale come etichetta. La regola di riscrittura è indicata in providers/well-known-annotations.md «Etichette di provenienza emesse dai provider».

Per le risorse emesse da una FeatureRecipe, il valore aggrega.ai/component-id è costruito a partire dall’associazione anziché dal nome del componente ospite — per ogni modo in cui una FeatureRecipe può consegnare quelle risorse, che sintetizzi un workload, emetta un insieme di artefatti autonomo o renderizzi un chart o un frammento fornito dal suo autore. Così una query che seleziona per identità le risorse di un’associazione le restituisce tutte, e nessuna di esse è indistinguibile da una risorsa emessa dal componente ospite stesso. Il modo in cui il valore è costruito dipende da dove è associata la Feature; in entrambi i casi il risultato è una stringa valida per un’etichetta Kubernetes.

Per un componente fornito da un Aggregate importato, l’identità è il nome qualificato di quel componente con il separatore che unisce il modulo al componente scritto per esteso — data-layer.main-db viene apposto come data-layer-zdmain-db — perché un punto non è un carattere che un nome di risorsa o un indirizzo del cluster possa portare in sicurezza. Un nome che hai scritto senza alcun separatore viene apposto byte per byte.

L’identità dice a che cosa una risorsa appartiene. È una domanda diversa da come una risorsa si chiama, e per una delle consegne le due hanno risposte diverse:

  • Dove una FeatureRecipe sintetizza un workload, Aggrega costruisce da sé quelle risorse, quindi le nomina anche in base all’identità: l’identità raggiunge il loro metadata.name, le loro etichette di selettore e i nomi dei file emessi oltre alle loro etichette. È un nome all’interno del cluster e non solo un’etichetta.
  • Dove una FeatureRecipe consegna un chart o un frammento scritto dal suo autore, i nomi appartengono a chi lo ha scritto. Il nome della release di Helm rispetto a cui quei template vengono renderizzati — e il prefisso sui file che quel rendering emette — restano quelli del componente ospite. I chart nominano abitualmente le proprie risorse in base al nome della release, quindi spostarlo rinominerebbe risorse che il chart stesso dichiara, in un cluster in cui sono già distribuite, per un motivo che non ha nulla a che fare con il chart. Le etichette portano comunque l’identità propria dell’associazione, ed è questo che mantiene reperibili le risorse dell’associazione.
  • Dove la Feature è associata a un confine, non esiste un componente ospite il cui nome possa farne le veci, quindi lì l’identità composta è la base dei nomi oltre che dell’etichetta.

In entrambi i casi il valore è composto dalle parti che hai scritto, unite da --, dietro un’apertura fissa che dice di quale dei due si tratta. Sono in uso due aperture, e un’identità di componente che scrivi non può aprirsi con nessuna delle due — ed è questo che impedisce che un nome che hai scritto e un nome composto da Aggrega vengano mai scambiati l’uno per l’altro.

Dove la Feature è associata a un componente, le parti sono un’apertura fissa cfr, l’identità del componente a cui la Feature è associata e la chiave sotto cui è associata. Una Feature associata al componente api sotto mon produce cfr--api--mon. Il componente ospite fa parte del valore perché un solo nome di Feature associato a più componenti emette un insieme di risorse separato su ciascuno, e ogni insieme ha bisogno di un’identità propria: associare mon sia ad api sia a worker produce cfr--api--mon e cfr--worker--mon anziché un solo valore per entrambi. Un’associazione chiamata esattamente come il componente che la ospita produce un valore distinto da quello proprio di quel componente per lo stesso motivo — mon associata a mon produce cfr--mon--mon.

Dove la Feature è associata a un confine — il servizio gateway compose-bridge è l’esempio canonico — le parti sono un’apertura fissa bfr, poi ogni segmento del percorso del confine a partire dal più esterno, poi il nome sotto cui la Feature è associata. Una Feature chiamata gateway su un confine in bridge produce bfr--bridge--gateway; la stessa Feature su un confine in prod/eu produce bfr--prod--eu--gateway.

Un carattere che il valore non può portare viene scritto per esteso anziché sostituito, e poiché il valore è un nome all’interno del cluster oltre che un’etichetta, è vincolato ai caratteri che ogni tipo di nome di risorsa Kubernetes ammette: lettere minuscole, cifre e il trattino. Così un trattino che hai scritto resta un trattino, una lettera minuscola o una cifra resta com’è, e qualsiasi altra cosa — compresa una lettera maiuscola, che il valore di un’etichetta ammette e un nome di risorsa rifiuta — diventa un breve escape: un’associazione chiamata my_zone contribuisce my-zuzone, e un componente myApi con un’associazione worker produce cfr--my-zx000041pi--worker. Quel valore con escape è quello con cui le risorse dell’associazione vengono etichettate e selezionate su ogni target, quello da cui prendono il nome un workload sintetizzato dall’associazione e i suoi file, e quello da cui deriva il nome della release di un’associazione a un confine. Una maiuscola è l’unico carattere che la regola dei nomi di risorsa aggiunge a ciò che un’etichetta da sola avrebbe scritto per esteso, quindi un valore composto le cui parti non ne contengono — cfr--api--mon, bfr--prod--eu--gateway — è il valore che un’etichetta da sola porterebbe. Due associazioni che puoi distinguere producono quindi due valori — comunque tu le abbia chiamate, e per quanto in profondità si trovi il confine — perché -- è una sequenza che nessuna parte scritta può contenere, quindi spostare la divisione tra le parti cambia il valore invece di collidere con esso.

Quanto possa essere lungo un valore composto è una risposta del target anziché un numero che Aggrega conserva: si interroga il target per cui le risorse vengono renderizzate, e il valore viene accorciato finché quel target non lo accetta. Il valore di un’etichetta Kubernetes porta al massimo 63 caratteri, e il nome di una release di Helm derivato dalla stessa identità è limitato in modo ancora più stretto, quindi la stessa associazione può risultare più corta sotto un target che sotto un altro. Un valore che rientra nel limite viene emesso esattamente come composto, che è il caso ordinario e il caso di ogni associazione nel catalogo della libreria standard. Uno che non rientra viene accorciato: ogni parte conserva il proprio inizio, e un digest di dieci caratteri dell’intera identità viene accodato dietro un marcatore che nessun nome che puoi scrivere produce — così un valore accorciato è riconoscibile come tale e non può mai essere letto come un valore che rientrava. Un’associazione gateway annidata in profondità può quindi essere renderizzata come bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e. È molto improbabile che due valori accorciati coincidano, e se accade una build si arresta anziché lasciare che due di essi condividano un nome.

Vedi errors/fatal-halts.md «The same name is derived more than once inside the output (Lo stesso nome viene derivato più di una volta all’interno dell’output)» per sapere quali coppie provocano un arresto e come separarle.

Il valore aggrega.ai/recipe-uri di una risorsa emessa da una FR si risolve nel name:version proprio della FeatureRecipe, non nell’identità della Recipe che la consuma — così gli strumenti a valle che leggono recipe-uri per identificare l’entità produttrice ottengono la provenienza corretta sia per l’output emesso dai componenti sia per quello emesso dalle FR.

Per i dettagli dell’emissione per provider (dove finiscono le etichette sull’output renderizzato e come ciascun provider le serializza), vedi providers/well-known-annotations.md «Provenance labels emitted by providers (Etichette di provenienza emesse dai provider)».

Etichette di output dichiarate dalla Recipe

Accanto all’insieme di provenienza di proprietà del compilatore, l’autore di una Recipe può dichiarare etichette proprie da apporre sull’output renderizzato della Recipe, tramite Recipe.spec.outputLabels:. Queste viaggiano sullo stesso binario di emissione delle etichette di provenienza — vengono unite nello stesso insieme di etichette e finiscono ovunque finisca la provenienza — ma sono di proprietà dell’autore anziché del compilatore. L’uso previsto è un tratto di realizzazione: una proprietà del modo in cui una specifica Recipe realizza un componente (per esempio hosting: managed rispetto a hosting: self-hosted per una Recipe di servizio gestito rispetto a una Recipe di chart self-hosted dello stesso tipo di componente), esposta sull’output affinché gli strumenti di costo, di policy e di inventario possano interrogarla.

I namespace aggrega.ai/ e app.kubernetes.io/ sono riservati all’insieme di provenienza; una chiave sotto uno dei due prefissi viene rifiutata al caricamento — in outputLabels: e in outputComponentLabels:, il blocco compagno che nomina una chiave di etichetta del componente e appone il valore che il componente stesso dichiara. Un insieme di etichette di output validato è quindi sempre disgiunto dalle chiavi di provenienza, così le due non collidono mai sull’output unito. Il criterio è la radice nuda: una chiave con ambito come component.aggrega.ai/hosting si trova in un namespace a sé stante e può essere scritta letteralmente o promossa. L’esposizione per provider (oggetto helm e pod-template nella sintesi; oggetto nel rendering da sorgente e negli artefatti; etichette dei servizi compose; tag per risorsa di terraform sui corpi degli artefatti .tf.json) corrisponde alla collocazione della provenienza ed è documentata per intero nella pagina dell’entità Recipe sotto «The outputLabels: field (Il campo outputLabels:)» e «The outputComponentLabels: field (Il campo outputComponentLabels:)».

Associazione di Feature — cinque superfici

Le Features si associano ai Components attraverso cinque superfici di scrittura distinte, ciascuna con ambito, utente previsto e precedenza di ordinamento diversi all’interno del modello a cipolla a 5 livelli. L’ordinamento completo delle associazioni e il modello a cipolla stesso sono documentati in architecture/10-compilation-pipeline.md; la tabella qui sotto elenca le cinque superfici una accanto all’altra.

LivelloSuperficieScritto daAmbitoRegola di cascata
1Blocco features: di un componente dell’AggregateSviluppatorePer istanza di componente (granulare)Nessuna — diretta dall’autore
2Blocco features: di un sottosistema dell’AggregateSviluppatoreAmbito del sottosistema (trasversale all’interno dell’Aggregate)Si propaga a cascata a ogni componente del sottosistema
3components.<id>.features del confine della ReleaseOpsPer istanza di componente (granulare, lato Ops)Nessuna — diretta dall’autore
4Blocco features: del confine della ReleaseOpsAmbito del confine (trasversale all’interno del confine)Si propaga a cascata a ogni componente del confine
5Espansione di features.annotations del ManifestOperatore della piattaformaGuidata dalle annotazioni (associazione sintetica)Si propaga a cascata attraverso l’albero dei confini (lato Release) o l’albero dei sottosistemi (lato Aggregate); si applicano l’override per componente e l’esclusione per sottochiave tramite null

Le cinque superfici si accumulano; un’associazione presente su qualsiasi superficie contribuisce all’insieme di funzionalità risolto del Component. Quando lo stesso nome di istanza di una Feature compare su più di una superficie, i contributi si fondono in un’unica associazione anziché sostituirsi a vicenda, e una discrepanza di tipo tra di essi arresta la build con un errore feature-merge-conflict.

Le cinque superfici sono intenzionali secondo la separazione delle responsabilità dell’architettura — sviluppatore (livelli 1-2), Ops (livelli 3-4), operatore della piattaforma (livello 5) — anziché ridondanti. Gli autori scelgono la superficie che corrisponde a chi possiede l’associazione e a quale ambito.

Quali etichette decidono se una Feature si applica

Una Feature dichiara dove può associarsi con spec.appliesTo e spec.appliesToAnyOf, e la build giudica tale dichiarazione rispetto alle etichette finalizzate del nodo su cui ricade l’associazione. Associare una Feature a un nodo che quelle etichette non soddisfano arresta la build; una Feature che non dichiara nessuna delle due superfici non esprime alcun requisito e si applica ovunque.

L’insieme finalizzato di etichette viene assemblato in due passaggi, e nessuno dei due è quello che gli autori presumono più spesso.

  1. Un nodo prende le proprie etichette dall’entità di catalogo Component nominata dal suo type:. Sono una proprietà del tipo di componente, non dell’istanza: l’Aggregate non può etichettare un’istanza di componente, e nemmeno la Release può farlo. I metadata.labels propri di un Aggregate descrivono l’Aggregate come modulo riutilizzabile e non si propagano a cascata ai componenti al suo interno. Così due istanze di uno stesso tipo portano etichette identiche, e cambiare le etichette di un nodo significa cambiare il tipo a cui punta — oppure cambiare l’entità di quel tipo.
  2. Un’associazione label-transform può poi riscriverle. Dove la configurazione del workspace associa un plugin di governance nel ruolo label-transform, questo viene eseguito alla costruzione della topologia e può aggiungere, modificare o rimuovere etichette dei nodi prima che qualsiasi cosa venga giudicata rispetto a esse. Non può toccare nient’altro, quindi le etichette sono l’unica parte di un nodo che può spostare — e sono esattamente la parte da cui dipende l’applicabilità.

Una proposta fatta in base alle etichette che un singolo documento dichiara è quindi un’approssimazione, non una previsione. Leggere i metadata.labels di un’entità Component ti dice con che cosa parte un nodo di quel tipo, che è la risposta giusta abbastanza spesso da essere utile e sbagliata in due modi specifici: un documento che condivide semplicemente il nome di un nodo è un soggetto diverso con etichette diverse, e un’associazione label-transform può spostare l’insieme da sotto qualsiasi documento. Gli strumenti che offrono suggerimenti di associazione dalla sola sorgente lavorano su quell’approssimazione; il giudizio che una build esprime riguarda l’insieme finalizzato.

Precedenza degli allegati

Quando due contributi forniscono lo stesso campo della stessa associazione, quattro regole decidono quale dei due porta l’output renderizzato. Vengono applicate in questo ordine, ed è l’ordine a rendere prevedibile il risultato:

  1. Origine. Un contributo scritto esplicitamente prevale su uno guidato dalle annotazioni, a qualunque ambito ciascuno sia stato dichiarato. Scrivere un campo in un blocco features: è il modo in cui un autore sovrascrive ciò che un’annotazione avrebbe contribuito, e un’annotazione non sostituisce mai silenziosamente qualcosa scritto a mano. Il compilatore registra l’annotazione soppressa accanto al valore vincente e la segnala come avviso, così la sovrascrittura è visibile anziché misteriosa.
  2. Proprietà dei pilastri. Ogni dominio riempie il proprio pilastro: le superfici dell’Aggregate contribuiscono values, le superfici della Release contribuiscono infra. Poiché i due lati non scrivono mai lo stesso pilastro, un contributo dello sviluppatore e un contributo dell’operatore non possono contendersi lo stesso campo — non c’è alcuna questione di precedenza tra sviluppatore e operatore a cui rispondere.
  3. Autorità della composizione. Una dichiarazione nell’Aggregate che stai distribuendo prevale su una dichiarazione all’interno di un Aggregate che esso compone, anche quando l’Aggregate composto ha dichiarato all’ambito più ristretto. La composizione resta autorevole: un modulo non può prevalere sull’Aggregate che lo consuma semplicemente scegliendo un ambito più ristretto.
  4. Specificità. All’interno di un livello di scrittura e di un pilastro, l’ambito più ristretto affina quello più ampio, campo per campo. Un’associazione con ambito di componente sovrascrive un’associazione a livello di sottosistema o di confine con lo stesso nome di istanza — ma solo per i campi che menziona effettivamente. I campi che l’ambito più ristretto tralascia mantengono i valori dell’ambito più ampio, così un’associazione condivisa può fornire la configurazione comune mentre un singolo componente ne regola un campo. Due contributi allo stesso ambito si risolvono in base all’ordine dell’autore, con il successivo che prevale, ed è questo che permette a un sottosistema interno di affinare uno esterno e a un confine più profondo di affinarne uno meno profondo.

La precedenza governa i valori dei campi. Non riordina la valutazione: la sequenza in cui il compilatore ripiega le superfici, e in cui esegue l’injectMapping pre-rendering di ciascuna associazione, è la sequenza fissa a cinque livelli documentata in architecture/10-compilation-pipeline.md. Il blocco inject scritto di un’associazione segue quella sequenza di valutazione anziché la graduatoria degli ambiti sopra, così un’associazione non porta mai due ordinamenti in competizione.

Quali tipi portano metadata.labels e metadata.annotations

metadata.labels si trova su Component, Feature, Aggregate e i quattro tipi di libreria; metadata.annotations sugli stessi tipi tranne Aggregate. Manifest, Release, Recipe, FeatureRecipe e Plugin non portano né l’uno né l’altro.

Riepilogo della propagazione a cascata

Le regole di propagazione a cascata tra le sei superfici, come le valuta il compilatore:

  1. Le etichette delle entità di catalogo (Superficie 1) restano sull’entità di catalogo. Non fluiscono verso le istanze; i consumatori le leggono ispezionando direttamente il contenuto del catalogo.
  2. I metadata.labels del Component (Superficie 2) fluiscono nel .context.labels per nodo dopo il passaggio facoltativo label-transform alla costruzione della topologia.
  3. I metadata.annotations del Component (Superficie 3) fluiscono nel contenitore per nodo .context.annotations.catalog.
  4. Le annotations: dell’Aggregate / del sottosistema (Superficie 4) si propagano a cascata attraverso la gerarchia dei sottosistemi, accumulandosi dai sottosistemi esterni verso l’interno, nel contenitore per nodo .context.annotations.aggregate.
  5. Le annotations: del confine della Release (Superficie 5) si propagano a cascata attraverso la gerarchia dei confini, dai confini esterni verso l’interno, nel contenitore per nodo .context.annotations.release.
  6. Le features.annotations del Manifest (Superficie 6) non si propagano a cascata direttamente ai dati IR per nodo; la sottofase di espansione guidata dalle annotazioni della risoluzione consuma i binding per sintetizzare associazioni di Feature per nodo, che il grafo IR (--ir-graph) registra con origin: annotation. Le associazioni sintetiche sono strutturalmente indistinguibili da quelle esplicite a valle della risoluzione, se non tramite quella provenienza — vedi providers/well-known-annotations.md per la trattazione completa dell’espansione e architecture/13-catalog-and-registry.md §«Annotation-driven Feature expansion (espansione delle Feature guidata dalle annotazioni)» per i meccanismi al caricamento del catalogo e in fase di ispezione.

Per la progettazione canonica delle annotazioni a cascata, vedi architecture/06-data-taxonomy-and-composition.md §2 (Flusso 5).

Riferimenti incrociati