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

Workload

Die architektonische Rolle der Art Workload — warum es sie gibt, wie sie sich mit den beiden anderen Eingabearten eines Recipe (sourced und artifacts) zusammensetzt, und die vollständige Schemaoberfläche — ist in ../../architecture/16-recipe-input-composition.md beschrieben. Diese Seite behandelt die Authoring-Oberfläche der Workload: wie ein Recipe-Autor Workload-Inhalte schreibt, was der Compiler wann auswertet, wie Workload-Felder mit dem featuresSchema der Component zusammenwirken und welche Säulen Templates innerhalb einer Workload lesen können.

Ort des Verfassens

Workload-Inhalte werden inline oder aus einer Datei verfasst, innerhalb eines Recipe oder eines FeatureRecipe (siehe FeatureRecipe). Ein Recipe deklariert höchstens ein workload:; ein FeatureRecipe deklariert ebenso höchstens ein eigenes:

# Inline (block scalar)
spec:
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
# ...

oder

# File-loaded via $import: (path relative to the Recipe directory)
spec:
workload:
$import: ./workload/workload.yaml

Beide Formen erzeugen nach dem Parsen dasselbe Workload-Objekt; die Wahl ist eine Frage der Authoring-Ergonomie. Eine dritte Form importiert eine über mehrere Recipes geteilte Workload aus einem Eintrag einer WorkloadLibrary, über ihre Identität mit bloßem Namen: $import: <Library>#/workloads/<entry>. Gemäß dem einheitlichen Vokabular für Dateiimporte akzeptiert $import: eine einzige Quelle — siehe ../vocabulary/cross-document-ref.md für die umfassendere Unterscheidung $ref: / $import:.

Workload-YAML wird nicht als eigenständige Katalogentität verfasst. Es gibt kein Verzeichnis catalog/workload/; die Workload-Grammatik existiert nur als Inhalt, den ein Recipe oder FeatureRecipe konsumiert — inline geschrieben, in einer Datei daneben oder in einem Eintrag einer WorkloadLibrary. Die Deklarationen apiVersion und kind innerhalb des YAML (apiVersion: aggrega.ai/v1beta1, kind: Workload) identifizieren den eingebetteten Inhalt für die Schemavalidierung; sie machen die Workload nicht unabhängig adressierbar.

Template-Auswertung

Workload-Inhalte werden vor dem Parsen als Go-Template gegen den vollständigen Säulenkontext ausgewertet. Wenn ein Recipe-Autor ein Template wie das folgende schreibt…

replicas: {{ optional .infra `replicas` 1 }}

…wertet der Compiler dieses Template während des Workload-Teildurchlaufs des Renderings aus, löst .infra.replicas gegen die infra-Nutzlast des Knotens auf und parst das resultierende YAML als Workload-Dokument. Die locals des Recipe werden aufgelöst, bevor die Workload ausgewertet wird, sodass ein Workload-Template sie bereits aufgelöst unter .locals liest.

Säulenzugriff innerhalb von Workload-Templates:

  • .values — vom Entwickler verfasste kognitive Nutzlast, deklariert im Aggregate.
  • .infra — von Ops verfasste physische Dimensionierung, deklariert im Release.
  • .parameters — bereits bei der Auflösung interpoliert; sichtbar über .values / .infra, wo immer der Entwickler oder Ops beim Verfassen auf .parameters.<name> verwiesen haben.
  • .locals — Recipe-privater Zustand, in der locals-Präambel aufgelöst und bei der Quellauflösung veröffentlicht; an jeder Stelle der Workload-Template-Auswertung verfügbar.
  • .context.instance_id — die abgeflachte Instanz-ID des Knotens; das Präfix der Ressourcennamen, die ein Provider ausgibt, der synthetisierte Ressourcen nach der Identität benennt.
  • .context.rendered_name — der Name, den ein Provider, der den Namen synthetisierter Ressourcen selbst ableitet, ihnen gibt, etwa der Release-Name bei helm; nur vorhanden, wo der Provider einen meldet. Siehe ../templates/rendered-resource-names.md.
  • .context.inject — die Injektions-Pipe nach der Interception, bereits von jedem injectMapping eines FeatureRecipe während des Inject-Mappings umgeschrieben.
  • .context.uses — die angereicherten ausgehenden Topologiekanten dieses Knotens, jede mit den aufgelösten provides, labels und kaskadierenden Annotationen des Ziels und unter .context.uses.<alias>.features.<slot> den Anbindungen, die diese Verbindung trägt.
  • .features — die eigenen Anbindungen des Knotens, jede mit ihrem type, values, infra und den aufgelösten provides. Eine Anbindung, die nach einem Slot benannt ist, den die Component in featuresSchema deklariert, füllt diesen Slot (siehe unten). Eine Anbindung, die eine Verbindung trägt, gehört nicht dazu; sie wird unter ihrer Verbindung gelesen, und eine Workload liefert sie aus, indem sie die Verbindung benennt (siehe Von einer Verbindung getragene Anmeldedaten ausliefern).

Siehe ../vocabulary/data-pillars.md für den vollständigen Vertrag des Säulenzugriffs und ../templates/expansion-matrix.md dafür, wo die Workload-Auswertung in der Abfolge der Template-Auswertung liegt.

Grundlagen der Feldsemantik

Das vollständige Workload-Schema steht in ../../architecture/16-recipe-input-composition.md unter „Die Workload-Art“. Die folgenden Authoring-Konventionen decken die Entscheidungen auf Feldebene ab, die ein Recipe-Autor trifft.

form

form deklariert die abstrakte Controller-Gestalt der Arbeitslast — die Art ihres Laufzeit-Lebenszyklus, unabhängig von einer Zielplattform. Es ist ein einzelner String, einer von stateless, stateful, daemon, scheduled, task, reference, und ist standardmäßig stateless, wenn es weggelassen wird:

  • stateless — austauschbare, horizontal skalierte Replikate ohne Identität pro Replikat (der übliche langlaufende Dienst).
  • stateful — Replikate mit stabiler Identität pro Replikat und Speicher pro Replikat. Ein Volume persistentTemplate ist ein Begleiter dieser Form.
  • daemon — eine Instanz pro geeignetem Host.
  • scheduled — wiederkehrende, zeitgesteuerte Ausführungen.
  • task — eine einzelne Ausführung bis zum Abschluss.
  • reference — keine eigenen Container: Die Komponente steht für einen externen Endpunkt, angegeben als endpoint (ein Host oder eine URL, unverändert durchgereicht) und ein optionaler port. Der helm-Provider gibt sie als Service vom Typ ExternalName aus; der compose-Provider gibt für sie nichts aus.

Die Form selbst enthält keine plattformnativen Ressourcenarten. Jeder Ziel-Provider, der eine Workload synthetisiert, bildet die Form auf seine eigene native Gestalt ab:

formKubernetes (helm)Compose
statelessDeploymentservice (kein persistentes Volume)
statefulStatefulSetservice + benanntes Volume
daemonDaemonSetbricht den Build ab
scheduledCronJobbricht den Build ab
taskJobbricht den Build ab

Die Provider terraform und cloudformation rendern Recipes mit Quelle sowie reine Artefakt-Recipes und synthetisieren keine Workload: Ein Recipe, das workload: deklariert und an einen der beiden gebunden ist, bricht den Build ab und nennt die Eingabearten, die der Provider unterstützt.

Wenn ein Ziel-Provider keine saubere Abbildung für eine Form hat, bricht der Build deutlich ab, statt die Arbeitslast in eine Gestalt herabzustufen, die die Absicht falsch darstellt — eine Form zu wählen, die eine Ziel-Boundary nicht ausdrücken kann, ist ein Fehler zur Build-Zeit, keine stille Herabstufung. Der compose-Provider bricht bei daemon, scheduled und task ab. Der helm-Provider gibt für scheduled einen CronJob aus (siehe schedule unten) und bricht nur ab, wenn sein Zeitplan fehlt oder fehlerhaft ist.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule ist der Cron-Zeitplan für eine Arbeitslast mit form: scheduled — das Begleitfeld, das der wiederkehrenden Form ihre Wiederholung gibt. Es ist ein einzelner String in einem einzigen kanonischen Format:

  • ein standardmäßiger crontab-Ausdruck mit 5 Feldern — Minute, Stunde, Tag des Monats, Monat, Wochentag (zum Beispiel 0 0 * * * für täglich um Mitternacht, */15 * * * * für alle fünfzehn Minuten), oder
  • eines der Makros @hourly, @daily, @weekly, @monthly, @yearly.

schedule ist erforderlich, wenn form: scheduled gilt, und nur dann sinnvoll. Eine Arbeitslast mit form: scheduled ohne Zeitplan, ein Zeitplan, der weder ein Ausdruck mit 5 Feldern noch ein bekanntes Makro ist (ein Ausdruck mit 6 Feldern und vorangestellten Sekunden, ein unbekanntes Token @ oder ein Feld mit unzulässigen Zeichen), oder ein schedule, das bei einer anderen Form gesetzt ist, ist ein Abbruch zur Build-Zeit, der die Korrektur nennt. Der helm-Provider reicht den Wert unverändert in spec.schedule des ausgegebenen CronJobs durch.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
report:
image: "reporter:1.0"
command: ["/report"]

suspend

suspend hält den wiederkehrenden Zeitplan einer Arbeitslast mit form: scheduled an. Es ist ein Boolean und standardmäßig false. Mit suspend: true wird die geplante Ressource weiterhin mit ihrem schedule gerendert, aber aus diesem Zeitplan startet keine Ausführung, bis er fortgesetzt wird, und eine Ausführung kann weiterhin manuell aus der Ressource gestartet werden. Das ist die Gestalt für eine Aufgabe, die nur laufen soll, wenn jemand sie anfordert.

