Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Helm-Provider

Der helm-Provider erzeugt flaches gerendertes Kubernetes-YAML für GitOps-Konsumenten (ArgoCD, Flux). Der Provider setzt pro (path, provider) zusammen: Das gerenderte YAML jedes auf helm abzielenden Knotens wird an den Assembler geleitet, der nach dem ausgewerteten directory: der Boundary, verbunden mit dem komponentenspezifischen subDirectory:, geschlüsselt ist, und dieser Assembler gibt eine YAML-Datei pro Kubernetes-Ressource aus. Nachgelagerte Werkzeuge vergleichen die Dateien und wenden sie direkt an, ohne einen Helm-Installationsschritt.

Wo der syncWave: <integer> der Boundary nicht 0 ist, trägt jede ausgegebene Kubernetes-Ressource ihn als Annotation argocd.argoproj.io/sync-wave: "<N>"; Helm-Hooks tragen zusätzlich helm.sh/hook-weight: "<N>". ArgoCD liest die sync-wave-Annotation und Helm das Gewicht eines Hooks, und beide ordnen die Ressourcen danach; eine Boundary in der Standardwelle 0 trägt keines von beiden, was beide Werkzeuge als Welle 0 lesen.

Diese Seite ist die Authoring-Referenz des helm-Providers. Zum providerübergreifenden Modell der Eingabezusammensetzung siehe architecture/16-recipe-input-composition.md. Zur Bereitschaft der einzelnen Provider siehe Status der Sprache → Providers.

Unterstützte Eingabearten

Der helm-Provider akzeptiert alle drei Eingabearten des Recipe in unterschiedlichen Rollen:

  • Modus mit Quelle. Ein Recipe mit source: <chart-path> zeigt auf ein Helm-Chart-Verzeichnis auf der Festplatte. Das Helm-Go-SDK lädt das Chart, das Werte-Dictionary des Basis-Renderings wird mit den Standardwerten des Charts zusammengeführt, und die Templates des Charts werden zu flachem Kubernetes-YAML gerendert.
  • Workload-Modus (synthetisiert). Ein Recipe mit workload: (inline oder per $import: geladen) deklariert ein Workload-Dokument. Der Provider synthetisiert direkt aus der Workload-Spezifikation eine oder mehrere Kubernetes-Ressourcen pro Knoten — ein Controller-Objekt, das durch das form der Workload gewählt wird, plus Services pro Service und PVCs pro persistentem Volume; siehe Workload-Modus (synthetisiert).
  • Nur-Artefakte-Modus. Ein Recipe mit artifacts: und weder source: noch workload: gibt die Manifeste aus, die sein Autor geschrieben hat, wobei die Provenienz-Labels und -Annotationen des Builds in die eigenen Metadaten jeder Ressource eingefügt werden.

Die drei lassen sich kombinieren: Ein Recipe kann ein Chart, eine Workload und artifacts: zusammen deklarieren, und jedes davon rendert und wird für sich ausgegeben, nebeneinander in der Ausgabe des Knotens — siehe Was jeder Provider akzeptiert, vollständig.

Schlüsselsatz von source:

Das source: des helm-Providers benennt ein Chart, und es akzeptiert beide Formen, die das Feld source: annimmt: einen reinen Dateisystempfad als String und ein strukturiertes Objekt, dessen url: den Ort trägt. Wo immer dieser Ort ein Dateisystempfad ist, wird er an dem Verzeichnis verankert, das die recipe.yaml enthält, die ihn deklariert, nicht an dem Verzeichnis, aus dem der Build aufgerufen wird, und er muss innerhalb dieses Verzeichnisses bleiben: Ein Pfad, der aus ihm herausführt, oder ein absoluter wird abgelehnt, weil jede Datei, die eine Veröffentlichung des Recipe mitführt, aus seinem Verzeichnis genommen wird — siehe entities/recipe.md „Content paths stay inside the Recipe’s own directory (Inhaltspfade bleiben im eigenen Verzeichnis des Recipe)“. Ein auf diese Weise benanntes Chart wird mit dem Recipe veröffentlicht, mit jeder Datei darunter, die die beim Fixieren des Recipe festgehaltenen Ignore-Regeln behalten — der helm-Provider lässt die Verzeichnisse der Versionskontrolle und die versteckten Dateien unter templates/ des Charts weg und beachtet die eigene .helmignore des Charts, und die .aggregaignore des Autors hat das letzte Wort, wie Welche Dateien mit einer Entität ausgeliefert werden beschreibt —, während eine Datei neben dem Recipe, die nichts von dem benennt, was es deklariert, nicht mitveröffentlicht wird. Das Rendern liest dieselben Dateien, die die Veröffentlichung mitführt, sodass ein Chart aus Ihrem Verzeichnis und aus einer Registry gleich gerendert wird. Die Form, in der Sie es geschrieben haben, ändert daran nichts: Ein strukturiertes source:, dessen url: ./charts/api-server ist, wird genau so verankert wie der reine String ./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 }}

Ein strukturiertes source: sagt dasselbe mit benannten Feldern, und was sein url: trägt, entscheidet, ob etwas abgerufen wird. Wo url: ein Transportschema trägt — oci://… für ein OCI-Chart, ein https://….tgz für ein direktes Chart-Archiv oder ein Repository-Root https:// zusammen mit chart: —, wird das Chart abgerufen: Die Art ergibt sich aus dem URL-Schema oder aus einem expliziten kind:, aggrega pull ruft das Chart ab und fixiert es in der Lockdatei, und der Build entpackt es aus dem Cache. Wo url: einen Dateisystempfad benennt, wird nichts abgerufen und nichts fixiert — das Chart wird von der Festplatte gelesen und genau wie die obige reine String-Form verankert.

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"

Nur url: entscheidet, woher ein Chart gelesen wird. Die anderen Felder wählen aus, was abgerufen würde, sodass sie bei einem Pfad nichts auswählen — sie erreichen die eigenen Templates des Recipe dennoch als .source.*.

Ein Chart lokal zu kopieren (Vendoring) wird als Alternative zum Abrufen unterstützt und ist nicht erforderlich. Das Schema akzeptiert ein offenes strukturiertes Objekt.

Das Chart am Quellpfad muss eine gültige Chart.yaml enthalten. Renderings mit Quelle, die das Chart nicht laden können, geben den zugrunde liegenden Fehler des Helm-SDK wörtlich aus. Ein leeres source: "" ist keine Angelegenheit von helm: Es benennt weder den Modus ohne Quelle noch den Modus mit Quelle, sodass die Ablehnung, die es erhält, dieselbe ist, welchen Provider das Recipe auch anzielt, und sie erfolgt beim Lesen des Recipe, bevor irgendein Chart geladen und bevor an diesen Provider verteilt wird. Welche Befehle sie melden, ist in entities/recipe.md „Source field scheme inventory (Bestandsaufnahme der Schemata des Feldes source)“ und errors/fatal-halts.md „Recipe source: is an empty string (Das Feld source des Recipe ist ein leerer String)“ dargelegt.

Modus mit Quelle

