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

Annotazioni ben note

I Providers leggono annotazioni specifiche per configurare il contesto specifico della piattaforma — impostate sul confine di una Release o sulla voce di un componente in una Release, oppure dichiarate nell’Aggregate su un sottosistema o su un’istanza di componente. Il compilatore stesso è agnostico rispetto ai valori di queste annotazioni — li fa passare come stringhe opache. Ogni provider dichiara quali annotazioni legge, in quale ambito e quale valore predefinito si applica quando l’annotazione è assente. Questa dichiarazione si trova in spec.provider.wellKnownAnnotations di un Plugin di rendering per provider, ed è deliberatamente ristretta: un provider elenca una chiave solo dove la legge. Un provider che non ne legge nessuna dichiara invece spec.provider.readsNoWellKnownAnnotations: true.

La matrice di supporto in questo capitolo è generata a partire da quelle dichiarazioni, alla granularità che la dichiarazione porta — per provider per tipo di input, perché un provider può leggere una chiave quando sintetizza un’unità di distribuzione e non avere modo di leggerla quando renderizza un artefatto copiato localmente. Scrivi facendo riferimento alla matrice qui: una cella dice che cosa legge quel provider su quel percorso, perché una cella non può dire nulla che il provider non abbia dichiarato. Una dichiarazione che nomina un tipo di input che il contratto di comportamento di rendering proprio del provider non renderizza viene rifiutata quando viene letta l’entità Plugin, così le due affermazioni non possono essere in disaccordo.

Il vocabolario riservato è l’insieme più ampio, e si trova invece in due posti — questo capitolo, che nomina ogni chiave riservata comprese quelle che nessun provider legge, e l’insieme dei prefissi riservati che il lint di pubblicazione controlla.

Gli invarianti

  1. Il compilatore non interpreta né convalida mai il valore di un’annotazione ben nota del provider: porta la chiave e il suo valore attraverso la cascata e avvisa dove una destinazione non agisce sulla chiave.
  2. Ogni provider documenta quali annotazioni legge e quali valori predefiniti applica.
  3. Le annotazioni si applicano in modo uniforme all’interno di un confine. Se un valore varia per componente, appartiene alle annotazioni a livello di componente (che sovrascrivono le annotazioni del confine) o a infra del componente.
  4. Le annotazioni ben note dei Provider non duplicano mai le etichette dei componenti. Le etichette dei Component descrivono che cosa è un componente. Le annotazioni dei confini descrivono dove viene distribuito un componente.
  5. Le Recipes non gestiscono le annotazioni ben note del provider. Il provider applica automaticamente il contesto di collocazione (namespace, prefisso di registry, service account) dopo che la Recipe ha prodotto il proprio contenuto.
  6. Il prefisso aggrega.ai/ è riservato alla libreria standard. Le annotazioni aziendali personalizzate usano un prefisso proprio.
  7. Le annotazioni a livello di Component nella Release sovrascrivono le annotazioni a livello di confine (deep-merge, prevale il componente). Dove un provider assembla l’output di più confini in un unico artefatto, può richiedere che un’annotazione si risolva in modo uniforme tra di essi — il provider helm-chart prende il nome del chart ombrello da aggrega.ai/chart-name e, quando più di un confine contribuisce allo stesso chart e questi risolvono quell’annotazione in valori diversi, la build si arresta nominando i confini in disaccordo, perché un chart non può portare due nomi.
  8. Le annotazioni che l’Aggregate dichiara raggiungono le stesse chiavi al di sotto di quelle della Release. Una chiave dichiarata su un sottosistema o su un’istanza di componente — nell’Aggregate stesso, o in un modulo che esso importa, dove raggiunge i componenti propri del modulo — si applica al componente ovunque la Release non imposti alcun valore per quella chiave; dove la Release ne imposta uno, sul confine o sulla voce del componente, il valore applicato è quello della Release. Le annotazioni proprie di un’entità del catalogo non ne impostano mai uno. aggrega.ai/chart-name è l’eccezione alla portata dell’Aggregate: nomina un assemblaggio anziché un componente, e viene letta dai confini della Release che vi contribuiscono.

La matrice completa delle annotazioni

Come leggere questa matrice

Le sei tabelle per categoria qui sotto nominano ogni annotazione del vocabolario riservato aggrega.ai/, che cosa controlla e che cosa fa il provider quando è assente. Se un dato provider applichi una data chiave è una questione più fine, perché un provider renderizza più di un tipo di input — un artefatto copiato localmente (sourced), un Workload che il provider sintetizza da sé (synthesized) o gli artifacts: di una Recipe come intero output di un nodo (artifacts-only) — e una chiave può essere letta su uno di questi percorsi pur essendo irraggiungibile su un altro. Quale provider renderizza quale tipo di input è indicato in ../../architecture/16-recipe-input-composition.md; che cosa applica ciascuno è Supporto per provider e tipo di input qui sotto, che è la dichiarazione autorevole di questa pagina.

Ogni cella di quella griglia porta uno di tre livelli:

  • Applicata — il provider applica la chiave su questo tipo di input, e l’output renderizzato cambia di conseguenza in modo deterministico.
  • Applicata in modo condizionale — il compilatore emette un override additivo accanto all’artefatto di destinazione anziché modificare l’artefatto, quindi che il valore abbia effetto dipende dal fatto che quell’artefatto esponga una propria chiave corrispondente. Efficace in pratica, mai una garanzia. Nessun provider implementa una cella condizionale, e la superficie di dichiarazione non ha modo di esprimerne una, quindi la griglia generata qui sotto emette solo gli altri due livelli. Il livello viene nominato perché la via esiste davvero per un artefatto copiato localmente, e un vocabolario a due livelli costringerebbe la matrice o a rivendicare una garanzia che non può dare o a negare del tutto che la via esista.
  • Non applicata — nessun provider applica la chiave su questo percorso: la destinazione non ha lì alcuno slot di rendering per essa, quindi il meccanismo di collocazione non contribuisce nulla a ciò che viene renderizzato, e la colonna Predefinito della tabella di categoria dice che cosa ottieni invece. Il valore passa comunque attraverso la build come stringa opaca, intatto. Il livello prende il nome dal meccanismo anziché dalla sorte del valore, perché si tratta di domande diverse e solo la prima è una a cui una cella può rispondere: ciò che un provider applica è una proprietà degli slot di rendering di quella destinazione, che è esattamente ciò che afferma la dichiarazione dietro ogni cella.