Der helm-Provider gibt das Feld als spec.suspend: true des CronJobs aus. Unter Kubernetes startet kubectl create job <name> --from=cronjob/<cronjob> eine Ausführung aus dem angehaltenen CronJob, und der Zeitplan wird fortgesetzt, sobald spec.suspend wieder false ist. suspend: false wird genau so gerendert wie ein weggelassenes suspend, sodass das Feld keine Ausgabe ändert, bis es gesetzt wird. Der compose-Provider hat keine geplante Gestalt und bricht bei jeder Arbeitslast mit form: scheduled ab, ob angehalten oder nicht.

suspend: true bei einer anderen Form ist ein Abbruch zur Build-Zeit, der die Korrektur nennt: Keine andere Form hat einen Zeitplan, den es anhalten könnte.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
report:
image: "reporter:1.0"
command: ["/report"]

replicas

Eine einzelne Ganzzahl für die Anzahl der Replikate der Arbeitslast. Standardmäßig 1, wenn weggelassen. Verwenden Sie einen Template-Ausdruck, um die Replikate aus der von Ops deklarierten Dimensionierung abzuleiten:

replicas: {{ optional .infra `replicas` 1 }}

containers und initContainers im Vergleich

containers ist eine geordnete Map mit dem Containernamen als Schlüssel. Container 0 (der erste Map-Schlüssel) ist für die Reihenfolge in der Pod-Spec der Kubernetes-Ausgabe und für die Semantik des Standard-Containers maßgeblich. initContainers ist eine geordnete Liste von Init-Container-Einträgen, die jeweils name, image und dieselbe Authoring-Gestalt für Variablen, Secrets und Volume-Mounts wie die Hauptcontainer haben.

name ist bei einem Eintrag in initContainers optional. Ein Eintrag, der ihn weglässt, erhält den Namen init-<index>, wobei der Index die Position des Eintrags in der Liste ist, gezählt ab 0. Da der Name den Container in der gerenderten Ausgabe und in jeder Diagnose, die ihn nennt, identifiziert, verdient ein Eintrag, auf den man sich beziehen möchte, einen expliziten Namen.

Die Erhaltung der Autorenreihenfolge ist ein tragender Vertrag des Workload-Modells — der Compiler gibt containers, volumes, services, die ports der Container, die variables der Container und die attachments der Container jeweils in der Reihenfolge aus, in der der Recipe-Autor sie deklariert hat, bei jedem Build. Recipe-Autoren können sich auf die geordnete Gestalt verlassen: Wenn das, was zur Laufzeit geschieht, von der Reihenfolge abhängt (Start von Sidecars, Verkettung mit $(VAR) in Umgebungsvariablen, volumeMounts, die auf zuvor deklarierte Volumes verweisen), IST die Authoring-Reihenfolge die Laufzeitreihenfolge innerhalb jeder dieser Sammlungen. Die Umgebung eines Containers kombiniert zwei davon, und über beide hinweg schreiben die synthetisierenden Provider zuerst die aus Anbindungen gelesenen Einträge (attachments, die as: env geliefert werden) und danach die einfachen variables, jede Art in der geschriebenen Reihenfolge — sodass auf einem Kubernetes-Ziel eine Variable als $(NAME) auf jede aus einer Anbindung gelesene Variable ihres Containers und auf jede vor ihr deklarierte Variable verweisen kann (siehe die Umgebungsreihenfolge des helm-Providers). Ein Container, der einen Namen sowohl als Eintrag in variables als auch als as: env gelieferten Eintrag in attachments angibt, bricht den Build ab, weil allein diese Reihenfolge entscheiden würde, welchen der beiden Werte der Prozess sieht (siehe A container gives one environment variable two values (Ein Container gibt einer Umgebungsvariable zwei Werte)).

Das Authoring der Containerfelder folgt diesen Konventionen:

  • image ist typischerweise ein Template-Ausdruck, der auf .values.image (das vom Entwickler ausgewählte Image) verweist, mit optionalen Overrides über .infra.* für ein umgebungsspezifisches Registry-Präfix.
  • variables ist eine einfache Map string → string für Umgebungsvariablen. Die Map vereint über Go-Template-Ausdrücke zwei unterschiedliche Datenquellen: Literale aus dem Entwickler-Pillar (Einträge, deren Template-Ausdrücke .values / .infra / .locals lesen — Payload, der aus den Pillars der Component stammt) und Daten aus der komponentenübergreifenden Pipe (Einträge, deren Template-Ausdrücke .context.inject.env.<KEY> lesen — Payload, der aus dem provides: einer anderen Komponente stammt und durch die Topologie-Pipe geleitet wird). Beide Quellen fließen in dieselbe Map variables; Autoren wählen pro Eintrag eine davon, je nachdem, ob der Wert komponentenlokal oder aus einer anderen Komponente abgeleitet ist. Übliche Muster: LOG_LEVEL: "{{ .values.log_level }}" stammt aus dem Entwickler-Pillar (komponentenlokal); DB_HOST: "{{ .context.inject.env.DB_HOST }}" stammt aus der komponentenübergreifenden Pipe (der Wert stammt aus dem provides.host einer Zielkomponente und wird über die Deklaration uses[].inject.env.DB_HOST des Aufrufers geleitet). Beide Formen werden zu einer einzigen Kubernetes-Liste env: im gerenderten Deployment kompiliert; die Semantik der doppelten Quelle besteht nur zur Authoring-Zeit.
  • attachments verweist auf Slots, die im featuresSchema der Component deklariert sind, oder, durch Nennung einer Verbindung, auf einen Slot, den der Socket dieser Verbindung deklariert (siehe den Abschnitt zur Integration unten).
  • ports ist eine Map benannter Ports (web: 8080, admin: 9901); Portnamen entsprechen containerbezogenen Portnamen und werden über services.<service>.ports.<portname> referenziert. Ein Port, der ein anderes Transportprotokoll als den Standard des Ziels verwendet, wird stattdessen in der erweiterten Form geschrieben — siehe Transportprotokolle der Ports unten.
  • volumeMounts verweist über den Namen auf Volumes, die an anderer Stelle im Abschnitt volumes: der Workload deklariert sind.
  • resources deklariert die requests und limits des Containers — die Mengen cpu und memory sowie optional Schlüssel erweiterter Ressourcen für GPUs und andere Geräte (siehe GPU- und Geräte-Arbeitslasten unten).
  • health verwendet die Intent-Gestalt (http: /path, tcp: <port>, exec: [cmd, ...]) — siehe den Abschnitt zu Health-Probes unten.

volumes

Jedes Volume hat genau einen Typ: ephemeral, configmap, secret, persistent oder persistentTemplate. Die Typen schließen sich innerhalb einer einzelnen Volume-Deklaration gegenseitig aus; jeder Typ hat seine eigenen Pflichtfelder:

volumes:
app-config:
configmap:
source: "{{ .locals.app_cm }}"
data:
persistent:
size: "10Gi"
class: "gp3"
cache:
ephemeral:
sizeLimit: "1Gi"

persistentTemplate erzeugt bei der Übersetzung in StatefulSet-Gestalt einen PVC pro Replikat; bei der Übersetzung für compose wird es zu einem einzigen gemeinsam genutzten benannten Volume herabgestuft, wobei eine Warnung zusammen mit dem Build gemeldet wird. Die erzeugte Datei selbst enthält keinen Hinweis auf die Herabstufung — sie ist Byte für Byte so, wie sie ohne die Warnung wäre.

Übersetzung pro Provider. Jeder Provider übersetzt die fünf Volume-Varianten in seine native Gestalt:

VarianteHelm / helm-chart (K8s)ComposeHinweise zu Verlusten
ephemeralemptyDir: { sizeLimit }Eintrag tmpfs: auf Service-Ebene, der den Mount-Pfad nennt (im Arbeitsspeicher)Compose-tmpfs liegt im RAM; das emptyDir von helm liegt standardmäßig auf der Festplatte des Nodes — eine semantische Abweichung beim zugrunde liegenden Speichermedium. sizeLimit erreicht keinen Teil der compose-Ausgabe: Der ausgegebene Eintrag ist allein der Mount-Pfad. Ein vom Autor geschriebenes sizeLimit löst eine Warnung unsupported-field aus, die es nennt und die zusammen mit dem Build gemeldet statt in die erzeugte Datei geschrieben wird.
configmapVerweis auf ein ConfigMap-Volume (nutzt eine ConfigMap-Ressource, die von den artifacts: des Recipes oder von einem Feature ausgegeben wird)Verweis configs: auf Service-Ebene, der die Configmap nennt und am Pfad des Volume-Mounts eingehängt wird; der passende Top-Level-Eintrag configs: stammt aus den artifacts: des RecipesBeide Ziele verweisen über den Namen auf die Configmap, und keines liest ihren Inhalt, sodass die Authoring-Gestalt symmetrisch ist. Was compose verliert, ist die Update-on-Rollout-Semantik der K8s-ConfigMap: Eine compose-Config ist auf den Inhalt festgelegt, den der Build ausgegeben hat. Ein Verweis, den kein Top-Level-Eintrag auflöst, bricht den Build ab, statt einen Mount auszugeben, der zur Laufzeit ins Leere zeigen würde.
secretVerweis auf ein Secret-Volume (nutzt das Secret, das eine Credential-Anbindung nennt — eines, das sein FeatureRecipe ausgibt, oder eines, das bereits existiert)env_file: für Secrets in Env-Gestalt oder eine per Bind-Mount eingebundene Secret-Datei für Secrets in Pfad-GestaltCompose fehlt eine erstklassige Semantik für Kubernetes-Secrets. Ein Secret in Pfad-Gestalt nimmt bewusst nicht den Weg über configs: der Variante configmap: Ein Inline-Config-Eintrag würde den Wert des Secrets im Klartext in die ausgegebene compose-Datei schreiben, und der Compiler löst ein Secret nie in Klartext auf. Die Bind-Quelle ist ein Pfad, den der Operator auf dem compose-Host erreichbar macht, außerhalb jedes Lebenszyklus einer Vault-Fetch-CRD.
persistentPVC-Ressource + volume.persistentVolumeClaimBenanntes VolumeBenannte Volumes in Compose sind eine flache hostseitige Abstraktion; der PVC von helm unterstützt die Angabe von Storage-Class, Zugriffsmodus und Kapazität, die compose ignoriert.
persistentTemplateStatefulSet.volumeClaimTemplates (PVC pro Replikat; Begleiter von form: stateful)Benanntes Volume (herabgestuft — ein einziges gemeinsames Volume über alle Replikate, mit gemeldeter Warnung)Compose kann keine Templates pro Replikat ausdrücken. Wenn persistentTemplate für compose übersetzt wird, wird ein einziges benanntes Volume ausgegeben, und die verringerte Treue wird als Warnung zusammen mit dem Build gemeldet statt in die erzeugte Datei geschrieben. Workloads, die auf Volume-Isolation pro Replikat angewiesen sind, sollten keine reinen compose-Boundaries als Ziel haben.

