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

Provider Helm-Chart

Il provider helm-chart produce un chart ombrello Helm pacchettizzato per ogni percorso di assemblaggio. Mentre il provider helm emette YAML Kubernetes piatto per il consumo diretto tramite GitOps, helm-chart emette uno scheletro di chart — un Chart.yaml + values.yaml ombrello più un sotto-chart per ogni nodo che contribuisce — che gli strumenti a valle possono installare tramite helm install o copiare in locale (vendoring) per un’ulteriore personalizzazione per ambiente. Il provider assembla per (path, provider): ogni nodo legato a una Recipe helm-chart contribuisce all’ombrello nella directory: valutata del confine unita alla subDirectory: di ciascun componente. Due confini che si valutano nello stesso percorso confluiscono in un unico chart ombrello unito che elenca ogni contributore come dipendenza di sotto-chart.

I template di un sotto-chart copiati dal chart di origine portano ciò che il loro autore ha scritto: il valore syncWave: <integer> del confine, l’helm.sh/hook-weight su un hook e le etichette di provenienza di Aggrega li raggiungono solo dove il chart li scrive. È il provider helm ad apporre argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" e le etichette di provenienza su ogni risorsa che renderizza. Un artefatto caricato con $import: che questo provider aggiunge a un sotto-chart porta le etichette di provenienza e l’annotazione argocd.argoproj.io/sync-wave, e nessun helm.sh/hook-weight (vedi «Regola di iniezione di artifacts:» più sotto). ArgoCD legge l’annotazione sync-wave, e Helm legge il peso di un hook.

Questa pagina è il riferimento di authoring del provider helm-chart. Per la distinzione tra helm e helm-chart, vedi la sezione Providers della pagina di stato; per il modello di composizione degli input comune a tutti i provider, vedi architecture/16-recipe-input-composition.md.

Tipi di input supportati

Il provider helm-chart accetta due tipi di input:

  • Modalità da sorgente. Una Recipe con source: <chart-path> punta a una directory di chart Helm su disco. Il chart viene copiato nella struttura dell’ombrello come sotto-chart, alla lettera tranne il name proprio del chart — vedi «Il nome del chart che spetta al chart ombrello»; non viene eseguito alcun rendering né alcuna elaborazione di template a livello del singolo nodo. Il ruolo di Aggrega è la composizione (l’assemblaggio dell’ombrello attraverso i nodi del confine), non la valutazione dei template.
  • Modalità artifacts: caricata con $import:. Una Recipe con voci artifacts: scritte con $import: per voce dichiara file di template aggiuntivi che il provider helm-chart inietta nella directory templates/ del sotto-chart dopo la copia del chart di origine. Ogni file viene pre-elaborato come template rispetto al contesto di template di Aggrega usando i delimitatori [[ ]] (vedi «Regola di iniezione di artifacts:» più sotto), così qualsiasi templating Helm {{ }} nello stesso file sopravvive fino al rendering a valle di helm install.

Una Recipe destinata a helm-chart che dichiara workload: viene rifiutata prima del rendering, con il rifiuto che qualsiasi provider dà per un tipo di input che non dichiara — nomina il tipo che questo provider supporta e indirizza l’autore verso un provider che sintetizza:

provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (il provider non supporta il tipo di input del nodo (nodo “api”). il provider “helm-chart” non supporta le recipe sintetizzate (questo provider supporta: da sorgente); dichiara uno dei tipi di input supportati, oppure punta a un provider che supporta il tipo sintetizzato)

La distinzione è voluta: la sintesi dei carichi di lavoro (tradurre un Workload astratto in risorse Kubernetes) è competenza esclusiva del provider helm. Il ruolo di helm-chart è la composizione di ombrello + sotto-chart per chart che l’autore ha già prodotto.