Due ambiti, e solo uno di essi rende il tipo di input un asse significativo:

  • Con ambito di nodo — aggrega.ai/namespace, aggrega.ai/image-registry, aggrega.ai/image-pull-secret, aggrega.ai/service-account e aggrega.ai/kubernetes-version danno forma all’output renderizzato proprio di un componente, prodotto dal percorso che il suo tipo di input seleziona. Queste sono le colonne della griglia.
  • Con ambito di assemblaggio e di riferimento — aggrega.ai/chart-name viene risolta una sola volta quando viene assemblato un chart ombrello, e le tre chiavi aggrega.ai/aws-* vengono risolte quando un riferimento attraversa un confine. Il tipo di input non è un asse per nessuna delle due: il valore viene letto all’assemblaggio o al riferimento, comunque sia stato renderizzato ciascun nodo che vi contribuisce. Hanno una tabella propria in Chiavi risolte per assemblaggio e per riferimento.

Categoria 1 — Collocazione

AnnotazioneApplicata daScopoPredefinito
aggrega.ai/namespacehelm (con sorgente, sintetizzato); compose (con sorgente, sintetizzato)Namespace Kubernetes (helm); nome della rete Docker (compose)Non iniettato se assente (helm); una rete che prende il nome dal percorso del file compose, condivisa da ogni nodo di quel file privo dell’annotazione (compose)
aggrega.ai/project-nameriservata; nessun provider la leggeRiservata a un nome di progetto Docker Compose—
aggrega.ai/regionriservata; nessun provider la leggeRiservata a una regione cloud nell’ambito di collocazione—
aggrega.ai/account-idriservata; nessun provider la leggeRiservata a un identificatore di account cloud nell’ambito di collocazione—
aggrega.ai/kubernetes-versionhelm (con sorgente)Versione di Kubernetes del cluster in cui viene distribuito il componente, che un chart renderizzato dalla sorgente legge come .Capabilities.KubeVersionLa versione per cui renderizza il helm template standard della stessa release di helm: quella della libreria client di Kubernetes con cui è costruito il provider

aggrega.ai/namespace ha un duplice scopo per progettazione. Esprime lo stesso intento di isolamento logico — «le risorse di questo confine vivono in un proprio ambito indirizzabile» — nella forma nativa di ciascuna destinazione: un metadata.namespace di Kubernetes per helm, un nome di rete Docker per compose. Gli autori di Recipe impostano una sola annotazione; ciascun provider la materializza in modo appropriato per la destinazione. Nel caso di compose, il nome della rete viene risolto per nodo dall’annotazione su quel nodo, ripiegando sul percorso del file compose dove il nodo non porta alcuna annotazione — così confini privi di annotazione che condividono un file compose condividono una rete, ed è aggrega.ai/namespace a separarli. Qualunque delle due fornisca l’identità, questa viene poi scritta nei caratteri che un nome di rete compose accetta — ogni altro carattere viene scritto come sequenza di escape anziché essere sostituito, così due identità che differiscono in qualsiasi modo restano su due reti, e le maiuscole e minuscole dell’identità vengono mantenute così come sono state scritte. Il riferimento del provider compose documenta la derivazione per intero, incluso come leggere un nome codificato e che cosa costa una ridenominazione.

aggrega.ai/kubernetes-version indica una proprietà del cluster in cui viene distribuito un componente anziché il punto in cui il componente vi finisce: i template dei chart scelgono una versione dell’API, un campo o un intero meccanismo in base alla versione per cui vengono renderizzati, e la build non ha alcun cluster da interrogare. Il provider helm legge il valore nel modo in cui helm template --kube-version legge il proprio flag e arresta la build su un valore che non è una versione; dove non ne viene indicata nessuna, un chart viene renderizzato per la versione per cui renderizza helm template della stessa release di helm. Il riferimento del provider helm documenta le forme accettate e il valore predefinito.

Categoria 2 — Registry

AnnotazioneApplicata daScopoPredefinito
aggrega.ai/image-registryhelm, compose — solo sintetizzatoPrefisso di registry per le immagini dei container, applicato a ogni riferimento a un’immagine di container sintetizzatoNessun prefisso
aggrega.ai/image-pull-secrethelm — solo sintetizzatoNome di imagePullSecrets di Kubernetes, unito alle voci esistenti del pod sintetizzatoNessuno

Categoria 3 — Rete

AnnotazioneApplicata daScopoPredefinito
aggrega.ai/cluster-domainriservata; nessun provider la leggeRiservata a un suffisso DNS per il rilevamento dei servizi tra namespace—
aggrega.ai/ingress-classriservata; nessun provider la leggeRiservata a una IngressClass di Kubernetes sulle risorse Ingress—
aggrega.ai/service-meshriservata; nessun provider la leggeRiservata alle annotazioni di iniezione del sidecar della mesh—

Categoria 4 — Sicurezza

AnnotazioneApplicata daScopoPredefinito
aggrega.ai/service-accounthelm — solo sintetizzatoServiceAccount di Kubernetes per i Pod sintetizzati; sovrascrive il workload.serviceAccount della Recipe quando sono impostati entrambiIl workload.serviceAccount della Recipe, oppure non impostato quando la Recipe non ne dichiara nessuno
aggrega.ai/pod-security-standardriservata; nessun provider la leggeRiservata a un livello dei Pod Security Standards—
aggrega.ai/iam-roleriservata; nessun provider la leggeRiservata a un ruolo di identità cloud associato a un carico di lavoro—

Categoria 5 — Pacchettizzazione

AnnotazioneApplicata daScopoPredefinito
aggrega.ai/chart-namehelm-chart — per assemblaggioNome del chart ombrelloNome dell’Aggregate e percorso di assemblaggio dell’ombrello, uniti — vedi Risoluzione del nome del chart
aggrega.ai/chart-versionriservata; nessun provider la leggeRiservata a una versione di chart Helm—
aggrega.ai/stack-nameriservata; nessun provider la leggeRiservata a uno stack nominato esplicitamente—
aggrega.ai/tf-backendriservata; nessun provider la leggeRiservata a un identificatore del backend di stato di Terraform—

Categoria 6 — Destinazione cloud

AnnotazioneApplicata daScopoPredefinito
aggrega.ai/aws-accountcloudformation — per riferimento tra confiniAccount AWS in cui viene distribuito lo stack (confine)Stesso account — un riferimento tra stack si risolve tramite l’importazione di un export di stack nello stesso account
aggrega.ai/aws-regioncloudformation — per riferimento tra confiniRegione AWS in cui viene distribuito lo stack (confine)Stessa regione — un riferimento tra stack si risolve tramite l’importazione di un export di stack nella stessa regione
aggrega.ai/aws-assume-role-arncloudformation — per riferimento tra confiniARN del ruolo IAM che una lettura di stack tra account assume per raggiungere i valori esportati di uno stack peerNessun ruolo viene fornito su un riferimento tra account