Die Controller-Gestalt wird durch die form der Arbeitslast bestimmt, nicht durch ihre Volumes. Ein StatefulSet wird ausgegeben, wenn form: stateful gilt; ein Volume persistentTemplate ist ein Begleiter dieser Form — es deklariert Speicher pro Replikat für eine Arbeitslast, die bereits die Identität pro Replikat hat, die ein StatefulSet bereitstellt. Ein Volume persistentTemplate bei einer anderen Form (oder beim Standard stateless) zu deklarieren, ist ein Fehler zur Build-Zeit, der die Korrektur nennt: declare form: stateful. Umgekehrt ist es erlaubt — eine Arbeitslast mit form: stateful muss kein Volume persistentTemplate deklarieren. Autoren, die StatefulSet-Semantik wollen, setzen form: stateful direkt.

Eine Arbeitslast mit form: stateful auf dem helm-Provider benötigt einen headless steuernden Service: Deklarieren Sie genau einen Service mit type: Headless in derselben Workload. Der Provider verbindet den serviceName des StatefulSets mit diesem headless Service (er stellt die stabilen Netzwerkidentitäten pro Pod bereit, die ein StatefulSet benötigt). Der Build bricht ab, wenn kein headless Service deklariert ist — ein StatefulSet hätte dann keinen steuernden Service, den es nennen könnte — oder wenn mehr als einer deklariert ist, wodurch der steuernde Service mehrdeutig bliebe. Eine StatefulSet-Arbeitslast kann neben dem einen headless steuernden Service weiterhin zusätzliche nicht headless Services deklarieren (zum Beispiel einen Service ClusterIP für den Client-Zugriff).

Ressourcenmengen

Diese Werte der Workload sind Mengen — Beträge in der Notation, die Kubernetes für Ressourcen verwendet: die Werte resources.requests und resources.limits eines Containers (oder Init-Containers) für cpu, für memory und für jeden Schlüssel einer erweiterten Ressource sowie ephemeral.sizeLimit, persistent.size und persistentTemplate.size eines Volumes. Das Workload-Schema typisiert jeden davon als String und schränkt seine Form nicht ein. Der Provider, der die Workload für ein Ziel synthetisiert, prüft jede Menge, die er ausgibt, und er prüft die Workload so, wie die Templates des Recipes sie ausgewertet haben, sodass ein Wert, der über infra, einen Release-Parameter oder eine andere Template-Eingabe ankam, anhand des Strings beurteilt wird, zu dem er gerendert wurde.

Eine Menge ist, ohne etwas davor oder danach:

  • ein optionales Vorzeichen, + oder -;
  • eine Zahl mit mindestens einer Ziffer — 2, 0.5, .5 oder 1.;
  • höchstens eines von beiden: ein Exponent — e oder E, ein optionales Vorzeichen, dann Ziffern, wie in 1e3 oder 5E-2 — oder ein Einheitensuffix: ein dezimales Suffix n, u, m, k, M, G, T, P oder E (10⁻⁹ bis 10¹⁸, in Tausenderschritten) oder ein binäres Suffix Ki, Mi, Gi, Ti, Pi oder Ei (1024 bis 1024⁶).

500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n und 4u sind Mengen; lots, 1.5 cores, 1 gigabyte, 10 GB und 1e1.5 sind es nicht — ein Exponent ist eine ganze Zahl. Ein einzelnes E nach der Zahl ist das dezimale Suffix für 10¹⁸ (12E); gefolgt von Ziffern leitet es einen Exponenten ein (1E3).

Dies ist die Form, die der Mengen-Parser von Kubernetes selbst akzeptiert, mit einem bewussten Unterschied: Ein String, dessen Zahl keine Ziffer hat — m, Ki, +, ., e5 —, wird abgelehnt, während Kubernetes ihn als null liest. Genau diesen String hinterlässt ein Template, wenn der Wert, den es interpoliert, leer ist: "{{ .infra.cpu }}m" mit einem leeren cpu wird zu m gerendert. Ihn abzulehnen macht aus einer leeren Eingabe einen Abbruch, der das Feld nennt, statt einer Anforderung der Größe null, die niemand meldet.

Was jedes Ziel mit einer Menge macht:

  • helm gibt jede Menge unverändert aus, nachdem es jede anhand der obigen Form geprüft hat. Ein Wert außerhalb davon bricht den Build mit einem Fehler ab, der den Node, den Pfad des Feldes in der Workload — containers.main.resources.requests.cpu, initContainers[0].resources.limits.memory, volumes.data.persistent.size — und den Wert nennt. Siehe Helm Provider → Modus Workload (synthetisiert).
  • compose rechnet cpu und memory aus dem geparsten Wert in seine eigenen Einheiten um: cpus wird zu einer dezimalen Anzahl von Kernen (500m → 0.5) und memory zu einer exakten Byteanzahl (1.5Gi → 1610612736). Ein Wert, der keine Menge ist, bricht den Build ab, ebenso eine Menge, die compose nicht exakt darstellen kann — ein negativer Betrag, ein Speicherbetrag, der keine ganze Zahl von Bytes ist (1500m), oder ein CPU-Betrag, der feiner als neun Dezimalstellen eines Kerns ist —, und der Fehler sagt, auf welchen der beiden Fälle er gestoßen ist. Eine Anzahl nvidia.com/gpu wird auf dieselbe Weise gelesen und wird zu einer Geräteanzahl, sodass auch eine, die keine ganze Zahl von Geräten ist, den Build abbricht. compose gibt keine andere erweiterte Ressource und keine Volume-Größe aus und prüft daher keines von beiden: Jeder andere Schlüssel einer erweiterten Ressource und ein ephemeral.sizeLimit werden mit einer Warnung verworfen, und eine persistente Größe beeinflusst nichts in seiner Ausgabe. Siehe Compose Provider → Container-Ressourcen.

Die Prüfung beurteilt nur die Form. Ob ein Cluster den Betrag einplanen kann oder ob der Betrag zu seinem Gerät passt, liegt außerhalb davon.

services

Eine geordnete Map von Service-Freigaben. Jeder Service deklariert seinen Typ (ClusterIP, Headless, NodePort, LoadBalancer, Loopback) — wie weit seine Ports reichen — und eine Map benannter Ports. Portnamen müssen mit den Namen der Container-Ports übereinstimmen, die an anderer Stelle in der Workload deklariert sind:

services:
http:
type: ClusterIP
ports:
web: 8080 # must exist in containers.<name>.ports

Mehrere Services auf einer einzelnen Workload sind üblich, um internen und externen Traffic getrennt bereitzustellen (interner ClusterIP für Konsumenten innerhalb des Clusters, LoadBalancer für externen Traffic, ClusterIP für das Scraping durch Prometheus).

Wie weit die Ports eines Service reichen. Der type legt es fest, und jedes Ziel rendert es in seinen eigenen Begriffen:

typeReichweitehelmcompose
ClusterIPdie Peers der Arbeitslast, im eigenen Netzwerk des Zielsein Service vom Typ ClusterIPveröffentlicht nichts; Peers erreichen den Port im compose-Netzwerk
Headlessdasselbe, ohne Cluster-Adresseein Service vom Typ ClusterIP mit clusterIP: Noneveröffentlicht nichts
NodePortüber das eigene Netzwerk des Ziels hinausein Service vom Typ NodePortjeder Port auf jeder Host-Schnittstelle veröffentlicht, als <service port>:<container port>
LoadBalancerüber das eigene Netzwerk des Ziels hinausein Service vom Typ LoadBalancerwie bei NodePort
Loopbacknur die eigene Loopback-Adresse des Hostshält den Build an und nennt den Servicejeder Port auf der IPv4-Loopback-Adresse veröffentlicht, als 127.0.0.1:<service port>:<container port>

Die Nummer eines Service-Ports und der Container-Port, den er benennt, sind zwei Nummern, so wie port und targetPort eines Kubernetes-Service: helm schreibt die Nummer des Eintrags als port des Service und adressiert den Container-Port über seinen Namen, und compose veröffentlicht die Nummer des Eintrags auf dem Host auf die Nummer des Container-Ports. Sind die beiden Nummern gleich, schreibt compose diese Nummer auf beiden Seiten.