Una Recipe destinata a helm-chart può anche dichiarare voci artifacts: a contenuto inline (voci il cui valore è uno scalare a blocco che porta il corpo del file inline nella Recipe anziché un riferimento caricato con $import:). Una voce a contenuto inline viene collocata nella radice del sotto-chart sotto la chiave con cui è scritta — nessun prefisso templates/ e nessun innesto di provenienza. I template propri di un chart leggono un file sciolto di questo tipo tramite .Files.Get / .Files.Glob di Helm (il pattern canonico ConfigMap-da-file), quindi un file nella radice del chart è una forma legittima e di prima classe anziché un errore.

Entrambe le forme vengono valutate con i delimitatori [[ ]] di Aggrega prima della collocazione, così il corpo di entrambe le forme può leggere il contesto dei pilastri della Recipe; {{ }} in entrambi i corpi viene lasciato intatto e diventa una direttiva Helm al momento del helm install a valle. Ciò che differisce tra le forme è dove finisce il file e se la provenienza vi viene unita:

  • Una voce caricata con $import: è un file di template: dopo la valutazione (vedi «Regola di iniezione di artifacts:» più sotto) viene iniettata nella directory templates/ del sotto-chart con la provenienza unita, così Helm la renderizza come manifest accanto ai template propri del chart.
  • Una voce a contenuto inline è un file di dati sciolto: dopo la valutazione finisce nella radice del chart, invariata rispetto a ciò che la valutazione ha prodotto e senza alcuna provenienza unita, per un consumo basato su .Files.

Regola di iniezione di artifacts:

Quando una Recipe helm-chart dichiara voci artifacts: tramite $import: per voce, ogni valore $import: è il percorso di un file di template risolto rispetto alla directory propria della Recipe (la directory che contiene lo YAML della Recipe su disco). Il provider:

  1. Legge il contenuto di ciascun file.
  2. Pre-elabora il contenuto come template con i delimitatori di Aggrega [[ ]] rispetto al contesto di template della Recipe (lo stesso contesto rispetto a cui viene valutato il valuesMapping: della Recipe). {{ }} all’interno del contenuto del file viene lasciato intatto — queste espressioni diventano direttive di template Helm al momento del helm install.
  3. Scrive ciascun file in charts/<instance-id>/templates/<authored-key> sotto il percorso di assemblaggio dell’ombrello, con i file di un bundle annidati sotto quella chiave. La chiave con cui la voce è scritta dà il nome al file; il percorso $import: ne seleziona il contenuto e non contribuisce in nulla al nome, quindi la struttura delle directory all’interno di quel percorso non raggiunge mai l’output.

La disciplina del doppio delimitatore [[ ]] / {{ }} è il dettaglio portante. Un tipico file di artefatto caricato con $import: può mescolare interpolazione al momento di Aggrega (es. [[ .values.image ]]) e interpolazione al momento di Helm (es. {{ .Release.Namespace }}). Ogni coppia di delimitatori scatta nella propria fase: Aggrega risolve [[ ]] al momento della compilazione, prima che il file venga collocato; Helm risolve {{ }} al momento dell’installazione, dopo che l’ombrello è stato consegnato.

Le collisioni di nomi di file tra i template del chart di origine e le iniezioni di artefatti caricati con $import: generano CATALOG_ERROR — la diagnostica nomina il percorso di output in collisione, come templates/cm.yaml, e i due tipi di input che lo hanno prodotto. Gli autori risolvono la collisione rinominando la chiave dell’artefatto o il template proprio del chart.

Insieme di chiavi di source:

Il source: del provider helm-chart nomina un chart e accetta entrambe le forme che il campo source: assume, lette esattamente come le descrive l’insieme di chiavi di source: del provider helm: una stringa semplice di percorso del filesystem e un oggetto strutturato il cui url: porta la posizione. Dove url: nomina un percorso del filesystem, non viene recuperato nulla e il chart viene letto dal disco; dove porta uno schema di trasporto — oci://…, per esempio, con kind: helm-oci-chart — aggrega pull recupera e fissa il chart, e la build lo copia dalla cache nell’ombrello come sotto-chart, alle stesse condizioni di un chart letto dal disco.

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