Ogni confine CloudFormation viene renderizzato in un unico stack. Quando un arco uses passa da un confine a un altro, il provider cloudformation deve sapere dove si trova lo stack peer per dare forma al riferimento: due stack nello stesso account e nella stessa regione si scambiano valori tramite un export e un’importazione di stack; un peer in un account o in una regione diversi richiede una lettura degli output dello stack tra account, facoltativamente sotto un ruolo assunto. Queste annotazioni portano quel contesto di collocazione. Ciascuna viene letta nel momento in cui il provider dà forma a un tale riferimento, e risolta in quel momento attraverso la normale cascata delle annotazioni — un valore impostato sul componente prevale su un valore impostato sul confine, e un valore che la Release imposta prevale su uno che l’Aggregate dichiara. Un valore a livello di confine è quindi il modo comune di esprimerle, non l’unico. Sono stringhe puntatore scalari opache — il provider le convoglia nel riferimento che costruisce e non le risolve mai rispetto allo stato effettivo di AWS; account, regione e ruolo sono forniti dalla Release o dichiarati nell’Aggregate, e l’ambiente di runtime risolve la lettura fisica finale. Quando ogni annotazione è assente, il provider tratta il peer come nello stesso account e nella stessa regione e non fornisce alcun ruolo.

Supporto per provider e tipo di input

Le chiavi con ambito di nodo, per provider e per tipo di input. Le intestazioni delle colonne omettono il prefisso aggrega.ai/ che ogni chiave porta. applied e — portano i livelli definiti sopra, dove — corrisponde a non applicata; n/a significa che il provider non renderizza affatto quel tipo di input, quindi lì non esiste alcun percorso su cui la chiave possa essere applicata o non applicata.

ProviderTipo di inputnamespaceimage-registryimage-pull-secretservice-accountkubernetes-version
helmsourcedapplied———applied
helmsynthesizedappliedappliedappliedapplied—
helmartifacts-only—————
composesourcedapplied————
composesynthesizedappliedapplied———
composeartifacts-only—————
helm-chartsourced—————
helm-chartsynthesizedn/an/an/an/an/a
helm-chartartifacts-onlyn/an/an/an/an/a
terraformsourced—————
terraformsynthesizedn/an/an/an/an/a
terraformartifacts-only—————
cloudformationsourced—————
cloudformationsynthesizedn/an/an/an/an/a
cloudformationartifacts-only—————

Ogni provider distribuito con il compilatore ha qui delle righe, compreso uno che non legge alcuna annotazione di collocazione — un insieme di righe vuoto sarebbe indistinguibile da un provider che nessuno ha ancora descritto. Un provider fornito separatamente dichiara ciò che legge nello stesso modo e non è elencato qui, perché una pagina pubblicata non può enumerare provider che non ha mai visto.

Una Recipe può dichiarare più di un tipo di input alla volta — un workload: con artifacts: accanto, per esempio. Leggi la griglia per tipo: l’output sintetizzato di un tale nodo è la riga synthesized, e i suoi file di artefatti sono il caso degli artefatti. La riga artifacts-only è il tipo di input in cui una Recipe dichiara artifacts: e nient’altro.

Non devi consultare la griglia per scoprirlo. Impostare una chiave che la destinazione di uno dei tuoi rendering non legge su nessuno dei tipi di input di quel rendering produce un avvertimento che nomina la chiave, la destinazione e ogni tipo di input che quel rendering dichiara, così una cella in cui sei finito per caso si annuncia nel momento in cui esegui la build anziché aspettare che ti venga in mente di guardare qui:

warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it

Su un rendering che dichiara più di un tipo di input, l’avvertimento riguarda quel rendering nel suo insieme, non una delle sue metà. Poiché i tipi si compongono per addizione, una destinazione che legge la chiave su uno qualsiasi di essi la applica davvero, e l’output di quel rendering porta il risultato — quindi non viene sollevato alcun avvertimento. Un avvertimento compare solo quando la chiave non viene applicata su nessuno dei tipi che quel rendering dichiara, e li nomina tutti:

warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored it

Quindi un workload: accanto a un source: basta a far sì che aggrega.ai/service-account abbia effetto su quel nodo, e la build non ne dice nulla — che è il resoconto onesto, perché il valore raggiunge la metà sintetizzata e compare nei manifest emessi.

Leggi la griglia per rendering, non per componente. Una funzionalità associata a un nodo genera le proprie risorse tramite la destinazione che la sua FeatureRecipe nomina, ai tipi di input che quella FeatureRecipe dichiara — così finisce in una propria riga di questa griglia, che non deve per forza essere la riga in cui finisce il suo componente ospitante. Un componente che sintetizza il proprio Workload mentre una funzionalità associata contribuisce artifacts: accanto ad esso legge la riga synthesized per i manifest propri del componente e la riga artifacts-only per i file dell’associazione, e una chiave applicata sulla prima può non essere applicata sulla seconda. L’avvertimento segue la stessa suddivisione e ti informa di ciascuna separatamente, perché sono file diversi. Una funzionalità associata a un confine anziché a un componente con nome legge la griglia nello stesso modo.

Il valore passa comunque intatto — la build non si arresta, perché un confine che comprende componenti su destinazioni eterogenee avrà sempre qualche rendering che non può agire su una data chiave, e questa è una Release ordinaria anziché un errore. Un’annotazione di confine si propaga in cascata, quindi una riga scritta produce un avvertimento per ogni rendering che non può agire su di essa, ed è così che vedi quali parti del tuo output sono interessate. Appartiene alla classe unsupported-field e si silenzia con il flag di quella classe; Avvertimenti ha i dettagli. Due limiti da conoscere: vengono controllate solo le chiavi con il prefisso aggrega.ai/ semplice, poiché una chiave con sotto-prefisso è il tuo vocabolario, e un provider che non dichiara alcuna affermazione di supporto non produce alcun avvertimento, perché non c’è nulla con cui confrontare ciò che hai scritto. Un provider che dichiara di non leggere nessuna di queste chiavi non è silenzioso in quel modo: readsNoWellKnownAnnotations: true sulla sua entità Plugin è un’affermazione che non copre alcuna chiave, quindi ogni chiave con prefisso semplice che raggiunge uno dei suoi rendering genera l’avvertimento. Il provider terraform lo dichiara.