Loopback ist für einen Port gedacht, den etwas auf derselben Maschine erreicht — ein Browser oder ein Agent, der auf dem Host läuft — und den sonst nichts erreichen soll. Auf compose ist die Bindung allein die IPv4-Loopback-Adresse: Die IPv6-Loopback-Adresse ::1 wird nicht gebunden, adressieren Sie den Port also als 127.0.0.1 statt über einen Namen, der zu ::1 aufgelöst werden kann. Ein deklarierter Transport wird auf dem Eintrag wie bei jedem veröffentlichten Port geschrieben, etwa 127.0.0.1:5514:5514/udp.

Benennen zwei Einträge denselben Port, gewinnt die größere Reichweite: Ein Port, den ein NodePort- oder LoadBalancer-Eintrag veröffentlicht, wird auf jeder Schnittstelle veröffentlicht, auch wenn ein Loopback-Eintrag ihn ebenfalls benennt, unabhängig davon, welcher der beiden zuerst deklariert ist.

Auf helm hält ein Loopback-Eintrag den Build an, statt als etwas gerendert zu werden, das er nicht ist. Ein Kubernetes-Service hat keinen Typ, der an die Loopback-Adresse eines Hosts bindet — auf welchen Knotenadressen ein NodePort-Service lauscht, ist eine Einstellung des gesamten Clusters, nicht eines einzelnen Service —, sodass ein ClusterIP-Service die Reichweite verwerfen würde, die der Eintrag verlangt, und ein NodePort-Service den Port auf jeder Knotenadresse veröffentlichen würde, die der Cluster zulässt. Der Abbruch nennt den Knoten und den Service; siehe A service type the helm provider cannot render (Ein Service-Typ, den der helm-Provider nicht rendern kann).

Konvention für synthetisierte Namen. Wenn der helm-Provider die Services einer Workload synthetisiert, wird der metadata.name jedes Service deterministisch aus dem Namen abgeleitet, den der eigene Controller der Arbeitslast trägt, und aus dem Authoring-Schlüssel des Service. Für die Workload einer Komponente ist dieser Name der Release-Name des Knotens: <release name>-<service-key>. Der Release-Name ist die Identität der Komponente, geschrieben im Alphabet, das ein Kubernetes-Name zulässt — derselbe Name, gegen den ein Chart gerendert wird, in den Templates eines Recipe lesbar als {{ .context.rendered_name }} —, sodass er überall dort der instance_id entspricht, wo die Identität keinen Unterstrich und keinen Großbuchstaben enthält. Eine Workload, die services.http auf dem Knoten api-server deklariert, erzeugt einen Service namens api-server-http; dieselbe Workload auf dem Knoten billing erzeugt billing-http, und auf dem Knoten my_api erzeugt sie my-zuapi-http. Der Name der Ausgabedatei folgt derselben Konvention: <release name>-<service-key>-service.yaml. Ein Recipe, das die Adresse eines solchen Service veröffentlicht, bildet sie aus {{ .context.rendered_name }}, niemals aus {{ .context.instance_id }}, das überall dort keinen Service benennt, wo sich die beiden unterscheiden — siehe ../templates/rendered-resource-names.md.

Eine Workload, die das FeatureRecipe einer Feature-Anbindung synthetisiert, wird nach der eigenen zusammengesetzten Identität der Anbindung benannt statt nach einem Release-Namen: nach dem Wert, den ihre Ressourcen in ihrem Label aggrega.ai/component-id tragen, zusammengesetzt aus der Host-Komponente und dem unter features: geschriebenen Schlüssel, hinter dem einleitenden cfr--. Ein dort abgeleiteter Release-Name wäre der des Hosts und würde die Ressourcen der Anbindung nach denen des Hosts benennen. So erzeugt ein FeatureRecipe, dessen Workload services.scrape deklariert, für eine Anbindung stats auf dem Knoten front-door ein Deployment cfr--front-door--stats und einen Service cfr--front-door--stats-scrape. Dieses erste Segment entspricht niemals der instance_id, und kein Schlüssel im Template-Kontext des FeatureRecipe enthält es: In den Templates einer Anbindung benennen {{ .context.rendered_name }} und {{ .context.instance_id }} beide den Host (front-door), und {{ .attachment_name }} ist allein der Schlüssel (stats), sodass {{ .context.rendered_name }}-scrape den eigenen scrape-Service des Hosts benennt, wo der Host einen deklariert, und niemals den der Anbindung — siehe ../templates/rendered-resource-names.md. Die Ausgabedatei steht hinter dem Präfix, das jede von einer Anbindung ausgegebene Datei trägt — der Name des Hosts und der der Anbindung, jeweils gefolgt von -- —, sodass dieser Service nach front-door--stats--cfr--front-door--stats-scrape-service.yaml geschrieben wird.

Die Konvention hat zwei praktische Folgen. Erstens sind Kollisionen zwischen Knoten konstruktionsbedingt ausgeschlossen — das Namenspräfix unterscheidet die Services über alle Knoten der Boundary hinweg, weil zwei verschiedene Identitäten stets zu zwei verschiedenen Release-Namen führen, die Identität einer Anbindung sowohl ihren Host als auch ihren Schlüssel enthält und kein Komponentenname mit cfr-- beginnen darf (der Build hält bei einem solchen an — siehe Component identity cannot be stamped on what it emits (Die Identität der Component kann dem, was sie ausgibt, nicht aufgeprägt werden)), sodass zwei Workloads, die jeweils services.http deklarieren, unterschiedliche K8s-Service-Ressourcen mit sich nicht überschneidenden Namen erzeugen. Der einzige Rest ist eine Identität einer Anbindung, die für das Ziel zu lang ist: Sie wird um einen Digest des Ganzen herum gekürzt, und zwei gekürzte Identitäten können prinzipiell zusammenfallen — siehe Provenienz-Labels in der gerenderten Ausgabe. Zweitens kann eine Workload einen Service-Schlüssel nicht zweimal deklarieren — eine services:-Map, die einen Schlüssel zweimal nennt, wird beim Parsen des Workload-YAML abgelehnt, und der Build hält an und nennt den Schlüssel und seine Zeile.

Das verbleibende Kollisionsrisiko liegt an der Grenze der Namenslänge in K8s: Kubernetes-Service-Namen sind auf 63 Zeichen begrenzt, und die synthetisierte Form <release name>-<service-key> kann diese Grenze überschreiten, wenn beide Segmente lang sind. Der Aggrega-Compiler erzwingt die Grenze nicht; der Build gibt den Service aus, und Kubernetes weist ihn ab, wenn er angewendet wird. Autoren mit tief verschachtelten Instanz-IDs (z. B. data-layer.regional.eu-west.primary) und langen Service-Schlüsseln sollten die kombinierte Länge unter 63 Zeichen halten. Dasselbe gilt für die Workload einer Anbindung: Eine zusammengesetzte Identität, die für das Ziel zu lang ist, wird gekürzt, der daran angehängte Service-Schlüssel jedoch nicht, sodass ein Service einer Anbindung mit einem langen Schlüssel dennoch 63 Zeichen überschreiten und ohne Abbruch gebaut werden kann.

Provider-spezifischer Hinweis (compose). Der compose-Provider leitet depends_on automatisch aus den uses-Kanten der IR ab. Diese Einträge werden ohne Bedingung ausgegeben — sie haben service_started-Semantik, unabhängig davon, ob das Ziel einen Healthcheck deklariert —, sodass ein Service, dessen Abhängigkeiten alle aus uses-Kanten stammen, die Liste in Kurzform ausgibt (depends_on: [<target>]). Einen aus einer Kante abgeleiteten Eintrag an die Gesundheit des Ziels zu knüpfen, ist nicht implementiert. Die Langform wird dort ausgegeben, wo ein Eintrag tatsächlich eine Bedingung trägt, und so wird das Warten auf einen Init-Container ausgedrückt; siehe providers/compose.md.

Transportprotokolle von Ports

Ein Container-Port wird in einer von zwei gleichwertigen Formen geschrieben. Die bloße Nummer ist die Kurzform und deklariert keinen Transport, sodass das Ziel seinen eigenen Standard anwendet — TCP auf jedem Ziel, das einen hat:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080

Die erweiterte Form enthält Nummer und Transport zusammen und ist das, was ein Port braucht, wenn er etwas anderes als diesen Standard überträgt:

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080 # short form — no transport declared
dns:
port: 53
protocol: UDP # TCP | UDP | SCTP
sigtran:
port: 2905
protocol: SCTP

Die beiden Formen dürfen innerhalb einer ports-Map frei gemischt werden, und ein Port ohne zu deklarierenden Transport bleibt in der Kurzform.

Der Transport wird einmal deklariert, am Container-Port. Ein Eintrag services.<service>.ports benennt einen Container-Port und übernimmt dessen Transport, sodass eine Service-Freigabe nicht vom Port abweichen kann, den der Container geöffnet hat. Es gibt keinen Schlüssel protocol an einem Service-Port, und einen zu schreiben wird abgelehnt.

Warum das Feld existiert. Zielplattformen behandeln einen nicht angegebenen Transport als den Stream-Transport. Eine Komponente, die einen Datagramm-Port braucht — Echtzeit-Medien, Telefonie, Namensauflösung, private Netzwerke, ein Spieleserver —, könnte sonst nur die Nummer deklarieren, und der Stack würde bereitgestellt, während jede Prüfung bestanden wird und sich kein Client verbindet, weil der Traffic aus Datagrammen besteht und der geöffnete Port nicht. Erst die Deklaration des Transports macht das ausdrückbar.

Der Compiler interpretiert den Wert nicht. Er liest keinen Transport aus dem Namen eines Ports und prüft den deklarierten Transport nicht gegen das, was der Prozess hinter dem Port tatsächlich spricht: Der Wert sind Daten, die Sie deklarieren und die die Engine des Ziels ausgibt. Ein Port namens dns ohne Schlüssel protocol ist ein TCP-Port, und ein Port namens web, der protocol: UDP deklariert, ist ein UDP-Port.