Ein Recipe mit source: <chart-path> und valuesMapping: durchläuft beim Basis-Rendering die folgende Pipeline:

  1. Das Chart unter <chart-path> wird über das Helm-Go-SDK geladen.
  2. Das Template valuesMapping wird gegen den Template-Kontext des Recipe ausgewertet. Seine YAML-Ausgabe wird als Werte-Overlay für das Chart behandelt.
  3. Das Overlay wird einmal mit den Standardwerten aus der values.yaml des Charts zusammengeführt; bei Kollisionen gewinnen die Schlüssel des Overlays (Helms Standardsemantik von helm install --values). Ein Schlüssel, den das Overlay auf null setzt, entfernt den Standardwert des Charts für ihn — auf oberster Ebene, innerhalb einer Tabelle oder in den Werten einer Abhängigkeit —, wie es helm install --values tut, sodass die Templates des Charts den Schlüssel als nicht vorhanden lesen; ein null an einem Schlüssel, dem das Chart keinen Standardwert gibt, erreicht die Templates als null.
  4. Das Helm-SDK rendert die Templates des Charts gegen die zusammengeführten Werte.
  5. Aggrega fügt seine Provenienz-Metadaten per YAML-Umschreibung nach dem Rendern in die gerenderten Manifeste ein und stellt so sicher, dass die Ausgabe mit Quelle dieselbe Kennzeichnung trägt wie die Ausgabe im Workload-Modus. Identitätswerte werden zu Labels (app.kubernetes.io/name, aggrega.ai/component-id, aggrega.ai/provider, aggrega.ai/provider-version, aggrega.ai/environment und — sofern gesetzt — aggrega.ai/aggregate-name, aggrega.ai/compiler-version), jeweils in einer Form geschrieben, die Kubernetes als Label-Wert akzeptiert; Werte, die ein Kubernetes-Label nicht darstellen kann, werden zu Annotationen (aggrega.ai/recipe-uri, aggrega.ai/boundary-path, aggrega.ai/sync-wave, wo die Welle nicht 0 ist, sowie der unveränderte Wert jedes Labels, dessen Wert umgeschrieben werden musste — ein Aggregate namens imported/flow erhält das Label imported-flow und unter demselben Schlüssel die Annotation imported/flow). Die Umschreibungsregel ist in well-known-annotations.md unter „Von Providern ausgegebene Provenienz-Labels“ festgehalten.
  6. Ausgabedateien landen flach im Ausgabeverzeichnis des Recipe, eine pro gerenderter Ressource, benannt <name-basis>-<kind>[-<namespace>]-<name>.yaml — dieselbe Basis, aus der der unten beschriebene Release-Name abgeleitet wird, gefolgt von der eigenen Art der Ressource, dem Namespace, sofern sie einen hat, und dem Namen, jeweils kleingeschrieben und mit jeder Folge anderer Zeichen auf einen einzelnen Bindestrich reduziert. Bei einer gewöhnlichen Komponente ist diese Basis die eigene Identität der Komponente, die auch das Label aggrega.ai/component-id der Ressource trägt; bei einem Chart, das der Autor einer Feature-Anbindung geliefert hat, bleibt sie die der Host-Komponente, während das Label die eigene Identität der Anbindung trägt. Ein Dokument ohne Art oder ohne Namen wird stattdessen nach seinem Template-Pfad benannt. Die Verzeichnisstruktur des Charts wird abgeflacht: In der gerenderten Ausgabe gibt es kein Unterverzeichnis templates/, und zwei Templates in verschiedenen Unterverzeichnissen mit demselben Dateinamen bleiben zwei Dateien, weil der Name von der Ressource statt vom Template kommt. Eine Datei, die der Block artifacts: des Recipe benennt, landet nicht hier: Sie liegt ein Verzeichnis tiefer, unter einem Verzeichnis, das nach der Komponente benannt ist, die sie deklariert hat, weil eine solche Datei nach dem Schlüssel benannt wird, den ihr Autor geschrieben hat, statt nach der Ressource, die sie trägt — ohne dieses Verzeichnis würden also zwei an ein Recipe gebundene Komponenten einen einzigen Pfad schreiben, ohne dass einer der beiden Autoren sie trennen könnte.

Der Namespace, gegen den das Chart rendert, wird aus der Annotation aggrega.ai/namespace gelesen, die von der Boundary herabkaskadiert, und erreicht das Chart als dessen Release-Namespace; wenn keine Boundary einen deklariert, rendert das Chart gegen default. Wo eine Boundary einen deklariert, wird jede Ressource mit Namespace, die das Chart ohne Namespace rendert — kein metadata.namespace oder eines, das leer oder null geschrieben ist —, im deklarierten Namespace ausgegeben, also dort, wo eine Installation des Charts mit Helm unter diesem Release-Namespace sie platziert, und ihre Datei wird mit dem Namespace-Segment benannt, genau wie bei einer Ressource, deren Template das Feld schreibt. Eine Ressource, deren Template einen Namespace schreibt, behält ihn, welchen Namespace er auch nennt. Eine clusterweite Ressource bleibt ohne Namespace. Ob eine Art einen Namespace hat, bestimmt bei einer Art, die die Kubernetes-API selbst bedient, deren eigener Geltungsbereich und bei einer benutzerdefinierten Art der scope, den eine CustomResourceDefinition im selben Rendering für sie deklariert — aus den Templates des Charts oder aus seinem Verzeichnis crds/. Eine Ressource einer Art, die keines von beiden einordnet, bleibt so, wie das Chart sie geschrieben hat, und der Build meldet sie, einmal pro Art, unter Nennung der Art und ihrer API-Gruppe; ebenso ein Dokument kind: List, dessen Elemente nicht platziert werden. Wo keine Boundary einen Namespace deklariert, wird nichts platziert und nichts gemeldet: Eine Ressource, die das Chart ohne Namespace schreibt, wird ohne ausgegeben und von dem platziert, was das anwendende Werkzeug auswählt.

Die Meldung ist eine Warnung zum Build, der dennoch abgeschlossen wird:

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

Wo das Chart einen Wert hat, der die CustomResourceDefinition der Art rendert, oder einen, der den Namespace selbst schreibt, platziert das Setzen dieses Werts über das valuesMapping des Recipe eine solche Ressource.

Die Kubernetes-Version, für die ein Chart gerendert wird

Die Templates eines Charts lesen die Kubernetes-Version, für die sie gerendert werden, als .Capabilities.KubeVersion, und viele wählen danach eine API-Version, ein Feld oder einen ganzen Mechanismus aus — etwa ein projiziertes Service-Account-Token ab 1.21 und darunter ein First-Party-Token. Der Build hat keinen Cluster, den er fragen könnte, daher ist die Version eine, die Sie angeben, dort, wo das Release festlegt, wo eine Komponente bereitgestellt wird: die Annotation aggrega.ai/kubernetes-version an einer Boundary oder an einer Komponente, wo sie Vorrang vor der ihrer Boundary hat, mit genau derselben Kaskade wie 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

Der Wert wird so gelesen, wie helm template --kube-version sein Flag liest, daher akzeptiert er die Formen, die dieses Flag akzeptiert, und ein Chart liest genau das, was dieses Flag ihm geben würde: "1.31" liest sich als v1.31, "v1.31.2" als v1.31.2, und Text nach den Zahlen bleibt in .Capabilities.KubeVersion.Version so erhalten, wie er geschrieben ist — "1.29.3-gke.100" liest sich als v1.29.3-gke.100 —, während .Capabilities.KubeVersion, als Ganzes ausgegeben, die Version ohne ihn liest. Ein Chart, das .Capabilities.KubeVersion.Version mit semverCompare vergleicht, liest ein solches Suffix als Vorabversion, sodass eine Bedingung ohne Untergrenze -0, etwa ">=1.21", nicht darauf passt, und ein Wert mit umgebenden Leerzeichen liest sich mit diesen Leerzeichen — " 1.30 " liest sich als "v 1.30 " — und scheitert an einem solchen Vergleich ganz: Schreiben Sie die reine Version, wo ein Chart sie vergleicht. Ein Wert, der keine Version ist — "one.two", "latest", eine einzelne Zahl —, bricht den Build unter der Bedingung für einen Wert ab, für den ein Plugin keine Darstellung hat, unter Nennung des Werts, der Komponente und ihrer Boundary; das Chart wird nie stattdessen für eine andere Version gerendert. Siehe A Kubernetes version the helm provider cannot render a chart for (Eine Kubernetes-Version, für die der helm-Provider kein Chart rendern kann). Ein leerer Wert wird als nicht gesetzt behandelt.