Perché un artefatto copiato localmente applica meno chiavi. Un’annotazione con ambito di nodo viene applicata dove il provider ha uno slot di rendering per essa. Quando il provider sintetizza da sé l’unità di distribuzione, possiede ogni campo del risultato, quindi un prefisso di registry, un pull secret e un service account hanno tutti un posto in cui finire. Un artefatto copiato localmente — un chart Helm, un file compose, un modulo Terraform — porta invece la propria interfaccia di configurazione, e il compilatore non legge quell’interfaccia, quindi non può sapere a quale delle chiavi proprie dell’artefatto corrisponderebbe un prefisso di registry o un service account. La collocazione che la chiamata di rendering circostante controlla si applica comunque, ed è per questo che aggrega.ai/namespace viene applicata a un chart renderizzato dalla sorgente. La collocazione che significherebbe decidere dove, all’interno dell’artefatto di qualcun altro, appartiene un valore non si applica, e un autore la fornisce tramite i valori propri di quell’artefatto. Ecco perché le righe con sorgente sono scarne dove le righe sintetizzate sono piene, ed è la forma da aspettarsi da qualsiasi chiave aggiunta in futuro.

Chiavi risolte per assemblaggio e per riferimento

Quattro delle chiavi incluse non hanno ambito di nodo, quindi si trovano fuori dalla griglia qui sopra anziché esservi incorporate: il tipo di input non è un asse significativo per esse, e dare a ciascuna una riga per tipo di input ripeterebbe una singola cella tre volte e implicherebbe una distinzione che non esiste. Ciascuna dichiara l’ambito del confine, e la tabella qui sotto è generata da quelle dichiarazioni.

AnnotazioneApplicata daScopoPredefinito
aggrega.ai/chart-namehelm-chartNome del chart Helm ombrello assemblato.Vengono usati il nome dell’Aggregate e il percorso di assemblaggio dell’ombrello — la sua directory di output sotto dist/, come boundaries/data/helm-chart —, ciascuno codificato, e uniti.
aggrega.ai/aws-accountcloudformationL’account AWS in cui viene distribuito lo stack (confine). Un riferimento tra confini lo legge per decidere se uno stack peer si trova nello stesso account.Il peer viene trattato come nello stesso account, e un riferimento tra stack si risolve tramite l’importazione di un export di stack nello stesso account anziché tramite una lettura degli output dello stack tra account.
aggrega.ai/aws-regioncloudformationLa regione AWS in cui viene distribuito lo stack (confine). Un riferimento tra confini la legge per decidere se uno stack peer si trova nella stessa regione.Il peer viene trattato come nella stessa regione, e un riferimento tra stack si risolve tramite l’importazione di un export di stack nella stessa regione.
aggrega.ai/aws-assume-role-arncloudformationL’ARN del ruolo IAM che una lettura di stack tra account assume per raggiungere i valori esportati di uno stack peer.Non viene fornito alcun ruolo, e un riferimento tra account non porta alcun assume-role.

Quando ciascuna viene risolta, cosa che la dichiarazione stessa non porta. aggrega.ai/chart-name viene risolta una sola volta per assemblaggio del chart ombrello, dalla cascata delle annotazioni del confine; ogni contributore a uno stesso assemblaggio deve risolverla allo stesso valore, e un disaccordo arresta la build nominando i confini. Le tre chiavi aggrega.ai/aws-* vengono risolte per riferimento tra confini con la precedenza del componente sul confine, quindi un valore del componente prevale su un valore del confine; la Categoria 6 qui sopra descrive il riferimento a cui ciascuna dà forma.

Nomi riservati che nessun provider legge

Undici chiavi nella matrice qui sopra sono contrassegnate con riservata; nessun provider la legge: aggrega.ai/project-name, aggrega.ai/region, aggrega.ai/account-id, aggrega.ai/cluster-domain, aggrega.ai/ingress-class, aggrega.ai/service-mesh, aggrega.ai/pod-security-standard, aggrega.ai/iam-role, aggrega.ai/chart-version, aggrega.ai/stack-name e aggrega.ai/tf-backend.

Impostarne una su una Release o in un Aggregate non ha alcun effetto sull’output renderizzato. Nessun provider le legge, e nessun valore predefinito viene applicato al loro posto — in particolare, nessun suffisso DNS viene applicato per aggrega.ai/cluster-domain, quindi una Recipe che ha bisogno di un dominio del cluster deve fornirlo come valore ordinario anziché affidarsi a questa annotazione. Un autore di Recipe che ha bisogno di uno di questi comportamenti lo esprime come valore della Recipe o come campo infra del componente.

Nessun provider dichiara queste undici. Il wellKnownAnnotations di un provider elenca solo ciò che legge, quindi nessuna delle undici vi compare — chi apre il Plugin helm, helm-chart, compose o cloudformation vede le chiavi che funzionano e nient’altro. Questo è il senso della dichiarazione ristretta: una chiave dichiarata è una chiave funzionante, e l’ambito accanto ad essa dice su quale percorso.

Due dei nomi riservati sono vicini a chiavi attive e non sono intercambiabili con esse. aggrega.ai/region e aggrega.ai/account-id nominano una regione e un account nell’ambito di collocazione e non raggiungono alcun provider; le chiavi che il provider cloudformation legge sono aggrega.ai/aws-region e aggrega.ai/aws-account, nel namespace del cloud, nella Categoria 6. Quando intendi il contesto di collocazione tra stack di CloudFormation, scrivi la forma aws- — la coppia senza prefisso è riservata per evitare collisioni, non collegata a nulla. Altri due nomi riservati sono coperti da altre superfici anziché da un’annotazione: aggrega.ai/stack-name è riservato, mentre il nome dello stack in cui viene renderizzato un confine cloudformation è derivato in modo deterministico dall’identità della release e del confine; e il ruolo di identità cloud di un carico di lavoro viene fornito come campo ordinario impostato dall’operatore sulla Feature che emette il legame, non tramite aggrega.ai/iam-role.

I nomi restano riservati, e restano elencati qui, perché il prefisso aggrega.ai/ è riservato: un catalogo aziendale non deve riutilizzare una di queste chiavi per un significato proprio, perché la piattaforma detiene la chiave per un significato suo. Questa matrice e l’insieme dei prefissi riservati che il lint di pubblicazione controlla costituiscono insieme il registro dei nomi riservati, e i due sono vincolati allo stesso insieme di nomi da un controllo che legge entrambi e fallisce quando divergono. Scrivere una delle undici, quindi, non fa fallire la validazione né fa scattare la regola «non usare il prefisso aggrega.ai/ semplice» — semplicemente non ha alcun effetto.

La versione del chart ombrello che un confine helm-chart emette è sempre 0.1.0; è un valore fisso anziché un valore predefinito di aggrega.ai/chart-version.