Il chart nel percorso di origine deve contenere un Chart.yaml valido nella propria radice; se manca, emerge un errore chiaro prima che la copia venga eseguita. La struttura delle directory del chart viene preservata durante la copia — templates/, values.yaml, Chart.yaml e qualsiasi altro file sono presenti nella directory del sotto-chart dopo la composizione. Ogni file arriva con i byte che hai scritto, fino a commenti, ordine delle chiavi e virgolette; l’unica eccezione è il campo name del Chart.yaml proprio del chart, che viene impostato dall’ombrello — vedi «Il nome del chart che spetta al chart ombrello».

Entrambi i modi di non nominare un chart vengono rifiutati, e i due rifiuti provengono da punti diversi — vale la pena saperlo, perché solo uno dei due cambia se cambi capacità. Un source: presente che tuttavia non dichiara nulla viene rifiutato dal compilatore prima che venga eseguito qualsiasi provider, quindi l’esito è lo stesso qualunque sia la capacità che la Recipe nomina; la diagnostica ti dice di omettere il campo per la modalità senza sorgente oppure di nominare un percorso non vuoto. Omettere del tutto source: è un authoring valido — è il modo in cui una Recipe richiede la modalità senza sorgente — e qui viene rifiutato perché helm-chart dichiara solo il tipo di input da sorgente, quindi il compilatore rifiuta la combinazione con lo stesso messaggio che dà per qualsiasi capacità richiesta per un tipo di input che non dichiara. Ciò che è proprio di helm-chart è la dichiarazione, non un rifiuto suo: per le risorse Kubernetes generate da un blocco workload:, usa invece la capacità helm.

Una Recipe che dichiara omits: viene rifiutata. La chiave omits: esclude dalla build i documenti che una sorgente renderizza, e questo provider non renderizza alcun documento al momento della build: copia il chart nell’ombrello, e i template del chart vengono renderizzati quando l’ombrello viene installato. Senza nulla di renderizzato non c’è nulla da escludere, quindi questo provider non dichiara di rispettare la chiave, e una Recipe o una FeatureRecipe che la dichiara viene rifiutata prima che venga copiata qualsiasi cosa — vedi The provider does not support omits (Il provider non supporta omits). Per un chart che tieni accanto alla Recipe, una riga nel .aggregaignore che si trova lì esclude invece un file del chart, dalla volta successiva in cui la Recipe viene fissata; per un chart recuperato il cui output deve perdere un documento, renderizzalo tramite il provider helm, che rispetta la chiave.

Composizione indicizzata per percorso — la forma a ombrello

Il provider viene eseguito in due fasi per ogni percorso di assemblaggio:

  1. Copia per contributore. Per ogni nodo legato a una Recipe helm-chart, il provider copia l’intero albero di directory del chart di origine in uno slot di sotto-chart. I file finiscono in modo piatto nella mappa di output per contributore; l’assemblatore nomina charts come la sottodirectory sotto cui stanno i suoi contributori, e l’orchestratore dà a ogni contributore una directory propria lì quando assembla l’ombrello — charts/<instance_id>/ per un componente. Anche un’associazione di Feature è un contributore — sia che copi in locale un chart sia che renderizzi manifest tramite il provider helm — e riceve una directory accanto a quella del componente anziché al suo interno; vedi «Dove finisce il chart di un’associazione».
  2. Assemblaggio dell’ombrello per (path, provider). Una volta completate tutte le copie per nodo del percorso, l’assemblatore emette un Chart.yaml + values.yaml ombrello nella radice del percorso di assemblaggio. L’ombrello dichiara una dipendenza per ogni nodo che contribuisce e instrada i valori per nodo in sotto-blocchi indicizzati per instance-id. Quando il percorso di assemblaggio riceve contributori da più di un confine (confini con directory: condivisa), ogni contributore finisce come dipendenza nello stesso ombrello.

Il Chart.yaml ombrello ha la forma:

apiVersion: v2
name: <effective-chart-name> # see "Chart-name resolution" below
version: 0.1.0
description: Aggrega umbrella chart for boundary "<assembly-path>"
dependencies:
- name: <encoded-instance-id> # the name the placed sub-chart carries
version: <user-chart-version> # from the source chart's Chart.yaml
alias: <encoded-instance-id> # see "How a name is derived" below
repository: file://charts/<instance_id> # the sub-chart's own directory

Risoluzione del nome del chart

Il name del chart dell’ombrello viene risolto tramite la cascata delle annotazioni del confine. L’annotazione aggrega.ai/chart-name effettiva di ciascun confine che contribuisce (il valore risolto dalla cascata, risalendo l’albero dei confini) determina il nome dell’ombrello; il valore risolto viene codificato per la posizione del nome del chart esattamente come qualsiasi altra identità, quindi un valore che contiene solo lettere, cifre, underscore e trattini che la regola più sotto mantiene raggiunge il chart alla lettera. Quando il percorso di assemblaggio riceve contributori da più di un confine, l’annotazione aggrega.ai/chart-name effettiva di ogni contributore DEVE risolversi nello stesso valore; le discrepanze arrestano la build con una diagnostica che nomina i valori in conflitto e i confini che contribuiscono.

La cascata risolve naturalmente la tensione DRY: dichiara aggrega.ai/chart-name una sola volta sul confine padre e i confini figli la ereditano tramite la cascata; i confini fratelli senza un padre comune devono dichiarare esplicitamente valori corrispondenti. I confini che non dichiarano aggrega.ai/chart-name in nessun punto della loro cascata ricadono sul nome dell’aggregato e sul percorso di assemblaggio — la directory di output dell’ombrello sotto dist/, come boundaries/data/helm-chart — ciascuno codificato e unito come descritto più sotto.

Il name di ogni voce di dipendenza è il nome che porta il sotto-chart collocato — l’identità codificata propria dell’istanza del componente, lo stesso valore dell’alias — per le ragioni esposte in «Il nome del chart che spetta al chart ombrello». La sua version è ancora la versione del Chart.yaml proprio del chart di origine. L’alias delimita i valori del sotto-chart sotto values.yaml.<alias>.*, conformemente alla convenzione dei valori ombrello di Helm, così i valori per istanza si propagano correttamente quando l’ombrello viene installato.

La directory del sotto-chart di un componente mantiene l’instance_id esattamente come scritto, quindi charts/<instance_id>/ è dove finiscono i suoi file e ciò a cui punta il repository della dipendenza. Due istanze dello stesso chart di origine coesistono quindi senza una collisione nel filesystem, e ciascuna mantiene il proprio blocco di valori sotto il proprio alias.

Il name della dipendenza e il suo repository sono stringhe diverse, ed è voluto. name è ciò che il chart in quella posizione DICHIARA, perché Helm lega una dipendenza a un chart figlio tramite il nome dichiarato dal figlio stesso; repository è dove si trova quel chart. Per un componente i due capita che si leggano allo stesso modo, perché entrambi derivano dallo stesso instance id. Per un’associazione di Feature differiscono — il nome dichiarato porta l’identità composta dell’associazione, mentre la directory porta le sue due coordinate unite — quindi leggere l’uno come l’altro nomina qualcosa che non c’è.

Dove finisce il chart di un’associazione

Un’associazione di Feature che copia in locale un chart riceve una directory propria accanto al componente a cui è associata, un livello sotto charts/:

charts/
├── api/ # the component's own chart
├── api--guardrail/ # a Feature attached to `api` under `guardrail`
└── api--audit/ # a second Feature attached to the same component

Una Feature associata a un confine anziché a un componente non ha un componente ospitante da nominare, quindi la sua directory è solo il suo nome di istanza: charts/aux/.

