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

Convenzioni di denominazione

Questo capitolo tratta le regole di denominazione e di uso delle maiuscole che si applicano ai contenuti Aggrega scritti dagli autori: il modello per i nomi di istanza scritti dall’utente, la disciplina delle maiuscole per i nomi dei campi nel DSL, le maiuscole che la piattaforma usa per gli identificatori che definisce essa anziché tu, e la sintassi dei commenti usata nella superficie di scrittura YAML.

Nomi di istanza

I nomi di istanza scritti dall’utente — le chiavi che lo sviluppatore scrive per componenti, feature, aggregati, sottosistemi, confini, e socket e alias uses — seguono tutti un unico pattern: ^[a-zA-Z0-9_-]+$. Sono validi sia il kebab-case (pii-filter, my-agent) sia lo snake_case (openai_key, db_credentials); i team possono adottare la convenzione che preferiscono.

Caratteri consentiti: alfanumerici (a-z, A-Z, 0-9), trattini (-) e trattini bassi (_). Nessun altro carattere è ammesso.

Esempi:

components:
web-server: # kebab-case
finance_worker: # snake_case
features:
pii-filter: # kebab-case
audit_logger: # snake_case
openai_key: # snake_case — natural for a credential attachment
db-password: # kebab-case — also valid
PatternAmbitoEsempi
^[a-zA-Z0-9_-]+$Tutti i nomi di istanza scritti dall’utenteweb-server, openai_key, pii-filter

Il pattern viene applicato in fase di risoluzione tramite patternProperties di JSON Schema.

Quanto costa il nome di un componente, e perché le maiuscole costano di più con alcuni target

Il pattern qui sopra dice che cosa puoi scrivere. Quanto un nome costa è una questione distinta, e cambia in base al target su cui un componente viene distribuito: conviene quindi saperlo prima di scegliere un nome, anziché nel momento in cui una build ne rifiuta uno.

Il nome di un componente diventa l’identità con cui viene marcata ogni risorsa che emette, e ogni target ricava i propri nomi da quell’identità: un installer di chart ne ricava un nome di release, un orchestratore di container ne ricava nomi di servizio. Un target il cui alfabeto è più ristretto del pattern non può contenere un carattere che non ammette, e Aggrega non ricondurrà silenziosamente un tale carattere a uno simile: due nomi che un autore sa distinguere non devono diventare un unico nome in un cluster. Per questo un carattere che il target non ammette viene invece scritto come sequenza di escape, e una sequenza di escape è più lunga del carattere che sostituisce.

La conseguenza pratica: una lettera maiuscola è gratuita con alcuni target e costosa con altri.

  • Con un target i cui nomi ammettono le maiuscole — un file compose di orchestrazione di container, per esempio — PaymentsAPI viene riportato esattamente come l’hai scritto e costa undici caratteri.
  • Con un target i cui nomi sono solo minuscoli — il nome di release di un installer di chart — ogni maiuscola viene sottoposta a escape, e un nome di sole sei maiuscole supera già ciò che quel target accetta.

C’è un secondo effetto, ed è il più incisivo: una sequenza di escape inizia con un trattino. Un target che richiede che un nome inizi con una lettera minuscola o una cifra rifiuterà quindi un nome il cui primo carattere è uno che non ammette, per quanto breve sia il resto: nessun accorciamento vi pone rimedio.

Le indicazioni derivano dai due effetti. Preferisci lettere minuscole e cifre, con trattini tra le parole, e inizia un nome con una lettera minuscola. payments-api viene riportato invariato da ogni target per cui Aggrega fornisce un provider. payments_api viene riportato da un file compose ma non dal target helm, i cui nomi di risorsa non ammettono il trattino basso: i Service, i workload e la release a cui assegna il nome del componente si scrivono payments-zuapi. PaymentsAPI lì costa ancora di più. Una Recipe che pubblica l’indirizzo di una tale risorsa legge la grafia propria del target anziché prevederla: vedi templates/rendered-resource-names.md.

