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

Provider Helm

Il provider helm produce YAML Kubernetes renderizzato piatto per i consumatori GitOps (ArgoCD, Flux). Il provider assembla per (path, provider): lo YAML renderizzato di ogni nodo destinato a helm viene instradato all’assemblatore indicizzato sulla directory: valutata del confine unita alla subDirectory: di ciascun componente, e quell’assemblatore emette un file YAML per ogni risorsa Kubernetes. Gli strumenti a valle confrontano e applicano direttamente i file, senza un passaggio di installazione Helm.

Dove il syncWave: <integer> del confine non è 0, ogni risorsa Kubernetes emessa lo porta come annotazione argocd.argoproj.io/sync-wave: "<N>"; gli hook Helm portano inoltre helm.sh/hook-weight: "<N>". ArgoCD legge l’annotazione sync-wave, e Helm legge il peso di un hook, ciascuno ordinando le risorse in base a esso; un confine all’ondata predefinita 0 non porta né l’una né l’altro, cosa che entrambi gli strumenti leggono come ondata 0.

Questa pagina è il riferimento di authoring del provider helm. Per il modello di composizione degli input comune a tutti i provider, vedi architecture/16-recipe-input-composition.md. Per la prontezza di ciascun provider, vedi Stato del linguaggio → Providers.

Tipi di input supportati

Il provider helm accetta tutti e tre i tipi di input della Recipe, in ruoli diversi:

  • Modalità con sorgente. Una Recipe con source: <chart-path> punta a una directory di chart Helm su disco. L’SDK Go di Helm carica il chart, il dizionario dei valori del rendering di base viene unito ai valori predefiniti del chart, e i template del chart vengono renderizzati in YAML Kubernetes piatto.
  • Modalità Workload (sintetizzata). Una Recipe con workload: (inline o caricato con $import:) dichiara un documento Workload. Il provider sintetizza una o più risorse Kubernetes per nodo — un oggetto controller scelto dal form del Workload più Services per ogni servizio e PVC per ogni volume persistente — direttamente dalla specifica del Workload; vedi Modalità Workload (sintetizzata).
  • Modalità solo artefatti. Una Recipe con artifacts: e senza né source: né workload: emette i manifest scritti dal suo autore, con le etichette e le annotazioni di provenienza della build innestate nei metadati propri di ciascuna risorsa.

I tre si combinano: una Recipe può dichiarare insieme un chart, un Workload e artifacts:, e ciascuno esegue il rendering ed emette per conto proprio, fianco a fianco nell’output del nodo — vedi Che cosa accetta ciascun provider, per intero.

Insieme di chiavi di source:

Il source: del provider helm nomina un chart, e accetta entrambe le forme che il campo source: assume: una stringa semplice di percorso del filesystem e un oggetto strutturato il cui url: porta la posizione. Ovunque quella posizione sia un percorso del filesystem, è ancorata alla directory che contiene il recipe.yaml che la dichiara, non alla directory da cui viene invocata la build, e deve restare all’interno di quella directory: un percorso che ne esce, o uno assoluto, viene rifiutato, perché ogni file che una pubblicazione della Recipe porta con sé è preso dalla sua directory — vedi entities/recipe.md «Content paths stay inside the Recipe’s own directory (I percorsi dei contenuti restano nella directory della Recipe stessa)». Un chart nominato in questo modo viene pubblicato con la Recipe, con ogni file al suo interno che le regole di esclusione registrate quando la Recipe è stata fissata mantengono — il provider helm lascia fuori le directory di controllo di versione e i file nascosti sotto templates/ del chart, rispetta il .helmignore proprio del chart, e il .aggregaignore dell’autore ha l’ultima parola, come descrive Quali file vengono distribuiti con un’entità — mentre un file accanto alla Recipe che nulla di ciò che essa dichiara nomina non lo è. Il rendering legge gli stessi file che la pubblicazione porta con sé, quindi un chart viene renderizzato allo stesso modo dalla tua directory e da un registry. La forma in cui l’hai scritto non cambia questo: un source: strutturato il cui url: è ./charts/api-server viene ancorato esattamente come la stringa semplice ./charts/api-server.

spec:
capability: helm
source: ./charts/api-server # filesystem path to a chart directory
valuesMapping: |
image: "{{ .values.image }}"
replicas: {{ optional .infra `replicas` 2 }}

Un source: strutturato dice la stessa cosa con campi nominati, e ciò che il suo url: porta decide se viene recuperato qualcosa. Dove url: porta uno schema di trasporto — oci://… per un chart OCI, un https://….tgz per un archivio di chart diretto, oppure una radice di repository https:// abbinata a chart: — il chart viene recuperato: il tipo deriva dallo schema dell’URL o da un kind: esplicito, aggrega pull recupera e fissa il chart nel lockfile, e la build lo estrae dalla cache. Dove url: nomina un percorso del filesystem, non viene recuperato né fissato nulla — il chart viene letto dal disco, ancorato esattamente come la forma a stringa semplice descritta sopra.

spec:
capability: helm
source:
kind: helm-oci-chart
url: ./charts/api-server # a path, so nothing is fetched and nothing is pinned
version: "1.0.0"

Solo url: decide da dove viene letto un chart. Gli altri campi selezionano ciò che verrebbe recuperato, quindi per un percorso non selezionano nulla — raggiungono comunque i template propri della Recipe come .source.*.

Copiare un chart in locale (vendoring) è supportato come alternativa al recupero, e non è obbligatorio. Lo schema accetta un oggetto strutturato aperto.

Il chart nel percorso di origine deve contenere un Chart.yaml valido. I rendering con sorgente che non riescono a caricare il chart riportano alla lettera l’errore sottostante dell’SDK di Helm. Un source: "" vuoto non è una questione di helm: non nomina né la modalità senza sorgente né quella con sorgente, quindi il rifiuto che ottiene è lo stesso qualunque sia il provider a cui punta la Recipe, e arriva durante la lettura della Recipe, prima che venga caricato qualsiasi chart e prima dello smistamento a questo provider. Quali comandi lo riportano è spiegato in entities/recipe.md «Source field scheme inventory (Inventario degli schemi del campo source)» e in errors/fatal-halts.md «Recipe source: is an empty string (Il campo source della Recipe è una stringa vuota)».

Modalità con sorgente