Nota: i legami features.annotations del Manifest che usano il prefisso aggrega.ai/ vengono rifiutati al caricamento; il prefisso è riservato esclusivamente alle annotazioni ben note dei provider documentate in questo capitolo. Gli autori di legami di Feature guidati da annotazioni usano feature.aggrega.ai/ per le scorciatoie della libreria standard o un dominio personalizzato per le scorciatoie aziendali.

Nota: un null esplicito su un’annotazione della Release rimuove il legame ereditato dal confine o dal componente che esegue l’override (rinuncia a una Feature guidata da annotazioni). I componenti fratelli nello stesso confine che non hanno rinunciato mantengono il legame ereditato; le chiavi assenti continuano a ereditare dalla cascata genitore come di consueto.

Annotazioni scritte nel catalogo che il compilatore legge

Tutto ciò che precede è un’annotazione di provider: scritta sulla Release o dichiarata nell’Aggregate, fatta passare dal compilatore come stringa opaca, letta da un provider. Un secondo vocabolario, molto più piccolo, va nella direzione opposta — scritto dall’Architetto sui metadata.annotations propri di un’entità del catalogo, letto dal compilatore e mai visto da un provider. L’invariante 1 qui sopra riguarda il vocabolario dei provider e non si estende a queste; il compilatore legge esattamente le chiavi elencate qui e nessun’altra.

Queste chiavi stanno sotto un sotto-prefisso <scope>.aggrega.ai/, non sotto il prefisso aggrega.ai/ semplice, quindi sono fuori dal registro dei nomi riservati che la matrice qui sopra porta e fuori dalla regola dei prefissi riservati che il lint di pubblicazione applica alle chiavi con prefisso semplice.

AnnotazioneScritta suLetta daScopo
features.aggrega.ai/requiredType.<label>metadata.annotations del Componentil compilatore, sul grafo finalizzatoDichiara un mandato di presenza: ogni istanza di questo Component deve portare almeno un’associazione il cui tipo è uguale al valore dell’annotazione. <label> è un suffisso scelto dall’autore che nomina il requisito nella diagnostica; non è il nome di uno slot e nulla lo dereferenzia. Ripeti la chiave con etichette diverse per dichiarare più mandati.

Il mandato è soddisfatto da un’associazione a qualsiasi ambito — un blocco features: a livello di componente o di sottosistema, un blocco della Release a livello di confine o di componente, oppure un’espansione guidata da annotazioni — perché verifica l’insieme finale delle associazioni dell’istanza anziché da dove proviene ciascuna associazione. Un mandato non soddisfatto arresta la build nominando l’etichetta e il tipo richiesto; un valore che non è l’URI di un tipo di Feature, o una chiave senza etichetta dopo il prefisso, si arresta con una diagnostica distinta di dichiarazione malformata. La trattazione completa dell’authoring, e come un mandato differisce da uno slot featuresSchema, si trova in entities/component.md «Obblighi di presenza».

Etichette di provenienza emesse dai provider

Le annotazioni qui sopra fluiscono nella build — la Release o l’Aggregate le scrivono, i provider le consumano. I Providers emettono anche un insieme parallelo di etichette in uscita dalla build, apponendole all’output renderizzato così che gli strumenti a valle possano ricondurre le risorse di runtime al contenuto del catalogo che le ha prodotte. Queste etichette di provenienza non vengono scritte sulla Release; sono derivate dallo stato proprio della build (identità della Recipe, percorso del confine, nome dell’aggregato, ambiente, sync wave, versione del compilatore) ed emesse dal provider al momento del rendering.

L’insieme che i provider emettono, apposto a ogni manifest Kubernetes che il provider helm renderizza, a ogni artefatto caricato tramite $import: che il provider helm-chart aggiunge a un sotto-chart, e a ogni servizio emesso da compose — i template propri di un sotto-chart di helm-chart vengono copiati come li ha scritti il loro autore, quindi portano qualunque cosa quell’autore abbia scritto:

EtichettaOrigineEmissione
app.kubernetes.io/nameID del nodo (oppure, per una risorsa emessa da una FeatureRecipe, l’identificatore derivato per quell’associazione — vedi più sotto)Solo helm e helm-chart — etichetta standard di Kubernetes, non emessa sui servizi compose
aggrega.ai/component-idID del nodo (oppure, per una risorsa emessa da una FeatureRecipe, l’identificatore derivato per quell’associazione — vedi più sotto)Tutti e tre i provider
aggrega.ai/recipe-uri<recipe-name>:<recipe-version> della Recipe produttrice (o della FeatureRecipe produttrice per le risorse emesse da una FR)Tutti e tre i provider, quando l’entità produttrice ha impostati sia il nome sia la versione; un’annotazione su helm e helm-chart
aggrega.ai/boundary-pathPercorso del confine in cui è stato instradato il componenteTutti e tre i provider, quando il percorso del confine non è vuoto; un’annotazione su helm e helm-chart
aggrega.ai/aggregate-namemetadata.name dell’AggregateTutti e tre i provider, quando è impostato
aggrega.ai/compiler-versionVersione del compilatore impressa al momento della buildTutti e tre i provider, quando è impostato
aggrega.ai/providerIl provider che ha renderizzato la risorsaTutti e tre i provider
aggrega.ai/provider-versionLa versione di quel providerTutti e tre i provider
aggrega.ai/environmentmetadata.environment della ReleaseTutti e tre i provider — ogni Release lo dichiara
aggrega.ai/sync-waveIntero syncWave per confineTutti e tre i provider, quando è diverso da zero; un’annotazione su helm e helm-chart

I valori di aggrega.ai/aggregate-name, aggrega.ai/environment, aggrega.ai/compiler-version, aggrega.ai/provider e aggrega.ai/provider-version provengono da stringhe che la build non vincola alle regole di Kubernetes sui valori delle etichette — un Aggregate di nome imported/flow, un ambiente di nome eu/prod, la versione (devel) di una build di sviluppo. Su helm e helm-chart ciascuna di queste etichette porta il proprio valore così come è scritto quando il valore è già un valore di etichetta valido: lettere, cifre, -, _ e ., una lettera o una cifra a entrambe le estremità, al massimo 63 caratteri. Altrimenti l’etichetta porta il valore riscritto in quella forma — ogni altro carattere diventa -, le sequenze di - si riducono a uno solo, le estremità vengono rifilate fino a una lettera o una cifra e il risultato viene troncato a 63 caratteri al massimo — e il valore letterale viene aggiunto come annotazione sotto la stessa chiave. Un Aggregate di nome imported/flow riceve quindi l’etichetta aggrega.ai/aggregate-name: imported-flow e l’annotazione aggrega.ai/aggregate-name: imported/flow; un valore privo di qualsiasi carattere che un’etichetta conserva viene portato dalla sola annotazione. Un selettore confronta il valore dell’etichetta così come appare nell’output renderizzato, e gli strumenti che hanno bisogno del nome esatto leggono l’annotazione quando è presente. Compose, i cui valori di etichetta non sono vincolati, porta il valore letterale come etichetta.