Una cifra iniziale è lecita da scrivere e non costa nulla con un file compose, ma il target helm la rifiuta. Il nome di un Service Kubernetes deve iniziare con una lettera, e i Service emessi da un chart o da un workload sintetizzato prendono il nome dal componente, quindi un componente chiamato 1cache arresta una build helm — il rifiuto nomina il componente e dice che il nome di un Service deve iniziare con una lettera — anziché produrre Service che il cluster rifiuterebbe.

Nulla di tutto questo è una regola che il compilatore applichi di sua iniziativa: non conosce le regole di denominazione di alcun target e non inventa alcun limite. Il provider di ciascun target risponde dei propri nomi, quindi un nome viene rifiutato solo quando il target su cui un componente viene effettivamente distribuito dichiara di non poterlo usare, e il rifiuto riporta la motivazione propria di quel target e indica la chiave spec.components che hai scritto. Un nome accettato con un target e rifiutato con un altro è il comportamento previsto, non un’incoerenza.

I nomi che Aggrega compone da sé — l’identità di una feature collegata a un confine, per esempio — sono trattati al contrario: vengono accorciati per adattarsi al target anziché rifiutati, perché sono assemblati da parti scritte in più punti e nessun singolo autore può vedere la lunghezza che raggiungono. Viene rifiutato solo un nome che hai scritto tu.

Il punto come separatore di percorso riservato

Il carattere punto (.) è escluso da tutti i nomi di istanza scritti dall’utente. Il punto ha lo scopo strutturale di separatore di percorso generato dal compilatore per i riferimenti a componenti tra aggregati.

Quando un Aggregate radice importa un sotto-aggregato chiamato data-layer che contiene un componente chiamato main-db, il compilatore costruisce l’ID assoluto appiattito data-layer.main-db unendo con un punto il nome di istanza dell’aggregato e il nome di istanza del componente. Questo percorso puntato compare in:

  • Target uses dello sviluppatore: target: data-layer.public_db — riferimento a un componente esportato da un aggregato annidato.
  • La diagnostica della build stessa: un arresto o un avviso relativo a quel componente lo nomina con il suo percorso puntato, quindi il nome che leggi è quello che puoi cercare nei tuoi documenti.

Il separatore non raggiunge un nome

Un percorso puntato è un indirizzo all’interno dei tuoi documenti, e non è un nome che un target di distribuzione accetterà. Il nome di un Service Kubernetes non ammette alcun punto; peggio, un punto all’interno di un indirizzo di cluster è ciò che separa un servizio dal namespace in cui risiede, quindi un nome puntato passato a un consumer come host verrebbe risolto in un servizio diverso anziché fallire.

Per questo il separatore viene riscritto in ogni nome ed etichetta che la build ricava dall’identità di un componente, e viene riscritto anziché sostituito: data-layer.main-db diventa data-layer-zdmain-db. Sostituirlo con un carattere che un target accetta permetterebbe a due componenti diversi di arrivare a un unico nome — data-layer.main-db e un componente che qualcuno ha scritto come data-layer-main-db — e un nome a cui arrivano due componenti non ne identifica nessuno.

Che cosa raggiunge, e che cosa no:

  • Raggiunge i nomi e le etichette ricavati dall’identità — metadata.name su una risorsa che Aggrega sintetizza, le etichette aggrega.ai/component-id e app.kubernetes.io/name, i selettori che vi corrispondono, i nomi dei file emessi, {{ .context.instance_id }} e il nome che un provider ricava per sé, come il nome di una release helm. Si muovono insieme, quindi un indirizzo che una Recipe compone dalla chiave che nomina una risorsa — .context.instance_id dove il target la nomina in base all’identità, .context.rendered_name dove il target riporta un nome proprio — nomina ancora la risorsa che la build emette.
  • Non raggiunge un nome che hai scritto tu. Un nome di componente che non contiene alcun separatore torna identico byte per byte, quindi solo un componente apportato da un Aggregate importato ha nell’output una grafia diversa da quella nel documento.
  • Non raggiunge i nomi all’interno di un chart o di un frammento forniti da un autore. Appartengono a chi li ha scritti, e un nome riportato da un chart di terze parti — un nome di custom resource della forma <plural>.<group>, in cui il punto è lecito — viene emesso esattamente come quel chart l’ha scritto.