Una Recipe con source: <chart-path> e valuesMapping: esegue la seguente pipeline nel rendering di base:

  1. Il chart in <chart-path> viene caricato tramite l’SDK Go di Helm.
  2. Il template valuesMapping viene valutato rispetto al contesto di template della Recipe. Il suo output YAML viene trattato come un overlay di valori per il chart.
  3. L’overlay viene unito ai valori predefiniti del values.yaml del chart, una sola volta; in caso di collisione prevalgono le chiavi dell’overlay (la semantica standard di Helm di helm install --values). Una chiave che l’overlay imposta a null rimuove il valore predefinito del chart per quella chiave — al livello superiore, all’interno di una tabella o nei valori di una dipendenza — come fa helm install --values, così i template del chart leggono la chiave come assente; un null su una chiave a cui il chart non dà alcun valore predefinito raggiunge i template come null.
  4. L’SDK di Helm renderizza i template del chart rispetto ai valori uniti.
  5. Aggrega inietta i propri metadati di provenienza nei manifest renderizzati tramite una riscrittura YAML post-rendering, garantendo che l’output con sorgente porti le stesse etichette dell’output della modalità Workload. I valori di identità diventano etichette (app.kubernetes.io/name, aggrega.ai/component-id, aggrega.ai/provider, aggrega.ai/provider-version, aggrega.ai/environment e — quando impostati — aggrega.ai/aggregate-name, aggrega.ai/compiler-version), ciascuna scritta in una forma che Kubernetes accetta come valore di etichetta; i valori che un’etichetta Kubernetes non può rappresentare diventano annotazioni (aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave dove l’ondata non è 0, e il valore letterale di ogni etichetta il cui valore ha dovuto essere riscritto — un Aggregate di nome imported/flow riceve l’etichetta imported-flow e l’annotazione imported/flow sotto la stessa chiave). La regola di riscrittura è enunciata in well-known-annotations.md «Etichette di provenienza emesse dai provider».
  6. I file di output finiscono in modo piatto nella directory di output della Recipe, uno per ogni risorsa renderizzata, con il nome <name-basis>-<kind>[-<namespace>]-<name>.yaml — la stessa base da cui viene derivato il nome della release descritto più sotto, seguita dal tipo proprio della risorsa, dal namespace dove ne ha uno e dal nome, ciascuno in minuscolo e con ogni sequenza di altri caratteri ridotta a un singolo trattino. Per un componente ordinario quella base è l’identità propria del componente, che è anche ciò che porta l’etichetta aggrega.ai/component-id della risorsa; per un chart fornito dall’autore di un’associazione di Feature resta quella del componente ospitante, mentre l’etichetta porta l’identità propria dell’associazione. Un documento che non porta un tipo o un nome prende invece il nome dal percorso del suo template. La struttura di directory del chart viene appiattita: non esiste una sottodirectory templates/ nell’output renderizzato, e due template in sottodirectory diverse che condividono un nome di file restano due file, perché il nome deriva dalla risorsa anziché dal template. Un file che il blocco artifacts: della Recipe nomina non finisce qui: si trova una directory più in basso, sotto una directory che prende il nome dal componente che lo ha dichiarato, perché un file del genere prende il nome dalla chiave che il suo autore ha scritto anziché dalla risorsa che porta — quindi, senza quella directory, due componenti legati a una stessa Recipe scriverebbero un unico percorso, senza che nessuno dei due autori possa separarli.

Il namespace rispetto a cui viene renderizzato il chart viene letto dall’annotazione aggrega.ai/namespace che discende a cascata dal confine e raggiunge il chart come namespace della sua release; quando nessun confine ne dichiara uno, il chart viene renderizzato rispetto a default. Dove un confine ne dichiara uno, ogni risorsa con namespace che il chart renderizza senza un namespace — nessun metadata.namespace, oppure uno scritto vuoto o null — viene emessa nel namespace dichiarato, che è dove la colloca l’installazione del chart con Helm sotto quel namespace della release, e il suo file viene nominato con il segmento del namespace esattamente come una risorsa il cui template scrive il campo. Una risorsa il cui template scrive un namespace lo mantiene, qualunque namespace nomini. Una risorsa a livello di cluster resta senza namespace. Se un tipo abbia un namespace è stabilito dall’ambito proprio dell’API di Kubernetes per un tipo che l’API serve direttamente e, per un tipo personalizzato, dallo scope che una CustomResourceDefinition nello stesso rendering dichiara per esso — dai template del chart o dalla sua directory crds/. Una risorsa di un tipo che nessuno dei due classifica viene lasciata come l’ha scritta il chart, e la build la segnala, una volta per tipo, nominando il tipo e il suo gruppo API; lo stesso vale per un documento kind: List, i cui elementi non vengono collocati. Dove nessun confine dichiara un namespace, nulla viene collocato e nulla viene segnalato: una risorsa che il chart scrive senza un namespace viene emessa senza, collocata da ciò che seleziona lo strumento che la applica.

La segnalazione è un avviso sulla build, che viene comunque completata:

warning: node "store" (provider "helm"): resources of kind "Probe" in API group "monitoring.example.org" write no namespace and are left without one rather than placed in namespace "shop": the kind is not one the Kubernetes API serves itself, and no CustomResourceDefinition in this chart's render gives it a single scope, so whether it is namespaced is not known when the build runs, and they land wherever the tool applying the output places them

Dove il chart ha un valore che renderizza la CustomResourceDefinition del tipo, o uno che scrive esso stesso il namespace, impostarlo tramite il valuesMapping della Recipe colloca una risorsa del genere.

La versione di Kubernetes per cui viene renderizzato un chart

I template di un chart leggono la versione di Kubernetes per cui vengono renderizzati come .Capabilities.KubeVersion, e molti scelgono in base a essa una versione dell’API, un campo o un intero meccanismo — un token di service account proiettato dalla 1.21 in poi, per esempio, e uno di prima parte al di sotto. La build non ha un cluster da interrogare, quindi la versione è una che dichiari tu, dove la Release dice dove viene distribuito un componente: l’annotazione aggrega.ai/kubernetes-version su un confine, oppure su un componente, dove prevale su quella del suo confine, propagandosi a cascata esattamente come aggrega.ai/namespace.

spec:
boundaries:
production:
annotations:
aggrega.ai/kubernetes-version: "1.31"
components:
api: {}
legacy:
annotations:
aggrega.ai/kubernetes-version: "1.28" # this component deploys to an older cluster