Verhalten je Ziel.

ZielEin Port ohne deklarierten TransportEin deklarierter Transport
helmcontainerPort und der Service-Port tragen keinen Schlüssel protocolunverändert als protocol: am Container-Port und an jedem Service-Port ausgegeben, der ihn benennt
composeveröffentlicht als <host>:<container>, unverändertveröffentlicht als <host>:<container>/tcp oder /udp; SCTP hat keine compose-Schreibweise und hält den Build an, statt einen Port zu veröffentlichen, der einen anderen Transport tragen würde

Ein Container-Port, den kein Service veröffentlicht, erreicht überhaupt keinen Teil einer compose-Datei — das ist das übliche Verhalten von compose für Container-Ports —, sodass ein auf einem solchen Port deklarierter Transport nirgends geschrieben werden kann und keinen Abbruch auslöst.

Health-Probes — Form der Absicht

Jeder Container deklariert seine Probes unter seinem eigenen Schlüssel health: (containers.<name>.health) in einer abstrakten Absichtsform; die Workload hat kein health auf oberster Ebene. Jeder Provider übersetzt die Absicht zum Zeitpunkt der Synthese in seine native Probe-Form.

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

Drei Absichtsformen (http:, tcp:, exec:) schließen sich innerhalb einer einzelnen Probe-Deklaration gegenseitig aus. Die Port-Auflösung für http: ohne expliziten Port nimmt den alphabetisch ersten Namen eines Ports, den der Container unter containers.<name>.ports deklariert — dieselbe Regel auf beiden Zielen, sodass eine Probe denselben Port liest, gleich welches Ziel sie rendert. Ein Container, der keinen benannten Port deklariert, kann keine HTTP-Probe tragen: Der Build hält mit einem Übersetzungsfehler an, der die betreffende Probe nennt.

Übersetzung je Provider. Jeder Provider übersetzt die abstrakte Probe-Absicht zum Zeitpunkt der Synthese in seine native Form:

AbsichtHelm (K8s)ComposeHinweise zu Verlusten
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"Compose fehlt eine native HTTP-Probe-Form; der CMD-SHELL-Wrapper setzt voraus, dass curl im Container-Image vorhanden ist.
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"Compose fehlt eine native TCP-Probe-Form; der CMD-SHELL-Wrapper setzt voraus, dass nc im Container-Image vorhanden ist.
exec: [cmd, ...]exec.command: [cmd, ...]CMD [cmd, ...]Eins-zu-eins-Abbildung; beide Provider übernehmen die Befehlsliste unverändert.

Die CMD-SHELL-Wrapper von Compose bilden HTTP- und TCP-Probes über in der Shell auswertbare Prädikate nach. Was compose fehlt, ist die native Probe-Form, nicht die Zeitfelder: Geschriebene periodSeconds, timeoutSeconds, failureThreshold und initialDelaySeconds werden als interval, timeout, retries und start_period in den Healthcheck übernommen — der Abschnitt „Probes“ in providers/compose.md enthält die Zuordnung Feld für Feld. Die native exec:-Form braucht überhaupt keinen Wrapper und wird auf beiden Zielen eins zu eins übersetzt.

Eine umhüllte Probe wird stillschweigend übersetzt: Nichts in der ausgegebenen docker-compose.yaml kennzeichnet sie, und keine Diagnose meldet die Umhüllung. Was der Build auf diesem Pfad meldet, ist ein Probe-Slot, der überhaupt keine Ausgabe erreicht — ein compose-Service trägt einen einzigen Healthcheck, sodass dort, wo eine Workload mehr als einen von ready:, live: und startup: deklariert, nur der bevorzugte Slot übersetzt wird (live vor ready vor startup) und eine Warnung unsupported-field den übersetzten Slot und die verworfenen Slots nennt.

Provider-spezifischer Hinweis (compose). Ein health:-Block auf einer Workload mit compose als Ziel knüpft die depends_on-Reihenfolge nicht an die Gesundheit: Die depends_on-Einträge des compose-Providers, die aus uses:-Kanten abgeleitet werden, verwenden immer service_started-Semantik, unabhängig davon, ob die Ziel-Workload Health-Probes deklariert. Diese Einträge an die Gesundheit des Ziels zu knüpfen, ist nicht implementiert — die Langform, die eine solche Bedingung tragen würde, wird selbst ausgegeben, für das Warten auf Init-Container, sodass nicht die Form fehlt, es auszudrücken, sondern die Entscheidung, eine Kante an die Gesundheit zu knüpfen. Siehe providers/compose.md für die vollständigen Ableitungsregeln.

K8s-förmige Durchreichfelder — scheduling, serviceAccount, podSecurityContext

Das Workload-Schema akzeptiert drei optionale Felder auf oberster Ebene, die vor allem dazu dienen, Kubernetes-native Primitive durch den helm-Provider durchzureichen und dabei die strukturelle Form von Aggrega zu bewahren. Der compose-Provider übersetzt die Teilmenge, die ein Compose-Gegenstück hat, und ignoriert den Rest mit einer ausgegebenen Warnung. Aggrega validiert die äußere Form, überwacht aber nicht den inneren Inhalt (siehe Validierungsoberfläche weiter unten) — die K8s-nativen inneren Werte werden unverändert in die von helm gerenderte Pod-Spec durchgereicht.

scheduling

scheduling fasst vier K8s-native Scheduling-Primitive — nodeSelector, affinity, tolerations, topologySpreadConstraints — in einem nach Zweck gegliederten Block zusammen. Jedes Unterfeld hat genau die Form des entsprechenden Kubernetes-Pod-Spec-Felds:

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
nodeSelector:
disktype: ssd
region: us-east-1
tolerations:
- key: dedicated
operator: Equal
value: gpu-workloads
effect: NoSchedule
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels: { app: "{{ .context.instance_id }}" }
topologyKey: kubernetes.io/hostname
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
containers:
app: { image: "..." }

Übersetzung durch den Provider. Der helm-Provider reicht jedes Unterfeld unverändert in die gerenderte Pod-Spec durch. Der compose-Provider übersetzt keines der vier: Er lässt den gesamten Block scheduling weg, und eine Warnung nennt ihn.

serviceAccount

serviceAccount ist ein einfacher String mit dem Namen des ServiceAccount, unter dem die Arbeitslast läuft:

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .context.rendered_name }}-runner"
containers:
app: { image: "..." }

Der Name wird aus {{ .context.rendered_name }} gebildet, dem Release-Namen, nach dem der helm-Provider die eigenen Ressourcen der Arbeitslast benennt, sodass es ein Name ist, den der Cluster akzeptiert, wie auch immer die Komponente heißt. Das Feld verweist auf einen bestehenden ServiceAccount; es erstellt keinen. Die zugehörigen RBAC-Ressourcen (das ServiceAccount-Objekt selbst sowie Role / RoleBinding / ClusterRole / ClusterRoleBinding) sollten über einen von zwei Kanälen ausgeliefert werden:

  • Recipe artifacts: — wenn die RBAC diesem Recipe inhärent ist (das Recipe weiß, dass es eine bestimmte Role für eine bestimmte Aufgabe braucht).
  • Features mit Ressourcengenerierung — wenn die RBAC übergreifend ist (ein Workload-Identity-FeatureRecipe, das IAM-gebundene ServiceAccounts an jede Komponente mit einem bestimmten Label anhängt).

serviceAccount: zu setzen, ohne dafür zu sorgen, dass der benannte ServiceAccount existiert, führt zu einem K8s-Laufzeitfehler beim Anwenden, nicht zu einem Fehler zur Build-Zeit — die Schema-Validierung der Arbeitslast prüft nicht, ob der ServiceAccount existiert (kein Zugriff auf den Cluster-Zustand zur Kompilierzeit gemäß der AOT-Reinheits-Invariante).

Der compose-Provider ignoriert serviceAccount: mit einer Warnung; Compose hat kein gleichwertiges Konzept der Identitätsbindung.

podSecurityContext

podSecurityContext enthält Sicherheitsprimitive auf Pod-Ebene — UID, GID, fsGroup, supplementalGroups —, die für jeden Container im Pod gelten:

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
supplementalGroups: [4000, 5000]
containers:
app: { image: "..." }

Feldsemantik. Alle vier Felder sind Ganzzahlen (numerische UIDs/GIDs, keine Strings); runAsUser und runAsGroup setzen die effektive UID/GID der Container-Prozesse; fsGroup setzt die Gruppenzugehörigkeit für in den Pod eingehängte Volumes; supplementalGroups fügt der Prozessgruppe jedes Containers zusätzliche GIDs hinzu.

Übersetzung durch den Provider. Der helm-Provider reicht den Block unverändert in die gerenderte Pod-Spec durch. Der compose-Provider hat kein Gegenstück für fsGroup oder supplementalGroups und lässt beide jeweils mit einer Warnung weg; runAsUser/runAsGroup werden auf jedem Service, den die Workload erzeugt, Sidecars und Init-Container eingeschlossen, in die Compose-Form user: 1000:3000 übersetzt, und eine runAsGroup ohne runAsUser daneben wird mit einer Warnung weggelassen. Jeder Container und Init-Container trägt außerdem einen eigenen securityContext — runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation sowie capabilities.add / capabilities.drop. Der helm-Provider gibt ihn am Container aus; der compose-Provider gibt readOnlyRootFilesystem als read_only aus, capabilities.add / capabilities.drop als cap_add / cap_drop und runAsUser / runAsGroup als eigenen user des Containers, der an die Stelle des Pod-Werts tritt; er lässt runAsNonRoot, allowPrivilegeEscalation und eine ohne runAsUser geschriebene runAsGroup jeweils mit einer Warnung weg und warnt auch dort, wo der eigene runAsUser eines Containers die runAsGroup des Pods auslässt. providers/compose.md enthält die Zuordnung Feld für Feld.