Wo keine Annotation eine Version nennt, rendert ein Chart für die Version, für die das unveränderte helm template desselben helm-Release rendert, also die Version der Kubernetes-Clientbibliothek, mit der der Provider gebaut ist: Ein gegen die Clientbibliothek v0.37 gebauter Provider rendert für Kubernetes v1.37.0. So rendert ein Chart in Aggrega so, wie das helm template seiner eigenen Autoren es rendert, und der Standard ändert sich nur, wenn sich die Clientbibliothek ändert, mit der der Provider gebaut ist. Nennen Sie die Version des Clusters, auf dem Sie bereitstellen, wann immer sie abweicht: Ein für eine neuere Version als die des Clusters gerendertes Chart kann eine API-Version ausgeben, die dieser Cluster nicht bedient.

Nur die Version wird auf diese Weise gesetzt. Jede andere Fähigkeit, die ein Chart liest — .Capabilities.APIVersions und .Capabilities.HelmVersion —, ist die eingebaute der helm-Bibliothek, sodass eine API, die ein Cluster aus einer installierten CustomResourceDefinition bedient, dem Chart nicht gemeldet wird. Der eigene Bereich kubeVersion eines Charts in seiner Chart.yaml wird nicht mit der Version verglichen: helm template lehnt ein Chart ab, dessen Bereich die Version ausschließt, für die es rendert, und der Build rendert es. Die Annotation prägt ein aus der Quelle gerendertes Chart und nichts anderes: Eine synthetisierte Workload und ein Körper artifacts: lesen kein .Capabilities, und der Provider helm-chart reicht sein Chart ungerendert weiter, damit es bei der Installation gerendert wird.

Gerenderte Dokumente auslassen. Dieser Provider berücksichtigt die Einträge omits:, die ein Recipe oder ein FeatureRecipe deklariert, in diesem Modus und in keinem anderen: Eine synthetisierte Workload und ein Körper artifacts: rendern ohne sie. Jedes Dokument, das das Chart rendert — aus einem Template oder aus einer Datei seines Verzeichnisses crds/ —, wird mit jedem Eintrag abgeglichen, der für den Build gilt, und ein Dokument, das ein beliebiger Eintrag benennt, wird ausgelassen. Ein Eintrag benennt ein Dokument mit den Wörtern, die das Dokument selbst trägt, denselben Wörtern, aus denen sein Ausgabedateiname und seine Render-Fakten gebildet werden: seinem kind, seinem metadata.name und, nur wo der Eintrag einen nennt, dem Namespace, in dem sich das Dokument befindet — dem, den sein Template schreibt, oder dem deklarierten Namespace der Boundary, wo dieser Provider das Dokument wie oben beschrieben platziert. Es ist nie der Namespace, gegen den das Chart lediglich rendert: Ohne deklarierten Namespace rendert das Chart gegen default, doch ein Dokument, dessen Template keinen Namespace schreibt, befindet sich in keinem, sodass ein Eintrag, der default nennt, nicht darauf passt. Ein Dokument ohne Art oder ohne Namen passt auf keinen Eintrag. Die ausgelassenen Dokumente werden gerendert und dann verworfen, sobald der Name jeder Datei feststeht, sodass jedes behaltene Dokument genau so benannt und geschrieben wird, wie es ohne die Einträge wäre, und ein ausgelassenes Dokument nichts erreicht, was der Build danach tut — keine Datei, keinen Namen im Vergleich, der zwei auf demselben Namen landende Beitragende ablehnt, keinen Render-Fakt, den ein Feature liest, nichts, was einem Pipeline-Schritt übergeben wird. Der Provider meldet, wie viele Dokumente jeder Eintrag getroffen hat, und ein Eintrag, der keines getroffen hat, bricht den Build ab; siehe An omits entry left out nothing the source rendered (Ein omits-Eintrag hat nichts von dem weggelassen, was die Quelle gerendert hat).

Das Helm-Release, unter dem ein Chart gerendert wird

Der Provider rendert mit dem SDK von Helm 4 in v4.3, sodass ein Chart liest, was ihm das eigene helm template von Helm 4 gibt, und dasselbe Chart mit denselben Werten bei jedem Build dieselben Bytes rendert. Ein gegen Helm 3 geschriebenes und geprüftes Chart kann diese Verhaltensweisen von Helm 4 beobachten:

  • .Capabilities.HelmVersion meldet die Version von Helm 4, v4.3.
  • Die Standard-Kubernetes-Version ist v1.37.0, weil Helm 4 in v4.3 gegen die Clientbibliothek v0.37 gebaut ist, und .Capabilities.APIVersions ist die Menge der API-Versionen dieser Clientbibliothek. Nennen Sie die Version, die Ihr Cluster ausführt, wie es Die Kubernetes-Version, für die ein Chart gerendert wird beschreibt.
  • Ein Standardwert null des Charts wird verworfen. Ein Schlüssel, den die values.yaml des Charts auf null setzt — auf oberster Ebene oder innerhalb einer Tabelle —, fehlt in .Values, sofern die Werte, die das Recipe liefert, ihn nicht setzen, sodass hasKey ihn als fehlend meldet, toYaml ihn weglässt und die values.schema.json des Charts gegen die Werte ohne ihn geprüft wird.
  • Ein Blockskalar behält seinen abschließenden Zeilenumbruch vor ---. Ein Dokument, das mit einem Blockskalar endet und auf das ein weiteres Dokument aus demselben Template folgt, behält den letzten Zeilenumbruch dieses Skalars, sodass der Skalar als | statt |- geschrieben wird.
  • .Chart ist eine nach Feldnamen geschlüsselte Map. .Chart.Name, .Chart.Version, .Chart.AppVersion und die anderen Felder lesen sich wie zuvor, aber toYaml .Chart oder toJson .Chart.Maintainers geben die Schlüssel als Name, AppVersion und so weiter aus, mit vorhandenen leeren Feldern, und ein Feld, das die Metadaten des Charts nicht tragen, liest sich als leer, statt das Rendering fehlschlagen zu lassen.
  • .Capabilities.KubeVersion.Version behält den Text einer Version so, wie er geschrieben ist, wie oben für die Annotation aggrega.ai/kubernetes-version beschrieben.
  • Eine values.yaml mit mehreren YAML-Dokumenten wird vollständig gelesen, wobei spätere Dokumente über frühere zusammengeführt werden.
  • .Files.Lines einer leeren Datei gibt keine Zeilen zurück, statt das Rendering fehlschlagen zu lassen.
  • Die von Helm 4 hinzugefügten Template-Funktionen — mustToYaml, mustToJson, mustToToml, mustToDuration und die Konvertierungen duration… — stehen den Templates eines Charts zur Verfügung.
  • Eine zweimal per Alias eingebundene Abhängigkeit gibt jedem Alias eine eigene Kopie der Abhängigkeiten dieser Abhängigkeit.
  • Die Validierung des Werte-Schemas akzeptiert oder lehnt nur an den Rändern anders ab: ein in Anführungszeichen gesetzter lokaler Teil einer E-Mail-Adresse, NaN und unendliche Zahlen, eine Zahl, die in enum und const mit einer Nicht-Zahl verglichen wird, und die Stelle, die für ein fehlschlagendes propertyNames, contentSchema oder späteres Array-Element gemeldet wird.