Il valore viene letto nel modo in cui helm template --kube-version legge il proprio flag, quindi accetta le forme che quel flag accetta e un chart legge esattamente ciò che quel flag gli darebbe: "1.31" viene letto come v1.31, "v1.31.2" come v1.31.2, e il testo dopo i numeri resta in .Capabilities.KubeVersion.Version così come scritto — "1.29.3-gke.100" viene letto come v1.29.3-gke.100 — mentre .Capabilities.KubeVersion stampato per intero legge la versione senza di esso. Un chart che confronta .Capabilities.KubeVersion.Version con semverCompare legge un suffisso del genere come una pre-release, quindi un vincolo senza un minimo -0, come ">=1.21", non vi corrisponde, e un valore che porta spazi attorno viene letto con quegli spazi — " 1.30 " viene letto come "v 1.30 " — e non supera affatto un confronto del genere: scrivi la versione nuda dove un chart la confronta. Un valore che non è una versione — "one.two", "latest", un singolo numero — arresta la build con la condizione per un valore che un plugin non ha modo di rappresentare, nominando il valore, il componente e il suo confine; il chart non viene mai renderizzato per un’altra versione al suo posto. Vedi A Kubernetes version the helm provider cannot render a chart for (Una versione di Kubernetes per cui il provider helm non può renderizzare un chart). Un valore vuoto viene trattato come non impostato.

Dove nessuna annotazione nomina una versione, un chart viene renderizzato per la versione per cui renderizza il helm template standard della stessa release di helm, che è la versione della libreria client di Kubernetes con cui è costruito il provider: un provider costruito con la libreria client v0.37 renderizza per Kubernetes v1.37.0. Così un chart viene renderizzato in Aggrega come lo renderizza il helm template dei suoi stessi autori, e il valore predefinito cambia solo quando cambia la libreria client con cui è costruito il provider. Indica la versione del cluster su cui distribuisci ogni volta che differisce: un chart renderizzato per una versione più recente di quella che il cluster esegue può emettere una versione dell’API che quel cluster non serve.

Solo la versione viene impostata in questo modo. Ogni altra capacità che un chart legge — .Capabilities.APIVersions e .Capabilities.HelmVersion — è quella incorporata nella libreria helm, quindi un’API che un cluster serve da una CustomResourceDefinition installata non viene segnalata al chart. L’intervallo kubeVersion proprio di un chart nel suo Chart.yaml non viene confrontato con la versione: helm template rifiuta un chart il cui intervallo esclude la versione per cui renderizza, e la build lo renderizza. L’annotazione determina un chart renderizzato da sorgente e nient’altro: un Workload sintetizzato e un corpo artifacts: non leggono .Capabilities, e il provider helm-chart consegna il proprio chart senza renderizzarlo, perché venga renderizzato quando viene installato.

Escludere i documenti renderizzati. Questo provider rispetta le voci omits: che una Recipe o una FeatureRecipe dichiara, in questa modalità e in nessun’altra: un Workload sintetizzato e un corpo artifacts: vengono renderizzati senza di esse. Ogni documento che il chart renderizza — da un template o da un file della sua directory crds/ — viene confrontato con ciascuna voce che si applica alla build, e un documento nominato da una qualsiasi voce viene lasciato fuori. Una voce nomina un documento con le parole che il documento stesso porta, le stesse parole da cui sono costruiti il suo nome di file di output e i suoi fatti di rendering: il suo kind, il suo metadata.name e, solo dove la voce ne nomina uno, il namespace in cui si trova il documento — quello che scrive il suo template, oppure il namespace dichiarato del confine dove questo provider colloca il documento come descritto sopra. Non è mai il namespace rispetto a cui il chart viene semplicemente renderizzato: senza alcun namespace dichiarato il chart viene renderizzato rispetto a default, eppure un documento il cui template non scrive alcun namespace non si trova in nessuno, quindi una voce che nomina default non vi corrisponde. Un documento che non porta un tipo o un nome non corrisponde a nessuna voce. I documenti lasciati fuori vengono renderizzati e poi scartati una volta stabilito il nome di ogni file, così ogni documento mantenuto viene nominato e scritto esattamente come lo sarebbe senza le voci, e un documento lasciato fuori non raggiunge nulla di ciò che la build fa in seguito — nessun file, nessun nome nel confronto che rifiuta due contributori che finiscono su uno stesso nome, nessun fatto di rendering che una Feature legge, nulla che venga passato a un passaggio della pipeline. Il provider riporta quanti documenti ha trovato ciascuna voce, e una voce che non ne ha trovato nessuno arresta la build; vedi An omits entry left out nothing the source rendered (Una voce omits non ha lasciato fuori nulla di ciò che la sorgente ha renderizzato).

La release Helm sotto cui viene renderizzato un chart

Il provider renderizza con l’SDK di Helm 4, alla v4.3, quindi un chart legge ciò che gli dà il helm template proprio di Helm 4, e lo stesso chart con gli stessi valori renderizza gli stessi byte a ogni build. Un chart scritto e verificato con Helm 3 può osservare questi comportamenti di Helm 4:

  • .Capabilities.HelmVersion riporta la versione di Helm 4, v4.3.
  • La versione predefinita di Kubernetes è v1.37.0, perché Helm 4 alla v4.3 è costruito con la libreria client v0.37, e .Capabilities.APIVersions è l’insieme delle versioni API di quella libreria client. Indica la versione che esegue il tuo cluster, come descrive La versione di Kubernetes per cui viene renderizzato un chart.
  • Un valore predefinito null del chart viene scartato. Una chiave che il values.yaml del chart imposta a null — al livello superiore o all’interno di una tabella — è assente da .Values a meno che i valori forniti dalla Recipe non la impostino, quindi hasKey la segnala come mancante, toYaml la omette, e il values.schema.json del chart viene verificato rispetto ai valori senza di essa.
  • Uno scalare a blocco mantiene la sua interruzione di riga finale prima di ---. Un documento che termina con uno scalare a blocco ed è seguito da un altro documento dello stesso template mantiene l’ultima interruzione di riga di quello scalare, quindi viene scritto | anziché |-.
  • .Chart è una mappa indicizzata per nome di campo. .Chart.Name, .Chart.Version, .Chart.AppVersion e gli altri campi si leggono come prima, ma toYaml .Chart o toJson .Chart.Maintainers stampano le chiavi come Name, AppVersion e così via, con i campi vuoti presenti, e un campo che i metadati del chart non portano viene letto come vuoto anziché far fallire il rendering.
  • .Capabilities.KubeVersion.Version mantiene il testo di una versione così come scritto, come descritto sopra per l’annotazione aggrega.ai/kubernetes-version.
  • Un values.yaml che contiene più documenti YAML viene letto per intero, con i documenti successivi uniti sopra quelli precedenti.
  • .Files.Lines di un file vuoto non restituisce alcuna riga anziché far fallire il rendering.
  • Le funzioni di template aggiunte da Helm 4 — mustToYaml, mustToJson, mustToToml, mustToDuration e le conversioni duration… — sono disponibili per i template di un chart.
  • Una dipendenza con due alias dà a ciascun alias la propria copia delle dipendenze di quella dipendenza.
  • La validazione dello schema dei valori accetta o rifiuta in modo diverso solo ai margini: la parte locale di un indirizzo email tra virgolette, NaN e i numeri infiniti, un numero confrontato con un non-numero in enum e const, e la posizione riportata per un propertyNames, un contentSchema o un elemento successivo di un array che fallisce.