🔴 Quest’ultimo punto ha una conseguenza su ciò che una Recipe dovrebbe pubblicare, ed è la cosa più facile da sbagliare in questa pagina. I template di un chart fornito nominano le proprie risorse in base all’identità che la piattaforma consegna loro — un nome di release, scritto nell’alfabeto proprio di quella piattaforma anziché in quello descritto sopra — e il target helm nomina i workload che sintetizza in base a quello stesso nome di release. Quindi, per l’output prodotto da sorgenti che hai fornito tu, e per un workload sintetizzato con un target di questo tipo, {{ .context.instance_id }} non è il nome che quelle risorse portano, e un indirizzo pubblicato a partire da esso non nomina nulla ogni volta che i due alfabeti differiscono. La chiave che riporta il nome della piattaforma, e quali provider ne riportano uno, sono descritti in templates/rendered-resource-names.md.

Riscrivere il separatore costa caratteri, e un nome di lunghezza limitata può esaurirli. Il separatore viene sostituito da una breve sequenza di escape anziché da un singolo carattere, quindi un’identità qualificata, una volta scritta, è un po’ più lunga di come appare nei tuoi documenti. Questo conta solo dove il nome che ne risulta ha una lunghezza limitata: il target che produce un componente indica quanto può essere lungo il valore di etichetta che accetterà, e dove l’identità scritta lo supererebbe, la build si arresta anziché emettere un valore che il target rifiuterebbe. L’arresto indica la lunghezza in cui deve rientrare l’identità stessa — la lunghezza prima della riscrittura, così che un nome scelto entro quel limite funzioni al primo colpo — e la soluzione è accorciare le parti scritte dall’autore: il nome che il documento importatore dà al sotto-aggregato, o il nome del componente al suo interno.

Il separatore è il motivo abituale per cui un nome viene scritto più lungo di come appare, ma non è l’unico. Anche due forme che un nome scritto dall’autore può legittimamente assumere non possono essere riportate così come sono, perché lasciarle renderebbe ambigua una sequenza di escape: un nome che termina con un trattino, e un nome in cui un trattino è immediatamente seguito da z. Ciascuna viene riscritta nello stesso modo, allo stesso costo. Ogni altro nome scritto dall’autore torna identico byte per byte, quindi un nome composto da lettere, cifre, trattini bassi e trattini tra le parole non è interessato da nulla di tutto questo.

Un nome di socket nel blocco uses proprio di un componente corrisponde a una chiave nello usesSchema dell’entità di catalogo — un socket dichiarato — oppure nomina un socket ad hoc dello sviluppatore, che compila anche su un’entità che non dichiara alcuno usesSchema; un nome che dista una sola modifica da un socket dichiarato genera un avviso che nomina entrambe le grafie. Gli uses per arco di una Release, e quelli dell’allegato di una Feature, possono nominare solo un socket che l’entità dichiara, e qualsiasi altro nome fallisce con un errore di validazione unknown-uses-socket.

Grafia dei nomi dei campi

Il DSL separa lo YAML rivolto agli sviluppatori (scritto da persone) dai contratti interni del compilatore (consumati da template e strumenti):

  • YAML rivolto agli sviluppatori (camelCase): i nomi di campo composti da più parole negli schemi di Aggregate, Release, Component, Feature, Recipe, FeatureRecipe, Manifest e Plugin usano il camelCase. Esempi: exportedComponents, syncWave, subDirectory, featuresSchema, usesSchema, valuesMapping, injectMapping, executionScope, appliesTo, appliesToAnyOf, conflictsWith. Segue le convenzioni delle API di Kubernetes.
  • Contratti interni (snake_case): i nomi di campo composti da più parole nello schema dell’IR Graph e nello schema del Template Context usano lo snake_case. Esempi rivolti all’utente che gli autori di Recipe incontrano: instance_id (in .context.instance_id — l’identità della Recipe), inject_raw (in .inject_raw, un pilastro di primo livello accanto a .inject anziché una chiave sotto .context — il contratto di iniezione non modificato), attachment_name (nel contesto di una FeatureRecipe di allegato — identifica lo slot che l’allegato riempie, o il nome con cui è stato allegato). Segue le convenzioni di JSON API e si allinea alla generazione dei tag struct JSON di Go.
  • Campi di una sola parola: minuscoli indipendentemente dal contesto. Esempi: values, infra, inject, provides, locals, features, labels, annotations, boundaries, components, subsystems, pipeline, source.