Ein Template, das die Engine selbst nicht ausführen kann — etwa ein über eine fehlende Tabelle gelesener Wert —, wird in der Form von Helm 4 gemeldet: Datei, Zeile und Spalte des Templates auf einer eigenen Zeile, dann das, was gerade ausgeführt wurde, und die Meldung, eingerückt, für jedes Template, das der Fehler durchlaufen hat. Das eigene fail oder required eines Charts behält seine einzeilige Form execution error at (<file>:<line>:<col>): <message>, und ebenso ein Fehler, den eine Template-Funktion zurückgibt.

Wie der Release-Name abgeleitet wird

Ein Chart mit Quelle rendert gegen einen Release-Namen, der jedes Template als .Release.Name erreicht. Charts benennen Ressourcen routinemäßig danach, sodass ein Release-Name eine Identität innerhalb des Clusters ist und kein Label am Build.

Der Release-Name ist die codierte Form derselben Basis, die dem Ausgabedateinamen der gerenderten Ressource als Präfix vorangestellt wird, sodass beide ein einziger, zweimal geschriebener Name sind. Diese Basis ist bei einer gewöhnlichen Komponente eine instance_id und bei einem an eine Boundary angebundenen Feature die zusammengesetzte Identität, die es trägt. Bei einem Chart, das vom Autor einer Feature-Anbindung stammt, ist sie der Name der Host-Komponente: Die eigenen Templates des Charts rendern gegen den Release-Namen, sodass eine Ableitung aus der Anbindung stattdessen Ressourcen umbenennen würde, die das Chart deklariert, in einem Cluster, in dem sie bereits bereitgestellt sind. Diese Ressourcen tragen in ihrem Label aggrega.ai/component-id dennoch die eigene Identität der Anbindung — wie eine Ressource heißt und wozu sie gehört, sind hier getrennte Fragen, und nur bei einer gewöhnlichen Komponente haben sie dieselbe Antwort. Ein Helm-Release-Name akzeptiert eine engere Zeichenmenge, als eine Identität enthalten kann: Kleinbuchstaben, Ziffern, Bindestriche und Punkte, beginnend und endend mit einem Kleinbuchstaben oder einer Ziffer, bis zu 53 Zeichen. Statt ein Zeichen zu ersetzen, das das Ziel nicht akzeptiert, schreibt die Ableitung es aus, sodass zwei Komponentenidentitäten, die sich nur in der Interpunktion oder in der Groß- und Kleinschreibung unterscheiden, immer bei zwei Release-Namen ankommen.

  • Ein Kleinbuchstabe und eine Ziffer werden genau wie verfasst übernommen.
  • Ein Bindestrich bleibt wie geschrieben erhalten, wo immer das Zeichen danach direkt übernommen wird und kein kleines z ist. Ein Bindestrich, auf den ein kleines z folgt, leitet ein Escape ein, daher wird ein geschriebener Bindestrich an dieser Stelle selbst ausgeschrieben — api-zone wird zu api-zhzone, und genau das erlaubt es, jeden Namen ohne Raten zurückzulesen. Ein Bindestrich, auf den nichts folgt, wird aus demselben Grund ausgeschrieben, sodass db- zu db-zh wird.
  • Jedes andere Zeichen wird als -z geschrieben, gefolgt von einem Buchstaben, der es benennt: d für einen Punkt, u für einen Unterstrich, s für ein Pfadtrennzeichen, h für einen Bindestrich, den die obige Regel nicht beibehält. Alles andere — einschließlich eines Großbuchstabens — wird als x und der sechsstellige hexadezimale Codepunkt des Zeichens geschrieben, und ein Byte, das überhaupt kein Zeichen beginnt, als b und sein eigener zweistelliger Wert.
  • Ein leerer Wert wird als -ze geschrieben, was kein nicht leerer Wert erzeugen kann.

Ein Punkt wird ausgeschrieben statt übernommen, obwohl Helm einen Punkt in einem Release-Namen akzeptiert, weil Helm auf beiden Seiten eines Punkts einen Kleinbuchstaben oder eine Ziffer verlangt und die Ableitung eigene Bindestriche setzt.

Weil zwei an eine Komponente angebundene Features beide gegen den Release-Namen dieser Komponente rendern, geben zwei Charts, die jeweils eine Ressource nach .Release.Name benennen, zwei Ressourcen mit einem Namen aus. Dieser Provider meldet den Namen, den jede Ressource trägt, die sein eigenes Rendering erzeugt, bezogen auf die Art dieser Ressource und, bei einer Art, die der Cluster in einem Namespace hält, auf ihren Namespace, und der Build lehnt zwei Beitragende ab, die auf einem dieser Namen landen, statt eine Ausgabe zu erzeugen, bei der das Anwenden beider nur die letzte übrig lässt — siehe ../errors/fatal-halts.md „The same name is derived more than once inside the output (Derselbe Name wird innerhalb der Ausgabe mehr als einmal abgeleitet)“. Eine Art, die der Cluster außerhalb jedes Namespace hält — eine ClusterRole, eine CustomResourceDefinition oder eine benutzerdefinierte Art, die eine CustomResourceDefinition im selben Rendering mit dem Geltungsbereich Cluster deklariert —, ist allein auf ihre Art bezogen und wird genau so eingestuft, wie die obige Namespace-Platzierung sie einstuft, sodass zwei Komponenten einer Ausgabe, die jeweils ein solches Objekt unter einem Namen schreiben, auch dann abgelehnt werden, wenn das Release sie in verschiedene Namespaces platziert. Die Abhilfe besteht darin, den Namen zusammenzusetzen, und welche Koordinate er braucht, hängt von der Anordnung ab. Zwei Anbindungen an einer Komponente teilen sich bereits den Host, also ist es die Anbindung, die das Template erreichen muss: Übergeben Sie .attachment_name über das valuesMapping: des FeatureRecipe an das Chart und setzen Sie es auf denjenigen der eigenen Werte des Charts, aus dem seine Ressourcennamen gebildet werden. Ein an zwei Komponenten angebundenes Chart ist der umgekehrte Fall — der Release-Name unterscheidet sich bereits pro Host, sodass eine nach .Release.Name benannte Ressource auf jedem von ihnen einen eigenen Namen trägt, ein literaler Name dagegen nicht. Ein FeatureRecipe, das seine Ressourcen über artifacts: liefert, wird unter denselben Bedingungen gemeldet: Dieser Provider liest den Namen, den jedes ausgegebene Dokument trägt, ob dieses Dokument aus einem Chart-Template oder aus einem Artefakt-Körper stammt, sodass auch ein literaler Name in einem solchen Körper, der an zwei Komponenten angebunden ist, den Build abbricht. Ein Artefakt-Körper ist ein Template, also setzen Sie den Namen aus .context.rendered_name zusammen — dem Release-Namen des Hosts, der sich pro Host unterscheidet und in den Zeichen geschrieben ist, die ein Kubernetes-Name erlaubt — und aus .attachment_name, wo er pro Host eindeutig sein muss; auf einem Host, der einen Artefaktsatz allein platziert und keinen Release-Namen meldet, setzen Sie ihn stattdessen aus .context.instance_id zusammen. Nicht jeder Name wird gemeldet, sodass ein Build, der nicht abbricht, nicht alles verglichen hat, was seine Ausgabe schließlich tragen wird. Derjenige, dem Sie beim Schreiben eines Charts am ehesten begegnen, ist eine Ressource, die generateName deklariert und deren Name dem Cluster zur Vervollständigung überlassen wird, sodass es noch nichts zu vergleichen gibt. Die oben verlinkte Seite enthält die vollständige Menge.