Note sull’emissione per provider

  • helm — le etichette finiscono in metadata.labels su ogni risorsa Kubernetes renderizzata (Deployment, Service, PVC, ecc.), e le chiavi che il valore di un’etichetta non può portare — aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave e il valore letterale di ogni etichetta riscritta come descritto sopra — in metadata.annotations. I percorsi della modalità con sorgente (rendering tramite l’SDK di Helm con iniezione delle etichette dopo il rendering), della modalità sintetizzata (sintesi del carico di lavoro) e di artifacts: producono lo stesso insieme.
  • helm-chart — le stesse etichette e annotazioni finiscono su ogni artefatto caricato tramite $import: che il provider aggiunge ai templates/ di un sotto-chart. I template propri del chart di origine, e un artefatto a contenuto inline collocato nella radice del sotto-chart, non ne portano nessuna — vedi helm-chart.md.
  • compose — le etichette finiscono in services.<name>.labels su ogni servizio compose emesso. La modalità con sorgente (iniezione delle etichette dopo l’unione sul documento unito di base + valuesMapping) e la modalità sintetizzata (sintesi del carico di lavoro che imposta direttamente il blocco delle etichette del servizio) producono entrambe lo stesso insieme. L’etichetta app.kubernetes.io/name, specifica di Kubernetes, viene omessa dall’output di compose.

Per le risorse emesse da una FeatureRecipe, il valore di aggrega.ai/component-id viene costruito a partire dall’associazione anziché dal nome del componente ospitante — per ogni modo in cui una FeatureRecipe può fornire quelle risorse, così le risorse di un’associazione non sono mai indistinguibili per etichetta da quelle proprie del componente ospitante. Che quell’identità sia anche ciò da cui quelle risorse prendono il nome dipende dalla modalità di fornitura: un carico di lavoro che Aggrega sintetizza prende il nome dall’identità, mentre un chart o un frammento fornito dall’autore dell’associazione mantiene il nome della release Helm e il prefisso del file di output del componente ospitante, perché i template propri dell’autore vengono renderizzati rispetto a quel nome. Come viene composto il valore — i due possibili inizi, le parti e la loro giunzione con --, come viene scritto per esteso un carattere che un’etichetta non può portare, come viene accorciato un valore troppo lungo per la sua destinazione, e di quali nomi è e non è la base — è indipendente dal provider, quindi è indicato una sola volta in vocabulary/labels-and-annotations.md «Etichette di provenienza emesse sull’output renderizzato» anziché essere ripetuto qui. Questa pagina si occupa dell’altra metà: dove finiscono le etichette sull’output renderizzato di ciascun provider.

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

Annotazioni sync-wave

La chiave aggrega.ai/sync-wave qui sopra è accoppiata a un’annotazione sync-wave che gli strumenti a valle leggono per ordinare ciò che applicano. Su compose la chiave è un’etichetta, che espone il valore dell’ondata alle query con selettori; su helm e helm-chart è un’annotazione, e l’annotazione accoppiata fa emergere il valore dove ciascuno strumento lo legge per convenzione.

AnnotazioneEmissioneConsumata da
argocd.argoproj.io/sync-wavehelm, su ogni risorsa Kubernetes che renderizza, e helm-chart, su ogni artefatto caricato tramite $import: — dove syncWave è diverso da zero sul confine che contribuisceOrdinamento sync-wave di ArgoCD
helm.sh/hook-weightSolo helm, sui manifest generati dai template del chart che portano già un’annotazione helm.sh/hook quando syncWave è diverso da zeroOrdinamento per hook-weight di Helm all’interno di una fase di hook

L’emissione di helm.sh/hook-weight dipende dal percorso

Una sottigliezza che vale la pena segnalare agli autori di chart: helm.sh/hook-weight viene emessa solo sui manifest renderizzati attraverso il percorso di templating del chart — la directory templates/ del chart renderizzata tramite l’SDK di Helm. I Manifests prodotti attraverso il percorso degli artefatti — sul provider helm ogni voce del blocco artifacts: della Recipe, a contenuto inline o caricata tramite $import:, e su helm-chart una voce caricata tramite $import: — portano l’annotazione argocd.argoproj.io/sync-wave e l’insieme completo delle etichette di provenienza, ma non ricevono helm.sh/hook-weight — nemmeno quando l’artefatto porta un’annotazione helm.sh/hook.

La distinzione è strutturale: helm.sh/hook e helm.sh/hook-weight sono primitive di ordinamento del runtime di Helm che si applicano alle risorse di hook generate dai template del chart. Gli artefatti dell’autore della Recipe sono risorse aggiuntive dichiarate al livello della Recipe; per impostazione predefinita non partecipano al ciclo di vita degli hook di Helm.

Se ti serve l’ordinamento per hook-weight di Helm su una risorsa di hook, scrivi la risorsa come template di chart sotto la directory source: di una Recipe che il provider helm renderizza, anziché come voce di artifacts:; i template di un sotto-chart di helm-chart vengono copiati come sono stati scritti e non ricevono nessuna delle due annotazioni. Il template del chart riceverà sia argocd.argoproj.io/sync-wave sia helm.sh/hook-weight, corrispondenti al valore syncWave del confine che contribuisce.

Esempi di authoring

Collocazione e configurazione del registry a livello di confine:

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
aggrega.ai/image-registry: registry.corp.com
aggrega.ai/image-pull-secret: corp-registry-creds
components:
api: {}
worker: {}

Override per componente (il componente prevale sul confine per la stessa chiave di annotazione):

release.yaml
spec:
boundaries:
production:
annotations:
aggrega.ai/namespace: prod-east
components:
api: {}
legacy-thing:
annotations:
aggrega.ai/namespace: legacy-east # override — this component deploys elsewhere

Cascata delle annotazioni lato Aggregate

Le annotazioni si trovano anche sulla superficie di authoring dell’Aggregate — nell’ambito del sottosistema (spec.subsystems.<name>.annotations) e nell’ambito dell’istanza di componente (spec.subsystems.<name>.components.<name>.annotations oppure spec.components.<name>.annotations per i componenti di primo livello). La cascata lato Aggregate porta le annotazioni scritte dallo sviluppatore giù lungo l’albero dei sottosistemi fino ai componenti contenuti.

La regola della cascata

