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
- 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.
- Ogni provider documenta quali annotazioni legge e quali valori predefiniti applica.
- 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
infradel componente. - 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.
- 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.
- Il prefisso
aggrega.ai/è riservato alla libreria standard. Le annotazioni aziendali personalizzate usano un prefisso proprio. - 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-chartprende il nome del chart ombrello daaggrega.ai/chart-namee, 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. - 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-accounteaggrega.ai/kubernetes-versiondanno 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-nameviene risolta una sola volta quando viene assemblato un chart ombrello, e le tre chiaviaggrega.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
| Annotazione | Applicata da | Scopo | Predefinito |
|---|---|---|---|
aggrega.ai/namespace | helm (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-name | riservata; nessun provider la legge | Riservata a un nome di progetto Docker Compose | — |
aggrega.ai/region | riservata; nessun provider la legge | Riservata a una regione cloud nell’ambito di collocazione | — |
aggrega.ai/account-id | riservata; nessun provider la legge | Riservata a un identificatore di account cloud nell’ambito di collocazione | — |
aggrega.ai/kubernetes-version | helm (con sorgente) | Versione di Kubernetes del cluster in cui viene distribuito il componente, che un chart renderizzato dalla sorgente legge come .Capabilities.KubeVersion | La 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
| Annotazione | Applicata da | Scopo | Predefinito |
|---|---|---|---|
aggrega.ai/image-registry | helm, compose — solo sintetizzato | Prefisso di registry per le immagini dei container, applicato a ogni riferimento a un’immagine di container sintetizzato | Nessun prefisso |
aggrega.ai/image-pull-secret | helm — solo sintetizzato | Nome di imagePullSecrets di Kubernetes, unito alle voci esistenti del pod sintetizzato | Nessuno |
Categoria 3 — Rete
| Annotazione | Applicata da | Scopo | Predefinito |
|---|---|---|---|
aggrega.ai/cluster-domain | riservata; nessun provider la legge | Riservata a un suffisso DNS per il rilevamento dei servizi tra namespace | — |
aggrega.ai/ingress-class | riservata; nessun provider la legge | Riservata a una IngressClass di Kubernetes sulle risorse Ingress | — |
aggrega.ai/service-mesh | riservata; nessun provider la legge | Riservata alle annotazioni di iniezione del sidecar della mesh | — |
Categoria 4 — Sicurezza
| Annotazione | Applicata da | Scopo | Predefinito |
|---|---|---|---|
aggrega.ai/service-account | helm — solo sintetizzato | ServiceAccount di Kubernetes per i Pod sintetizzati; sovrascrive il workload.serviceAccount della Recipe quando sono impostati entrambi | Il workload.serviceAccount della Recipe, oppure non impostato quando la Recipe non ne dichiara nessuno |
aggrega.ai/pod-security-standard | riservata; nessun provider la legge | Riservata a un livello dei Pod Security Standards | — |
aggrega.ai/iam-role | riservata; nessun provider la legge | Riservata a un ruolo di identità cloud associato a un carico di lavoro | — |
Categoria 5 — Pacchettizzazione
| Annotazione | Applicata da | Scopo | Predefinito |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — per assemblaggio | Nome del chart ombrello | Nome dell’Aggregate e percorso di assemblaggio dell’ombrello, uniti — vedi Risoluzione del nome del chart |
aggrega.ai/chart-version | riservata; nessun provider la legge | Riservata a una versione di chart Helm | — |
aggrega.ai/stack-name | riservata; nessun provider la legge | Riservata a uno stack nominato esplicitamente | — |
aggrega.ai/tf-backend | riservata; nessun provider la legge | Riservata a un identificatore del backend di stato di Terraform | — |
Categoria 6 — Destinazione cloud
| Annotazione | Applicata da | Scopo | Predefinito |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — per riferimento tra confini | Account 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-region | cloudformation — per riferimento tra confini | Regione 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-arn | cloudformation — per riferimento tra confini | ARN del ruolo IAM che una lettura di stack tra account assume per raggiungere i valori esportati di uno stack peer | Nessun 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.
| Provider | Tipo di input | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-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 itSu 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 itQuindi 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.
| Annotazione | Applicata da | Scopo | Predefinito |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | Nome 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-account | cloudformation | L’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-region | cloudformation | La 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-arn | cloudformation | L’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.annotationsdel Manifest che usano il prefissoaggrega.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 usanofeature.aggrega.ai/per le scorciatoie della libreria standard o un dominio personalizzato per le scorciatoie aziendali.Nota: un
nullesplicito 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.
| Annotazione | Scritta su | Letta da | Scopo |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | metadata.annotations del Component | il compilatore, sul grafo finalizzato | Dichiara 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:
| Etichetta | Origine | Emissione |
|---|---|---|
app.kubernetes.io/name | ID 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-id | ID 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-path | Percorso del confine in cui è stato instradato il componente | Tutti e tre i provider, quando il percorso del confine non è vuoto; un’annotazione su helm e helm-chart |
aggrega.ai/aggregate-name | metadata.name dell’Aggregate | Tutti e tre i provider, quando è impostato |
aggrega.ai/compiler-version | Versione del compilatore impressa al momento della build | Tutti e tre i provider, quando è impostato |
aggrega.ai/provider | Il provider che ha renderizzato la risorsa | Tutti e tre i provider |
aggrega.ai/provider-version | La versione di quel provider | Tutti e tre i provider |
aggrega.ai/environment | metadata.environment della Release | Tutti e tre i provider — ogni Release lo dichiara |
aggrega.ai/sync-wave | Intero syncWave per confine | Tutti 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 inmetadata.labelssu 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-wavee il valore letterale di ogni etichetta riscritta come descritto sopra — inmetadata.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 diartifacts:producono lo stesso insieme.helm-chart— le stesse etichette e annotazioni finiscono su ogni artefatto caricato tramite$import:che il provider aggiunge aitemplates/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 inservices.<name>.labelssu 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’etichettaapp.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.
| Annotazione | Emissione | Consumata da |
|---|---|---|
argocd.argoproj.io/sync-wave | helm, su ogni risorsa Kubernetes che renderizza, e helm-chart, su ogni artefatto caricato tramite $import: — dove syncWave è diverso da zero sul confine che contribuisce | Ordinamento sync-wave di ArgoCD |
helm.sh/hook-weight | Solo helm, sui manifest generati dai template del chart che portano già un’annotazione helm.sh/hook quando syncWave è diverso da zero | Ordinamento 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:
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):
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereCascata 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.
nullYAML 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 overrideAnnotazioni 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.
# Aggregatespec: 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# Releasespec: 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 bindingspec: 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# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0Dopo 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: 100Il legame del Manifest dichiara l’instradamento di tutte e quattro le sottochiavi in liste maps: raggruppate per pilastro:
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connectionsLa 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.infraomaps.valuesdel legame; il sottovalore viene instradato verso il campo dello schema della Feature nominato, nel pilastro dichiarato. nullYAML 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 parentAnnotazioni effettive dopo la cascata:
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" }—read_replicasescluso 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 scopecomponents: api: annotations: feature.myco/db-pool: nullL’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 subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: nullL’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.
Riferimenti correlati
- 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.annotationsdel Manifest, dove i legami di annotazione dichiarano il proprio instradamentomaps:. - ../../architecture/11-governance-and-compliance.md — come la provenienza viene impressa in fase di compilazione, a complemento delle annotazioni controllate dall’autore.