Eine instance_id api ergibt also den Release-Namen api, data.main-db ergibt data-zdmain-db und db_host ergibt db-zuhost. Eine Identität, die nur aus Kleinbuchstaben, Ziffern und Bindestrichen besteht, die die Ableitung beibehält, erscheint genau wie verfasst. Identische Eingabe erzeugt immer den identischen Namen.

Zwei der Bedingungen von Helm sind Eigenschaften der Basis und nicht der Ableitung: Ein Release-Name muss mit einem Kleinbuchstaben oder einer Ziffer beginnen, und er darf höchstens 53 Zeichen lang sein. Eine Basis, deren erstes Zeichen ausgeschrieben wird, beginnt ihren Namen mit dem Bindestrich, mit dem jedes Escape eingeleitet wird, und eine, die ausgeschriebene Zeichen enthält, wird codiert länger, als sie verfasst wurde. Der Build fragt diesen Provider nach beidem und handelt zur Build-Zeit nach der Antwort, statt die Ablehnung zur Anwendungszeit dem Cluster zu überlassen — siehe ../errors/fatal-halts.md „The target will not accept a name derived from an authored identity (Das Ziel akzeptiert keinen von einer verfassten Identität abgeleiteten Namen)“. Was er mit der Antwort tut, hängt davon ab, wer die Basis geschrieben hat. Ein Name, den Sie geschrieben haben, wird abgelehnt statt verändert, und die Ablehnung nennt das Feld, das Sie geschrieben haben, und das Budget, das Ihnen zur Verfügung steht; ein Name, den Aggrega zusammengesetzt hat, wird gekürzt, bis dieser Provider ihn akzeptiert.

Der Cluster unterwirft die nach einer Komponente benannten Ressourcen einer Regel, die strenger ist als die von Helm: Ein Service-Name muss mit einem Buchstaben beginnen, während ein Release-Name mit einer Ziffer beginnen darf. Ein Chart benennt seine Services routinemäßig nach dem Release-Namen, und auch die Services einer synthetisierten Arbeitslast beginnen damit, sodass dieser Provider auch einen Komponentennamen ablehnt, der mit einer Ziffer beginnt, und ihn als Service name meldet, den das Ziel nicht verwenden kann. Keine Länge behebt ein erstes Zeichen, daher nennt diese Ablehnung keine. Beginnen Sie eine instance_id also mit einem Kleinbuchstaben, und halten Sie sie kurz genug, dass ihre codierte Form noch passt.

Eine Änderung der Basis, aus der ein Release-Name abgeleitet wird, benennt die Cluster-Ressourcen um, die ein Chart nach .Release.Name benennt, sowie jede Ressource, die dieser Provider für die Komponente synthetisiert, und Kubernetes benennt eine Ressource nicht an Ort und Stelle um. Das anwendende Werkzeug erstellt die Ressource unter ihrem neuen Namen und entfernt die unter dem alten Namen, was bei zustandsbehafteten Ressourcen bedeutet, dass der an den alten Namen gebundene Speicher freigegeben wird. Behandeln Sie eine solche Änderung als zu planende Ersetzung — mit Leeren, Migration oder einem festgelegten Zeitfenster — statt als auszurollende Aktualisierung.

Workload-Modus (synthetisiert)

Ein Recipe mit workload: (inline oder per $import: geladen) synthetisiert Kubernetes-Ressourcen aus der abstrakten Absicht der Workload. Das Workload-Schema ist unter entities/workload.md dokumentiert; dieser Abschnitt behandelt, was der helm-Provider ausgibt.

Für jeden Knoten:

  • Ein Controller-Objekt, das durch das form der Workload gewählt wird: stateless (und der Standardwert) gibt ein Deployment aus, stateful ein StatefulSet, daemon ein DaemonSet, task einen Job, scheduled einen CronJob, dessen spec.schedule das Feld schedule der Workload ist (ein Cron-Ausdruck mit 5 Feldern oder ein Makro @); eine Arbeitslast der Form scheduled ohne Zeitplan oder mit einem fehlerhaften bricht den Build mit einer deutlichen Meldung ab. Eine Arbeitslast der Form scheduled, die suspend: true deklariert, gibt ihren CronJob mit spec.suspend: true aus, sodass kein Lauf aus dem Zeitplan startet, bis sie fortgesetzt wird, während ein Job weiterhin von Hand aus dem CronJob erstellt werden kann; eine, die es nicht deklariert, gibt überhaupt keinen Schlüssel suspend aus. Das Deployment und das StatefulSet tragen die Replikatanzahl; DaemonSet, Job und CronJob tragen keine. Eine Workload mit stateful erfordert genau einen in der Workload deklarierten Service type: Headless, der das StatefulSet steuert; der Provider verbindet den serviceName des StatefulSet mit dem gerenderten Namen dieses Service, und der Build bricht ab, wenn kein Headless-Service deklariert ist (oder wenn mehr als einer deklariert ist). Ein Volume persistentTemplate ist ein Begleiter von form: stateful — eines in einer anderen Form zu deklarieren, bricht den Build mit einer Meldung ab, die die Abhilfe nennt.
  • Ein Service pro deklariertem Eintrag unter services: in der Workload, der die benannten Ports freigibt, die die Service-Spezifikation auflistet. Der type des Eintrags wird zum Typ des Service — ClusterIP, NodePort und LoadBalancer unverändert, und Headless als Service ClusterIP mit clusterIP: None. Ein Eintrag Loopback bricht stattdessen den Build ab und nennt den Knoten und den Service: Ein Kubernetes-Service hat keinen Typ, der an die Loopback-Adresse eines Hosts bindet, und auf welchen Knotenadressen ein Service NodePort lauscht, ist eine Einstellung des gesamten Clusters, sodass der Eintrag abgelehnt wird, statt mit einer Reichweite gerendert zu werden, die er nicht verlangt hat. Siehe A service type the helm provider cannot render (Ein Service-Typ, den der helm-Provider nicht rendern kann).
  • Ein PersistentVolumeClaim pro Volume persistent, dimensioniert und gestaltet nach der Spezifikation des Volumes. Ein Volume persistentTemplate gibt keinen eigenständigen Claim aus: Es wird zu einem Eintrag volumeClaimTemplates in der eigenen Spezifikation des StatefulSet, weshalb es ein Begleiter von form: stateful ist.