Un template che il motore stesso non riesce a eseguire — un valore letto attraverso una tabella mancante, per esempio — viene riportato nella forma di Helm 4: il file, la riga e la colonna del template su una riga a sé, poi ciò che si stava eseguendo e il messaggio, rientrati, per ogni template attraverso cui è passato l’errore. Il fail o il required proprio di un chart mantiene la sua forma su una sola riga execution error at (<file>:<line>:<col>): <message>, e lo stesso vale per un errore restituito da una funzione di template.

Come viene derivato il nome della release

Un chart con sorgente esegue il rendering rispetto a un nome di release, che raggiunge ogni template come .Release.Name. I chart nominano abitualmente le risorse in base a esso, quindi un nome di release è un’identità all’interno del cluster anziché un’etichetta sulla build.

Il nome della release è la forma codificata della stessa base che fa da prefisso al nome del file di output della risorsa renderizzata, quindi i due sono un unico nome scritto due volte. Quella base è un instance_id per un componente ordinario, e l’identità composta che porta una Feature associata a un confine. Per un chart fornito dall’autore di un’associazione di Feature è il nome del componente ospitante: i template propri del chart eseguono il rendering rispetto al nome della release, quindi derivarlo invece dall’associazione rinominerebbe risorse che il chart dichiara, in un cluster dove sono già distribuite. Quelle risorse portano comunque l’identità propria dell’associazione nella loro etichetta aggrega.ai/component-id — come si chiama una risorsa e a cosa appartiene sono qui questioni separate, e solo per un componente ordinario hanno la stessa risposta. Un nome di release Helm accetta un insieme di caratteri più ristretto di quello che può contenere un’identità: lettere minuscole, cifre, trattini e punti, con inizio e fine in una lettera minuscola o una cifra, fino a 53 caratteri. Anziché sostituire un carattere che la destinazione non accetta, la derivazione lo scrive per esteso, così due identità di componente che differiscono solo per la punteggiatura o per le maiuscole e minuscole arrivano sempre a due nomi di release.

  • Una lettera minuscola e una cifra vengono riportate esattamente come scritte.
  • Un trattino viene mantenuto come scritto dall’autore ovunque il carattere che lo segue sia riportato direttamente e non sia una z minuscola. Un trattino seguito da una z minuscola apre una sequenza di escape, quindi uno scritto dall’autore in quella posizione viene a sua volta scritto per esteso — api-zone diventa api-zhzone, ed è questo che permette di ricondurre qualsiasi nome senza dover indovinare. Un trattino senza nulla dopo di sé viene scritto per esteso per lo stesso motivo, quindi db- dà db-zh.
  • Ogni altro carattere viene scritto come -z seguito da una lettera che lo nomina: d per un punto, u per un underscore, s per un separatore di percorso, h per un trattino che la regola precedente non mantiene. Qualsiasi altra cosa — compresa una lettera maiuscola — viene scritta come x seguito dal punto di codice esadecimale a sei cifre del carattere, e un byte che non inizia alcun carattere come b seguito dal proprio valore a due cifre.
  • Un valore vuoto viene scritto -ze, che nessun valore non vuoto può produrre.

Un punto viene scritto per esteso anziché riportato, anche se Helm ne accetta uno in un nome di release, perché Helm richiede una lettera minuscola o una cifra su ciascun lato di un punto e la derivazione inserisce trattini propri.

Poiché due Features associate a un solo componente eseguono entrambe il rendering rispetto al nome della release di quel componente, due chart che nominano ciascuno una risorsa in base a .Release.Name emettono due risorse con un solo nome. Questo provider riporta il nome che porta ogni risorsa prodotta dal suo stesso rendering, circoscritto al tipo di quella risorsa e, per un tipo che il cluster tiene in un namespace, al suo namespace, e la build rifiuta due contributori che arrivano a uno stesso di questi nomi anziché emettere un output in cui applicarli entrambi lascia solo l’ultimo — vedi ../errors/fatal-halts.md «The same name is derived more than once inside the output (Lo stesso nome viene derivato più di una volta all’interno dell’output)». Un tipo che il cluster tiene al di fuori di ogni namespace — un ClusterRole, una CustomResourceDefinition, o un tipo personalizzato che una CustomResourceDefinition nello stesso rendering dichiara con l’ambito Cluster — è circoscritto al solo tipo, classificato esattamente come lo classifica la collocazione nei namespace descritta sopra, quindi due componenti di uno stesso output che scrivono ciascuno un oggetto del genere con uno stesso nome vengono rifiutati anche dove la Release li colloca in namespace diversi. Il rimedio è comporre il nome, e quale coordinata gli serve dipende dalla disposizione. Due associazioni su un solo componente condividono già l’ospitante, quindi è l’associazione che deve raggiungere il template: passa .attachment_name nel chart tramite il valuesMapping: della FeatureRecipe e impostalo su quello, tra i valori propri del chart, da cui sono costruiti i nomi delle sue risorse. Un solo chart associato a due componenti è il caso opposto — il nome della release differisce già per ogni ospitante, quindi una risorsa nominata in base a .Release.Name porta un nome proprio su ciascuno di essi, mentre un nome letterale no. Una FeatureRecipe che consegna le proprie risorse tramite artifacts: viene riportata alle stesse condizioni: questo provider legge il nome che porta ogni documento emesso, che quel documento provenga da un template di chart o da un corpo di artefatti, quindi anche un nome letterale in un tale corpo associato a due componenti arresta la build. Un corpo di artefatti è un template, quindi componi il nome da .context.rendered_name — il nome della release dell’ospitante, che differisce per ogni ospitante ed è scritto nei caratteri che un nome Kubernetes ammette — e da .attachment_name dove deve essere distinto per ogni ospitante; su un ospitante che colloca da solo un insieme di artefatti, che non riporta alcun nome di release, componilo invece da .context.instance_id. Non ogni nome viene riportato, quindi una build che non si arresta non ha confrontato tutto ciò che il suo output finirà per portare. Quello che è più probabile incontrare scrivendo un chart è una risorsa che dichiara generateName, il cui nome viene lasciato da completare al cluster e che quindi non ha ancora nulla da confrontare. La pagina linkata sopra riporta l’insieme completo.

Così un instance_id api dà il nome di release api, data.main-db dà data-zdmain-db, e db_host dà db-zuhost. Un’identità composta solo da lettere minuscole, cifre e trattini che la derivazione mantiene compare esattamente come scritta. Un input identico produce sempre un nome identico.

