Feature
Il ruolo concettuale dell’entità Feature (il tratto operativo modulare del Dominio 2) è descritto in architecture/04-entity-taxonomy.md. La distinzione tra Features operative e Features di credenziali (quelle con l’etichetta feature.aggrega.ai/kind: secret) è descritta in architecture/08-credential-model.md. Il vocabolario delle etichette semantiche usato dai selettori di Feature si trova in entities/component. Questa pagina tratta la superficie di authoring del catalogo di Feature.
Posizione nel catalogo
A differenza dei Components (che usano URI a tre segmenti con sottodirectory per categoria), le Features sono organizzate in modo piatto: una directory per ogni Feature sotto il suo publisher, contenente una directory per ogni versione.
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...URI OCI: hub.aggrega.ai/feature/{publisher}/{feature-name}:{version} (ad es. hub.aggrega.ai/feature/core/data-masking:1.0.0).
Contratto di authoring
Le Features dichiarano:
metadata.labels: usafeature.aggrega.ai/kind: secretper contrassegnare una Feature come Feature di credenziali. L’etichetta è un metadato descrittivo per l’autore, per il sito del catalogo e per i selettori di etichette; nessun ramo del compilatore la legge, e ciò che un collegamento produce è deciso dalla FeatureRecipe a cui il Manifest mappa il suo tipo, non dall’etichetta. Una Feature di credenziali e una Feature ordinaria si collegano allo stesso modo, sulla stessa superficie di collegamento, a qualsiasi ambito. La famiglia di credenziali della libreria standard si suddivide per risultato:core/secret-valueconsegna un valore nella pipe di iniezione;core/referenced-secretnomina una risorsa segreta referenziabile (un Secret di Kubernetes, un segreto di AWS Secrets Manager, una voce di Vault), creata dall’output della sua FeatureRecipe o già esistente, e dichiara un contratto di outputschema.provides—name(il localizzatore della risorsa, neutrale rispetto al provider) ekey(il campo dati al suo interno) — che un consumatore legge come.features.<slot>.provides.<key>per fare riferimento alla risorsa senza ricavarne di nuovo il nome;core/referenced-secret-setmaterializza una risorsa che porta un insieme di chiavi dati fornito dal chiamante e pubblica solo il localizzatore, per un consumatore il cui target conosce già i nomi delle chiavi che legge;core/secret-providedespone il valore di un segreto preesistente;core/generated-secretnon produce nulla, perché il motore di destinazione genera e gestisce la credenziale da sé, quindi non dichiara névaluesnéprovidese le sue FeatureRecipes sono puro cablaggio che non renderizza alcun byte. Due assi separano i membri: chi fornisce il materiale — un autore lo scrive o indica dove recuperarlo, oppure il motore di destinazione lo possiede interamente, come concore/generated-secret— e cosa produce il collegamento: un valore iniettato, una risorsa referenziabile o nulla di renderizzato. Ogni membro è pari agli altri sulla stessa superficie di collegamento, quindi uno slot di credenziali è sempre vincolato e ciò che varia tra le Releases è ciò che lo vincola. Una Feature di credenziali che dichiara un contrattoschema.providesobbliga ogni FeatureRecipe che la implementa a pubblicare quelle chiavi — altrimenti la build si interrompe — e ilselectordi uno slot difeaturesSchemapunta al membro della famiglia di cui ha bisogno.usesSchema(facoltativo): dichiara i socket topologici che la Feature può consumare (ad es. il socketpath/keydi una Feature di credenziali che punta a un vault). Vedi architecture/13-catalog-and-registry.md §2 per il meccanismo dello Split Schema.schema: valida i blocchivalueseinfradel collegamento della Feature — l’intento cognitivo che lo sviluppatore configura su ogni collegamento nell’Aggregate (ivaluessono il dominio dello sviluppatore, e lo schema della Release vietavalues:sui collegamenti delle Feature) e la capacità che l’operatore decide per ambiente nella Release (infra). Un campo che dichiara undefault:viene sia validato rispetto a esso sia inserito nel pilastro renderizzato quando nessuno lo scrive; vedi Ambito della Feature e forma di authoring. Accetta JSON Schema 2020-12 espresso nell’abbreviazione YAML in forma compatta (il predefinito; vedivocabulary/compact-form-authoring.md) o in YAML JSON Schema completo, con$ref:tra documenti verso voci di SchemaLibrary per forme condivise (vedivocabulary/cross-document-ref.md). Una foglia che contiene materiale segreto dichiarasensitive: true— le Features di credenziali nella libreria standard contrassegnano la foglia che contiene il materiale e lasciano deliberatamente non contrassegnati i localizzatori che pubblicano, poiché un nome di risorsa e una chiave dati sono entrambi pubblici. La parola chiave, e il limite di ciò che dichiararla ottiene, sono invocabulary/compact-form-authoring.md«Dichiarare una foglia sensibile».featuresSchema(facoltativo): dichiara gli slot di collegamento di cui la Feature ha bisogno per il proprio funzionamento — una Feature dichiara gli slot esattamente come fa un Component, quindi una Feature che a sua volta necessita di una credenziale (la chiave API di una Feature sidecar di Datadog, per esempio) nomina il punto di binding invece di ricorrere agli slot del Component ospite. Vedi La credenziale propria di una Feature per una Feature che dichiara il proprio slot e una FeatureRecipe che legge ciò che lo riempie. Ogni slot accetta gli stessi campi di uno slotfeaturesSchemadi un Component, con la stessa semantica — inclusi unselectorfacoltativo (un selettore di etichette in stile Kubernetes che vincola quale Feature può riempire lo slot, l’analogo per gli slot di un selettore di socketusesSchema; un riempimento le cui etichette non lo soddisfano interrompe la build, e il selettore è valutato rispetto alle etichette della Feature collegata e a nient’altro), unsensitivefacoltativo (che dichiara che qualunque cosa vincoli lo slot gestisce materiale segreto — un’affermazione sul punto di binding anziché su un particolare riempimento) e la stessa apertura: dichiarare uno slot non vieta mai un collegamento sotto un nome che nessuno slot dichiara. La tabella completa dei campi, la dichiarazione di sensibilità a livello di slot e come differisce da quella di una foglia dello schema, e le due forme in cui viene distribuita un’unica entità che dichiara slot si trovano tutte in entities/component.md «Slot di collegamento».appliesTo/appliesToAnyOf: selettori di etichette che controllano a quali Components la Feature può collegarsi. Sono valutati dal motore nativo di corrispondenza delle etichette del compilatore durante la fase di analisi statica. Vedi Collegamento basato su etichette più avanti e architecture/13-catalog-and-registry.md §2 «Selettori in stile Kubernetes» per il riferimento sulla sintassi dei selettori.interoperability(facoltativo): un blocco annidato che contieneconflictsWith— le Features insieme alle quali questa Feature non può raggiungere un componente. La build si interrompe prima del rendering quando un componente finisce per portarle entrambe, a qualunque ambito ciascuna sia stata collegata. Vedi Il bloccointeroperabilitypiù avanti per la spiegazione completa.
Il rendering strutturale di una Feature è legato alla sua FeatureRecipe corrispondente, che mappa l’interfaccia della Feature a un’implementazione infrastrutturale concreta.
Collegamento basato su etichette
I due selettori applies dello schema della Feature controllano a quali Components la Feature si collega, valutati dal motore nativo di corrispondenza delle etichette del compilatore durante la fase di analisi statica:
appliesTo— una stringa di selettore di etichette in stile Kubernetes; la superficie di composizione AND. I requisiti separati da virgole devono valere tutti, con il vocabolario completo degli operatori:key=value,key!=value,key in (v1, v2),key notin (v1, v2),keyda solo (etichetta presente),!key(etichetta assente). Una Feature che dichiaraappliesTo: "datastore.aggrega.ai/engine=vector"si collega solo ai Components etichettati con quella esatta coppia chiave-valore;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"esprime «qualsiasi server o worker che non contenga dati riservati» in un’unica stringa di selettore.appliesToAnyOf— la superficie di composizione OR. Un elenco di elementi selettore in cui è sufficiente che un singolo elemento corrisponda. Ogni elemento è o un selettore in forma di stringa (stessa grammatica diappliesTo; i requisiti all’interno della stringa sono combinati in AND) o una mappa chiave-valore piatta per la corrispondenza di sola uguaglianza. Si usa quando una Feature si adatta a più forme di componente non correlate — per esempio, una Feature di osservabilità che si applica a{ component.aggrega.ai/type: worker }OPPURE a{ component.aggrega.ai/type: task }senza costringere le due in un’unica stringa di selettore.
Senza la forma any-of, gli architetti dovrebbero duplicare lo stesso YAML della Feature per ogni forma di componente non correlata a cui la Feature si adatta. Le due forme si compongono: una Feature può dichiararle entrambe, e i risultati sono combinati in AND tra le forme — la stringa appliesTo deve valere e almeno un elemento di appliesToAnyOf deve corrispondere. Un selettore omesso o vuoto non dichiara alcun vincolo e corrisponde a ogni insieme di etichette.
Una stringa di selettore viene letta rispetto alle sei forme ogni volta che si valuta un collegamento della Feature, e un requisito al di fuori di esse interrompe la build invece di essere letto come un altro selettore: un requisito vuoto (una virgola iniziale, finale o doppia, o una stringa di soli separatori), una chiave che contiene spazi bianchi o uno qualsiasi tra =, !, (, ) e la virgola, e un insieme in ( o notin ( non chiuso. È ciò che intercetta gli errori che altrimenti selezionerebbero silenziosamente l’opposto di quanto inteso: appliesTo: "!tier=frontend", scritto per tenere una Feature lontana dai frontend, viene rifiutato perché ! nomina una chiave di etichetta e nient’altro — tier!=frontend è il modo per escludere un valore — e tier in frontend viene rifiutato a favore di tier in (frontend). Un valore è il testo dopo il suo operatore, qualunque carattere contenga, quindi tier==frontend richiede un’etichetta il cui valore è =frontend. L’interruzione nomina la Feature, il suo selettore e il requisito che non è stato possibile leggere. Una Feature che nulla collega non viene mai valutata, quindi un selettore malformato su di essa non viene segnalato finché un collegamento non la nomina.
Vedi architecture/13-catalog-and-registry.md §2 «Selettori in stile Kubernetes» per il riferimento sulla sintassi dei selettori — la grammatica accettata da un selettore di Feature è la stessa accettata dai selettori di socket usesSchema, la forma di stringa che gli utenti Kubernetes conoscono da kubectl get -l.
Il blocco interoperability
Lo schema della Feature dichiara un blocco spec.interoperability facoltativo che porta un unico controllo: con quali altre Features questa Feature può coesistere su un componente.
interoperability.conflictsWith — un elenco delle Features mutuamente esclusive con la Feature che si sta definendo, ciascuna scritta nel modo in cui il type di un collegamento nomina una Feature. Impedisce di generare configurazioni incompatibili — collegare allo stesso componente sia una mesh solo TCP sia un proxy consapevole di HTTP, per esempio.
La build si interrompe prima di renderizzare qualsiasi cosa quando un componente finisce per portare questa Feature e una Feature nominata dal suo elenco. Ciò che conta è la portata: un collegamento raggiunge il componente su cui è scritto, e ogni componente all’interno del sottosistema o del confine su cui è scritto, inclusi i confini annidati; un collegamento scritto su una voce di componente della Release, o prodotto dall’espansione guidata dalle annotazioni, raggiunge il suo componente allo stesso modo. Quindi un conflitto dichiarato interrompe la build quando le due Features sono collegate allo stesso componente, quando una è su un confine e l’altra su un componente al suo interno, quando una è su un confine esterno e l’altra su un confine annidato al suo interno che contiene un componente, e quando una è su un sottosistema e l’altra su un componente di quel sottosistema. Due Features collegate a confini fratelli che non condividono alcun componente non si incontrano mai, e un confine che non contiene alcun componente non raggiunge nulla — in nessuno dei due casi la build si interrompe.
- Una dichiarazione è sufficiente. La build si interrompe quando l’elenco di una delle due Feature nomina l’altra; la seconda Feature non deve elencare a sua volta la prima.
- Nomi, qualunque siano le versioni. Ogni voce e il tipo di ogni collegamento vengono confrontati togliendo l’eventuale versione, quindi una voce
core/fixed-replica-controllercorrisponde a un collegamento dicore/fixed-replica-controller:2.0.0, e una voce che porta una versione corrisponde a ogni versione della Feature che nomina. - I nomi sono tutto ciò che legge. Il compilatore confronta i nomi dichiarati dall’autore della Feature con le Features che un componente porta — lo stesso tipo di valutazione di
appliesTo, su dati scritti dall’autore. Se due Features siano incompatibili è un giudizio dell’autore, e l’elenco è il luogo in cui viene registrato.
L’interruzione nomina la Feature il cui elenco nomina l’altra, ogni punto in cui ciascuna delle due è stata collegata — sul componente nell’Aggregate, su un sottosistema, su un confine della Release con il suo percorso, su una voce di componente della Release, o tramite l’espansione guidata dalle annotazioni di un’annotazione nominata — e il componente in cui si incontrano. Una coppia che si incontra su più componenti viene segnalata una volta per ciascuno. Vedi errors/fatal-halts.md per il messaggio.
Esempio:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controllerQuesta Feature si collega solo ai Components di tipo server e dichiara l’incompatibilità con un’altra Feature che controlla le repliche: una build in cui un componente qualsiasi finisce per portarle entrambe si interrompe prima del rendering. Una FeatureRecipe che ha bisogno del nome del componente a cui è collegata — per puntare un autoscaler al suo target, per esempio — lo legge dal suo contesto di template e lo scrive ovunque il suo output ne abbia bisogno: .context.instance_id è l’identità del componente, e .context.rendered_name è il nome che il provider del componente stesso dà alle risorse che renderizza per esso, ed è quello con cui indirizzare una risorsa — con helm, il nome del Deployment emesso da un carico di lavoro sintetizzato, e il nome della release da cui un chart costruisce i propri nomi.
Ereditarietà tramite extends
Una Feature può dichiarare spec.extends: <feature-name> che punta a una Feature base di cui eredita la superficie di authoring. Il riferimento nomina la base tramite il suo metadata.name, non tramite la coordinata di registro con cui la Feature viene pubblicata, e accetta le stesse tre forme di versione di ogni riferimento di catalogo: semplice (core/queue) per la versione più alta disponibile, esatta (core/queue:1.0.0) o un intervallo caret (core/queue:^1.0.0). Il compilatore percorre la catena dei genitori al caricamento del catalogo, verifica che la catena sia aciclica, quindi unisce le spec dei genitori nel figlio per produrre un’unica Feature risolta. I campi scritti dal figlio hanno la precedenza in caso di collisione di chiavi; metadata.labels e metadata.annotations del genitore, i selettori appliesTo / appliesToAnyOf, il blocco interoperability, usesSchema, featuresSchema e le dichiarazioni JSON Schema 2020-12 su schema vengono uniti automaticamente verso il basso. Ogni altro campo di metadata è quello del figlio alla lettera, quindi identità e provenienza non si ereditano mai.
Cosa eredita il metadata: di una Feature. labels e annotations si uniscono chiave per chiave lungo la catena, a partire dalla base, e il valore della Feature che estende prevale su una chiave condivisa — la stessa regola seguita dai Components. Il resto di metadata: non viaggia: name, version, description, maintainers, license, repository, home e keywords sono quelli propri della Feature che estende, esattamente come scritti.
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }Il core/kafka-queue unito eredita appliesTo dal genitore, eredita le proprietà values.qos e infra.partition_count, e vi aggiunge values.compression_codec. Un figlio che dichiara esplicitamente appliesTo sostituisce in blocco il selettore del genitore (l’unione dei selettori di etichette non è profonda — il selettore del figlio sostituisce quello del genitore). Lo schema.values.qos di un figlio sostituisce la dichiarazione del genitore per quella proprietà.
Come eredita ciascuna parte della superficie di collegamento. Le due forme di selettore si ereditano indipendentemente l’una dall’altra, perché si compongono invece di sostituirsi: ogni forma presente deve valere — la stringa appliesTo deve corrispondere, e almeno un elemento di appliesToAnyOf deve corrispondere — mentre una forma assente non vincola nulla. Quindi una Feature può prendere il selettore AND della sua base dichiarando un proprio insieme OR. Il blocco interoperability si eredita campo per campo — un figlio che dichiara il blocco senza un elenco conflictsWith porta comunque l’elenco dichiarato dalla sua base, mentre un figlio che dichiara il proprio conflictsWith sostituisce l’elenco della base invece di aggiungervisi. Una Feature che non dichiara nessuno dei tre si collega esattamente dove si collega la sua base.
L’ereditarietà è un’unione di schemi, non un binding di interfacce. Una catena extends: di Feature produce un’unica Feature risolta, non una famiglia polimorfica. L’URI della Feature base della catena non è ciò a cui fa riferimento il campo feature: di un binding del Manifest — i Manifests vincolano tramite l’URI della Feature foglia, e lo schema risolto include le proprietà ereditate. Il contratto di Feature che una FeatureRecipe implements: è analogamente l’URI foglia; le FeatureRecipes non percorrono la catena di ereditarietà.
aggrega pull recupera la base. Una Feature base è una dipendenza di ogni Release che associa una Feature che la estende, indipendentemente dal fatto che qualcos’altro la nomini. aggrega pull segue ogni extends: fino alla fine della catena, recupera dal registry una base che nessuna directory di catalogo contiene e registra ogni base nel lockfile della Release, referenziata dallo spec.extends della Feature che la nomina; una build legge la base da lì.
Modalità di errore. Una catena extends: ciclica, e un genitore che nessuna entità di catalogo fornisce, interrompono la build, nominando la Feature da cui è partita la risoluzione, la Feature di cui aprire la riga extends: e il riferimento che dichiara. I messaggi sono in Cyclic extends on Components or Features (extends ciclico su Components o Features) e An extends: chain cannot be assembled (Non è possibile assemblare una catena).
Per il vocabolario più ampio su ereditarietà / interfaccia tra Components, Features e Features di credenziali, vedi vocabulary/inheritance-and-interface.md.
Componibilità: il contratto sociale della purezza
La convenzione della libreria standard è una Feature, una funzione interna — un sidecar di osservabilità è una Feature di osservabilità; un sidecar di proxy di rete è una Feature di proxy di rete; non si combinano in un unico composito con due aspetti non correlati. La convenzione mantiene le singole Features componibili, versionate in modo indipendente e collegabili in modo indipendente.
Il compilatore Go principale non impone questa convenzione. Le definizioni di Feature con aspetti misti sono sintatticamente legali e compilano senza errori. L’imposizione è facoltativa:
- Le aziende che creano cataloghi interni possono scrivere un plugin linter personalizzato che ispeziona le definizioni di Feature in CI/CD e avvisa quando le etichette
appliesTodi una singola Feature coprono domini di capacità non correlati. - Un autore di Feature che registra, in
interoperability.conflictsWith, che due Features si sovrapporrebbero aderisce a un controllo in fase di build: il compilatore interrompe la build ovunque le due raggiungano un unico componente. Confronta i nomi dichiarati e nient’altro, quindi impone la dichiarazione scritta da un autore anziché la convenzione di purezza stessa.
Le Features open source della libreria standard seguono la convenzione di purezza per disciplina di authoring; i cataloghi aziendali sono liberi di discostarsene quando un composito strettamente accoppiato si adatta davvero al modello di deployment.
Che cosa giustifica una Feature, e dove va la regolazione propria di un prodotto
Una Feature è un collegamento: porta qualcosa che lo sviluppatore o l’operatore collega deliberatamente — risorse, un passo di pipeline, cablaggio — e la convenzione della libreria standard è che possa essere onorata da almeno due prodotti indipendenti. Questa seconda metà è il test da applicare prima di crearne una, perché la portabilità è ciò che la parola collegamento promette. Un collegamento dice che la capacità viaggia: collegala a un componente, collegala a un altro, e la realizzazione di ciascun prodotto la onora nei propri termini.
Una capacità che un solo prodotto sul campo possiede è una regolazione propria di quel prodotto anziché una Feature. Va inserita come valore scritto sulla superficie propria di quel prodotto, che l’autore che la decide imposta nel proprio pilastro e legge accanto a tutto il resto che configura lo stesso prodotto. Pubblicarla invece come Feature offre una portabilità che nessun altro prodotto può fornire: il collegamento nomina un solo prodotto per costruzione, quindi un autore che lo collega al prossimo prodotto a cui ricorre si trova davanti a un build che si arresta nominando il tipo, e la Feature ha insegnato una capacità che non ha mai avuto.
Il test conta i prodotti sul campo, non i componenti di questo catalogo, ciascuno letto dal proprio riferimento di configurazione corrente. Due prodotti indipendenti che implementano una capacità la rendono portabile indipendentemente da quanti di essi siano distribuiti qui, quindi una Feature può essere dichiarata prima che qualcosa nel catalogo la realizzi — collegarla arresta allora il build nominando il tipo — e ogni realizzazione distribuita è una FeatureRecipe per un solo prodotto, che onora il collegamento in qualunque modo quel prodotto lo configuri.
Il pinning dei certificati upstream è il caso esemplare. Un pin è un controllo su quale chiave un upstream può presentare: accettare solo un certificato la cui chiave pubblica corrisponde a una fornita dalla Release. È un’asserzione diversa dal richiedere che il certificato di un upstream si concateni a un trust anchor fornito dalla Release, e diversa ancora dall’asserire ciò che dice il soggetto di un certificato — entrambe stabiliscono ciò che un certificato deve dire, mentre un pin stabilisce quale chiave deve essere. Diversi gateway qui possono verificare rispetto a un anchor, ed è per questo che dataplane.aggrega.ai/upstream-tls: trust-anchor è un valore che un selettore può confrontare. Il pinning è una capacità separata, e almeno due prodotti indipendenti la implementano per le connessioni che aprono verso un upstream: Tyk accetta la chiave pubblica dell’upstream in formato PEM, ed Envoy ne accetta un hash. Quindi è una Feature, core/upstream-key-pinning, il cui selettore nomina dataplane.aggrega.ai/upstream-pinning: public-key, e ciò che questo catalogo realizza ha una risposta prodotto per prodotto: core/gateway/tyk porta il valore e una FeatureRecipe per ciascuno dei suoi target, mentre i gateway qui che incorporano Envoy espongono la sua impostazione di pin solo per i certificati presentati dai client, o non la espongono affatto, quindi non portano alcun valore e un collegamento a essi si arresta al selettore. Un pin restringe ciò che un upstream può presentare; è un controllo, non una garanzia che la connessione sia per il resto solida.
Due limiti al test, e il secondo è la metà che si tralascia più facilmente:
- È una disciplina di authoring, non un controllo del compilatore. Una Feature che dichiara opzioni che nessun prodotto implementa supera allo stesso modo la validazione dello schema, il linter di pubblicazione e un render — il compilatore non interpreta ciò che una Feature promette. Il giudizio resta all’autore del catalogo.
- L’incapacità di un prodotto di onorare un’opzione non è un motivo per eliminare quell’opzione. Dove due o più prodotti offrono una capacità con nomi che si raggruppano, la capacità è portabile e la Feature la mantiene; il prodotto che non può onorarla la rifiuta. Una Feature ridotta a ciò che ogni prodotto supporta non ha quasi più nulla da dire.
Ambito della Feature e forma di authoring
Lo spec.schema di una Feature definisce le forme values: e infra: proprie della Feature — l’intento cognitivo che lo sviluppatore configura per ogni collegamento della Feature nell’Aggregate (values), distinto dai numeri di capacità che l’operatore decide per ambiente (infra). I pilastri della Feature vivono nei propri namespace e sono validati indipendentemente dai pilastri del Component ospite. Quando lo sviluppatore collega una Feature autoscaler a un Component web-server nell’Aggregate, l’Aggregate porta i values: del Component (forma dell’ospite) più i values: della Feature (la forma dell’intento di scaling — quale metrica guida lo scaling); i numeri di capacità rivolti all’operatore (min_replicas / max_replicas) fluiscono attraverso il blocco infra: della Release sul collegamento della Feature.
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10Lo schema: della Feature valida i blocchi values: e infra: propri del collegamento della Feature. Lo schema: del Component valida quelli propri del Component. I due sono valutati indipendentemente nella fase di analisi statica; un pilastro del collegamento che non corrisponde allo schema: della Feature arresta il build con un errore circoscritto al punto di collegamento della Feature, non al Component ospite. Ciò che viene validato è la configurazione effettiva del collegamento — il risultato della composizione di ogni ambito che l’ha configurato — quindi un valore reso conforme in un ambito e poi sovrascritto con qualcosa di non valido in uno più ristretto viene intercettato.
I default dichiarati si materializzano nei pilastri renderizzati del collegamento. Oltre alla validazione, un default: dichiarato su un campo values o infra di una Feature viene inserito nel pilastro renderizzato di quel collegamento al momento del build per ogni chiave che nessuno ha scritto — così un template di FeatureRecipe che legge {{ .infra.tier }} riceve il valore dichiarato nello schema anziché uno vuoto. I valori forniti dall’autore prevalgono sempre, e un default riempie solo le chiavi che essi omettono: un collegamento che scrive una chiave dello schema della Feature riceve comunque i default dichiarati per le altre chiavi di quello schema, e un oggetto annidato scritto in parte mantiene ciò che è stato scritto e acquisisce i fratelli che non lo erano.
Tre proprietà del riempimento sono utili da conoscere durante l’authoring:
- Un default non sostituisce mai un valore fornito da un ambito. Dove una Feature è collegata a più di un ambito — un confine di Release e uno dei suoi componenti, per esempio — prevale il valore dell’ambito più ristretto e il default riempie solo ciò che nessun ambito ha scritto.
- Un default riempie un collegamento; non ne crea mai uno. Dichiarare default su una Feature che nulla collega non contribuisce nulla all’output, quindi lo schema di una Feature non può aggiungere configurazione che nessun autore ha chiesto.
- Un collegamento dichiarato su un confine di Release anziché su un singolo componente riempie solo
infra, perché quella superficie non porta alcun bloccovalues:da riempire.
Poiché la materializzazione usa la stessa risoluzione dello schema della validazione, un default dichiarato su una Feature genitore raggiunge i collegamenti di un figlio extends:, e anche i default raggiunti tramite un $ref: tra documenti verso una SchemaLibrary si materializzano. I default dichiarati solo all’interno di un riferimento locale nel documento #/$defs/, o sotto un ramo allOf / oneOf / anyOf, non vengono materializzati.
Una conseguenza merita di essere detta chiaramente, perché la sola validazione non la rivelerà: un campo required: che porta anche un default: è soddisfatto da quel default, quindi ometterlo è lecito — e il valore su cui il controllo ha dato esito positivo è il valore che porta l’output renderizzato.
Il contesto di template del compilatore espone lo stato dell’istanza della Feature alla FeatureRecipe associata tramite il campo .features.<alias> (che contiene .type, .resolved_version, .labels, .values, .infra e .provides per ogni collegamento). I template all’interno della FeatureRecipe leggono i values: propri della Feature tramite .values.<field> nell’ambito di template proprio della FeatureRecipe; i values: del Component ospite non sono direttamente visibili ai template della FeatureRecipe a meno che la Feature non dichiari esplicitamente un socket uses: verso il Component ospite.
Questa separazione degli ambiti rende le Features componibili: una Feature autoscaler non dipende dal Component a cui è collegata; il suo schema: descrive l’intento di autoscaling indipendentemente dall’ospite. I values: del Component ospite riguardano l’ospite; i values: della Feature riguardano la Feature; i due pilastri si compongono senza far trapelare nomi di campo oltre il confine.
Destinazioni dei binding di annotazione
Una Feature non dichiara essa stessa binding di annotazione; li porta la mappa mappings.features.annotations del Manifest. Una Feature partecipa indirettamente alla relazione di binding come destinazione di instradamento: ogni binding nomina un tipo di Feature tramite il suo campo feature:, e le liste maps.infra e maps.values del binding dichiarano percorsi puntati nelle proprietà spec.schema.infra.<path> e spec.schema.values.<path> della Feature nominata.
Al caricamento del catalogo, il compilatore verifica che ogni percorso puntato nelle liste maps di un binding corrisponda a una proprietà che lo spec.schema della Feature di destinazione dichiara effettivamente nel pilastro nominato. Un binding che instrada verso un percorso che lo schema della Feature non dichiara arresta il caricamento del catalogo con un OPS_ERROR chiaro, che nomina il binding, la Feature di destinazione, e il pilastro e il percorso attraverso cui ha instradato — il binding è scritto nel Manifest, che è il documento dell’operatore. Gli autori di schema sanno quindi che qualsiasi proprietà dichiarata sotto spec.schema.values.<path> o spec.schema.infra.<path> è raggiungibile come destinazione di binding; viceversa, qualsiasi proprietà attraverso cui instrada un binding del Manifest deve esistere nello schema della Feature di destinazione.
Quando un’annotazione lato Aggregate o lato Release corrisponde a un binding, il compilatore sintetizza un collegamento di Feature i cui payload dei pilastri instradano il valore dell’annotazione nei percorsi nominati. Il collegamento sintetizzato è strutturalmente indistinguibile da un collegamento di Feature esplicito dichiarato dall’autore nello stesso punto; il rendering a valle, la validazione e il contesto di template della FeatureRecipe consumano entrambe le forme in modo uniforme. Per la forma del binding, la partizione tra lato e pilastro e la disciplina per cui prevale il collegamento esplicito, vedi entities/manifest.md §«Binding di Feature guidati da annotazioni». Per la regola di cascata lato Aggregate e un esempio di authoring, vedi providers/well-known-annotations.md §«Cascata delle annotazioni lato Aggregate».
Il blocco assertions:
Feature.spec.assertions: è una mappa facoltativa di regole con nome che esprimono invarianti architetturali del contratto della Feature — regole tra campi sui values: della Feature e sullo stato risolto del Component collegato. Ogni chiave è un identificatore di regola che compare nel messaggio di errore; ogni valore è il corpo di un template Go. Il compilatore le valuta dopo la validazione dello schema e prima che la FeatureRecipe associata esegua il render, nell’ordine in cui sono scritte, e la prima regola che fallisce arresta il build con il messaggio di errore proprio di quella regola.
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}Come le asserzioni del Component, le asserzioni della Feature esprimono invarianti a livello di contratto — proprietà che il collegamento della Feature deve soddisfare indipendentemente da quale FeatureRecipe implementi il rendering. Per regole tra campi che dipendono dall’implementazione specifica (un requisito di un plugin Wasm, una particolarità di un chart), usa invece il campo assertions: della FeatureRecipe. Per la grammatica di authoring completa, il contesto di template e la ripartizione delle responsabilità tra le asserzioni della Feature e quelle della FeatureRecipe, vedi templates/assertions-block.md.