Gli sviluppatori non incontrano lo snake_case nel proprio YAML, e gli autori di template non incontrano il camelCase nei propri template Go. Le aggiunte allo schema seguono queste convenzioni.

Tre grafie che si incrociano in un’unica istruzione

La scrittura delle Recipe incrocia abitualmente tutte e tre le convenzioni di grafia in un’unica istruzione: il campo DSL definito dallo schema usa il camelCase, il nome di istanza scritto dall’utente usa il kebab-case o lo snake_case, e il riferimento al contesto del template usa lo snake_case. Gli autori che riconoscono questi incroci come convenzioni separate leggono lo YAML risultante senza difficoltà; quelli che cercano di ricondurre le grafie a un’unica convenzione faticano con i confini.

L’esempio canonico: il template valuesMapping: di una Recipe che fa riferimento all’istanza di Component prodotta tramite il contesto del template.

# Recipe authored against a Component the developer instantiated as "web-server"
# (kebab-case instance name) in their Aggregate.
spec:
valuesMapping: | # camelCase — schema-defined DSL field
name: "{{ .context.instance_id }}" # snake_case — template context
# internal contract
image: "{{ .values.image }}" # snake_case — template context
# internal contract

Tre grafie, un’istruzione:

  • valuesMapping — camelCase. Il nome del campo DSL che lo schema definisce per il template di mapping della Recipe. Camel perché lo YAML del linguaggio rivolto agli sviluppatori segue le convenzioni delle API di Kubernetes.
  • web-server (a cui si fa riferimento indirettamente tramite il componente prodotto) — kebab-case. Il nome di istanza scritto dall’utente nell’Aggregate; lo sviluppatore ha scelto la forma con il trattino. Potrebbe essere ugualmente web_server (snake_case); entrambi sono validi secondo il pattern dei nomi di istanza.
  • instance_id, image — snake_case. Nomi di campo all’interno del contesto del template (.context.instance_id, .values.image). Snake perché l’IR Graph e il contesto del template seguono le convenzioni JSON-API e si allineano alla generazione dei tag struct JSON di Go.

Le tre grafie non sono intercambiabili. Un autore di Recipe che scrive {{ .context.instanceId }} (camelCase) arresta la build: .context dichiara le proprie chiavi, e instanceId non è tra queste, quindi il riferimento viene rifiutato prima che venga prodotto qualsiasi cosa e la diagnostica elenca le chiavi che .context definisce — vedi errors/fatal-halts.md «Template references a root the render context does not define (Il template fa riferimento a una radice che il contesto di rendering non definisce)». Uno sviluppatore che scrive web.server (con un punto) incorre nel rifiuto del pattern dei nomi di istanza, perché il punto è riservato come separatore di percorso. L’obiettivo della disciplina: tieni a mente le tre convenzioni quando leggi o scrivi; affidati ai confini (dove ti trovi nello YAML o nel template) per sapere quale grafia si applica.

Identificatori definiti dalla piattaforma

Tutto ciò che precede regola i nomi sulla superficie di authoring — un nome di istanza che scegli, un campo di schema che il linguaggio definisce perché tu lo compili, una chiave del contesto del template che leggi. Altri due registri regolano gli identificatori che la piattaforma stessa definisce e che tu ti limiti a rileggere o a digitare. Sono separati perché svolgono compiti diversi, ed è il compito a deciderne la forma.

Il registro descrittivo: kebab-case, in modo uniforme. Un identificatore di questo registro dice a parole che cosa nomina, così puoi leggerlo e agire di conseguenza senza cercare nulla. Un flag della CLI, l’id di una regola di lint di pubblicazione, il codice di una classe di diagnostica e il codice con cui è registrata una condizione di arresto vi appartengono tutti.

--no-unsupported-field-warnings # a CLI flag you type
category-matches-directory # a lint rule id, printed in `aggrega lint` output
unsupported-field # a diagnostic class code
artifact-provenance-skipped # another
parameter-contract-violation # the code a halting condition is registered under