Due delle condizioni di Helm sono proprietà della base anziché della derivazione: un nome di release deve iniziare con una lettera minuscola o una cifra, e deve essere lungo al massimo 53 caratteri. Una base il cui primo carattere viene scritto per esteso inizia il proprio nome con il trattino con cui si apre ogni sequenza di escape, e una che contiene caratteri scritti per esteso risulta, una volta codificata, più lunga di come è stata scritta. La build interroga questo provider su entrambe, e agisce in base alla risposta al momento della build anziché lasciare il rifiuto al cluster al momento dell’applicazione — vedi ../errors/fatal-halts.md «The target will not accept a name derived from an authored identity (La destinazione non accetta un nome derivato da un’identità scritta)». Ciò che fa con la risposta dipende da chi ha scritto la base. Un nome che hai scritto tu viene rifiutato anziché modificato, e il rifiuto nomina il campo che hai scritto e il budget che hai a disposizione; un nome composto da Aggrega viene accorciato finché questo provider non lo accetta.

Il cluster sottopone le risorse nominate in base a un componente a una regola più severa di quelle di Helm: il nome di un Service deve iniziare con una lettera, mentre un nome di release può iniziare con una cifra. Un chart nomina abitualmente i propri Services in base al nome della release, e anche i Services di un carico di lavoro sintetizzato iniziano con esso, quindi questo provider rifiuta anche un nome di componente che inizia con una cifra, segnalandolo come un Service name che la destinazione non può usare. Nessuna lunghezza rimedia a un primo carattere, quindi quel rifiuto non ne indica alcuna. Inizia quindi un instance_id con una lettera minuscola, e mantienilo abbastanza breve perché la sua forma codificata ci stia ancora.

Cambiare la base da cui viene derivato un nome di release rinomina le risorse del cluster che un chart nomina in base a .Release.Name, e ogni risorsa che questo provider sintetizza per il componente, e Kubernetes non rinomina una risorsa sul posto. Lo strumento che applica l’output crea la risorsa con il nuovo nome e rimuove quella con il vecchio nome, il che, per le risorse stateful, significa che lo storage legato al vecchio nome viene rilasciato. Tratta una tale modifica come una sostituzione da pianificare — con drenaggio, migrazione o una finestra programmata — anziché come un aggiornamento da distribuire.

Modalità Workload (sintetizzata)

Una Recipe con workload: (inline o caricato con $import:) sintetizza risorse Kubernetes a partire dall’intento astratto del Workload. Lo schema del Workload è documentato in entities/workload.md; questa sezione descrive ciò che emette il provider helm.

Per ogni nodo:

  • Un oggetto controller scelto dal form del Workload: stateless (e il valore predefinito) emette un Deployment, stateful uno StatefulSet, daemon un DaemonSet, task un Job, scheduled un CronJob il cui spec.schedule è il campo schedule del Workload (un’espressione cron a 5 campi o una macro @); un carico di lavoro scheduled senza pianificazione, o con una pianificazione malformata, arresta la build in modo esplicito. Un carico di lavoro scheduled che dichiara suspend: true emette il proprio CronJob con spec.suspend: true, così nessuna esecuzione parte dalla pianificazione finché non viene ripreso, mentre un Job può ancora essere creato a mano dal CronJob; uno che non lo dichiara non emette alcuna chiave suspend. Il Deployment e lo StatefulSet portano il numero di repliche; DaemonSet, Job e CronJob non ne portano alcuno. Un Workload stateful richiede esattamente un Service type: Headless dichiarato nel Workload per governare lo StatefulSet; il provider collega il serviceName dello StatefulSet al nome renderizzato di quel Service, e la build si arresta se non è dichiarato alcun Service headless (o se ne è dichiarato più di uno). Un volume persistentTemplate è un complemento di form: stateful — dichiararne uno su qualsiasi altra forma arresta la build con un messaggio che nomina la correzione.
  • Un Service per ogni voce services: dichiarata sul Workload, che espone le porte con nome elencate dalla specifica del servizio. Il type della voce diventa il tipo del Service — ClusterIP, NodePort e LoadBalancer alla lettera, e Headless come Service ClusterIP con clusterIP: None. Una voce Loopback arresta invece la build, nominando il nodo e il servizio: un Service Kubernetes non ha alcun tipo che si leghi all’indirizzo di loopback di un host, e su quali indirizzi dei nodi resta in ascolto un Service NodePort è un’impostazione dell’intero cluster, quindi la voce viene rifiutata anziché renderizzata con una portata che non ha chiesto. Vedi A service type the helm provider cannot render (Un tipo di servizio che il provider helm non può renderizzare).
  • Un PersistentVolumeClaim per ogni volume persistent, dimensionato e configurato a partire dalla specifica del volume. Un volume persistentTemplate non emette alcuna claim autonoma: diventa una voce volumeClaimTemplates all’interno della specifica propria dello StatefulSet, ed è per questo che è un complemento di form: stateful.

Nomi delle risorse. Ogni risorsa che questa modalità emette per un componente prende il nome dal nome della release del componente — lo stesso nome rispetto a cui esegue il rendering un chart con sorgente, derivato come illustra Come viene derivato il nome della release — e il provider riporta quel nome alla build come {{ .context.rendered_name }}. L’oggetto controller porta il nome della release stesso; ogni Service è <release name>-<service key>; ogni claim autonoma è <release name>-<volume>, e il volume del pod fa riferimento esattamente a quella claim; un secret consegnato come file viene montato da un volume del pod chiamato <release name>-secret-<slot>, con lo slot scritto nell’alfabeto che il cluster accetta, come lo è il nome della release — così uno slot server_certificate viene montato da <release name>-secret-server-zucertificate, e uno slot letto tramite una connessione ha il punto dopo il nome della connessione scritto allo stesso modo; il serviceName di uno StatefulSet è il nome del Service headless che esso emette; e un Workload esposto solo tramite nome esterno emette un unico Service che porta il nome della release. Così un componente api emette un Deployment api e un Service default api-default, e un componente my_api emette my-zuapi e my-zuapi-default — nomi che il cluster accetta, dove l’identità così come è scritta non lo sarebbe. Una Recipe che pubblica l’indirizzo di uno di quei Services lo costruisce da {{ .context.rendered_name }}, come mostra ../templates/rendered-resource-names.md; per un componente il cui nome non contiene underscore né lettere maiuscole il nome della release è uguale al suo instance_id, quindi i suoi nomi si leggono esattamente come l’identità. Un carico di lavoro sintetizzato da un’associazione di Feature è l’unica eccezione: prende il nome dall’identità composta propria dell’associazione — il valore che porta la sua etichetta aggrega.ai/component-id — perché l’associazione esegue il rendering rispetto al suo componente ospitante, e un nome di release derivato lì darebbe al carico di lavoro dell’associazione il nome dell’ospitante ed entrerebbe in conflitto con quello proprio dell’ospitante. Quell’identità non contiene mai una lettera maiuscola: una maiuscola nel nome dell’ospitante o in quello dell’associazione viene scritta per esteso come sequenza di escape, come ogni altro carattere che il nome di una risorsa rifiuta, così un’associazione worker su un componente myApi emette un Deployment cfr--my-zx000041pi--worker e un Service default cfr--my-zx000041pi--worker-default, e ogni nome che il carico di lavoro porta è uno che il cluster accetta.