Un’annotazione a livello di sottosistema si propaga a ogni sottosistema annidato e a ogni componente contenuto nel sottoalbero del sottosistema. Le annotazioni di livello più vicino sovrascrivono quelle di livello più esterno con granularità per chiave: un’annotazione a livello di componente sovrascrive qualsiasi annotazione ereditata a livello di sottosistema per la stessa chiave, senza influire sulle chiavi sorelle né sui componenti fratelli.

Una chiave di annotazione in un ambito si trova in uno di tre stati:

  • Chiave assente — l’ambito non dichiara alcun valore per questa annotazione. I sottosistemi annidati e i componenti contenuti ereditano qualsiasi binding da un ambito antenato.
  • Un valore stringa — l’ambito dichiara un valore. I sottosistemi annidati e i componenti contenuti ereditano questo valore, a meno che non dichiarino un proprio valore o non vi rinuncino.
  • null YAML esplicito — l’ambito rimuove dal proprio sottoalbero qualsiasi legame ereditato per questa chiave. I componenti fratelli e i sottosistemi fratelli mantengono la propria ereditarietà indipendente; solo il sottoalbero dell’ambito che rinuncia perde il legame.
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool" # propagates to api and worker
components:
api:
# inherits feature.myco/db-pool: "shared-pool"
worker:
annotations:
feature.myco/db-pool: null # opts out for this component only
special:
annotations:
feature.myco/db-pool: "vip-pool" # closer-level override

Annotazioni dei Provider dichiarate nell’Aggregate

Anche le chiavi della matrice qui sopra scendono in cascata attraverso l’Aggregate, e un provider applica ciò che la cascata lascia su ciascun componente. L’aggrega.ai/namespace di un sottosistema colloca ogni componente al di sotto di esso; il valore proprio di un’istanza di componente colloca invece quel componente. Un modulo che l’Aggregate importa porta una propria cascata: i suoi sottosistemi e le sue istanze di componente raggiungono i componenti propri del modulo, e nulla di ciò che l’Aggregate importatore dichiara raggiunge l’interno di un modulo.

La Release sta al di sopra dell’Aggregate su ogni chiave. Dove la Release imposta una chiave per un componente — sul suo confine o sulla voce propria del componente — viene applicato il valore della Release; dove non ne imposta nessuno, quello dell’Aggregate. I due lati si sovrappongono chiave per chiave, così una Release che imposta solo aggrega.ai/namespace lascia in vigore un aggrega.ai/image-registry dichiarato dall’Aggregate.

Un null esplicito nella Release ritira solo il valore proprio della Release. Una voce di componente che scrive aggrega.ai/namespace: null rimuove il namespace che il confine della sua Release le avrebbe assegnato, e il componente prende allora il valore che il suo Aggregate dichiara — oppure nessuno, dove anche l’Aggregate non ne dichiara nessuno. Una Release non può rimuovere un valore che l’Aggregate dichiara; può solo impostarne uno proprio al di sopra.

# Aggregate
spec:
subsystems:
billing:
annotations:
aggrega.ai/namespace: billing # api and worker render into billing
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0
annotations:
aggrega.ai/namespace: billing-batch # worker renders into billing-batch
# Release
spec:
boundaries:
production:
components:
api:
annotations:
aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing
worker: {}

aggrega.ai/chart-name è l’unica chiave al di fuori di questa portata: nomina un chart ombrello assemblato da più componenti, quindi viene letta dai confini della Release che contribuiscono a quel chart, mai dalle annotazioni di un componente.

Un template di una Recipe o di una FeatureRecipe legge i contenitori delle annotazioni per nome — .context.annotations.aggregate, .context.annotations.release e .context.annotations.catalog contengono ciascuno ciò che quel lato ha scritto — quindi un template che legge una chiave di collocazione da un contenitore vede solo il valore di quel lato.

La partizione tra lato e pilastro

L’invariante dell’Aggregate come superficie di authoring limita le annotazioni lato Aggregate al pilastro dei valori. Un legame di annotazione di un Manifest dichiara percorsi di instradamento sotto maps.infra (instradamento lato Release) oppure sotto maps.values (instradamento lato Aggregate); un’annotazione lato Aggregate il cui legame dichiara solo percorsi maps.infra arresta la build con una diagnostica chiara che nomina la chiave dell’annotazione, il pilastro instradato e il lato di authoring. La regola simmetrica si applica al lato Release: le annotazioni lato Release possono instradare solo attraverso maps.infra; un’annotazione lato Release su un legame solo per i valori genera l’errore parallelo. Ogni diagnostica viene classificata nel dominio del documento in cui è stato scritto il valore dell’annotazione — [DEVELOPER_ERROR] da un Aggregate, [OPS_ERROR] da una Release — così l’intestazione nomina la superficie da aprire.

I legami che dichiarano percorsi in entrambi i pilastri instradano a ogni passaggio il sottoinsieme compatibile con il lato: un’annotazione lato Aggregate attiva solo i percorsi del pilastro dei valori, e un’annotazione lato Release attiva solo i percorsi del pilastro infra. La composizione tra lati — values dall’Aggregate, infra dalla Release — produce un’associazione di Feature per ogni coppia (Component, Feature) con entrambi i pilastri popolati e una provenienza per foglia che registra quale lato ha contribuito ciascuna foglia.

Esempio di authoring — un’annotazione di sottosistema viene instradata a values

# Manifest binding
spec:
mappings:
features:
type:
core/db-pool: db-pool-helm:1.0.0
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- pool # routes to values.pool
# Aggregate
spec:
subsystems:
data:
annotations:
feature.myco/db-pool: "shared-pool"
components:
api:
type: core/server:1.0.0
worker:
type: core/server:1.0.0

Dopo l’espansione delle annotazioni, sia api sia worker portano un’associazione sintetica della Feature feature.myco/db-pool il cui campo values.pool vale "shared-pool". Il grafo della build (aggrega validate --release <release> --ir-graph) registra ogni foglia con origin: annotation, side: aggregate e annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool.

Valori di annotazione strutturati

Una Feature con più campi configurabili invita a usare un’unica chiave di annotazione che porti valori per diversi di essi contemporaneamente. La forma di annotazione strutturata consente a una chiave di instradare verso più percorsi di legame in un’unica dichiarazione:

# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)
subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "prod-db"
read_replicas: 5
# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)
boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100

Il legame del Manifest dichiara l’instradamento di tutte e quattro le sottochiavi in liste maps: raggruppate per pilastro:

# Manifest
spec:
mappings:
features:
annotations:
feature.myco/db-pool:
feature: core/db-pool:1.0.0
maps:
values:
- db_name
- read_replicas
infra:
- pool_size
- max_connections