GPU- und Geräte-Arbeitslasten

Eine Arbeitslast, die spezialisierte Hardware braucht — eine GPU oder ein anderes vom Hersteller bereitgestelltes Gerät —, drückt zwei unabhängige Belange aus: die Laufzeit auf Pod-Ebene, die der gerätefähige Knoten bereitstellt (runtimeClassName), und die Menge des Geräts pro Container, die die Arbeitslast beansprucht (ein Extended-Resource-Schlüssel unter resources eines Containers). Eine typische GPU-Arbeitslast deklariert beides zusammen, aber jedes steht für sich, und jedes kann ohne das andere vorkommen.

Beide Felder beschreiben Rechenressourcen — den Pod und den Container, der auf dem Gerät läuft —, daher gehören sie auf eine Arbeitslast, die Container ausführt. Eine Arbeitslast, die nur einen externen Endpunkt trägt und keine eigenen Container deklariert, hat keinen Pod und keinen Container, an den sie angehängt werden könnten: runtimeClassName auf einer solchen reinen Endpunkt-Arbeitslast zu setzen, hält den Build an und nennt runtimeClassName und das Recipe, dessen Workload es deklariert hat, und ohne Container gibt es keinen Ort für eine Geräte-Ressourcenanforderung.

runtimeClassName

runtimeClassName ist ein einzelner String, der die RuntimeClass benennt, unter der der Pod läuft — die Container-Laufzeit, die ein gerätefähiger Knoten bereitstellt, zum Beispiel eine GPU-Laufzeit namens nvidia. Es ist ein Selektor auf Pod-Ebene: Er gilt für jeden Container der Arbeitslast. Der Compiler reicht den Namen unverändert als deterministischen Zeiger durch; der Cluster löst ihn zum Scheduling-Zeitpunkt in eine RuntimeClass auf, die sein Administrator konfiguriert hat. Aggrega prüft nicht, ob eine passende RuntimeClass existiert — es hat zur Kompilierzeit keinen Zugriff auf den Cluster-Zustand —, sodass ein Name ohne konfigurierte RuntimeClass beim Anwenden als Scheduling-Fehler auftritt, nicht als Fehler zur Build-Zeit.

Extended-Resource-Schlüssel

resources.requests und resources.limits eines Containers tragen die gewöhnlichen Mengen cpu und memory und daneben Extended-Resource-Schlüssel: hersteller- oder domänenbezogene Gerätemengen, deren Schlüssel ein vollqualifizierter Name <domain>/<name> ist, etwa nvidia.com/gpu oder amd.com/gpu. Das Domänensegment enthält mindestens einen Punkt, und dieser Punkt unterscheidet einen erweiterten Schlüssel (nvidia.com/gpu) von den bloßen Mengen cpu und memory. Jeder Wert ist eine Mengenangabe als String ("1", "2"), die der Compiler unverändert durchreicht, und der helm-Provider prüft ihre Form, bevor er sie ausgibt (siehe Ressourcenmengen); das Device-Plugin des Clusters löst das Gerät zum Scheduling-Zeitpunkt auf und weist es zu.

Ausgearbeitetes Beispiel — eine GPU-Inferenz-Arbeitslast

apiVersion: aggrega.ai/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

Die Arbeitslast wählt für ihren Pod die Laufzeit nvidia und beansprucht eine GPU für den Container inference. Die GPU-Menge erscheint sowohl in requests als auch in limits: Ein Gerät ist nicht überbuchbar, daher werden Anforderung und Limit auf denselben Wert gesetzt.

Übersetzung durch den Provider. Dies sind Kubernetes-native Konzepte. Der helm-Provider gibt runtimeClassName an der gerenderten Pod-Spec aus und jeden Extended-Resource-Schlüssel unverändert unter resources.requests / resources.limits des Containers, sodass sie den Cluster über die Kubernetes-Ausgabe erreichen. Der compose-Provider reserviert eine nvidia.com/gpu-Anzahl als ebenso viele NVIDIA-GPUs auf dem Service des Containers (siehe Compose Provider → Container-Ressourcen); ein einzelner Host kennt kein Runtime-Class-Konzept und kein Gegenstück für irgendeinen anderen Extended-Resource-Schlüssel, sodass eine Arbeitslast, die runtimeClassName oder einen anderen Schlüssel deklariert, auf einem compose-Ziel ohne ihn gerendert wird.

Ausführung im Netzwerk des Knotens

Standardmäßig läuft eine Arbeitslast in einem eigenen Netzwerk-Namespace: Ihre Container sehen nur ihre eigenen Schnittstellen, und der Datenverkehr erreicht sie über die Adressübersetzung des Ziels. hostNetwork: true fordert die andere Anordnung an – die Arbeitslast läuft im eigenen Netzwerk-Namespace des Knotens, sieht also die Schnittstellen des Knotens, und die Ports, die ihre Container öffnen, sind über die eigenen Adressen des Knotens erreichbar, ohne Übersetzung dazwischen.

Genau das benötigt eine ganze Klasse von Software. Echtzeitmedien, Telefonie, virtuelle private Netzwerke und ähnlicher Datenverkehr tragen die Adresse der Gegenstelle in der Nutzlast, sodass eine unterwegs umgeschriebene Adresse beim Empfänger einen Ort beschreibt, den die Gegenstelle nicht erreichen kann; die Ausführung auf den Adressen des Knotens ist es, die beides konsistent hält.

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

Was es deklariert und was nicht

hostNetwork wählt einen Netzwerk-Namespace, und das ist alles.

  • Es deklariert keine Ports. Die Ports, die eine Arbeitslast öffnet, werden weiterhin unter containers.<name>.ports deklariert, genau wie ohne es, und sie bedeuten weiterhin dasselbe. Die Deklaration von hostNetwork fügt weder einen Port hinzu noch entfällt dadurch die Notwendigkeit, einen zu deklarieren.
  • Es deklariert keine Anzahl von Ports. Eine Anwendung, die viele zusammenhängende Ports benötigt – etwa ein Medienserver, der einen Bereich nach der Prozessoranzahl einer Maschine bemisst –, konfiguriert diesen Bereich in ihrem eigenen Konfigurationsinhalt, aus Werten, die ihr Betreiber liefert, auf dieselbe Weise, wie sie alles andere konfiguriert, was sie beim Start liest. Das ist eine Einstellung der Anwendung und nicht der Arbeitslast, und der Vertrag der Arbeitslast ist nicht der Ort, an dem sie steht.
  • Nichts wird abgeleitet. Der Compiler liest keine Bedeutung aus dem Wert und leitet ihn aus nichts anderem ab: nicht aus dem Namen eines Ports, nicht aus dem Typ oder den Labels einer Komponente, nicht daraus, wie viele Ports deklariert sind. Eine Arbeitslast läuft im Netzwerk des Knotens dann und nur dann, wenn sie es angibt.

Da es Rechenressourcen beschreibt, gehört hostNetwork zu einer Arbeitslast, die Container ausführt. Eine Arbeitslast, die nur einen externen Endpunkt enthält, deklariert keine Container und hat daher keinen Netzwerk-Namespace, den sie wählen könnte: Die Deklaration von hostNetwork auf einer reinen Endpunkt-Arbeitslast bricht den Build ab und nennt dabei hostNetwork und das Recipe, dessen Workload es deklariert hat.

Übersetzung durch den Provider

Der helm-Provider gibt hostNetwork: true in der gerenderten Pod-Spezifikation aus, so wie Kubernetes dieselbe Wahl ausdrückt. Die Deklaration erreicht die Pod-Spezifikation und sonst nichts – die ausgegebenen Services sind mit und ohne sie identisch.

Der compose-Provider gibt network_mode: host auf dem eigenen Dienst der Arbeitslast aus. Daraus, wie compose Netzwerke modelliert, folgt eine Konsequenz: Ein Dienst in diesem Modus ist nicht an das Boundary-Netzwerk angeschlossen, weil compose das Anschließen an ein Netzwerk und das Übernehmen des Host-Namespace als Alternativen und nicht als Ergänzungen behandelt. Seine Gegenstellen erreichen ihn daher über die eigenen Adressen des Hosts statt über den Dienstnamen – was Host-Networking auf jedem Ziel bedeutet –, und jeder andere Dienst der Boundary bleibt unberührt.

Zwei Formen lassen sich auf diesem Ziel damit kombinieren. Ein Sidecar-Container folgt dem Hauptdienst ohne eigene Deklaration in das Netzwerk des Hosts, weil er den Namespace des Hauptdienstes übernimmt, indem er ihn benennt. Ein Init-Container tut das nicht: Er wird zu einem Dienst, auf den der Hauptdienst wartet, und tritt daher aus eigenem Recht dem Boundary-Netzwerk bei, statt einen Namespace zu übernehmen, der dieses Warten zirkulär machen würde. Eine Arbeitslast, die sowohl hostNetwork als auch initContainers deklariert, führt ihren eigenen Dienst daher im Netzwerk des Knotens aus, während ihre Init-Dienste im Boundary-Netzwerk bleiben – eine engere Anordnung als der eine gemeinsame Namespace, den die Pod-Form bietet, und eine, die der compose-Provider in einer Warnung unsupported-field benennt, statt sie zur Laufzeit entdecken zu lassen.

Eine Arbeitslast, die hostNetwork nicht deklariert, enthält keinen solchen Schlüssel in ihrer Ausgabe: Der Schlüssel fehlt, statt als false ausgegeben zu werden.

Integration der Anbindungen mit dem featuresSchema der Component