Ressourcennamen. Jede Ressource, die dieser Modus für eine Komponente ausgibt, wird nach dem Release-Namen der Komponente benannt — demselben Namen, gegen den ein Chart mit Quelle rendert, abgeleitet wie in Wie der Release-Name abgeleitet wird dargelegt —, und der Provider meldet diesen Namen dem Build als {{ .context.rendered_name }}. Das Controller-Objekt trägt den Release-Namen selbst; jeder Service ist <release name>-<service key>; jeder eigenständige Claim ist <release name>-<volume>, und das Volume des Pods verweist genau auf diesen Claim; ein als Datei geliefertes Secret wird aus einem Pod-Volume namens <release name>-secret-<slot> eingehängt, wobei der Slot im Alphabet geschrieben wird, das der Cluster akzeptiert, so wie der Release-Name — ein Slot server_certificate wird also aus <release name>-secret-server-zucertificate eingehängt, und bei einem über eine Verbindung gelesenen Slot wird der Punkt nach dem Namen der Verbindung auf dieselbe Weise geschrieben; der serviceName eines StatefulSet ist der Name des Headless-Service, den es ausgibt; und eine Workload, die nur über einen externen Namen erreichbar gemacht wird, gibt einen Service aus, der den Release-Namen trägt. Eine Komponente api gibt also ein Deployment api und einen Service default namens api-default aus, und eine Komponente my_api gibt my-zuapi und my-zuapi-default aus — Namen, die der Cluster akzeptiert, wo die Identität in ihrer geschriebenen Form es nicht wäre. Ein Recipe, das die Adresse eines dieser Services veröffentlicht, bildet sie aus {{ .context.rendered_name }}, wie ../templates/rendered-resource-names.md zeigt; bei einer Komponente, deren Name keinen Unterstrich und keinen Großbuchstaben enthält, ist der Release-Name gleich ihrer instance_id, sodass ihre Namen genau wie die Identität lauten. Eine Arbeitslast, die eine Feature-Anbindung synthetisiert, ist die einzige Ausnahme: Sie wird nach der eigenen zusammengesetzten Identität der Anbindung benannt — dem Wert, den ihr Label aggrega.ai/component-id trägt —, weil die Anbindung gegen ihre Host-Komponente rendert und ein dort abgeleiteter Release-Name die Arbeitslast der Anbindung nach dem Host benennen und mit der eigenen des Hosts kollidieren würde. Diese Identität enthält nie einen Großbuchstaben: Ein Großbuchstabe im Namen des Hosts oder in dem der Anbindung wird als Escape ausgeschrieben, wie jedes andere Zeichen, das ein Ressourcenname ablehnt, sodass eine Anbindung worker an einer Komponente myApi ein Deployment cfr--my-zx000041pi--worker und einen Service default namens cfr--my-zx000041pi--worker-default ausgibt, und jeder Name, den die Arbeitslast trägt, ist einer, den der Cluster akzeptiert.

Namenslängen, die von der Workload abhängen. Für zwei dieser Namen gelten im Cluster eigene Grenzen, und der Build prüft beide, sobald die Workload aufgelöst ist, statt die Ablehnung dem Cluster zum Zeitpunkt des Anwendens zu überlassen. Ein CronJob-Name hat höchstens 52 Zeichen, weniger als die anderen Namen des Clusters, weil der Controller den Job jedes Laufs nach dem CronJob benennt und ein Suffix anhängt; er wird nur für eine Workload scheduled geprüft. Jeder Service-Name, <release name>-<service key>, hat höchstens 63 Zeichen. Jenseits einer der beiden Grenzen hängt das Weitere davon ab, wer den Namen geschrieben hat, genau wie beim Releasenamen: Ein von Ihnen geschriebener Komponentenname wird abgelehnt, wobei der Build an dem von Ihnen geschriebenen Schlüssel spec.components anhält und die Art des Namens, seine Länge und das Budget Ihres Namens nennt — siehe ../errors/fatal-halts.md „The target will not accept a name derived from an authored identity (Das Ziel akzeptiert keinen Namen, der aus einer verfassten Identität abgeleitet ist)“; eine zusammengesetzte Identität, etwa die, nach der die Workload einer Feature-Anbindung benannt ist, wird gekürzt, bis jeder Name passt. Ein Service-Name wird aus Ihrem Komponentennamen und einem Schlüssel gebildet, den die Workload deklariert — im Recipe oder in einem FeatureRecipe —, daher nennt eine Ablehnung diesen Schlüssel und die Stelle, an der die Workload ihn deklariert, spec.workload.services.<key>; ein Schlüssel, der keinem Komponentennamen Platz lässt, muss selbst gekürzt werden. Eine Komponente mit einer Workload scheduled kann also einen codierten Namen von bis zu 52 Zeichen haben, und eine Komponente web kann Service-Schlüssel von bis zu 59 Zeichen tragen. Bei einem Feature, das an eine ganze Boundary angebunden ist, steht die Identität fest, bevor seine Workload aufgelöst wird, weil davon abhängen kann, wo seine Ausgabe zusammengesetzt wird; daher wird für die Ressourcen, die es synthetisiert, keine der beiden Grenzen geprüft.

Jede ausgegebene Ressource trägt die vollständigen Provenienz-Labels und -Annotationen von Aggrega plus ein Selektorpaar (app: <instance_id>), das zwischen dem Deployment/StatefulSet und seinen Services verdrahtet ist. Ein Label-Wert lässt die Identität in ihrer geschriebenen Form zu, sodass der Selektor sie beibehält, während die obigen Namen den Release-Namen übernehmen. Die Container-Namen im gerenderten Deployment sind die Container-Schlüssel der Workload, wobei die Zeichen . und _ durch - ersetzt werden (Kubernetes-Namensbereinigung).

Port-Transport. Ein Container-Port, der ein Transportprotokoll deklariert, gibt es unverändert als protocol: am gerenderten containerPort aus, und jeder Service-Port, der diesen Container-Port benennt, trägt denselben Wert — das Transportprotokoll wird einmal deklariert, am Container-Port, sodass die Freigabe ihm nicht widersprechen kann. Ein Port, der kein Transportprotokoll deklariert, gibt an keiner der beiden Ressourcen einen Schlüssel protocol aus, sodass der Standardwert des Clusters gilt. Alle drei Werte, die die Workload zulässt (TCP, UDP, SCTP), werden unverändert ausgegeben; helm benötigt keine Herabstufung, da Kubernetes jeden von ihnen direkt ausdrückt.

Ausführung im Netzwerk des Knotens. Eine Workload, die hostNetwork: true deklariert, gibt hostNetwork: true in der gerenderten Pod-Spezifikation aus, sodass der Pod im eigenen Netzwerk-Namespace des Knotens läuft und die Ports, die seine Container öffnen, unter den Adressen des Knotens erreichbar sind. Kubernetes drückt die Wahl direkt aus, sodass nichts herabgestuft wird. Die Deklaration erreicht die Pod-Spezifikation und sonst nichts: Sie fügt keinen Port hinzu, entfernt keinen und schreibt keinen um, und die ausgegebenen Services sind mit und ohne sie identisch. Eine Workload, die sie nicht deklariert, gibt überhaupt keinen Schlüssel hostNetwork aus.

Ressourcenmengen. Jede Menge, die der Provider in die Manifeste kopiert, wird unverändert ausgegeben, und jede wird zuerst gegen die Mengenform geprüft, die in Workload → Ressourcenmengen dargelegt ist: die Werte resources.requests und resources.limits jedes Containers und jedes Init-Containers — cpu, memory und jede erweiterte Ressource wie nvidia.com/gpu — sowie ephemeral.sizeLimit, persistent.size und persistentTemplate.size jedes Volumes. Die Prüfung läuft auf der Workload, wie die Templates des Recipe sie ausgewertet haben, sodass ein Wert, der über infra oder einen Release-Parameter angekommen ist, danach beurteilt wird, wozu er gerendert wurde. Ein Wert außerhalb der Form bricht den Build mit einem TRANSLATION_ERROR ab, der den Knoten, den Pfad des Feldes in der Workload und den Wert nennt — zum Beispiel containers.main.resources.requests.cpu: "lots" is not a quantity: it does not begin with a number —, wo das Chart sonst sauber gebaut und vom Cluster bei der Installation abgelehnt würde. Ein leer gelassenes cpu, memory oder sizeLimit wird in den Manifesten weggelassen und daher nicht geprüft; ein leer gelassener Wert einer erweiterten Ressource oder eine leer gelassene persistente Größe würde dennoch ausgegeben und wird daher abgelehnt. Die Prüfung beurteilt nur die Form: Ob der Cluster die Menge einplanen kann, kann der Provider zur Build-Zeit nicht wissen.