Lunghezze dei nomi che dipendono dal Workload. Due di questi nomi sono soggetti nel cluster a limiti propri, e la build li controlla entrambi una volta risolto il Workload, anziché lasciare il rifiuto al cluster al momento dell’applicazione. Il nome di un CronJob ha al massimo 52 caratteri, meno degli altri nomi del cluster perché il controller dà al Job di ogni esecuzione il nome del CronJob con l’aggiunta di un suffisso; viene controllato solo per un Workload scheduled. Il nome di ogni Service, <release name>-<service key>, ha al massimo 63 caratteri. Oltre l’uno o l’altro limite, ciò che accade dipende da chi ha scritto il nome, esattamente come per il nome della release: un nome di componente che hai scritto tu viene rifiutato, e la build si arresta alla chiave spec.components che hai scritto indicando il tipo di nome, la sua lunghezza e il budget di caratteri del tuo nome — vedi ../errors/fatal-halts.md «The target will not accept a name derived from an authored identity (La destinazione non accetta un nome derivato da un’identità scritta dall’autore)»; un’identità composta, come quella da cui prende il nome il workload di un’associazione di Feature, viene accorciata finché ogni nome non rientra nei limiti. Il nome di un Service è formato dal nome del tuo componente e da una chiave che il workload dichiara — nella Recipe o in una FeatureRecipe — quindi un rifiuto nomina quella chiave e il punto in cui il workload la dichiara, spec.workload.services.<key>; una chiave che non lascia spazio ad alcun nome di componente deve essere accorciata a sua volta. Quindi un componente che porta un Workload scheduled può avere un nome codificato di al massimo 52 caratteri, e un componente web può portare chiavi di Service di al massimo 59. Una Feature associata a un intero boundary ha la propria identità stabilita prima che il suo Workload venga risolto, perché il punto in cui il suo output viene assemblato può dipendere da quell’identità, quindi nessuno dei due limiti viene controllato per le risorse che sintetizza.

Ogni risorsa emessa porta l’insieme completo delle etichette e delle annotazioni di provenienza di Aggrega più una coppia di selettori (app: <instance_id>) collegata tra il Deployment/StatefulSet e i suoi Services. Il valore di un’etichetta ammette l’identità così come è scritta, quindi il selettore la mantiene mentre i nomi descritti sopra prendono il nome della release. I nomi dei container nel Deployment renderizzato sono le chiavi dei container del Workload con i caratteri . e _ sostituiti da - (sanitizzazione dei nomi di Kubernetes).

Trasporto delle porte. Una porta del container che dichiara un trasporto lo emette alla lettera come protocol: sul containerPort renderizzato, e ogni porta di Service che nomina quella porta del container porta lo stesso valore — il trasporto viene dichiarato una sola volta, sulla porta del container, quindi l’esposizione non può essere in disaccordo con esso. Una porta che non dichiara alcun trasporto non emette alcuna chiave protocol su nessuna delle due risorse, lasciando in vigore il default del cluster. Tutti e tre i valori che il Workload ammette (TCP, UDP, SCTP) vengono emessi alla lettera; helm non ha bisogno di alcuna degradazione, poiché Kubernetes esprime ciascuno di essi direttamente.

Esecuzione sulla rete del nodo. Un Workload che dichiara hostNetwork: true emette hostNetwork: true sulla specifica del pod renderizzata, così il pod viene eseguito nel namespace di rete proprio del nodo e le porte che aprono i suoi container sono raggiungibili sugli indirizzi del nodo. Kubernetes esprime la scelta direttamente, quindi nulla viene degradato. La dichiarazione raggiunge la specifica del pod e nient’altro: non aggiunge, non rimuove e non riscrive alcuna porta, e i Services emessi sono identici con e senza di essa. Un Workload che non la dichiara non emette alcuna chiave hostNetwork.

Quantità di risorse. Ogni quantità che il provider copia nei manifest viene emessa alla lettera, e ciascuna viene prima verificata rispetto alla forma di quantità descritta in Workload → Quantità di risorse: i valori resources.requests e resources.limits di ogni container e di ogni init container — cpu, memory e ogni risorsa estesa come nvidia.com/gpu — e ephemeral.sizeLimit, persistent.size e persistentTemplate.size di ogni volume. La verifica viene eseguita sul Workload così come lo hanno valutato i template della Recipe, quindi un valore arrivato tramite infra o un parametro della Release viene giudicato in base a ciò in cui è stato renderizzato. Un valore al di fuori della forma arresta la build con un errore TRANSLATION_ERROR che nomina il nodo, il percorso del campo nel Workload e il valore — per esempio containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number — laddove altrimenti la build del chart andrebbe a buon fine e il cluster lo rifiuterebbe all’installazione. Un cpu, memory o sizeLimit lasciato vuoto viene omesso dai manifest e quindi non viene verificato; il valore di una risorsa estesa o una dimensione persistente lasciati vuoti verrebbero comunque emessi, quindi vengono rifiutati. La verifica giudica soltanto la forma: se il cluster possa pianificare la quantità non è qualcosa che il provider possa sapere al momento della build.

La denominazione dei file di output ha due forme. L’oggetto controller prende il nome dal nome della release e dal suo tipo — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. Un file per risorsa prende il nome dalla risorsa che porta, con il tipo per ultimo: <release name>-<svcName>-service.yaml e <release name>-<volName>-pvc.yaml, ciascuno preso dal metadata.name proprio di quella risorsa secondo la convenzione dei nomi sintetizzati in entities/workload.md. Un Workload esposto solo tramite nome esterno emette <release name>-service.yaml, non essendoci alcuna chiave di servizio da portare.

Fatti di rendering