Der Block containers.<name>.attachments der Workload verweist auf Zugangsdaten-Slots, die im featuresSchema der Component deklariert sind – oder, bei einem Eintrag, der eine Verbindung nennt, auf einen Slot, den der Socket dieser Verbindung deklariert (siehe Zugangsdaten zustellen, die eine Verbindung trägt); er deklariert keine neuen Slots. Siehe ../entities/component.md für die Authoring-Oberfläche von featuresSchema. from benennt den Slot; es ist nicht der Name des generierten Secrets.

Ein Eintrag in containers.<name>.attachments wird zu einem Verweis auf eine Secret-Ressource gerendert – ein Kubernetes-secretKeyRef (für as: env) oder ein Secret-gestütztes Volume (für as: file) –, die beide über den Namen auf das Secret zeigen. Der Synthesizer löst diesen Namen und den Datenschlüssel aus den bereitgestellten provides des Slots auf: Das gerenderte secretKeyRef.name des Eintrags ist das .features.<slot>.provides.name des Slots, und der Datenschlüssel ist .features.<slot>.provides.key. Der Recipe-Autor schreibt nur from: <slot> und as: env; der Synthesizer liest die aufgelösten provides – er leitet den Namen nicht erneut ab. Es ist dasselbe Lesen von .features.<slot>.provides.<key>, das ein Source-Recipe für ein existingSecret verwendet: Ein einzelner Zugangsdaten-Slot versorgt einen Source-Recipe-Verbraucher und einen Verbraucher einer synthetisierten Workload identisch (Source/Workload-Symmetrie).

Vier Validierungsregeln bestimmen die Integration:

  • Jeder Wert von attachments.<KEY>.from muss einem Slot-Namen entsprechen, der im featuresSchema der Component deklariert ist – oder, bei einem Eintrag, der eine Verbindung nennt, im Socket dieser Verbindung. Ein unbekannter Slot-Name ist ein Fehler zur Ladezeit.
  • Der Zustellmechanismus as: (env oder file) muss in der von der Component deklarierten Allowlist inject: des Slots vorkommen. Eine Workload, die as: file für einen Slot deklariert, dessen Eintrag in featuresSchema inject: [env] angibt, ist ein Fehler zur Ladezeit.
  • Slots, die im featuresSchema der Component mit inject: [] (Blackbox-Zustellung) markiert sind, dürfen überhaupt nicht in attachments:-Blöcken einer Workload vorkommen. Diese Slots werden durch die interne Verdrahtung des Recipe zugestellt (etwa über den Parameter existingSecret eines Helm-Charts), nicht über die Bereitstellung in der Workload.
  • Der referenzierte Slot muss referenzierbar sein – seine Füllung muss einen provides-Lokator (name, key) für eine Secret-Ressource veröffentlichen, eine, die ihre Realisierung ausgibt, oder eine, die bereits existiert. Ein Slot, der durch per Inject zugestellte Zugangsdaten gefüllt wird (die einen Wert in die Inject-Pipe schreiben und keinen Lokator veröffentlichen), hat nichts, worauf verwiesen werden könnte; ihn aus einem attachments:-Eintrag einer Workload zu referenzieren, ist ein Fehler zur Ladezeit. Per Inject zugestellte Zugangsdaten erreichen den Container über die Inject-Pipe des Slots (ein Eintrag in variables, der .context.inject.env.<KEY> liest), nicht über einen attachments:-Eintrag.

Hinweis zum Provider. Helm rendert den oben beschriebenen secretKeyRef/Secret-Volume-Verweis. Der compose-Provider hat kein natives Primitiv für Umgebungsvariablen aus Secrets; ein Anbindungseintrag as: env auf einer Workload, die auf compose zielt, wird als Umgebungseintrag mit leerem Wert und einer Warnung gerendert, die den Eintrag nennt (siehe die Seite zum compose-Provider), während die Referenzierbarkeitsregel (agnostisch gegenüber Fähigkeiten) weiterhin gilt.

Beispiel:

# In the Component catalog entity
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe's Workload
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected at load time: blackbox slot

Zugangsdaten zustellen, die eine Verbindung trägt

Der Socket einer Component kann in usesSchema.<socket>.featuresSchema die Slots deklarieren, die jede über ihn verdrahtete Verbindung füllt – sodass eine Komponente, die mehrere Ziele erreicht, einen Satz Zugangsdaten pro Verbindung hält statt einen für alle. Eine solche Anbindung gehört nicht zu den eigenen .features der Komponente; sie liegt unter ihrer Verbindung, bei .context.uses.<alias>.features.<slot>. Ein Eintrag der Workload stellt sie zu, indem er die Verbindung neben dem Slot nennt:

  • in einem Eintrag attachments eines Containers connection: <alias> neben from: <slot>;
  • in einem Eintrag envFrom eines Containers connection: <alias> neben secret: <slot> – connection wird nur neben secret akzeptiert.

Beide Formen werden auf jedem Container und jedem Init-Container akzeptiert. <alias> ist der Name, unter dem die Verbindung im Block uses der Komponente geschrieben ist, im Aggregate oder im Release – der Schlüssel, unter dem ein Recipe die Verbindung unter .context.uses liest –, und <slot> ist ein Slot, den der Socket deklariert, über den diese Verbindung verdrahtet ist.

Bevor eine der obigen Regeln die Workload liest, wird jeder Eintrag, der eine Verbindung nennt, auf den Namen umgeschrieben, den die Anbindung, die diese Verbindung in diesem Slot trägt, an der Komponente annimmt: der Alias, ein Punkt und der Slot (gpt.credential). Jede Regel läuft dann auf dem umgeschriebenen Eintrag genau so, wie sie auf einem Eintrag läuft, der einen der eigenen Slots der Component nennt: Die Allowlist inject: des Socket-Slots bestimmt as:, ein Socket-Slot, der inject: [] deklariert, kann nicht referenziert werden, die Anbindung, die ihn füllt, muss referenzierbar sein, und der Provider löst den Namen des Secrets und den Datenschlüssel aus den aufgelösten provides dieser Anbindung auf – sodass der Eintrag jeder Verbindung auf die eigenen Zugangsdaten dieser Verbindung verweist. Ein Socket-Slot, der sensitive: true deklariert, wird für den Eintrag genau so gelesen wie die Deklaration eines Slots der Component. Der umgeschriebene Eintrag ist das, was der Provider erhält; der Schlüssel connection erreicht ihn nicht.

Drei Einträge werden abgewiesen, jeweils unter Nennung dessen, was sie genannt haben:

  • ein Eintrag, der eine Verbindung nennt, die die Komponente nicht zieht – die Abweisung nennt die Verbindung, den Slot und die Verbindungen, die die Komponente zieht;
  • ein Eintrag, der einen Slot nennt, den der Socket der Verbindung nicht deklariert – die Abweisung nennt den Slot, die Verbindung, den Socket und die Slots, die er deklariert;
  • ein Eintrag, der den zusammengesetzten Namen (from: gpt.credential) selbst schreibt. Der Slot einer Verbindung wird benannt, indem man die Verbindung nennt, sodass der zusammengesetzte Name nie ein zweiter Weg ist, ihn zu erreichen.

Eine Verbindung, die im Slot keine Anbindung trägt, lässt den Eintrag ohne etwas, worauf er verweisen könnte, und die Referenzierbarkeitsregel weist ihn ab. Eine Workload, die ein FeatureRecipe rendert, ist an die Slots gebunden, die das Feature deklariert, das es implementiert, und diese erreichen keine der Verbindungen der Host-Komponente; ein Eintrag dort, der eine Verbindung nennt, wird daher abgewiesen, da er eine nennt, die die Komponente nicht zieht.

Beispiel:

# In the Component catalog entity
spec:
usesSchema:
models:
featuresSchema:
credential:
sensitive: true
inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`
# through the `models` socket, each carrying its own `credential`
workload: |
containers:
main:
attachments:
MODEL_KEY_GPT:
from: credential
connection: gpt
as: env
MODEL_KEY_NIM:
from: credential
connection: nim
as: env

Bei helm wird MODEL_KEY_GPT als secretKeyRef gerendert, der das Secret nennt, das die Zugangsdaten der Verbindung gpt veröffentlicht haben, und MODEL_KEY_NIM als derjenige, der das Secret der Verbindung nim nennt. Bei compose wird ein Eintrag as: env, der eine Verbindung nennt, mit leerem Wert und demselben Hinweis auf teilweise Unterstützung ausgegeben, den ein Eintrag erhält, der einen der eigenen Slots der Component nennt.

Validierungsoberfläche

Jede Workload wird zur Ladezeit des Recipe validiert, bevor irgendein Rendering läuft. Die Validierung hat zwei Stufen:

  • Schema-Validierung. Der Wert der Workload wird mit dem eingebetteten Workload-Schema aggrega.ai/v1beta1 vereinheitlicht. Fehler enthalten den Feldpfad und die verletzte Einschränkung (zum Beispiel .containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). Die Schema-Validierung setzt jeden Typ, jede Aufzählung, jeden Bereich und jede Disjunktion durch, die im Schema deklariert sind – einschließlich des Controller-form mit geschlossener Menge (eines von stateless, stateful, daemon, scheduled, task, reference), des Dienst-type mit geschlossener Menge (eines von ClusterIP, Headless, NodePort, LoadBalancer, Loopback), des ganzzahligen Portbereichs (1..65535), der Disjunktion der Probe-Form (genau eines von http, tcp, exec) und der Disjunktion der Volume-Variante (genau eines von ephemeral, configmap, secret, persistent, persistentTemplate).
  • Validierung der Querverweise. Die Anbindungsverweise der Workload werden gegen das featuresSchema der Component geprüft – und, bei einem Eintrag, der eine Verbindung nennt, gegen die Slots, die der Socket dieser Verbindung deklariert – (Slot-Zugehörigkeit, Zustell-Allowlist as:, Blackbox-Ausschluss) sowie gegen die aufgelösten provides jedes referenzierten Slots (Referenzierbarkeit – die Füllung muss name/key veröffentlichen). Das sind entitätsübergreifende Prüfungen, die eine reine Schema-Validierung nicht durchführen kann.

Beide Stufen erzeugen dieselbe Meldungsform mit dem Präfix CATALOG_ERROR; Fehlschläge brechen den Build ab, bevor irgendeine Rendering-Ausgabe erzeugt wird. Recipe-Autoren erhalten gezielte Rückmeldungen, die das genaue Feld identifizieren, das fehlgeschlagen ist, und die Einschränkung, die es abgewiesen hat.

Die durchgereichten Felder in K8s-Form (scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, die items-Listen in ConfigMap- und Secret-Volumes, Lifecycle-Hooks mit httpGet) werden nur strukturell validiert – das Schema von Aggrega schränkt ihr Vorhandensein und ihre äußere Form ein, aber die innere Form dieser durch die K8s-API definierten Werte liegt in der Verantwortung des Providers (der helm-Provider übergibt sie unverändert an die K8s-Pod-Spezifikation; der compose-Provider weist sie je nach Fall ab oder schwächt sie ab). Eine Workload mit einem fehlerhaft geformten affinity-Wert besteht die Validierung von Aggrega, und der Fehler zeigt sich stattdessen während der Synthese durch den Provider.

Ressourcenmengen sind für das Schema auf dieselbe Weise Zeichenketten: Keine der beiden Stufen prüft ihre Form. Das tut der synthetisierende Provider, auf der ausgewerteten Workload, und er bricht bei einem Wert außerhalb der Mengenform ab – siehe Ressourcenmengen.

Zusätzliche Ressourcen gehören außerhalb der Workload

Die Workload beschreibt nur die Form der Arbeitslast – Container, Volumes, Dienste, Replikate, Scheduling, Sicherheitskontext, Service-Account. Sie hat kein Feld additionalResources und keine Inline-Deklarationen von ConfigMap / Secret / CRD.

Recipe-Autoren geben zusätzliche Ressourcen über zwei Kanäle außerhalb der Workload aus:

  • artifacts: auf Recipe-Ebene – für Ressourcen, die diesem Recipe eigen sind (eine bestimmte ConfigMap, auf die die Workload des Recipe verweist, eine einmalige CRD-Registrierung, die das Recipe benötigt). Das Feld ist eine Map benannter Einträge; jeder Eintrag wird inline geschrieben oder über ein $import: pro Eintrag geladen. Siehe den Abschnitt zum Artefakt-Mechanismus in ../../architecture/16-recipe-input-composition.md für die drei Authoring-Modi.
  • Features mit Ressourcengenerierung – für querschnittliche Belange, die über Release-Selektoren angebunden werden (ein ServiceMonitor-Feature, das an jede Komponente mit bereitgestellten Metriken angebunden wird, ein NetworkPolicy-Feature, das an jede Produktions-Arbeitslast angebunden wird). Siehe ../entities/featurerecipe.md für die Authoring-Oberfläche des FeatureRecipe.

Die Workload bleibt auf die Form der Arbeitslast konzentriert; querschnittliche und dem Recipe eigene zusätzliche Manifeste haben ihre eigenen Authoring-Orte.

Gängige Workload-Muster

Das Workload-Schema ist breit – es deckt HTTP-Server mit einem Container, Sidecar-Muster mit mehreren Containern, Init-Container-Ketten, Batch-Jobs und zustandsbehaftete Dienste mit persistenten Volumes ab. Drei Muster wiederholen sich so häufig, dass es Verschwendung wäre, das Grundgerüst für jedes Recipe neu zu schreiben. Die folgenden Blöcke sind Vorlagen zum Kopieren und Einfügen, die Recipe-Autoren an bestimmte Komponenten anpassen können.

Ein Muster, das mehrere Recipes gemeinsam nutzen, kann einmal als Eintrag einer WorkloadLibrary veröffentlicht und mit $import: <Library>#/workloads/<entry> importiert werden; die Vorlagen hier sind Ausgangspunkte zum Anpassen oder zum Veröffentlichen auf diese Weise.

Muster 1 – Server mit bereitgestellten Metriken

Eine typische Webanwendung, die Anwendungsdatenverkehr auf einem Port bedient und von Prometheus abgerufene Metriken auf einem separaten Port bereitstellt. Zwei Dienste in der Workload – einer für die Anwendung, einer für die Metriken – halten Service-Mesh-Richtlinien und Load-Balancer-Konfiguration sauber trennbar.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
metrics: {{ optional .values `metrics_port` 9090 }}
variables:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"
health:
ready:
http: /healthz
timeoutSeconds: 5
live:
http: /healthz
timeoutSeconds: 5
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}
metrics:
type: ClusterIP
ports:
metrics: {{ optional .values `metrics_port` 9090 }}

Der Metrikdienst wird typischerweise für die Erkennung durch Prometheus über eine Feature-Anbindung auf der Release-Oberfläche annotiert (z. B. feature.aggrega.ai/prometheus-scrape: "true"); die Workload selbst bleibt frei von Provider-spezifischen Scrape-Annotationen.

Muster 2 – Batch-Job

Eine Arbeitslast, die bis zum Abschluss läuft, statt unbegrenzt Datenverkehr zu bedienen. Das Muster setzt form: task, lässt services: vollständig weg – Batch-Jobs stellen keine Ports bereit – und stützt sich auf die Task-Form des Ziel-Providers (ein Kubernetes-Job beim helm-Provider; der compose-Provider hat keine Task-Form und bricht bei form: task ab). Der helm-Provider legt eine für Jobs gültige Pod-restartPolicy fest (Never, sofern der Container nicht OnFailure deklariert), da ein Job-Pod den Standardwert Always nicht verwenden kann.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]
args:
- "--config"
- "/etc/config/job.yaml"
variables:
JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}"
volumeMounts:
- name: config
path: /etc/config
volumes:
config:
configmap:
source: "{{ .context.instance_id }}-config"

Das Konfigurations-Volume verweist auf eine ConfigMap, die das Recipe voraussichtlich neben der Workload über artifacts: ausgibt (siehe „Zusätzliche Ressourcen gehören außerhalb der Workload“ oben) – die Workload selbst deklariert nur die verbrauchende Seite. Die Identität benennt sie bei einem Provider, der die Arbeitslast nach der Identität benennt, wie es compose tut; unter helm, das die Ressourcen der Arbeitslast nach dem helm-Release-Namen benennt, bilden Sie den Namen der ConfigMap – hier und im Artefakt – stattdessen aus {{ .context.rendered_name }}, sodass es einer ist, den der Cluster akzeptiert, wie auch immer die Komponente heißt.

Muster 3 – Sidecar-Paar

Ein Pod mit zwei Containern, in dem der Hauptcontainer die Anwendungslogik übernimmt und der Sidecar einen querschnittlichen Belang (TLS-Terminierung, Log-Versand, Service-Mesh-Proxy, KI-Guardrail). Die Autorenreihenfolge in containers: ist tragend – der helm-Provider gibt Container in deklarierter Reihenfolge aus; der erste Schlüssel (hier main) ist das Standard-Container-Ziel für kubectl logs und ähnliche Werkzeuge.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
main:
image: "{{ .values.app_image }}"
ports:
app: {{ optional .values `app_port` 8080 }}
variables:
UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}"
sidecar:
image: "{{ .values.sidecar_image }}"
ports:
proxy: {{ optional .values `proxy_port` 9000 }}
variables:
PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"
services:
external:
type: ClusterIP
ports:
proxy: {{ optional .values `proxy_port` 9000 }}

Der Service stellt den Port des Sidecars bereit (nicht den des Hauptcontainers) und leitet externen Datenverkehr über den Sidecar per localhost an den Hauptcontainer weiter. Die beiden Container teilen sich den Netzwerk-Namespace des Pods, sodass localhost:<port> den Partnercontainer direkt erreicht. Bei Sidecars, die eine Injektion von Zugangsdaten benötigen (das kanonische KI-Guardrail-Muster), liegen die Zugangsdaten typischerweise im attachments:-Block des Sidecars statt in dem des Hauptcontainers – so bleiben die Zugangsdaten auf die Prozessgrenze des Sidecars beschränkt.

Auswahl des Musters

Die drei Muster entsprechen unterschiedlichen Belangen der Auslieferungsform:

  • Server mit Metriken – langlebige Dienste, die der Cluster am Leben hält; mehrere Service-Bereitstellungen zur Trennung des Datenverkehrs.
  • Batch-Job – begrenzte Ausführung; keine Service-Bereitstellung; stützt sich für die Eingabe auf eine vom Recipe ausgegebene ConfigMap oder auf externen Zustand.
  • Sidecar-Paar – Pod mit mehreren Containern und gemeinsamem Netzwerk-Namespace; der Service des Sidecars stellt den querschnittlichen Belang bereit.

Ein viertes Muster – zustandsbehafteter Server mit persistentem Volume – setzt form: stateful und deklariert Speicher pro Replikat über volumes.<name>.persistentTemplate; der helm-Provider gibt für die zustandsbehaftete Form ein StatefulSet aus (siehe providers/helm.md). Das Muster gleicht in seiner Form „Server mit Metriken“ mit form: stateful, einem zusätzlichen persistentTemplate-Volume und genau einem Dienst mit type: Headless, der das StatefulSet steuert (ohne ihn bricht der Build ab); Autoren, die es benötigen, passen Muster 1 mit allen drei Deklarationen an.

Querverweise