Helm-Chart-Provider
Der helm-chart-Provider erzeugt pro Zusammensetzungspfad ein gepacktes Helm-Umbrella-Chart. Wo der helm-Provider flaches Kubernetes-YAML für die direkte Nutzung per GitOps ausgibt, gibt helm-chart ein Chart-Gerüst aus — eine Chart.yaml + values.yaml des Umbrella-Charts plus ein Sub-Chart pro beitragendem Knoten —, das nachgelagerte Werkzeuge über helm install installieren oder zur weiteren umgebungsspezifischen Anpassung lokal kopieren (Vendoring) können. Der Provider setzt pro (path, provider) zusammen: Jeder an ein helm-chart-Recipe gebundene Knoten trägt zum Umbrella-Chart am ausgewerteten directory: der Boundary bei, verbunden mit dem subDirectory: der jeweiligen Komponente. Zwei Boundaries, die zum selben Pfad ausgewertet werden, fallen in ein einziges zusammengeführtes Umbrella-Chart zusammen, das jeden Beitragenden als Sub-Chart-Abhängigkeit auflistet.
Die aus dem Quell-Chart kopierten Templates eines Sub-Charts tragen, was ihr Autor geschrieben hat: Der Wert syncWave: <integer> der Boundary, das helm.sh/hook-weight an einem Hook und die Provenienz-Labels von Aggrega erreichen sie nur dort, wo das Chart sie schreibt. Der helm-Provider ist derjenige, der argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" und die Provenienz-Labels auf jede Ressource stempelt, die er rendert. Ein per $import: geladenes Artefakt, das dieser Provider einem Sub-Chart hinzufügt, trägt die Provenienz-Labels und die Annotation argocd.argoproj.io/sync-wave und kein helm.sh/hook-weight (siehe „Injektionsregel für artifacts:“ unten). ArgoCD liest die sync-wave-Annotation, und Helm liest das Gewicht eines Hooks.
Diese Seite ist die Authoring-Referenz des helm-chart-Providers. Zur Aufteilung zwischen helm und helm-chart siehe den Abschnitt Providers der Statusseite; zum providerübergreifenden Modell der Eingabezusammensetzung siehe architecture/16-recipe-input-composition.md.
Unterstützte Eingabearten
Der helm-chart-Provider akzeptiert zwei Eingabearten:
- Quellbasierter Modus. Ein Recipe mit
source: <chart-path>zeigt auf ein Helm-Chart-Verzeichnis auf der Festplatte. Das Chart wird als Sub-Chart in die Umbrella-Struktur kopiert, unverändert bis auf das eigenenamedes Charts — siehe „Der Chart-Name, der dem Umbrella-Chart gehört“; auf Ebene der einzelnen Knoten findet kein Rendern und keine Template-Verarbeitung statt. Die Rolle von Aggrega ist Komposition (Umbrella-Zusammensetzung über die Knoten der Boundary hinweg), nicht Template-Auswertung. - Modus
artifacts:mit Laden über$import:. Ein Recipe mit Einträgen inartifacts:, die pro Eintrag als$import:verfasst sind, deklariert zusätzliche Template-Dateien, die der helm-chart-Provider nach dem Kopieren des Quell-Charts in das Verzeichnistemplates/des Sub-Charts einfügt. Jede Datei wird mit den Delimitern[[ ]]gegen den Template-Kontext von Aggrega vorab als Template verarbeitet (siehe „Injektionsregel fürartifacts:“ unten), sodass jegliches Helm-Templating{{ }}in derselben Datei bis zum nachgelagerten Rendern durchhelm installerhalten bleibt.
Ein Recipe, das auf helm-chart abzielt und workload: deklariert, wird abgelehnt, bevor es rendert, mit der Ablehnung, die jeder Provider für eine Eingabeart gibt, die er nicht deklariert — sie nennt die Art, die dieser Provider unterstützt, und verweist den Autor auf einen Provider, der synthetisiert:
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 (der Provider unterstützt die Eingabeart des Knotens nicht (Knoten “api”). Der Provider “helm-chart” unterstützt keine synthetisierten Recipes (dieser Provider unterstützt: quellbasiert); deklarieren Sie eine der unterstützten Eingabearten oder zielen Sie auf einen Provider ab, der die synthetisierte Art unterstützt)
Die Aufteilung ist beabsichtigt: Die Synthese von Arbeitslasten (das Übersetzen einer abstrakten Workload in Kubernetes-Ressourcen) ist ausschließlich Sache des helm-Providers. Die Rolle von helm-chart ist die Komposition aus Umbrella-Chart und Sub-Charts für Charts, die der Autor bereits erstellt hat.
Ein Recipe, das auf helm-chart abzielt, kann auch Einträge in artifacts: mit Inline-Inhalt deklarieren (Einträge, deren Wert ein Block-Skalar ist, der den Dateikörper inline im Recipe trägt, statt eines per $import: geladenen Verweises). Ein Eintrag mit Inline-Inhalt wird im Root des Sub-Charts unter seinem verfassten Schlüssel abgelegt — kein Präfix templates/ und kein Einfügen von Provenienz. Die eigenen Templates eines Charts lesen eine solche lose Datei über Helms .Files.Get / .Files.Glob (das kanonische ConfigMap-aus-Dateien-Muster), sodass eine Datei im Chart-Root eine legitime, vollwertige Form ist und kein Fehler.
Beide Formen werden vor dem Ablegen mit den Aggrega-Delimitern [[ ]] ausgewertet, sodass ein Körper jeder der beiden Formen den Säulen-Kontext des Recipe lesen kann; {{ }} in beiden Körpern bleibt unangetastet und wird zum Zeitpunkt des nachgelagerten helm install zu einer Helm-Direktive. Was sich zwischen den Formen unterscheidet, ist, wo die Datei landet und ob Provenienz in sie eingemischt wird:
- Ein per
$import:geladener Eintrag ist eine Template-Datei: Nach der Auswertung (siehe „Injektionsregel fürartifacts:“ unten) wird er mit eingemischter Provenienz in das Verzeichnistemplates/des Sub-Charts eingefügt, sodass Helm ihn als Manifest neben den eigenen Templates des Charts rendert. - Ein Eintrag mit Inline-Inhalt ist eine lose Datendatei: Nach der Auswertung landet er im Chart-Root, unverändert gegenüber dem, was die Auswertung erzeugt hat, und ohne eingemischte Provenienz, für die Nutzung über
.Files.
Injektionsregel für artifacts:
Wenn ein helm-chart-Recipe Einträge in artifacts: über $import: pro Eintrag deklariert, ist jeder Wert von $import: ein Pfad zu einer Template-Datei, der relativ zum eigenen Verzeichnis des Recipe aufgelöst wird (dem Verzeichnis, das die YAML-Datei des Recipe auf der Festplatte enthält). Der Provider:
- Liest den Inhalt jeder Datei.
- Verarbeitet den Inhalt vorab als Template mit den Aggrega-Delimitern
[[ ]]gegen den Template-Kontext des Recipe (denselben Kontext, gegen den dasvaluesMapping:des Recipe ausgewertet wird).{{ }}im Dateiinhalt bleibt unangetastet — daraus werden zum Zeitpunkt vonhelm installHelm-Template-Direktiven. - Schreibt jede Datei nach
charts/<instance-id>/templates/<authored-key>unterhalb des Zusammensetzungspfads des Umbrella-Charts, wobei die Dateien eines Bundles unter diesem Schlüssel verschachtelt sind. Der Schlüssel, unter dem der Eintrag verfasst ist, benennt die Datei; der Pfad von$import:wählt ihren Inhalt aus und trägt nichts zum Namen bei, sodass die Verzeichnisstruktur innerhalb dieses Pfads nie die Ausgabe erreicht.
Die Disziplin der doppelten Delimiter [[ ]] / {{ }} ist das tragende Detail. Eine typische per $import: geladene Artefaktdatei kann Interpolation zur Aggrega-Zeit (z. B. [[ .values.image ]]) mit Interpolation zur Helm-Zeit (z. B. {{ .Release.Namespace }}) mischen. Jedes Delimiterpaar greift in seiner eigenen Phase: Aggrega löst [[ ]] zur Kompilierzeit auf, bevor die Datei abgelegt wird; Helm löst {{ }} zur Installationszeit auf, nachdem das Umbrella-Chart ausgeliefert ist.
Dateinamenkollisionen zwischen den Templates des Quell-Charts und den per $import: geladenen Artefakt-Injektionen lösen CATALOG_ERROR aus — die Diagnose nennt den kollidierenden Ausgabepfad, etwa templates/cm.yaml, und die beiden Eingabearten, die ihn erzeugt haben. Autoren lösen die Kollision, indem sie den Schlüssel des Artefakts oder das eigene Template des Charts umbenennen.
Schlüsselsatz von source:
Das source: des helm-chart-Providers benennt ein Chart, und es akzeptiert beide Formen, die das Feld source: annimmt, gelesen genau so, wie es der Schlüsselsatz von source: des helm-Providers beschreibt: einen reinen Dateisystempfad als String und ein strukturiertes Objekt, dessen url: den Ort trägt. Wo url: einen Dateisystempfad nennt, wird nichts abgerufen und das Chart von der Festplatte gelesen; wo es ein Transportschema trägt — zum Beispiel oci://… mit kind: helm-oci-chart —, ruft aggrega pull das Chart ab und fixiert es, und der Build kopiert es aus dem Cache als Sub-Chart in das Umbrella-Chart, zu denselben Bedingungen wie ein von der Festplatte gelesenes Chart.
spec: capability: helm-chart source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Das Chart am Quellpfad muss in seinem Root eine gültige Chart.yaml enthalten; fehlt sie, erscheint ein klarer Fehler, bevor das Kopieren läuft. Die Verzeichnisstruktur des Charts bleibt beim Kopieren erhalten — templates/, values.yaml, Chart.yaml und alle anderen Dateien sind nach der Komposition im Sub-Chart-Verzeichnis vorhanden. Jede Datei kommt mit den Bytes an, die Sie geschrieben haben, bis hin zu Kommentaren, Schlüsselreihenfolge und Anführungszeichen; die einzige Ausnahme ist das Feld name der eigenen Chart.yaml des Charts, das das Umbrella-Chart setzt — siehe „Der Chart-Name, der dem Umbrella-Chart gehört“.
Beide Arten, kein Chart zu benennen, werden abgelehnt, und die beiden Ablehnungen kommen von verschiedenen Stellen — das ist wissenswert, weil sich nur eine davon ändert, wenn Sie die Fähigkeit wechseln. Ein source:, das vorhanden ist und dennoch nichts deklariert, wird vom Compiler abgelehnt, bevor irgendein Provider läuft, sodass das Ergebnis dasselbe ist, welche Fähigkeit das Recipe auch nennt; die Diagnose fordert Sie auf, das Feld für den Modus ohne Quelle wegzulassen oder einen nicht leeren Pfad zu nennen. source: ganz wegzulassen ist zulässiges Authoring — so fordert ein Recipe den Modus ohne Quelle an — und wird hier abgelehnt, weil helm-chart nur die quellbasierte Eingabeart deklariert, sodass der Compiler die Kombination mit derselben Meldung ablehnt, die er für jede Fähigkeit gibt, die für eine Eingabeart angefordert wird, die sie nicht deklariert. Was helm-chart selbst gehört, ist die Deklaration, keine eigene Ablehnung: Für Kubernetes-Ressourcen, die aus einem Block workload: erzeugt werden, verwenden Sie stattdessen die Fähigkeit helm.
Ein Recipe, das omits: deklariert, wird abgelehnt. Der Schlüssel omits: lässt Dokumente, die eine Quelle rendert, aus dem Build heraus, und dieser Provider rendert zur Build-Zeit kein Dokument: Er kopiert das Chart in das Umbrella-Chart, und die Templates des Charts werden gerendert, wenn das Umbrella-Chart installiert wird. Wo nichts gerendert wird, gibt es nichts auszulassen, daher deklariert dieser Provider nicht, dass er den Schlüssel berücksichtigt, und ein Recipe oder FeatureRecipe, das ihn deklariert, wird abgelehnt, bevor irgendetwas kopiert wird — siehe The provider does not support omits (Der Provider unterstützt omits nicht). Für ein Chart, das Sie neben dem Recipe aufbewahren, lässt stattdessen eine Zeile in der dortigen .aggregaignore eine Datei des Charts weg, ab dem nächsten Mal, wenn das Recipe fixiert wird; für ein abgerufenes Chart, dessen Ausgabe ein Dokument verlieren muss, rendern Sie es über den Provider helm, der den Schlüssel berücksichtigt.
Pfadbasierte Komposition — die Umbrella-Form
Der Provider läuft pro Zusammensetzungspfad in zwei Phasen:
- Kopie pro Beitragendem. Für jeden an ein helm-chart-Recipe gebundenen Knoten kopiert der Provider den vollständigen Verzeichnisbaum des Quell-Charts in einen Sub-Chart-Slot. Dateien landen flach in der Ausgabe-Map pro Beitragendem; der Assembler nennt
chartsals das Unterverzeichnis, unter dem seine Beitragenden liegen, und der Orchestrator gibt jedem Beitragenden dort beim Zusammensetzen des Umbrella-Charts ein eigenes Verzeichnis —charts/<instance_id>/für eine Komponente. Eine Feature-Anbindung ist ebenfalls ein Beitragender — ob sie ein Chart lokal kopiert oder Manifeste über den helm-Provider rendert — und erhält ein Verzeichnis neben dem der Komponente statt darin; siehe „Wo das Chart einer Anbindung landet“. - Umbrella-Zusammensetzung pro
(path, provider). Sobald alle Kopien pro Knoten für den Pfad abgeschlossen sind, gibt der Assembler am Root des Zusammensetzungspfads eineChart.yaml+values.yamldes Umbrella-Charts aus. Das Umbrella-Chart deklariert eine Abhängigkeit pro beitragendem Knoten und leitet die Werte pro Knoten in nach instance-id geschlüsselte Unterblöcke. Wenn der Zusammensetzungspfad Beitragende aus mehr als einer Boundary erhält (Boundaries mit gemeinsamemdirectory:), landet jeder Beitragende als Abhängigkeit im selben Umbrella-Chart.
Die Chart.yaml des Umbrella-Charts hat folgende Form:
apiVersion: v2name: <effective-chart-name> # see "Chart-name resolution" belowversion: 0.1.0description: 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 directoryAuflösung des Chart-Namens
Der name des Umbrella-Charts wird über die Annotationskaskade der Boundaries aufgelöst. Die effektive Annotation aggrega.ai/chart-name jeder beitragenden Boundary (der durch die Kaskade aufgelöste Wert, beim Aufstieg durch den Boundary-Baum) bestimmt den Umbrella-Namen; der aufgelöste Wert wird für die Chart-Namensposition genau wie jede andere Identität codiert, sodass ein Wert, der nur Buchstaben, Ziffern, Unterstriche und Bindestriche enthält, die die Regel unten beibehält, das Chart unverändert erreicht. Wenn der Zusammensetzungspfad Beitragende aus mehr als einer Boundary erhält, MUSS die effektive Annotation aggrega.ai/chart-name jedes Beitragenden zum selben Wert aufgelöst werden; Abweichungen brechen den Build mit einer Diagnose ab, die die widersprüchlichen Werte und die beitragenden Boundaries nennt.
Die Kaskade löst die DRY-Spannung auf natürliche Weise: Deklarieren Sie aggrega.ai/chart-name einmal an der übergeordneten Boundary, und untergeordnete Boundaries erben es über die Kaskade; Geschwister-Boundaries ohne gemeinsame übergeordnete Boundary müssen übereinstimmende Werte explizit deklarieren. Boundaries, für die nirgends in ihrer Kaskade aggrega.ai/chart-name deklariert ist, fallen auf den Aggregatnamen und den Zusammensetzungspfad zurück — das Ausgabeverzeichnis des Umbrella-Charts unter dist/, etwa boundaries/data/helm-chart —, die jeweils wie unten beschrieben codiert und verbunden werden.
Der name jedes Abhängigkeitseintrags ist der Name, den das platzierte Sub-Chart trägt — die eigene codierte Identität der Komponenteninstanz, derselbe Wert wie der alias — aus den Gründen in „Der Chart-Name, der dem Umbrella-Chart gehört“. Seine version ist weiterhin die Version aus der eigenen Chart.yaml des Quell-Charts. Der Alias ordnet die Werte des Sub-Charts unter values.yaml.<alias>.* ein, entsprechend Helms Konvention für Umbrella-Werte, sodass sich Werte pro Instanz korrekt fortpflanzen, wenn das Umbrella-Chart installiert wird.
Das Sub-Chart-Verzeichnis einer Komponente behält die instance_id genau so bei, wie sie verfasst wurde, sodass charts/<instance_id>/ der Ort ist, an dem ihre Dateien landen, und das, worauf das repository der Abhängigkeit zeigt. Zwei Instanzen desselben Quell-Charts bestehen daher ohne Dateisystemkollision nebeneinander, und jede behält ihren eigenen Werteblock unter ihrem eigenen Alias.
Der name der Abhängigkeit und ihr repository sind unterschiedliche Strings, und das ist beabsichtigt. name ist das, was das Chart an diesem Ort DEKLARIERT, weil Helm eine Abhängigkeit über den eigenen deklarierten Namen des Kind-Charts an dieses bindet; repository ist der Ort, an dem dieses Chart liegt. Bei einer Komponente lesen sich beide zufällig gleich, da beide aus derselben Instanz-ID abgeleitet sind. Bei einer Feature-Anbindung unterscheiden sie sich — der deklarierte Name trägt die zusammengesetzte Identität der Anbindung, während das Verzeichnis ihre beiden Koordinaten verbunden trägt —, sodass das Lesen des einen als das andere etwas benennt, das nicht da ist.
Wo das Chart einer Anbindung landet
Eine Feature-Anbindung, die ein Chart lokal kopiert, erhält ein eigenes Verzeichnis neben der Komponente, an die sie angebunden ist, eine Ebene unter 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 componentEin an eine Boundary statt an eine Komponente angebundenes Feature hat keine Host-Komponente zu benennen, daher ist sein Verzeichnis allein sein Instanzname: charts/aux/.
Warum daneben statt darin. Helm erkennt ein Kind-Chart unter charts/* — eine Ebene, kein rekursiver Durchlauf. Ein tiefer platziertes Chart ist kein Kind von irgendetwas; es sind Daten im Verzeichnis eines anderen Kindes, nur über .Files erreichbar. Ein im eigenen Chart-Verzeichnis der Komponente platziertes Chart würde also in die Ausgabe kopiert, ließe den Build gelingen und trüge keine seiner Ressourcen zu dem bei, was Sie bereitstellen — ohne dass irgendetwas es meldet. Jeden Beitragenden in seinem eigenen Verzeichnis auf oberster Ebene zu platzieren ist das, was die Ressourcen der Anbindung rendern lässt.
Das Umbrella-Chart deklariert die Anbindung außerdem als eine seiner Abhängigkeiten. Beide Hälften sind nötig: Ein Chart, das unter charts/ vorhanden ist und in dependencies: fehlt, ist ein Lint-Fehler, und ein in dependencies: deklariertes Chart ohne passendes vorhandenes Kind-Chart führt dazu, dass das Umbrella-Chart das Laden verweigert.
Die beiden Koordinaten werden verbunden, nicht aneinandergehängt. Ein Verzeichnisname wird aus dem Host und der Instanz über dieselbe unten beschriebene Escape-Regel gebildet, die auf jede Koordinate angewendet wird, bevor sie über -- verbunden werden. Sie direkt über -- aneinanderzureihen wäre mehrdeutig: Ein Host namens a--b mit einer Instanz c und ein Host a mit einer Instanz b--c würden dasselbe Verzeichnis erreichen. Jede Koordinate zuerst zu codieren hält sie auseinander, sodass ein verfasstes -- innerhalb einer Koordinate als -zh- erscheint.
Was der Verzeichnisname zulässt. ASCII-Buchstaben in beiden Schreibweisen, Ziffern, der Punkt und der Unterstrich werden so durchgereicht, wie Sie sie geschrieben haben, sodass sich API--aux und web.api--aux so lesen, wie Sie es erwarten würden. Ein von Ihnen geschriebener Bindestrich bleibt überall erhalten, wo das Zeichen danach eines dieser Zeichen ist, sodass web-api--aux unverändert bleibt; ein doppelter Bindestrich wird maskiert, weil das Paar die Verbindungsstelle ist. Alles andere wird nach derselben Regel maskiert wie ein Chart-Name. Die Menge ist so gezogen, weil diese Verzeichnisnamen sowohl Pfade auf der Festplatte als auch der Ort sind, den der Zeiger file:// einer Abhängigkeit auflöst, und ein Zeichen, das in einem Dateinamen unproblematisch ist, eine URL abschneiden oder neu decodieren lassen kann.
Werte folgen dem deklarierten Namen, nicht dem Verzeichnis. Die Werte eines Kind-Charts werden unter dem Namen eingeordnet, den dieses Chart deklariert, daher werden Werte für das obige Chart über den deklarierten Namen von api--guardrail — cfr-zh-api-zh-guardrail — adressiert statt über sein Verzeichnis.
Sie schreiben diesen Schlüssel nie selbst. Sie schreiben die Werte an die Anbindung, und die values.yaml des Umbrella-Charts wird für Sie zusammengesetzt, mit dem Block bereits an der Adresse, unter der das platzierte Chart adressiert wird. Für ein an eine Komponente angebundenes Feature sind das die values:, die Sie an der Anbindung deklarieren, gelesen vom eigenen valuesMapping: des FeatureRecipe; für ein an eine Boundary angebundenes Feature ist es das infra:, das Sie dort deklarieren, da ein an eine Boundary angebundenes Feature keine Säule der Komponentenwerte hat. Was es auch ist, die Map, zu der valuesMapping: aufgelöst wird, wird zum eigenen Block der Anbindung im Umbrella-Chart:
# the umbrella's values.yaml, composed for youapi: # the component's own chart replicaCount: 3cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought auditEndpoint: "https://audit.internal"Dies ist der einzige Weg, den diese Werte haben. Ein Chart, das ein Feature mitbringt, kommt mit seinen Dateien so an, wie sein Autor sie geschrieben hat — abgesehen von dem einzigen Manifest-Feld, das in „Der Chart-Name, der dem Umbrella-Chart gehört“ beschrieben ist —, daher schreibt nichts Ihre Werte in dieses Chart, und der Block des Umbrella-Charts ist das, was sie liefert. Ein Chart, dessen Block nie angekommen ist, ist kein defektes Chart: Es rendert die Standardwerte, die seine eigene values.yaml mitliefert, und meldet Erfolg; geben Sie daher einem Standardwert einen Wert, der Ihnen auffallen würde, wenn Sie den Unterschied beim Authoring sehen wollen.
Eine Anbindung, deren FeatureRecipe über den helm-Provider rendert
Ein FeatureRecipe der Fähigkeit helm, das an eine Komponente auf diesem Ziel angebunden ist, bringt fertige Kubernetes-Manifeste statt eines Charts mit. Sie landen im eigenen Verzeichnis der Anbindung genau so, wie der helm-Provider sie gerendert hat, und der Provider gibt diesem Verzeichnis die zwei Dinge, die es zu einem Chart machen, das Helm installiert: eine minimale Chart.yaml, die den eigenen Namen der Anbindung in der Version 0.1.0 deklariert, und ein einziges Template, templates/rendered.yaml, das jede gerenderte YAML-Datei über Helms .Files.Get anhand ihres Namens ausgibt:
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" }}Der deklarierte Name ist derjenige, den ein Chart deklarieren würde, das dieselbe Anbindung lokal kopiert hätte, sodass der Abhängigkeitseintrag des Umbrella-Charts und sein Werteblock genau wie oben beschrieben adressiert werden. .Files.Get gibt die Bytes einer Datei unverändert zurück, statt sie ein zweites Mal auszuwerten, sodass ein Manifest mit literalen Template-Klammern — das {{ $labels.instance }} einer Alerting-Regel, die Abfrage eines Dashboards — mit diesen unversehrt installiert wird. Seine Werte wurden in diese Manifeste aufgelöst, als der helm-Provider sie gerendert hat, sodass der Block, den die values.yaml des Umbrella-Charts unter diesem Namen trägt, von nichts gelesen wird.
Der Chart-Name, der dem Umbrella-Chart gehört
Das Einzige, was Aggrega in einem Chart ändert, das Sie lokal kopiert haben, ist das eigene Feld name dieses Charts. In der Chart.yaml des platzierten Charts wird name auf die codierte Identität dessen gesetzt, was dieses Chart beigetragen hat.
Bei einer Komponente ist das die eigene Identität der Komponenteninstanz — derselbe Wert wie der alias der Abhängigkeit —, und der Abhängigkeitseintrag des Umbrella-Charts nennt ebenfalls diesen Wert, sodass beide Seiten immer übereinstimmen.
Ein Chart, das eine Feature-Anbindung mitbringt, ist ein eigenständiger Beitragender und deklariert seine eigene Identität, statt die Identität der Komponente zu wiederholen, an die es angebunden ist. Diese Identität wird aus zwei Dingen zusammengesetzt, die Sie geschrieben haben — der Komponente, die die Anbindung beherbergt, und dem Namen, unter dem das Feature angebunden ist —, hinter einem kurzen Präfix, das sie als Identität einer Anbindung statt einer Komponente kennzeichnet; der zusammengesetzte Wert wird dann über die unten beschriebene Ableitung für die Position des Chart-Namens geschrieben, genau wie jede andere Identität.
Wird also ein Feature, das ein Chart lokal kopiert, unter dem Namen guardrail an eine Komponente namens api angebunden, wird ein Chart platziert, das cfr-zh-api-zh-guardrail deklariert, während das eigene Chart dieser Komponente weiterhin api deklariert. Die beiden sind getrennte Beitragende, und jedes deklariert einen eigenen Namen, statt dass beide den des Hosts deklarieren.
Nichts anderes im Chart wird angetastet. Jede andere Datei kommt Byte für Byte so an, wie Sie sie geschrieben haben, und innerhalb von Chart.yaml sind jedes andere Feld, jeder Kommentar, die Schlüsselreihenfolge und die Anführungszeichen genau wie verfasst. Ein Schlüssel, der an anderer Stelle im Manifest verschachtelt ist und zufällig ebenfalls name heißt — etwa der Name eines Maintainers —, bleibt unberührt.
Warum das Umbrella-Chart dieses Feld braucht. Der name eines Charts ist das, woran Helm eine Abhängigkeit des Umbrella-Charts bindet. Er wird von demjenigen geschrieben, der das Chart verfasst hat, und das ist bei einem von Upstream bezogenen Chart nicht die Person, die es bereitstellt — daher können zwei Komponenten in einem Zusammensetzungspfad ganz vernünftigerweise Charts lokal kopieren, deren Manifeste denselben Namen deklarieren. Behielten beide Sub-Charts diesen gemeinsamen Namen, würden beide Abhängigkeiten des Umbrella-Charts zu demjenigen der beiden aufgelöst, das Helm zuerst geladen hat: Das Chart der einen Komponente würde zweimal gerendert und das der anderen gar nicht, während die Werte jeder Komponente dennoch ankämen, sodass die Ausgabe vollständig aussähe und falsch wäre. Den Namen des platzierten Charts aus der Komponenteninstanz abzuleiten, beseitigt den gemeinsamen Namen ganz, weshalb nichts abgelehnt werden muss — einschließlich der beiden Fälle, für die es keine andere Abhilfe gibt: dasselbe Chart unter zwei Komponenten lokal kopieren, wo der Name konstruktionsbedingt geteilt ist, und ein Chart lokal kopieren, das Sie nicht geschrieben haben, dessen Namen Sie nicht ändern können.
Das Einzige, was Sie beobachten können. Ein Template, das den Namen seines eigenen Charts liest — {{ .Chart.Name }} und alles daraus Abgeleitete, etwa das verbreitete Idiom zur Ressourcenbenennung {{ .Chart.Name }}-{{ .Release.Name }} —, liest die codierte Instanzidentität, nicht den Namen, der in der Chart.yaml des Quell-Charts steht. Das ist es, was ein solches Template bereits gelesen hat, bevor das Feld gesetzt wurde, denn Helm meldet ein Sub-Chart unter dem Alias, über den sein übergeordnetes Chart es bindet; das Setzen des Feldes bringt die Datei auf der Festplatte in Übereinstimmung mit dem, was das Rendern bereits erzeugt hat. Für das ausgearbeitete Beispiel unten liest ein Template im Sub-Chart api-east also api-east.
Wenn ein Ressourcenname den verfassten Namen des Charts tragen muss, legen Sie diesen Namen in der values.yaml des Charts ab und lesen Sie ihn von dort — ein Wert gehört Ihnen, und Aggrega rührt ihn nicht an.
Wie ein Name abgeleitet wird
Ein Helm-Chart-Name und ein Helm-Abhängigkeitsalias akzeptieren jeweils eine engere Zeichenmenge, als ein Aggregatname, ein Boundary-Pfad oder eine instance_id enthalten kann. Statt ein Zeichen zu ersetzen, das das Ziel nicht akzeptiert, schreibt die Ableitung es aus, sodass zwei Identitäten, die sich nur in der Interpunktion unterscheiden, immer bei zwei Namen ankommen — und ein unter einem Alias geschriebener Wert immer nur das Sub-Chart erreichen kann, das dieser Alias benennt.
- Ein Buchstabe, eine Ziffer und ein Unterstrich werden genau wie verfasst übernommen.
- Ein Bindestrich bleibt wie verfasst erhalten, wo immer das Zeichen nach ihm direkt übernommen wird und kein kleines
zist. Ein Bindestrich, auf den ein kleineszfolgt, leitet ein Escape ein, sodass ein an dieser Stelle verfasster Bindestrich selbst ausgeschrieben wird — ausapi-zonewirdapi-zhzone, und genau das erlaubt es, jeden Namen ohne Raten zurückzulesen. - Jedes andere Zeichen wird als
-zgeschrieben, gefolgt von einem Buchstaben, der es benennt:dfür einen Punkt,sfür ein Pfadtrennzeichen,hfür einen Bindestrich, den die obige Regel nicht beibehält. Alles andere wird alsxund der sechsstellige hexadezimale Codepunkt des Zeichens geschrieben, und ein Byte, das überhaupt kein Zeichen beginnt, alsbund sein eigener zweistelliger Wert — sodass ein Name, der kein gültiger Text ist, dennoch unterscheidbar ausgeschrieben statt zusammengelegt wird. - Ein leerer Wert wird als
-zegeschrieben, was kein nicht leerer Wert erzeugen kann. - Wo zwei Identitäten einen Chart-Namen bilden — ein Aggregatname, der einen Zusammensetzungspfad qualifiziert —, werden sie durch
--verbunden. Eine einzelne codierte Identität enthält dieses Paar nie, sodass der verbundene Name eindeutig angibt, welche Identität welche ist.
Eine instance_id data.main-db ergibt also den Alias data-zdmain-db, und das Aggregat fullstack-app mit dem Zusammensetzungspfad boundaries/data/helm-chart ergibt den Chart-Namen fullstack-app--boundaries-zsdata-zshelm-chart. Identische Eingabe erzeugt immer den identischen Namen.
Die values.yaml des Umbrella-Charts ist nach Alias geschlüsselt:
api-server: # sub-chart alias = encoded instance_id image: "registry/api-server:v2" replicaCount: 3billing-svc: image: "registry/billing:v1" replicaCount: 2Wenn das valuesMapping: eines Sub-Charts gegen seinen Template-Kontext ausgewertet wird, befüllt die resultierende Werte-Map diesen nach Alias geschlüsselten Unterblock automatisch. Das gilt für jeden Beitragenden zum Umbrella-Chart, nicht nur für Komponenten: Eine Feature-Anbindung, die ein Chart lokal kopiert, ist ein eigenständiger Beitragender, sodass das valuesMapping: ihres FeatureRecipe einen eigenen Block befüllt, geschlüsselt nach dem Namen, den ihr platziertes Chart deklariert. Siehe „Wo das Chart einer Anbindung landet“.
Ein Schlüssel, den das valuesMapping: auf null setzt, wird als null in seinen Block geschrieben. Bei einer Installation mit Helm 4 entfernt ein null in der eigenen values.yaml des Umbrella-Charts den Standardwert des Sub-Charts für diesen Schlüssel nur dann, wenn die Installation auch Werte für dieses Sub-Chart liefert; eine Installation, die keine dafür liefert, verwirft das null, und der Standardwert des Sub-Charts bleibt bestehen. Ein null in den an helm install übergebenen Werten entfernt den Standardwert in jedem Fall.
Provider-spezifische Besonderheiten
- Die
Chart.yamldes Sub-Charts ist erforderlich. Der Kopiervorgang setzt eine vorhandeneChart.yamlim Root des Quellpfads voraus. Fehlt sie, bricht der Build ab, bevor der Umbrella-Schritt läuft. - Der
namedes platzierten Charts gehört dem Umbrella-Chart. Er wird auf die codierte Identität dessen gesetzt, was das Chart beigetragen hat — die eigene Identität einer Komponenteninstanz oder, bei einem Chart, das eine Feature-Anbindung mitbringt, die eigene Identität dieser Anbindung —, und er ist das Einzige in einem lokal kopierten Chart, das Aggrega ändert. Siehe „Der Chart-Name, der dem Umbrella-Chart gehört“. - Ein Quell-Chart muss eine Version und einen Namen deklarieren. Die Version des Abhängigkeitseintrags ist diejenige, die die eigene
Chart.yamldes Quell-Charts deklariert, sodass ein Chart, das keine Version deklariert, den Build abbricht, statt eine zu erhalten — eine Abhängigkeit, die auf eine Version fixiert ist, die das Sub-Chart nicht trägt, würde die instanzspezifischen Werte des Umbrella-Charts daran hindern, es zu erreichen. Ein Chart, dessenChart.yamlkeinen Namen deklariert, mehr als ein YAML-Dokument enthält oder sich nicht parsen lässt, bricht den Build aus demselben Grund ab: Das Umbrella-Chart kann kein Sub-Chart zusammensetzen, das es nicht lesen kann. - Codierte Aliase und Chart-Namen. Eine instance_id, ein Aggregatname oder ein Boundary-Pfad mit einem Zeichen, das ein Helm-Chart-Name oder ein Abhängigkeitsalias nicht akzeptiert, erscheint im gerenderten Umbrella-Chart codiert, gemäß „Wie ein Name abgeleitet wird“ oben. Eine Identität, die nur aus Buchstaben, Ziffern, Unterstrichen und Bindestrichen besteht, die die Ableitung beibehält, erscheint genau wie verfasst.
- Repository-Zeiger
file://. Die Abhängigkeitseinträge des Umbrella-Charts verwenden einen Repository-Zeigerfile://, der das eigene Verzeichnis des Kind-Charts benennt —file://charts/<instance_id>für eine Komponente und das eigene Verzeichnis der Anbindung für ein Chart, das ein Feature mitbringt. Das ist die Konvention des lokalen Dateisystems für Kind-Charts im selben Baum und ermöglicht eshelm dependency build, das Umbrella-Chart ohne Aufrufe externer Registries aufzulösen. Der Zeiger benennt einen Ort und nie den deklarierten Namen des Charts; die beiden unterscheiden sich bei einer Anbindung, undhelm dependency buildist der Schritt, der einen Zeiger ablehnt, der ein nicht vorhandenes Verzeichnis benennt. - Kein Template-Rendering auf helm-chart-Ebene. Der Provider ruft die Render-Pipeline des Helm-SDK nicht auf; er kopiert und setzt zusammen. Autoren, die vorgerenderte flache Manifeste benötigen, sollten stattdessen den Modus mit Quelle des helm-Providers verwenden.
Ausgearbeitetes Beispiel
Eine Boundary mit zwei Knoten, jeder Knoten an ein helm-chart-Recipe gebunden, das auf dasselbe Quell-Chart zeigt:
# Recipe — used by both `api-east` and `api-west` instancesapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helmchart version: 1.0.0spec: capability: helm-chart implements: core/api-server source: ./charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Nach der Komposition enthält der ausgewertete Zusammensetzungspfad der Boundary (standardmäßig dist/<boundary-directory>/<capability>/, weil subDirectory: standardmäßig {{ .capability }} ist):
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.yamlBeide Sub-Charts sind Kopien des einen Quell-Charts, und jedes trägt den Namen seiner eigenen Instanz in seiner Chart.yaml — genau das erlaubt es, ein Chart zweimal in einem einzigen Umbrella-Chart lokal zu kopieren. Alles andere ist in beiden Kopien mit der Quelle identisch.
Ein helm install <release-name> dist/<boundary-directory>/helm-chart gegen dieses Layout installiert beide Instanzen als ein einziges Helm-Release, wobei die nach Alias geschlüsselten Werte des Umbrella-Charts die Templates jedes Sub-Charts steuern.
Querverweise
providers/helm.md— Schwester-Provider, der flaches gerendertes Kubernetes-YAML statt eines Chart-Gerüsts ausgibt; übernimmt die Synthese von Arbeitslasten.entities/recipe.md— Authoring-Oberfläche des Recipe und die drei Eingabearten.entities/release.md— Boundary-Semantik des Release und Ausgabeverzeichnisse pro Boundary.architecture/16-recipe-input-composition.md— providerübergreifende Provider-Fähigkeitsmatrix.10-status.md#providers— aktuelle Einstufung der Bereitschaft.