Assegnare un nome a una risorsa renderizzata
Una Recipe deve abitualmente nominare qualcosa che il proprio output ha prodotto: un hostname da pubblicare tramite provides:, un riferimento all’interno di un valuesMapping:, un identificatore scritto in un corpo artifacts:. Due chiavi del contesto di template portano i nomi disponibili per questo, e rispondono a domande diverse. Leggere quella sbagliata produce un output silenziosamente errato anziché rifiutato — un indirizzo che nomina una risorsa che nulla ha emesso — quindi questa pagina stabilisce quale chiave risponde a quale domanda.
Stabilisce inoltre la distinzione su cui poggiano le due chiavi: un target e un riferimento non sono la stessa cosa, e un target non è mai un nome che una piattaforma di distribuzione risolverà.
Un target nomina un componente; un riferimento nomina una risorsa renderizzata
Un target è un’identità d’autore. È il valore che uno sviluppatore scrive per dire a quale componente punta un arco — target: my_db in un blocco uses — ed è l’identità che la build usa per trovare quel componente, riportarlo nelle diagnostiche e indicizzarne i fatti. Si legge allo stesso modo con ogni provider, perché è un fatto relativo ai tuoi documenti anziché a una qualsiasi piattaforma.
Un riferimento è ciò che fa puntare un artefatto renderizzato a un altro. È scritto nel vocabolario proprio di un provider: un indirizzo interno al cluster sotto helm, un nome di servizio sotto compose, un’interpolazione sotto terraform, un valore importato sotto cloudformation. Un riferimento è diverso sotto ogni provider, perché ogni piattaforma risolve i riferimenti a modo suo.
🔴 Un target non viene mai scritto nell’output renderizzato. Ogni provider ricava i propri nomi, quindi un’identità scritta dall’autore consegnata a una piattaforma come nome è sbagliata ogni volta che le due grafie differiscono — e differiscono esattamente per i caratteri che l’alfabeto proprio di un target non ammette. Un’identità che non contiene alcun carattere di questo tipo sopravvive invariata, ed è ciò che rende facile sbagliare: l’errore funziona finché qualcuno non nomina un componente con un trattino basso o una lettera maiuscola.
Il riferimento di cui un consumatore ha bisogno viene quindi pubblicato dal produttore, perché la Recipe di un produttore è ciò che conosce il vocabolario del proprio provider — un consumatore può associare un provider del tutto diverso, e non può scrivere un riferimento per una piattaforma verso cui non esegue il rendering. Il consumatore legge una normale stringa pubblicata.
La coppia di esempio
La Recipe del produttore pubblica l’indirizzo; il consumatore lo rilegge attraverso l’alias dell’arco.
# The PRODUCER's Recipe — a helm Recipe sourcing a chart the author supplied.# It publishes an in-cluster address built from the name that chart's own# templates render their resources against.spec: capability: helm source: ./charts/postgres provides: host: "{{ .context.rendered_name }}.svc.cluster.local" port: "5432"# The CONSUMER's Aggregate — it names the producer by its TARGET, which is an# authoring identity and stays in the documents. The uses block is keyed by the# socket the catalog entity declares, then by the alias you choose for the edge.spec: components: api: type: core/compute/api-server uses: databases: primary: target: my_db inject: env: - in: DB_HOST from: host - in: DB_PORT from: port# The CONSUMER's Recipe — it reads the published REFERENCE, never the target.# The context keys an edge by its alias, so the socket does not reappear here.spec: capability: helm valuesMapping: | { "db_host": "{{ .context.uses.primary.provides.host }}" }Per un chart fornito dall’autore sotto helm, un componente chiamato my_db esegue il rendering delle proprie risorse con il nome della release my-zudb. Quindi il chart del produttore emette un Service il cui metadata.name è my-zudb, l’host pubblicato è my-zudb.svc.cluster.local, e il consumatore contatta un Service che esiste — sia che legga il valore tramite .context.uses.primary.provides.host sia che lo riceva come DB_HOST iniettato.
Scrivere lì {{ .context.uses.primary.target }} pubblicherebbe invece my_db.svc.cluster.local. Quel valore non ha un aspetto sbagliato: è l’identità che lo sviluppatore ha scritto, con la grafia esatta con cui l’ha scritta. Semplicemente non nomina alcun Service, e nulla nella build lo segnala.
Le due chiavi, come coppia
Nessuna delle due chiavi è leggibile da sola, perché ciascuna è definita da ciò che l’altra non è.
| Chiave | Che cosa nomina |
|---|---|
{{ .context.instance_id }} | L’identità del nodo, e il nome delle risorse costruite per questo nodo per le quali nessun provider ricava un nome — un insieme di artefatti collocato dal tuo blocco artifacts:, e un workload sintetizzato dal tuo blocco workload: da un provider che lo nomina in base all’identità, come fa compose. Sempre presente. |
{{ .context.rendered_name }} | Il nome che il provider assegnato ricava per le risorse che renderizza per questo nodo — per una sorgente fornita da te, il nome rispetto al quale i template che hai fornito renderizzano le proprie risorse, come il nome della release che un chart legge; per un workload: che sintetizza, il nome che dà a quelle risorse quando le nomina in base a un nome proprio anziché all’identità, come fa helm. Presente solo dove quel provider ne ricava uno. Sui template propri di un’associazione di Feature è il nome del componente host — vedi più sotto. |
La divisione deriva da dove il nome deve essere utilizzabile. Un chart o un modulo che hai fornito tu ha dei template, e quei template nominano le proprie risorse in base a qualunque identità la piattaforma consegni loro — quindi il nome deve essere quello che quella piattaforma userà, scritto nell’alfabeto proprio di quella piattaforma. Un workload sintetizzato non ha template tuoi, ma le sue risorse devono comunque portare nomi che la piattaforma accetta: un provider i cui nomi ammettono tutto ciò che un nome scritto dall’autore può contenere le nomina in base all’identità, e uno i cui nomi non lo ammettono le nomina in base al nome che ricava — e poi riporta quel nome qui, così non devi mai prevederlo.
Un nodo che dichiara sia una sorgente fornita sia un workload: emette entrambi i tipi di output contemporaneamente, e non ha bisogno di una terza chiave. Con helm entrambi prendono il nome dall’unico nome della release, quindi rendered_name serve per entrambi: le risorse proprie del chart lo portano comunque i suoi template lo compongano, e ogni Service sintetizzato è <rendered_name>-<service key>. Con un provider che nomina un workload sintetizzato in base all’identità, nomina le risorse di quel workload con instance_id e quelle dell’output fornito con qualunque cosa il provider riporti per esso.
Gli alfabeti sono il motivo per cui i due possono differire. Il nome di un componente scritto dall’autore può contenere un trattino basso o una lettera maiuscola; il nome della release di un chart no, e anziché ricondurre un tale carattere a uno simile — il che permetterebbe a due componenti che sai distinguere di arrivare a un unico nome in un cluster — la derivazione lo scrive per esteso. Vedi ../providers/helm.md «How the release name is derived (Come viene derivato il nome della release)» per l’alfabeto e il limite di lunghezza propri di quel provider.
Quali provider riportano un nome, e perché gli altri no
helm ne riporta uno: il nome della release. Un chart fornito come sorgente lo legge come .Release.Name e abitualmente nomina le proprie risorse in base a esso, e il provider nomina in base a esso anche ogni risorsa che sintetizza per un componente — il controller con il nome della release stesso, e ogni Service come <release name>-<service key>. Quindi un indirizzo pubblicato per l’uno o l’altro tipo di output è costruito da rendered_name. Per un nodo che colloca da solo un insieme di artefatti non ne riporta alcuno: i nomi in quell’insieme sono quelli che il suo autore ha scritto.
# A synthesized helm Recipe publishing the address of the Service its workload# declares under the key `default`.spec: capability: helm workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "valkey/valkey:8" ports: redis: 6379 services: default: type: ClusterIP ports: redis: 6379 provides: host: "{{ .context.rendered_name }}-default" port: "6379"Un componente chiamato cache pubblica cache-default, e uno chiamato my_cache pubblica my-zucache-default — in ciascun caso il nome del Service che la build emette.
Gli altri quattro non ne riportano alcuno, e le ragioni non sono le stesse. Nessuno di loro è un provider in attesa di supporto — in ciascun caso o non c’è alcun nome derivato da riportare, oppure il nome che ti serve è già raggiungibile in un altro modo.
-
cloudformationecompose— i nomi li hai scritti tu, oppure l’identità è il nome. Una Recipe cloudformation scrive gli id logici delle proprie risorse e il provider li legge esattamente come sono scritti; un file compose che hai fornito nomina i propri servizi e il provider unisce ed etichetta quel file senza rinominare nulla al suo interno. Un workload checomposesintetizza prende il nome dall’identità del nodo, che un file compose ammette così come è scritta, quindi{{ .context.instance_id }}è quel nome. Non c’è alcuna derivazione da riportare, e i nomi sono quelli presenti nei tuoi stessi documenti. Quel nome è il servizio principale del workload, quello che un peer raggiunge; un servizio sidecar o di init che esso porta prende il nome dalla stessa identità e dal nome del container, uniti da--, come descrive Come viene denominato un servizio sidecar o di init. -
terraform— il nome è funzione di dove sono stati collocati i file. Il bloccomoduledi un contributore prende il nome dalla directory di output in cui è stata scritta la sua configurazione, che viene stabilita quando i file del confine vengono assemblati anziché quando un nodo viene renderizzato. Nel momento in cui vengono eseguiti i template di una Recipe, quella posizione non esiste ancora. -
helm-chart— il nome che ricava è l’indirizzo proprio del chart collocato, che è una cosa diversa dal nome rispetto al quale i template di quel chart eseguono il rendering. Questo provider imposta il camponamedi un chart che hai incorporato all’identità codificata di ciò che lo ha contribuito, che è anche l’alias con cui l’umbrella vincola quel sub-chart e la chiave sotto cui sono circoscritti i suoi valori. Per un componente, quell’identità è ciò che porta{{ .context.instance_id }}, quindi il nome del chart collocato è già raggiungibile sotto la chiave che dice che cos’è. Il nome rispetto al quale eseguono il rendering i template propri del chart incorporato è il nome della release, che la release dell’umbrella fornisce al momento dell’installazione anziché essere ricavato da questo provider — quindi qui non c’è alcun nome di questo tipo che questa chiave possa riportare. Vedi../providers/helm-chart.md«The chart name the umbrella owns (Il nome del chart che spetta al chart ombrello)».
Leggere la chiave dove non viene riportato alcun nome
Leggere {{ .context.rendered_name }} su un nodo il cui provider non riporta alcun nome di questo tipo arresta la build, e la diagnostica dice quale chiave scrivere invece. Non renderizza un valore vuoto: un indirizzo a cui manca un segmento è un artefatto sbagliato che viene distribuito, il che è peggio di una build che si ferma.
Quale rimedio offre l’arresto dipende dal nodo anziché da dove hai scritto il riferimento:
- Un nodo che non fornisce alcuna sorgente propria, con un provider che non riporta alcun nome per esso, ha le proprie risorse nominate in base alla propria identità, quindi l’arresto nomina
{{ .context.instance_id }}— esiste un valore corretto e l’arresto lo dice. - Un nodo che invece fornisce una sorgente, con un provider che non ricava alcun nome per esso, non ha alcun sostituto. L’arresto lo dice anziché offrirne uno, perché indirizzarti all’identità lì nominerebbe risorse che il tuo nodo non porta.
Il rifiuto copre provides: e ogni altro template che una Recipe scrive inline — il suo valuesMapping:, il suo corpo workload:, ogni voce artifacts:, e i with: e when: di ogni passo della pipeline.
🔴 Entrambe le forme di import ne sono escluse. Una voce valuesMapping:, workload: o artifacts: fornita tramite $import: — che l’import nomini un file locale o una voce di libreria — non porta alcun testo nella tua Recipe finché il rendering non la risolve, quindi un riferimento a questa chiave all’interno di un tale corpo non viene controllato. Renderizza il nome che il provider del nodo importatore riporta dove quel provider ne riporta uno, e un valore vuoto anziché un arresto dove non ne riporta alcuno. Un corpo importato legge quindi la chiave solo quando ogni Recipe che lo importa è legata a un provider che riporta un nome — una voce di libreria scritta per Recipes helm che usano un chart come sorgente, e che lo dichiara nella propria descrizione. Un corpo destinato a importatori il cui provider potrebbe non riportarne alcuno prende invece il nome tramite un valore che imposta la Recipe importatrice.
Le voci locals: di una Recipe non leggono affatto la chiave. Un local condivide il proprio contesto con il template source: della Recipe, e se il nodo fornisce una sorgente è una delle cose da cui dipende il nome, quindi lì il nome non viene offerto. Un riferimento a {{ .context.rendered_name }} in un local quindi si arresta qualunque cosa riporti il provider, con la diagnostica per un riferimento che il contesto di rendering non definisce (E0060), che elenca .context.instance_id come l’unica chiave che .context offre lì. Leggi la chiave nella voce provides: o nel template inline che ne ha bisogno.
Sui template propri di un’associazione di Feature
Sui template che scrive la FeatureRecipe di un’associazione di Feature — i suoi locals:, source:, provides:, injectMapping:, valuesMapping:, workload:, ogni voce artifacts:, e i with: e when: di ogni passo della pipeline — {{ .context.rendered_name }} è il nome del componente host: quello che il provider proprio dell’host riporta per le risorse che renderizza per l’host, che è il valore che legge la Recipe propria dell’host. Fa coppia con {{ .context.instance_id }}, che su quei template è l’identità del componente host; l’associazione stessa è .attachment_name. Un’associazione scritta su una delle connessioni di un componente legge il nome del componente consumatore, perché quel componente è il suo host.
È questa la chiave da cui costruire i nomi delle risorse proprie di un’associazione. Una FeatureRecipe che nomina un Secret, una route o una policy in base al componente a cui è associata ha bisogno di un nome che la piattaforma accetti, e l’identità dell’host così come è scritta non lo è ovunque contenga un trattino basso o una lettera maiuscola. Con helm, un componente chiamato my_db riporta my-zudb, quindi un Secret chiamato {{ .context.rendered_name }}-{{ .attachment_name }} per un’associazione root viene renderizzato come my-zudb-root, dove {{ .context.instance_id }} darebbe my_db-root, che un cluster rifiuta. Il valore resta quello dell’host qualunque sia il provider tramite cui l’associazione esegue il rendering.
È presente ovunque il provider dell’host riporti un nome — con helm, un host la cui Recipe fornisce un chart o dichiara un workload: — e assente dove non ne riporta alcuno: un host che colloca da solo un insieme di artefatti, e un host su qualsiasi altro provider. Leggerla su un’associazione di un tale host arresta la build con la diagnostica per un riferimento che il contesto di rendering non definisce (E0060), che elenca le chiavi che .context definisce lì. {{ .context.instance_id }} è tra queste, ed è ciò da cui prendono il nome le risorse proprie dell’host su un tale host, quindi una FeatureRecipe scritta per host che potrebbero non riportare alcun nome legge invece l’identità.
Il rifiuto copre i template che una FeatureRecipe scrive inline, eccetto il suo injectMapping:. Un injectMapping:, e una voce valuesMapping:, workload: o artifacts: che la FeatureRecipe fornisce tramite $import:, non vengono controllati: su un host che non riporta alcun nome un riferimento lì renderizza un valore vuoto anziché arrestarsi.
Dove un’associazione consegna un chart fornito dal suo autore, i template di quel chart eseguono il rendering rispetto al nome della release del componente host, deliberatamente: ricavarlo invece dall’associazione rinominerebbe risorse che l’autore del chart ha dichiarato e che potrebbe aver già distribuito. .attachment_name è il valore che distingue due associazioni su un unico host — vedi ../providers/helm.md «How the release name is derived (Come viene derivato il nome della release)».
Nomi ricavati dall’associazione di una connessione
Un’associazione che una connessione porta è un’associazione del componente consumatore, con nome <alias>.<slot> — gpt.credential per lo slot credential della connessione scritta sotto l’alias gpt (vedi la voce di connessione dell’Aggregate). Quel nome composto è il .attachment_name rispetto al quale esegue il rendering la sua FeatureRecipe, e contiene il punto.
Ne derivano due tipi di nome, che trattano il punto in modo diverso.
Un nome che la FeatureRecipe compone mantiene qualunque cosa scriva il suo template. Le realizzazioni di credenziali della libreria standard nominano la propria risorsa {{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, quindi la credenziale sulla connessione gpt di un componente chiamato router viene renderizzata come una risorsa chiamata router-gpt.credential, punto incluso, che è un nome di oggetto Kubernetes valido. Il punto sopravvive in un nome di questo tipo esattamente quando il template lo mantiene.
Un nome che la build ricava dall’identità dell’associazione scrive il punto per esteso. Le etichette dell’identità e il file emesso sono composti a partire dal componente host e dal nome dell’associazione tramite la stessa codifica che attraversa ogni nome ricavato da un’identità, e questa scrive il punto come zd e una lettera maiuscola come escape del suo code point, perché l’identità viene spesa come nome di risorsa oltre che come etichetta, e un nome di Service non ammette né l’uno né l’altra: una connessione scritta sotto l’alias gptPro arriverebbe a cfr--router--gpt-zx000050ro-zdcredential. La risorsa di cui sopra ha l’etichetta aggrega.ai/component-id: cfr--router--gpt-zdcredential (e allo stesso modo app.kubernetes.io/name), e con il provider helm viene emessa come router--gpt-zdcredential--router-secret-router-gpt-credential.yaml. Vedi Convenzioni di denominazione «The separator does not reach a name (Il separatore non raggiunge un nome)» per il motivo per cui il punto viene scritto per esteso anziché sostituito.
Argomenti correlati
- Contratto del contesto dei template — la forma completa del contesto in cui si trovano queste chiavi.
- Matrice di espansione dei template — quali pilastri legge ciascun punto di template.
- Triade della topologia:
provides,inject,uses— come un valore pubblicato attraversa un arco fino a un consumatore. - Convenzioni di denominazione — che cosa puoi scrivere come nome di un componente, e quanto costa un nome con un alfabeto più ristretto.
errors/fatal-halts.md— l’arresto che questa pagina descrive, con il messaggio che emette.