Die Benennung der Ausgabedateien hat zwei Formen. Das Controller-Objekt wird nach dem Release-Namen und seiner Art benannt — <release name>-deployment.yaml, <release name>-statefulset.yaml, <release name>-daemonset.yaml, <release name>-job.yaml, <release name>-cronjob.yaml. Eine Datei pro Ressource wird nach der Ressource benannt, die sie trägt, mit der Art am Ende: <release name>-<svcName>-service.yaml und <release name>-<volName>-pvc.yaml, jeweils aus dem eigenen metadata.name dieser Ressource gemäß der Konvention für synthetisierte Namen unter entities/workload.md genommen. Eine Workload, die nur über einen externen Namen erreichbar gemacht wird, gibt <release name>-service.yaml aus, da es keinen Service-Schlüssel zu tragen gibt.

Render-Fakten

Neben den Dateien, die er rendert, meldet dieser Provider zu jedem Knoten vier Render-Fakten: was die von ihm ausgegebenen Kubernetes-Dokumente über ihre Pods, ihre Selektoren, ihre Ports und den Namespace aussagen, in den jedes ausgegeben wird. Ein an die Komponente angebundenes FeatureRecipe liest die eigenen Fakten der Komponente unter .context.render_facts; eines, das readsCallerRenderFacts: true setzt, liest außerdem an jedem Eintrag von .context.used_by die Fakten einer Komponente, die sich mit seinem Host verbindet, und eines, das readsTargetRenderFacts: true setzt, liest an jedem Eintrag von .context.uses die Fakten einer Komponente, mit der sein Host verdrahtet ist. So kann ein Feature die Pods der Komponenten benennen, die seinen Host aufrufen, oder der Komponenten, die sein Host erreicht — etwa eine Netzwerkrichtlinie, die genau diese zulässt —, und zwar aus dem, was ihr Rendering tatsächlich ausgegeben hat, ohne dass jemand ein Label von Hand wiederholt. Die Namen und die Einträge unten sind der Vertrag dieses Providers.

FaktEin Eintrag proJeder Eintrag trägt
pod_template_labelsausgegebenem Pod-Template: das spec.template eines Deployment, StatefulSet, DaemonSet, ReplicaSet oder Job, das Job-Template eines CronJob und ein einzelner Pod, der sein eigenes istkind, name und namespace der Ressource, die das Template trägt; labels, die Labels des Templates
controller_selectorsausgegebenem Deployment, StatefulSet, DaemonSet, ReplicaSet, Job und CronJobkind, name, namespace; match_labels, die matchLabels seines Selektors
service_selectorsausgegebenem Servicename, namespace; selector, die Labels, an die er Datenverkehr sendet
container_portsContainer eines Pod-Templates, das eine Liste ports deklariert, Init-Container eingeschlossenkind, name und namespace der Ressource, die das Template trägt; container, der Name des Containers; ports, ein Eintrag pro Port mit seinem name, container_port und protocol

So lesen sich die Fakten:

  • Jeder Fakt ist eine Liste. Ein Template iteriert immer über einen Fakt, auch wenn er einen einzigen Eintrag enthält; es gibt keinen Einzelwert, der für sich allein zu lesen wäre.
  • Alle vier, bei jedem Rendering. Jeder wird gemeldet, wann immer dieser Provider einen Knoten rendert, als leere Liste, wenn das Rendering nichts ausgegeben hat, was er beschreibt — eine Komponente, deren Chart nur eine ConfigMap ausgibt, meldet vier leere Listen. Das Rendering eines anderen Providers meldet keinen dieser Namen, und ein Name, den niemand gemeldet hat, liest sich als nichts.
  • Aus dem Ausgegebenen gelesen, auf jedem Pfad. Die Fakten stammen aus den Dokumenten, die das Rendering ausgegeben hat, gleich welcher Modus sie erzeugt hat: aus den gerenderten Manifesten eines Charts, denen einer synthetisierten Workload und den Manifesten, die ein Autor über artifacts: platziert hat und die genau das melden, was diese Manifeste tragen. Sie werden im selben Durchgang über dieselben Dokumente gelesen wie die Ressourcennamen, die dieser Provider für die Prüfung des Builds auf doppelte Namen meldet. Die eigenen Provenienz-Labels einer Ressource gehören zu dem, was sie trägt, sodass die labels eines einzelnen Pods sie enthalten; das Pod-Template eines Charts oder eines Artefakts behält die Labels, die sein Autor geschrieben hat.
  • Einträge können aus dem eigenen Rendering der Komponente und aus den Renderings ihrer Features stammen. Eine Komponente kann von mehr als einem Aufruf gerendert werden — etwa von einem Chart und einer Platzierung über artifacts: —, und die Listen, die ein Name aus diesen Aufrufen erhält, werden in der Reihenfolge, in der die Aufrufe liefen, zu einer zusammengeführt. An .context.used_by und .context.uses nehmen die Fakten der Komponente am anderen Ende einer Verbindung auch auf, was die an sie angebundenen Features gerendert haben, nach ihren eigenen; .context.render_facts trägt nur das eigene Rendering der Komponente.
  • In der Reihenfolge der Ausgabe. Einträge folgen der Reihenfolge, in der das Rendering die Ressourcen ausgegeben hat. Eine Label-Map ist eine Map mit Schlüsseln wie jede andere im Kontext, sodass ein Template, das über eine iteriert, ihre Schlüssel in Schlüsselreihenfolge antrifft.
  • Was ein Dokument weglässt, lässt sein Eintrag weg. Eine über generateName benannte Ressource hat keinen name; eine Ressource, die kein metadata.namespace schreibt, hat keinen namespace, ebenso wenig eine, die es leer oder null schreibt, was ebenfalls keinen Namespace nennt; ein ohne matchLabels geschriebener Controller — ein Job, der sich auf den vom Cluster erzeugten Selektor verlässt — hat keine match_labels; ein Service ohne Selektor hat keinen selector; ein Port ohne Namen oder Protokoll hat keines von beiden. Jeder andere leer geschriebene Teil wird leer gemeldet. protocol wird nur gemeldet, wo das Dokument eines schreibt, sodass ein Template, das es braucht, den eigenen Standardwert des Clusters, TCP, selbst schreibt. container_port ist überall dort eine Zahl, wo das Dokument einen schreibt.
  • namespace ist der, den das Dokument schreibt, nie eine Vermutung. Es ist das eigene metadata.namespace der Ressource — bei einem Pod-Template das der Ressource, die es trägt, also dort, wo seine Pods laufen; ein innerhalb des Pod-Templates selbst geschriebener Namespace wird nicht gelesen. Eine synthetisierte Workload schreibt den Namespace, den ihre Boundary deklariert, auf jede Ressource, die sie ausgibt, sodass ihre Einträge diesen Namespace tragen. Die Einträge eines Charts tragen, was seine ausgegebenen Dokumente schreiben: wo eine Boundary einen Namespace deklariert, diesen Namespace — ob die Templates des Charts ihn projizieren oder der Provider die Ressource darin platziert (siehe Modus mit Quelle) —, sofern nicht ein Template einen eigenen festlegt, den der Eintrag stattdessen trägt; wo keiner deklariert ist, den Release-Namespace, default, wo die Templates ihn projizieren, und nichts, wo sie keinen schreiben. Wo nichts geschrieben ist, trägt der Eintrag keinen namespace statt des Standardwerts der Boundary oder des Clusters, weil eine solche Ressource dort landet, wo das Werkzeug, das die Ausgabe anwendet, sie platziert, was beim Lauf des Builds nicht bekannt ist. Ein Template unterscheidet beides mit optional: {{ optional . "namespace" "" }} ist genau dort leer, wo das Dokument keinen geschrieben hat, sodass ein Feature, das etwas neben den Pods einer Komponente platziert, eine Komponente, deren Pod-Namespace bekannt ist, von einer unterscheiden kann, bei der er es nicht ist.
  • Erkannt nach Art und API-Gruppe. Pod und Service werden in der Core-Gruppe gelesen, die vier Controller in apps, Job und CronJob in batch, in jeder Version der Gruppe. Eine benutzerdefinierte Ressource einer anderen Gruppe, die zufällig einen dieser Art-Namen trägt, wird nicht als solche gelesen. Die matchExpressions eines Selektors werden nicht gemeldet, ebenso wenig eine Ressource, die in ein Dokument kind: List eingebettet ist, oder ein Wert, der über einen YAML-Merge-Schlüssel geschrieben ist.