Oltre ai file che renderizza, questo provider riporta quattro fatti di rendering su ogni nodo: ciò che i documenti Kubernetes che ha emesso dicono dei loro pod, dei loro selettori, delle loro porte e del namespace in cui ciascuno viene emesso. Una FeatureRecipe associata al componente legge i fatti propri del componente in .context.render_facts; una che imposta readsCallerRenderFacts: true legge anche, su ogni voce di .context.used_by, i fatti di un componente che si collega al suo ospitante, e una che imposta readsTargetRenderFacts: true legge, su ogni voce di .context.uses, i fatti di un componente a cui il suo ospitante è collegato. È così che una Feature può nominare i pod dei componenti che chiamano il suo ospitante, o dei componenti che il suo ospitante raggiunge — una policy di rete che ammette esattamente quelli, per esempio — a partire da ciò che i loro rendering hanno effettivamente emesso, senza che nessuno ripeta un’etichetta a mano. I nomi e le voci qui sotto sono il contratto di questo provider.

FattoUna voce perOgni voce porta
pod_template_labelstemplate di pod emesso: lo spec.template di un Deployment, StatefulSet, DaemonSet, ReplicaSet o Job, il template del job di un CronJob, e un Pod a sé stante, che è il proprio templatekind, name e namespace della risorsa che porta il template; labels, le etichette del template
controller_selectorsDeployment, StatefulSet, DaemonSet, ReplicaSet, Job e CronJob emessokind, name, namespace; match_labels, i matchLabels del suo selettore
service_selectorsService emessoname, namespace; selector, le etichette a cui invia il traffico
container_portscontainer di un template di pod che dichiara un elenco ports, init container compresikind, name e namespace della risorsa che porta il template; container, il nome del container; ports, una voce per porta con il suo name, container_port e protocol

Come si leggono i fatti:

  • Ogni fatto è un elenco. Un template itera sempre su un fatto, anche quando contiene una sola voce; non esiste un valore singolo da leggere da solo.
  • Tutti e quattro, a ogni rendering. Ciascuno viene riportato ogni volta che questo provider esegue il rendering di un nodo, come elenco vuoto quando il rendering non ha emesso nulla di ciò che descrive — un componente il cui chart emette solo una ConfigMap riporta quattro elenchi vuoti. Il rendering di un altro provider non riporta nessuno di questi nomi, e un nome che nessuno ha riportato si legge come nulla.
  • Letti da ciò che è stato emesso, su ogni percorso. I fatti provengono dai documenti che il rendering ha emesso, qualunque modalità li abbia prodotti: i manifest renderizzati di un chart, quelli di un Workload sintetizzato, e i manifest che un autore ha collocato tramite artifacts:, che riportano esattamente ciò che quei manifest portano. Vengono letti nello stesso passaggio, sugli stessi documenti, dei nomi di risorsa che questo provider riporta per la verifica dei nomi duplicati della build. Le etichette di provenienza proprie di una risorsa fanno parte di ciò che porta, quindi le labels di un Pod a sé stante le includono; il template di pod di un chart o di un artefatto mantiene le etichette che il suo autore ha scritto.
  • Le voci possono provenire dal rendering proprio del componente e dai rendering delle sue Features. Un componente può essere renderizzato da più di una chiamata — un chart e una collocazione artifacts:, per esempio — e gli elenchi che un nome riceve da quelle chiamate vengono uniti in uno solo, nell’ordine in cui le chiamate sono state eseguite. Su .context.used_by e .context.uses, i fatti del componente all’altra estremità di una connessione uniscono anche ciò che hanno renderizzato le Features associate a esso, dopo i propri; .context.render_facts porta solo il rendering proprio del componente.
  • Nell’ordine di emissione. Le voci seguono l’ordine in cui il rendering ha emesso le risorse. Una mappa di etichette è una mappa con chiavi come ogni altra nel contesto, quindi un template che ne itera una incontra le sue chiavi in ordine di chiave.
  • Ciò che un documento omette, la sua voce lo omette. Una risorsa nominata tramite generateName non ha name; una risorsa che non scrive alcun metadata.namespace non ha namespace, e non ne ha neppure una che lo scrive vuoto o null, che a sua volta non nomina alcun namespace; un controller scritto senza matchLabels — un Job che si affida al selettore generato dal cluster — non ha match_labels; un Service senza selettore non ha selector; una porta senza nome o senza protocollo non ha né l’uno né l’altro. Ogni altra parte scritta vuota viene riportata vuota. protocol viene riportato solo dove il documento ne scrive uno, quindi un template che ne ha bisogno scrive da sé il default proprio del cluster, TCP. container_port è un numero ovunque il documento ne scriva uno.
  • namespace è quello che il documento scrive, mai un’ipotesi. È il metadata.namespace proprio della risorsa — per un template di pod, quello della risorsa che lo porta, che è dove vengono eseguiti i suoi pod; un namespace scritto all’interno del template di pod stesso non viene letto. Un Workload sintetizzato scrive il namespace dichiarato dal suo confine su ogni risorsa che emette, quindi le sue voci portano quel namespace. Le voci di un chart portano ciò che scrivono i documenti che emette: dove un confine dichiara un namespace, quel namespace — sia che i template del chart lo proiettino, sia che il provider vi collochi la risorsa (vedi Modalità con sorgente) — a meno che un template non ne fissi uno proprio, che la voce porta al suo posto; dove non ne è dichiarato alcuno, il namespace della release, default, dove i template lo proiettano, e nulla dove non ne scrivono alcuno. Dove non è scritto nulla la voce non porta alcun namespace anziché il default del confine o del cluster, perché una risorsa del genere finisce ovunque la collochi lo strumento che applica l’output, cosa che non è nota quando viene eseguita la build. Un template distingue i due casi con optional: {{ optional . "namespace" "" }} è vuoto esattamente dove il documento non ne ha scritto alcuno, così una Feature che colloca qualcosa accanto ai pod di un componente può distinguere un componente il cui namespace dei pod è noto da uno per cui non lo è.
  • Riconosciuti per tipo e gruppo API. Pod e Service vengono letti nel gruppo core, i quattro controller in apps, Job e CronJob in batch, a qualsiasi versione del gruppo. Una risorsa personalizzata di un altro gruppo che porta per caso uno di questi nomi di tipo non viene letta come tale. Le matchExpressions di un selettore non vengono riportate, e nemmeno una risorsa racchiusa in un documento kind: List o un valore scritto tramite una chiave di merge YAML.

Ciò che i fatti non possono vedere. Descrivono i documenti che la build emette, e nulla di ciò che il cluster crea in seguito. I pod che un controller crea a runtime da una risorsa personalizzata — il cluster di database di un operatore, per esempio — non compaiono in alcun documento emesso, quindi sono assenti per costruzione; lo stesso vale per qualsiasi etichetta che un admission controller mutante aggiunge quando i manifest vengono applicati. Una Feature che deve ammettere pod del genere ne prende le etichette dalla documentazione propria della risorsa personalizzata, come farebbe un autore senza questi fatti.