Dove una classe di diagnostica ha un flag di soppressione, il codice e il flag sono le stesse parole nello stesso ordine — unsupported-field viene silenziato da --no-unsupported-field-warnings — quindi la classe su cui hai trovato corrispondenza ti indica il flag da usare, senza nulla da tradurre. Un codice di classe è il nome stabile su cui gli strumenti fanno corrispondenza per riconoscere un rilevamento senza analizzare il testo del suo messaggio; la formulazione del messaggio può migliorare, il codice non cambia.

Il registro dei codici brevi: la lettera E e quattro cifre. Una condizione di arresto porta anche un codice breve — E0007 — ed è l’unico identificatore definito dalla piattaforma che non è in kebab-case. Il motivo è la posizione: apre ogni diagnostica di arresto, accanto alla categoria, prima del file e della riga che stai per leggere.

[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge

Un codice descrittivo non può stare lì. Il più lungo di essi riempirebbe da solo un terminale stretto, prima della posizione che ti dice dove guardare. Così l’intestazione prende un identificatore scelto per la sua larghezza, e il compromesso è deliberato: quattro cifre non dicono nulla di una condizione, ed è per questo che ogni codice breve è pubblicato accanto alla condizione che nomina e al testo con cui quella condizione viene resa nel riferimento degli error sentinel. Cita un codice breve in un report, digitalo in una ricerca e risolvilo lì.

Entrambi i registri nominano le stesse condizioni da due direzioni, e nessuno dei due sostituisce l’altro. Usa il codice descrittivo quando scrivi uno strumento che si basa su una condizione; cita il codice breve quando parli di una condizione con una persona.

Il kebab-case che compare qui e nei nomi di istanza non è una collisione. Il pattern dei nomi di istanza riguarda ciò che puoi scrivere — lì sono validi sia il kebab-case sia lo snake_case, e i team ne scelgono uno. Questo registro riguarda ciò che la piattaforma scrive, dove non c’è nulla da scegliere: non scegli mai la grafia dell’id di una regola di lint, e la piattaforma non sceglie mai la grafia del nome del tuo componente.

Lascia invariate le grafie dei campi. I campi di schema scritti dall’autore restano in camelCase e le chiavi del contesto del template restano in snake_case. Nessuno degli identificatori di questo registro è un campo su una delle due superfici — sono nomi brevi e stabili per un flag, una regola o una classe di rilevamenti — quindi il fatto che un codice di diagnostica sia in kebab-case non dice nulla su come si scrive un campo di schema.

Disciplina dei suffissi nei nomi dei percorsi di documento

Un sottoinsieme di campi del linguaggio contiene valori di percorso di documento: stringhe che puntano a una posizione all’interno di un altro documento (la sezione volumes di un Workload prodotto, la voce featuresSchema di un Component, il livello mappings di un Manifest). I valori seguono la sintassi RFC 6901 JSON Pointer: token separati da barre che identificano il percorso attraverso il documento di destinazione.

RFC 6901 è la grammatica di percorso di riferimento per ogni superficie di percorso di documento in Aggrega. Il contratto dei plugin Wasm consuma documenti JSON Patch RFC 6902 i cui percorsi sono puntatori RFC 6901 (secondo plugins/plugin-contract.md, output JSONPatch del ruolo label-transform); l’inventario delle stringhe di formato della grammatica URI cita RFC 6901 accanto alla sintassi dei template Go e agli helper Sprig (secondo vocabulary/uri-grammar.md, «Format-string inventory»); gli export .locals di ciascuna Recipe usano RFC 6901 per puntare alle posizioni del Workload sintetizzato che i plugin Wasm Injector ricevono nella pipeline dei plugin attraverso il payload with del proprio step. Una grammatica, più superfici che la consumano.

La disciplina dei suffissi nei nomi distingue i due lati di authoring di questi valori di percorso tramite una deliberata suddivisione dei suffissi, allineata alla più ampia sezione sulla grafia dei nomi dei campi qui sopra:

  • I campi di schema che contengono JSON Pointer RFC 6901 usano il suffisso camelCase *Path. I campi fanno parte dello schema YAML rivolto agli sviluppatori, quindi seguono la convenzione camelCase. Nessuno schema di entità dichiara un campo del genere; i percorsi di documento che un autore scrive sono le chiavi di export .locals qui sotto.
  • Le chiavi di export .locals che contengono JSON Pointer RFC 6901 usano il suffisso snake_case *_path. Le chiavi fanno parte della superficie di export interna della Recipe — lette dai template successivi della Recipe stessa e da una pipeline di plugin Wasm attraverso il payload pipeline[].with che fa riferimento a .locals — quindi seguono la convenzione snake_case. Esempi:
    • volumes_path — .locals.volumes_path: "/spec/template/spec/volumes" espone la posizione dell’array volumes del Workload sintetizzato.
    • containers_path — .locals.containers_path: "/spec/template/spec/containers" espone la posizione dell’array containers.
    • resource_path — .locals.resource_path: "/resource/aws_s3_bucket/main" espone un percorso di risorsa nativo di Terraform.
    • root_path — .locals.root_path: "/data" espone il percorso radice consumato dalla pipe del renderer.

Le due convenzioni di suffisso riflettono la convenzione a due livelli della sezione sulla grafia dei nomi dei campi: i campi definiti dallo schema usano il camelCase; gli identificatori scritti dall’utente o privati della Recipe usano lo snake_case (o il kebab-case). La disciplina dei suffissi *Path / *_path rende visibile a livello di identificatore la natura di grammatica di percorso del valore: chi legge uno dei due suffissi sa che il valore segue la sintassi RFC 6901 senza dover ispezionare il valore stesso.

Esempio svolto: un Wasm Injector che consuma gli export *_path di una Recipe.

# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumes
spec:
locals:
primary_compute: "worker-container"
containers_path: "/spec/template/spec/containers"
volumes_path: "/spec/template/spec/volumes"
# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe
# above realizes. Its templates read `.locals`: an attachment sees the host
# Recipe's resolved locals merged with the attachment's own block.
spec:
pipeline:
- id: workload_injector
plugin: pipeline-step/k8s-workload-injector:2.0.0
function: inject_secret
with: |
target_container: "{{ .locals.primary_compute }}"
containers_path: "{{ .locals.containers_path }}"
volumes_path: "{{ .locals.volumes_path }}"

Le chiavi *_path sono export privati della Recipe; i valori containers_path / volumes_path sono stringhe JSON Pointer RFC 6901. Il plugin Injector consuma le stringhe per posizionare il proprio output JSONPatch rispetto all’AST del Workload prodotto. L’attachment le raggiunge sul proprio pilastro .locals — non esiste un campo .context.uses[].locals, quindi un consumer non può leggere i locals del proprio target attraverso un arco uses; ciò che attraversa un arco è il provides del target.

Per il più ampio inventario delle stringhe di formato (sintassi dei template Go, funzioni Sprig, JSON Pointer accanto alle regex SemVer e alla grammatica dei selettori di etichette), vedi vocabulary/uri-grammar.md, «Format-string inventory». Per la superficie del contratto dei plugin Wasm che consuma patch RFC 6902 indirizzate da puntatori RFC 6901, vedi plugins/plugin-contract.md.

Sintassi dei commenti

I caratteri di commento dipendono dal linguaggio circostante:

  • Contesto YAML (la superficie di authoring predefinita per ogni entità Aggrega): usa #
  • Contesto dei template Go (all’interno degli scalari a blocco valuesMapping: di una Recipe, degli scalari a blocco injectMapping: di una FeatureRecipe, delle voci di mapping di una MappingLibrary, dei corpi assertions: dei blocchi di asserzioni): usa {{/* ... */}} per i commenti di template che il motore di template riconosce e rimuove al momento del rendering, oppure # per i commenti a livello YAML al di fuori del corpo del template.

Gli schemi in forma compatta sotto schema:, usesSchema:, featuresSchema: e parameters: sono interamente YAML; l’annotazione description: per campo è la superficie documentata per la documentazione inline dei campi (port: { type: integer, description: "TCP listen port" }).