Was die Fakten nicht sehen können. Sie beschreiben die Dokumente, die der Build ausgibt, und nichts, was der Cluster später erzeugt. Die Pods, die ein Controller zur Laufzeit aus einer benutzerdefinierten Ressource erzeugt — etwa der Datenbank-Cluster eines Operators —, erscheinen in keinem ausgegebenen Dokument und fehlen daher konstruktionsbedingt; ebenso jedes Label, das ein mutierender Admission-Controller beim Anwenden der Manifeste hinzufügt. Ein Feature, das solche Pods zulassen muss, entnimmt ihre Labels der eigenen Dokumentation der benutzerdefinierten Ressource, wie es ein Autor ohne diese Fakten täte.

Ein FeatureRecipe, das in die Pods seines Hosts genau die Pods der Komponenten zulässt, die ihn aufrufen, und die eigenen Pods des Hosts über den Controller-Selektor des Hosts auswählt:

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 }}

Bei einem Host api, der von einer Komponente web aufgerufen wird, deren Workload dieser Provider synthetisiert hat, wählt die Richtlinie app: "api" aus und lässt einen podSelector zu, der jedes Label des Pod-Templates von web trägt — dieselben Labels, die das spec.template.metadata.labels seines ausgegebenen Deployment enthält. Weil das FeatureRecipe den Schlüssel setzt, rendert seine Anbindung, sobald jede Komponente gerendert hat, sodass die Fakten vorhanden sind, gleich welche von api und web der Build zuerst erreicht; ohne den Schlüssel bricht ein Template, das render_facts an .context.used_by liest, den Build ab, bevor irgendetwas gerendert wird.

Ein podSelector im from einer Richtlinie passt auf Pods im eigenen Namespace der Richtlinie, sodass die obige Richtlinie Aufrufer zulässt, die in den Namespace ausgegeben wurden, in dem sie angewendet wird. Ein Aufrufer, dessen Einträge einen anderen namespace tragen, wird zugelassen, indem sein podSelector mit einem namespaceSelector auf dem Label kubernetes.io/metadata.name dieses Namespace kombiniert wird, das Kubernetes auf jedem Namespace setzt.

Provider-spezifische Besonderheiten

  • Chart-Downloads verwenden nur die integrierten Handler von Helm. Ein aus einem Helm-Repository abgerufenes Chart wird mit den eigenen integrierten Handlern http und https von Helm heruntergeladen. Ein Downloader-Plugin von Helm — eines, das für den Befehl helm installiert ist, oder eines, das im Verzeichnis liegt, aus dem der Build läuft — wird nie herangezogen, sodass das, was in diesem Verzeichnis liegt, nicht ändern kann, wie ein Chart abgerufen wird.

  • Einfügen der Provenienz. Der Pfad mit Quelle und der synthetisierte Pfad laufen auf dieselbe Menge an Labels und Annotationen hinaus; Renderings mit Quelle fügen sie per YAML-Umschreibung nach dem Rendern ein (nachdem das Helm-SDK bereits gerendert hat), sodass Chart-Autoren die Labels von Aggrega nicht durch ihre eigenen Templates schleusen müssen.

  • Reihenfolge der Umgebung — Einträge aus Secrets zuerst. Die Liste env eines synthetisierten Containers trägt zwei Arten von Einträgen: Jeder Eintrag attachments, der as: env geliefert wird, liest seinen Wert über valueFrom.secretKeyRef aus einem Secret, und jeder Eintrag variables trägt einen einfachen value. Der Provider schreibt zuerst jeden aus einem Secret gelesenen Eintrag und danach jede einfache Variable, jede Art in der Reihenfolge, in der sie verfasst ist, und führt die Quellen von envFrom getrennt unter envFrom auf. Kubernetes expandiert eine Referenz $(NAME) in einem Wert von env aus den Einträgen, die im selben Container vor ihr aufgeführt sind, nie aus einem danach aufgeführten, sodass diese Reihenfolge es einer einfachen Variable erlaubt, einen aus einem Secret gelesenen Wert per Referenz zusammenzusetzen, während das Geheimnis selbst im Secret bleibt:

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

    Der gerenderte Container führt DB_PASSWORD vor DATABASE_URL auf, sodass der Prozess die URL mit eingesetztem Passwort erhält. Eine Variable kann auch auf jede vor ihr verfasste Variable verweisen, wodurch die verfasste Reihenfolge innerhalb von variables bedeutsam bleibt. Init-Container folgen derselben Reihenfolge. Ein Container, der einen Namen sowohl als Eintrag variables als auch als as: env gelieferten Eintrag attachments angibt, bricht den Build ab, statt beide Einträge zu schreiben, weil dann allein diese Reihenfolge entscheiden würde, welchen Wert der Prozess sieht (siehe A container gives one environment variable two values (Ein Container gibt einer Umgebungsvariable zwei Werte)).

  • Namespace-Kaskade — die beiden Modi erreichen die Ressource unterschiedlich. Beide lesen aggrega.ai/namespace aus der Annotationskaskade der Boundary, und keiner erfindet einen Namespace, wenn keine Boundary einen deklariert. Im synthetisierten Modus schreibt der Provider metadata.namespace direkt und lässt das Feld ganz weg, wenn die Kaskade keinen Wert liefert. Im Modus mit Quelle liefert der Provider den Wert als Release-Namespace des Charts — default, wenn die Kaskade keinen liefert —, und das eigene Template des Charts entscheidet, ob es ihn projiziert; wo ein Namespace deklariert ist, schreibt der Provider ihn dann in jede Ressource mit Namespace, die das Chart ohne einen gerendert hat (siehe Modus mit Quelle). Mit einem deklarierten Namespace platzieren also beide Modi jede Ressource mit Namespace darin — abgesehen von einem Namespace, den ein Chart selbst festlegt, und einer Art, die der Provider nicht einordnen kann. Ohne deklarierten Namespace trennen sich ihre Wege: Ein Chart, das den Release-Namespace projiziert, platziert seine Ressourcen in default, wo die synthetisierte Ausgabe keinen schreibt, und ein Chart, das keinen Namespace schreibt, platziert sie in keinem, sodass sie dort landen, wo das Werkzeug, das die Manifeste anwendet, sie ablegt. Die lokalen Charts, die die FeatureRecipes der Standardbibliothek mitführen, lesen den Kaskadenwert stattdessen direkt über ihr valuesMapping: Dadurch können sie das Feld weglassen, wenn keine Boundary einen Namespace deklariert, passend zur synthetisierten Ausgabe, was der Release-Namespace allein nicht ausdrücken kann, weil er nie leer ist.

Ausgearbeitete Beispiele

Modus mit Quelle — Recipe, das auf ein lokal kopiertes Chart zeigt:

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" }}"

Workload-Modus — Recipe, das eine Inline-Workload deklariert:

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 }}

Querverweise