Una FeatureRecipe che ammette nei pod del suo ospitante esattamente i pod dei componenti che lo chiamano, selezionando i pod propri dell’ospitante tramite il selettore del controller dell’ospitante:

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: admit-callers
version: 1.0.0
spec:
capability: helm
implements: example/admit-callers:1.0.0
readsCallerRenderFacts: true
artifacts:
allow-callers.yaml: |
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: {{ .context.rendered_name }}-allow-callers
spec:
podSelector:
matchLabels:
{{- range .context.render_facts.controller_selectors }}
{{- range $k, $v := .match_labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
policyTypes:
- Ingress
ingress:
- from:
{{- range .context.used_by }}
{{- range .render_facts.pod_template_labels }}
- podSelector:
matchLabels:
{{- range $k, $v := .labels }}
{{ $k }}: {{ toJson $v }}
{{- end }}
{{- end }}
{{- end }}

Per un ospitante api chiamato da un componente web il cui Workload è stato sintetizzato da questo provider, la policy seleziona app: "api" e ammette un podSelector che porta ogni etichetta del template di pod di web — le stesse etichette contenute nello spec.template.metadata.labels del suo Deployment emesso. Poiché la FeatureRecipe imposta la chiave, la sua associazione viene renderizzata quando ogni componente è stato renderizzato, così i fatti ci sono qualunque tra api e web la build raggiunga per primo; senza la chiave, un template che legge render_facts su .context.used_by arresta la build prima che qualsiasi cosa venga renderizzata.

Un podSelector nel from di una policy corrisponde ai pod nel namespace proprio della policy, quindi la policy qui sopra ammette i chiamanti emessi nel namespace in cui viene applicata. Un chiamante le cui voci portano un altro namespace viene ammesso abbinando il suo podSelector a un namespaceSelector sull’etichetta kubernetes.io/metadata.name di quel namespace, che Kubernetes imposta su ogni namespace.

Particolarità specifiche del Provider

  • I download dei chart usano solo i gestori integrati di Helm. Un chart recuperato da un repository Helm viene scaricato con i gestori integrati propri di Helm, http e https. Un plugin downloader di Helm — uno installato per il comando helm, o uno che si trova nella directory da cui viene eseguita la build — non viene mai consultato, quindi ciò che si trova in quella directory non può cambiare il modo in cui un chart viene recuperato.

  • Iniezione della provenienza. I percorsi con sorgente e sintetizzato convergono sullo stesso insieme di etichette e annotazioni; i rendering con sorgente le iniettano tramite una riscrittura YAML post-rendering (dopo che l’SDK di Helm ha già eseguito il rendering), così gli autori di chart non devono far passare le etichette di Aggrega attraverso i propri template.

  • Ordine dell’ambiente — prima le voci lette da Secret. L’elenco env di un container sintetizzato porta due tipi di voce: ogni voce attachments consegnata as: env legge il proprio valore da un Secret tramite valueFrom.secretKeyRef, e ogni voce variables porta un value semplice. Il provider scrive prima ogni voce letta da Secret e dopo di esse ogni variabile semplice, ciascun tipo nell’ordine in cui è scritto, ed elenca separatamente le sorgenti envFrom sotto envFrom. Kubernetes espande un riferimento $(NAME) in un valore env a partire dalle voci elencate prima di esso nello stesso container, mai da una elencata dopo, quindi questo ordine permette a una variabile semplice di comporre per riferimento un valore letto da Secret mentre il segreto stesso resta nel Secret:

    containers:
    api:
    image: "api:1.0"
    variables:
    DATABASE_URL: "postgres://app:$(DB_PASSWORD)@db:5432/app"
    attachments:
    DB_PASSWORD: { from: db-credentials, as: env }

    Il container renderizzato elenca DB_PASSWORD prima di DATABASE_URL, così il processo riceve l’URL con la password al suo posto. Una variabile può anche fare riferimento a qualsiasi variabile scritta prima di essa, il che mantiene significativo l’ordine di scrittura all’interno di variables. Gli init container seguono lo stesso ordine. Un container che fornisce un nome sia come voce variables sia come voce attachments consegnata as: env arresta la build anziché scrivere entrambe le voci, perché sarebbe allora solo questo ordine a decidere quale valore vede il processo (vedi A container gives one environment variable two values (Un container assegna due valori a una stessa variabile d’ambiente)).

  • Cascata del namespace — le due modalità raggiungono la risorsa in modo diverso. Entrambe leggono aggrega.ai/namespace dalla cascata delle annotazioni del confine, e nessuna delle due inventa un namespace quando nessun confine ne dichiara uno. In modalità sintetizzata il provider scrive direttamente metadata.namespace, e omette del tutto il campo quando la cascata non produce alcun valore. In modalità con sorgente il provider fornisce il valore come namespace della release del chart — default quando la cascata non ne produce alcuno — e il template proprio del chart decide se proiettarlo; dove è dichiarato un namespace, il provider lo scrive poi in ogni risorsa con namespace che il chart ha renderizzato senza (vedi Modalità con sorgente). Così, con un namespace dichiarato, entrambe le modalità collocano in esso ogni risorsa con namespace — eccetto un namespace che un chart fissa da sé e un tipo che il provider non riesce a classificare. Senza alcun namespace dichiarato divergono: un chart che proietta il namespace della release colloca le sue risorse in default, dove l’output sintetizzato non ne scrive alcuno, e un chart che non scrive alcun namespace non le colloca in nessuno, così finiscono dove le mette lo strumento che applica i manifest. I chart locali che portano le FeatureRecipes della libreria standard leggono invece direttamente il valore della cascata tramite il loro valuesMapping: così possono omettere il campo quando nessun confine dichiara un namespace, in linea con l’output sintetizzato, cosa che il namespace della release da solo non può esprimere perché non è mai vuoto.

Esempi pratici

Modalità con sorgente — Recipe che punta a un chart copiato in locale:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helm
version: 1.0.0
spec:
capability: helm
implements: core/api-server
source: ./vendor/charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}
service:
type: ClusterIP
port: {{ .values.port }}
env:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"

Modalità Workload — Recipe che dichiara un Workload inline:

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-workload
version: 1.0.0
spec:
capability: helm
implements: core/api-server
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
api:
image: "{{ .values.image }}"
ports:
web: {{ .values.port }}
services:
svc:
type: ClusterIP
ports:
web: {{ .values.port }}

Riferimenti incrociati