La forma del valore dell’annotazione è una di tre:

  • Stringa scalare — un singolo valore. Il legame deve dichiarare esattamente un percorso in totale; lo scalare viene instradato verso quel percorso.
  • Oggetto strutturato — una mappa da sottochiave a sottovalore. Il percorso di ciascuna sottochiave deve comparire nella lista maps.infra o maps.values del legame; il sottovalore viene instradato verso il campo dello schema della Feature nominato, nel pilastro dichiarato.
  • null YAML esplicito — rinuncia in blocco al legame ereditato per questo ambito della cascata.

Ogni sottochiave all’interno di un valore strutturato si risolve in modo indipendente rispetto alla lista maps del legame. Una sottochiave assente sia da maps.infra sia da maps.values arresta la build con un errore chiaro che nomina la sottochiave non valida e i percorsi dichiarati.

Unione in cascata per i valori strutturati

Le annotazioni strutturate scendono in cascata con un deep-merge per sottochiave. L’annotazione di un ambito figlio della cascata si unisce per sottochiave all’annotazione del genitore; il livello più vicino sovrascrive il genitore con granularità di sottochiave:

subsystems:
data:
annotations:
feature.myco/db-pool:
db_name: "data-default"
read_replicas: 3
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-override" # overrides parent at this subkey only
# read_replicas not listed → inherits 3 from parent
analytics:
annotations:
feature.myco/db-pool:
read_replicas: null # per-subkey opt-out: removes inherited subkey
# db_name not listed → inherits "data-default" from parent

Annotazioni effettive dopo la cascata:

  • Component api: { db_name: "api-override", read_replicas: 3 }
  • Component analytics: { db_name: "data-default" } — read_replicas escluso per rinuncia in questo ambito

Un livello figlio della cascata il cui valore è uno scalare (rispetto a un genitore strutturato) sostituisce in blocco anziché unirsi. Le discrepanze di forma tra livelli della cascata si risolvono a favore del valore di livello più vicino; il compilatore non avvisa in caso di discrepanza di forma.

null sull’intero valore e null per sottochiave

La cascata prevede due meccanismi di rinuncia a granularità diverse:

# Whole-value null — opts out wholesale at this scope
components:
api:
annotations:
feature.myco/db-pool: null

L’intero legame dell’annotazione viene soppresso in questo componente; nessuna associazione sintetica di Feature viene sintetizzata da questa chiave di annotazione in questo ambito. I componenti fratelli mantengono il proprio legame ereditato.

# Per-subkey null — opts out just one subkey
components:
api:
annotations:
feature.myco/db-pool:
db_name: "api-db"
read_replicas: null

L’annotazione continua a contribuire in questo ambito, ma la sottochiave read_replicas viene soppressa. Le altre sottochiavi (dichiarate in questo ambito o ereditate dai livelli genitori della cascata) restano valide.

Indicazioni per l’authoring: usa null sull’intero valore per disattivare in un ambito un’associazione di Feature guidata da annotazioni. Usa null per sottochiave quando vuoi mantenere la maggior parte del contributo di un’annotazione ma sopprimere uno o più campi specifici.

Partizione tra lato e pilastro per sottochiave

L’invariante dell’Aggregate come superficie di authoring si applica per sottochiave quando il valore di un’annotazione è strutturato. Il pilastro di ciascuna sottochiave (secondo la dichiarazione maps del legame) deve essere compatibile con il lato di authoring:

  • Un’annotazione lato Aggregate può portare solo sottochiavi instradate verso maps.values.
  • Un’annotazione lato Release può portare solo sottochiavi instradate verso maps.infra.

Una sottochiave instradata verso un pilastro incompatibile arresta la build con un errore chiaro che cita la sottochiave e il pilastro specifici. La catena di errori raccoglie tutte le sottochiavi incompatibili per annotazione prima di arrestarsi — gli operatori vedono ogni problema in un unico ciclo di build anziché procedere a cicli di correzione e ricompilazione ripetuti.

Validazione del tipo per sottochiave

Il valore di runtime di ciascuna sottochiave viene convalidato rispetto al tipo dichiarato nello spec.schema della Feature di destinazione, nel pilastro instradato. I tipi dichiarati supportati sono string, integer, number, boolean, object, array, null. Un sottovalore il cui tipo YAML non corrisponde al tipo dichiarato dello schema arresta la build con un errore chiaro che nomina la sottochiave, il tipo effettivo e il tipo dichiarato.

La corrispondenza dei tipi è rigorosa — nessuna coercizione. Una stringa "20" rispetto a un campo dello schema di tipo intero arresta la build; gli autori dichiarano correttamente i tipi nello schema della Feature oppure usano annotazioni scalari che passano come stringhe.

Leva di authoring per una validazione rigorosa. Le proprietà senza un type dichiarato nello spec.schema della Feature accettano qualsiasi forma del valore di runtime, mappe annidate comprese. Quando lo schema non dichiara un vincolo, la build non ne inventa uno. Gli autori che vogliono una validazione rigorosa del tipo per sottochiave dichiarano type su ogni proprietà in spec.schema. Il livello di rendering della FeatureRecipe a valle gestisce qualunque forma porti il contributo dell’annotazione.

Composizione tra lati

Quando sia un’annotazione lato Aggregate (sottochiavi values) sia un’annotazione lato Release (sottochiavi infra) puntano alla stessa associazione di Feature sullo stesso Component, la build unisce i contributi in un’unica associazione di Feature con entrambi i pilastri popolati. La provenienza per foglia registra l’origine di ciascuna sottochiave — l’associazione sintetizzata porta values.db_name attribuito al punto di authoring dell’Aggregate e infra.pool_size attribuito al punto di authoring della Release.

Lo schema della composizione tra lati è la forma di authoring canonica per le Features con campi misti di intento dello sviluppatore e di dimensionamento dell’operatore: l’Aggregate dichiara le scelte cognitive (quale database, quante repliche a livello di applicazione); la Release dichiara il dimensionamento fisico (quanto è grande il pool, quante connessioni a livello di infrastruttura). Un unico legame del Manifest le collega con un solo insieme di dichiarazioni maps.

  • Architettura dei Provider — l’architettura a plugin dei provider e il ruolo del Plugin di rendering dei provider.
  • ../entities/release.md — la superficie di authoring della Release dove si trovano le annotazioni di confine e di componente.
  • ../entities/aggregate.md — la superficie di authoring dell’Aggregate dove si trovano le annotazioni a livello di sottosistema e di componente.
  • ../entities/manifest.md — la mappa mappings.features.annotations del Manifest, dove i legami di annotazione dichiarano il proprio instradamento maps:.
  • ../../architecture/11-governance-and-compliance.md — come la provenienza viene impressa in fase di compilazione, a complemento delle annotazioni controllate dall’autore.