Perché accanto e non dentro. Helm individua un chart figlio in charts/* — un livello, non una visita ricorsiva. Un chart collocato più in profondità non è figlio di nulla; è un dato dentro la directory di un altro figlio, raggiungibile solo tramite .Files. Quindi un chart collocato dentro la directory del chart proprio del componente verrebbe copiato nell’output, farebbe riuscire la build e non contribuirebbe con nessuna delle sue risorse a ciò che distribuisci — senza che nulla lo segnali. Collocare ogni contributore nella propria directory di primo livello è ciò che fa renderizzare le risorse dell’associazione.

L’ombrello dichiara anche l’associazione come una delle sue dipendenze. Servono entrambe le metà: un chart presente sotto charts/ e assente da dependencies: è un errore di lint, e un chart dichiarato in dependencies: senza un chart figlio corrispondente presente fa sì che l’ombrello rifiuti di caricarsi.

Le due coordinate vengono unite, non concatenate. Il nome di una directory è composto dal componente ospitante e dall’istanza tramite la stessa regola di escape descritta più sotto, applicata a ciascuna coordinata prima che vengano unite con --. Accostarle direttamente con -- sarebbe ambiguo: un componente ospitante chiamato a--b con un’istanza c, e un componente ospitante a con un’istanza b--c, arriverebbero alla stessa directory. Codificare prima ciascuna coordinata le tiene distinte, quindi un -- scritto all’interno di una coordinata appare come -zh-.

Che cosa ammette il nome della directory. Le lettere ASCII maiuscole e minuscole, le cifre, il punto e l’underscore passano così come li hai scritti, quindi API--aux e web.api--aux si leggono come ti aspetteresti. Un trattino che hai scritto viene mantenuto ovunque il carattere che lo segue sia uno di questi, quindi web-api--aux resta invariato; un trattino doppio viene sottoposto a escape, perché la coppia è la giunzione. Qualsiasi altra cosa viene sottoposta a escape con la stessa regola di un nome di chart. L’insieme è delimitato così perché questi nomi di directory sono sia percorsi su disco sia la posizione che il puntatore file:// di una dipendenza risolve, e un carattere che va bene in un nome di file può troncare o far ridecodificare un URL.

I valori seguono il nome dichiarato, non la directory. I valori di un chart figlio sono delimitati sotto il nome che quel chart dichiara, quindi i valori per il chart sopra si indirizzano tramite il nome dichiarato di api--guardrail — cfr-zh-api-zh-guardrail — anziché tramite la sua directory.

Non scrivi mai quella chiave tu stesso. Scrivi i valori sull’associazione, e il values.yaml dell’ombrello viene composto per te con il blocco già all’indirizzo con cui viene indirizzato il chart collocato. Per una Feature associata a un componente si tratta dei values: che dichiari sull’associazione, letti dal valuesMapping: proprio della FeatureRecipe; per una Feature associata a un confine si tratta dell’infra: che dichiari lì, poiché una Feature associata a un confine non ha un pilastro di valori del componente. In entrambi i casi, la mappa in cui si risolve il valuesMapping: diventa il blocco proprio dell’associazione nell’ombrello:

# the umbrella's values.yaml, composed for you
api: # the component's own chart
replicaCount: 3
cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought
auditEndpoint: "https://audit.internal"

Questa è l’unica via che hanno quei valori. Un chart che una Feature porta arriva con i suoi file come li ha scritti il suo autore — a parte l’unico campo del manifest descritto in «Il nome del chart che spetta al chart ombrello» — quindi nulla scrive i tuoi valori in quel chart, ed è il blocco dell’ombrello a fornirli. Un chart il cui blocco non è mai arrivato non è un chart rotto: renderizza i valori predefiniti che il suo values.yaml porta con sé e segnala successo, quindi dai a un valore predefinito un valore che noteresti, se vuoi vedere la differenza durante l’authoring.

Un’associazione la cui FeatureRecipe esegue il rendering tramite il provider helm

Una FeatureRecipe della capacità helm, associata a un componente su questa destinazione, porta manifest Kubernetes finiti anziché un chart. Finiscono nella directory propria dell’associazione esattamente come il provider helm li ha renderizzati, e il provider dà a quella directory le due cose che ne fanno un chart che Helm installa: un Chart.yaml minimale, che dichiara il nome proprio dell’associazione alla versione 0.1.0, e un unico template, templates/rendered.yaml, che emette ciascun file YAML renderizzato tramite .Files.Get di Helm in base al suo nome:

charts/api--guardrail/
├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0
├── guardrail-config.yaml # the manifest the helm provider rendered
└── templates/
└── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}

Il nome dichiarato è quello che dichiarerebbe un chart copiato in locale dalla stessa associazione, quindi la voce di dipendenza dell’ombrello e il suo blocco di valori vengono indirizzati esattamente come descritto sopra. .Files.Get restituisce i byte di un file così come sono anziché valutarli una seconda volta, quindi un manifest che contiene parentesi graffe di template letterali — il {{ $labels.instance }} di una regola di alerting, la query di una dashboard — viene installato con queste intatte. I suoi valori sono stati risolti in quei manifest quando il provider helm li ha renderizzati, quindi il blocco che il values.yaml dell’ombrello porta sotto quel nome non viene letto da nulla.

Il nome del chart che spetta al chart ombrello

L’unica cosa che Aggrega modifica all’interno di un chart che hai copiato in locale è il campo name proprio di quel chart. Nel Chart.yaml del chart collocato, name viene impostato sull’identità codificata di ciò che ha contribuito quel chart.

Per un componente, è l’identità propria dell’istanza del componente — lo stesso valore dell’alias della dipendenza — e anche la voce di dipendenza dell’ombrello nomina quel valore, così i due lati concordano sempre.

Un chart portato da un’associazione di Feature è un contributore a pieno titolo, e dichiara la propria identità anziché ripetere quella del componente a cui è associato. Quell’identità è composta da due cose che hai scritto — il componente che ospita l’associazione e il nome con cui la Feature è associata — dietro un breve prefisso che la contrassegna come identità di un’associazione anziché di un componente; il valore composto viene poi scritto per la posizione del nome del chart tramite la derivazione descritta sotto, esattamente come qualsiasi altra identità.

Così, associare una Feature che copia in locale un chart a un componente chiamato api con il nome guardrail colloca un chart che dichiara cfr-zh-api-zh-guardrail, mentre il chart proprio di quel componente dichiara ancora api. I due sono contributori separati, e ciascuno dichiara un nome proprio anziché dichiarare entrambi quello dell’ospitante.

Nient’altro nel chart viene toccato. Ogni altro file arriva byte per byte come l’hai scritto, e all’interno di Chart.yaml ogni altro campo, ogni commento, l’ordine delle chiavi e le virgolette sono esattamente come scritti. Una chiave annidata altrove nel manifest che si chiama anch’essa name — il nome di un maintainer, per esempio — viene lasciata com’è.

Perché l’ombrello ha bisogno di quel campo. Il name di un chart è ciò a cui Helm lega una dipendenza dell’ombrello. Lo scrive chi ha creato il chart, che per un chart acquisito dall’upstream non è la persona che lo distribuisce — quindi due componenti in uno stesso percorso di assemblaggio possono, in modo del tutto ragionevole, copiare in locale chart i cui manifest dichiarano lo stesso nome. Se entrambi i sotto-chart mantenessero quel nome condiviso, entrambe le dipendenze dell’ombrello si risolverebbero in quello dei due che Helm ha caricato per primo: il chart di un componente verrebbe renderizzato due volte e quello dell’altro per niente, mentre i valori di ciascun componente arriverebbero comunque, quindi l’output sembrerebbe completo e sarebbe sbagliato. Derivare il nome collocato dall’istanza del componente elimina del tutto il nome condiviso, ed è per questo che non c’è nulla da rifiutare — compresi i due casi che non hanno altro rimedio: copiare in locale lo stesso chart sotto due componenti, dove il nome è condiviso per costruzione, e copiare in locale un chart che non hai scritto tu, il cui nome non puoi cambiare.

L’unica cosa che puoi osservare. Un template che legge il nome del proprio chart — {{ .Chart.Name }}, e tutto ciò che ne deriva, come il comune idioma di denominazione delle risorse {{ .Chart.Name }}-{{ .Release.Name }} — legge l’identità codificata dell’istanza, non il nome scritto nel Chart.yaml del chart di origine. È ciò che un template del genere leggeva già prima che il campo venisse impostato, perché Helm riporta un sotto-chart sotto l’alias con cui il suo genitore lo lega; impostare il campo fa concordare il file su disco con ciò che il rendering produceva già. Così, per l’esempio svolto più sotto, un template nel sotto-chart api-east legge api-east.

Se il nome di una risorsa deve portare il nome scritto dall’autore del chart, metti quel nome nel values.yaml del chart e leggilo da lì — un valore è tuo e Aggrega non lo tocca.

Come viene derivato un nome

Il nome di un chart Helm e l’alias di una dipendenza Helm accettano ciascuno un insieme di caratteri più ristretto di quello che possono contenere un nome di aggregato, un percorso di confine o un instance_id. Anziché sostituire un carattere che la destinazione non accetta, la derivazione lo scrive per esteso, così due identità che differiscono solo per la punteggiatura arrivano sempre a due nomi — e un valore scritto sotto un alias può raggiungere soltanto il sotto-chart che quell’alias nomina.

  • Una lettera, una cifra e un underscore vengono riportati esattamente come scritti.
  • Un trattino viene mantenuto come scritto 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 in quella posizione viene a sua volta scritto per esteso — api-zone diventa api-zhzone, ed è questo che permette di ricondurre qualsiasi nome alla forma originale senza tirare a indovinare.
  • Ogni altro carattere viene scritto come -z seguito da una lettera che lo nomina: d per un punto, s per un separatore di percorso, h per un trattino che la regola precedente non mantiene. Qualsiasi altra cosa 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 — così un nome che non è testo valido viene comunque scritto per esteso in modo distinto anziché essere compresso.
  • Un valore vuoto viene scritto -ze, che nessun valore non vuoto può produrre.
  • Dove due identità compongono un unico nome di chart — un nome di aggregato che qualifica un percorso di assemblaggio — vengono unite da --. Una singola identità codificata non contiene mai quella coppia, quindi il nome unito dice senza ambiguità quale identità è quale.

Così un instance_id data.main-db dà l’alias data-zdmain-db, e l’aggregato fullstack-app con il percorso di assemblaggio boundaries/data/helm-chart dà il nome di chart fullstack-app--boundaries-zsdata-zshelm-chart. Un input identico produce sempre un nome identico.

Il values.yaml dell’ombrello è indicizzato per alias:

api-server: # sub-chart alias = encoded instance_id
image: "registry/api-server:v2"
replicaCount: 3
billing-svc:
image: "registry/billing:v1"
replicaCount: 2

Quando il valuesMapping: di un sotto-chart viene valutato rispetto al suo contesto di template, la mappa di valori risultante popola automaticamente questo sotto-blocco indicizzato per alias. Questo vale per ogni contributore dell’ombrello, non solo per i componenti: un’associazione di Feature che copia in locale un chart è un contributore a pieno titolo, quindi il valuesMapping: della sua FeatureRecipe popola un blocco proprio, indicizzato per il nome che dichiara il suo chart collocato. Vedi «Dove finisce il chart di un’associazione».

Una chiave che il valuesMapping: imposta a null viene scritta nel suo blocco come null. Con un’installazione tramite Helm 4, un null nel values.yaml proprio dell’ombrello rimuove il valore predefinito del sotto-chart per quella chiave solo quando l’installazione fornisce anche valori per quel sotto-chart; un’installazione che non ne fornisce alcuno scarta il null, e il valore predefinito del sotto-chart resta valido. Un null nei valori passati a helm install rimuove il valore predefinito in entrambi i casi.

Particolarità specifiche del Provider

  • Il Chart.yaml del sotto-chart è obbligatorio. L’operazione di copia richiede che sia presente un Chart.yaml nella radice del percorso di origine. La sua assenza arresta la build prima che venga eseguito il passaggio dell’ombrello.
  • Il name del chart collocato spetta all’ombrello. Viene impostato sull’identità codificata di ciò che ha contribuito il chart — l’identità propria di un’istanza di componente oppure, per un chart portato da un’associazione di Feature, l’identità propria di quell’associazione — ed è l’unica cosa che Aggrega modifica all’interno di un chart copiato in locale. Vedi «Il nome del chart che spetta al chart ombrello».
  • Un chart di origine deve dichiarare una versione e un nome. La versione della voce di dipendenza è quella dichiarata dal Chart.yaml proprio del chart di origine, quindi un chart che non dichiara alcuna versione arresta la build anziché riceverne una — una dipendenza fissata a una versione che il sotto-chart non porta lascerebbe i valori per istanza dell’ombrello senza modo di raggiungerlo. Un chart il cui Chart.yaml non dichiara alcun nome, contiene più di un documento YAML o non è analizzabile arresta la build per lo stesso motivo: l’ombrello non può comporre un sotto-chart che non riesce a leggere.
  • Alias e nomi di chart codificati. Un instance_id, un nome di aggregato o un percorso di confine che contiene un carattere che il nome di un chart Helm o l’alias di una dipendenza non accetta compare codificato nell’ombrello renderizzato, secondo «Come viene derivato un nome» più sopra. Un’identità composta solo da lettere, cifre, underscore e trattini che la derivazione mantiene compare esattamente come scritta.
  • Puntatore di repository file://. Le voci di dipendenza dell’ombrello usano un puntatore di repository file:// che nomina la directory propria del chart figlio — file://charts/<instance_id> per un componente, e la directory propria dell’associazione per un chart portato da una Feature. È la convenzione del filesystem locale per i chart figli interni all’albero e consente a helm dependency build di risolvere l’ombrello senza chiamate a registry esterni. Il puntatore nomina una posizione e mai il nome dichiarato del chart; i due differiscono per un’associazione, e helm dependency build è il passaggio che rifiuta un puntatore che nomina una directory che non esiste.
  • Nessun rendering di template a livello di helm-chart. Il provider non invoca la pipeline di rendering dell’SDK di Helm; copia e compone. Gli autori che hanno bisogno di manifest piatti pre-renderizzati dovrebbero usare invece la modalità con sorgente del provider helm.

Esempio svolto

Un confine a due nodi, ciascun nodo legato a una Recipe helm-chart che punta allo stesso chart di origine:

# Recipe — used by both `api-east` and `api-west` instances
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helmchart
version: 1.0.0
spec:
capability: helm-chart
implements: core/api-server
source: ./charts/api-server
valuesMapping: |
image: "{{ .values.image }}"
replicaCount: {{ optional .infra `replicas` 2 }}

Dopo la composizione, il percorso di assemblaggio valutato del confine (per impostazione predefinita dist/<boundary-directory>/<capability>/, perché subDirectory: ha come valore predefinito {{ .capability }}) contiene:

dist/<boundary-directory>/helm-chart/
├── Chart.yaml # umbrella; lists api-east and api-west as dependencies
├── values.yaml # alias-keyed: api-east + api-west values blocks
└── charts/
├── api-east/ # ./charts/api-server, name: api-east
│ ├── Chart.yaml
│ ├── values.yaml
│ └── templates/
│ └── deployment.yaml
└── api-west/ # ./charts/api-server, name: api-west
├── Chart.yaml
├── values.yaml
└── templates/
└── deployment.yaml

Entrambi i sotto-chart sono copie dell’unico chart di origine, e ciascuno porta il nome della propria istanza nel suo Chart.yaml — ed è questo che permette di copiare in locale lo stesso chart due volte in un unico ombrello. Tutto il resto in entrambe le copie è identico all’origine.

Un helm install <release-name> dist/<boundary-directory>/helm-chart su questa struttura installa entrambe le istanze come un’unica release Helm, con i valori dell’ombrello indicizzati per alias che guidano i template di ciascun sotto-chart.

Riferimenti incrociati