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

WorkloadLibrary

Eine WorkloadLibrary ist eine Katalogentität, die wiederverwendbare Workload-Template-Fragmente enthält. Recipes und FeatureRecipes, die dieselbe Form der Arbeitslast bereitstellen – einen Server mit bereitgestellten Metriken, einen Batch-Job, ein Sidecar-Paar –, deklarieren diese Form einmal in einer Bibliothek und verweisen zum Zeitpunkt der Verwendung über eine Direktive workload: { $import: ... } darauf. Die Bibliotheksentität gehört zu Stufe 3: optional für Kataloge, die Arbeitslasten Recipe-übergreifend wiederverwenden müssen. Kataloge, deren Recipes jeweils ihre eigene, eigenständige Form der Arbeitslast mitbringen, werden ohne jede WorkloadLibrary ausgeliefert.

Die Rolle der WorkloadLibrary

Plattformarchitekten schreiben WorkloadLibraries, um den Workload-Inhalt zu zentralisieren, der in den Recipes und FeatureRecipes des Katalogs wiederkehrt. Eine Bibliothek ist keine bereitstellbare Build-Anweisung; sie ist ein Namespace für Definitionen. Recipe- und FeatureRecipe-Autoren verweisen über eine $import:-Direktive auf Bibliothekseinträge, die einmal geschrieben und überall dort verwendet werden, wo der Import aufgelöst wird.

Die Trennung zwischen „Bibliothek“ und „Verbraucher“ ist beabsichtigt. Recipes kodieren Build-Anweisungen (source, valuesMapping, artifacts). FeatureRecipes kodieren Verhaltensanbindungen. WorkloadLibraries kodieren nur Workload-Inhalt – die Form der Arbeitslast, die der Provider zu Provider-nativen Manifesten synthetisiert. Wenn die drei Rollen getrennt bleiben, kann sich jede Entitätsart in ihrem eigenen Tempo weiterentwickeln; Autoren, die keinen gemeinsamen Workload-Inhalt benötigen, begegnen der Bibliotheksentität nie.

Entitätshülle

Eine WorkloadLibrary-Entität trägt den Standard-Katalogumschlag. apiVersion: aggrega.ai/v1beta1 und kind: WorkloadLibrary kennzeichnen die Entitätsart; metadata.name ist ein Bezeichner in PascalCase; metadata.version folgt strikter semantischer Versionierung. Beide sind erforderlich. metadata.description, metadata.labels und metadata.annotations sind optional – Labels und Annotationen sind opake, vom Autor deklarierte Metadaten, die mitgeführt werden, damit alles, was die Bibliothek liest, darauf abgleichen kann, und der Compiler interpretiert ihre Werte nicht. Der Inhalt der Bibliothek liegt unter spec.workloads, einer erforderlichen Map, die mindestens einen Eintrag deklarieren muss.

Die Hülle ist auf allen drei Ebenen geschlossen — die Dokumentwurzel, metadata und spec weisen jeweils Schlüssel zurück, die das Schema nicht deklariert.

apiVersion: aggrega.ai/v1beta1
kind: WorkloadLibrary
metadata:
name: BaseWorkloads
version: 1.0.0
spec:
workloads:
SimpleServer: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}

Workload-Einträge verfassen

Jeder Eintrag ist ein Go-Template-Fragment, das als YAML-String verfasst wird. Die gerenderte Ausgabe des Eintrags ist ein vollständiges Workload-Dokument — es trägt eigene apiVersion: aggrega.ai/v1beta1 und kind: Workload —, weil das Feld workload: eines Recipe genau eine vollständige Workload aufnimmt, kein Fragment, das in eine umgebende eingefügt wird, und der Import das gesamte Feld ersetzt. Ein MappingLibrary-Eintrag ist auf dieselbe Weise vollständig: Der Import eines solchen Eintrags ersetzt das gesamte valuesMapping: des Recipe.

Der Rumpf ist für die Entitätshülle opak. Der Compiler speichert den String beim Laden der WorkloadLibrary wörtlich und parst das Template dort nicht; der Template-Parser läuft zum Zeitpunkt der Verwendung, wenn ein Recipe oder ein FeatureRecipe den Eintrag importiert. Das wörtliche Speichern des Fragments bewahrt die Treue zur verfassten Form für die erneute Ausgabe, und es bedeutet, dass ein Template-Fehler dort auftritt, wo der Eintrag verwendet wird und sein Säulenkontext bekannt ist, statt an der Bibliothek.

Da ein Workload-Dokument mehrzeilig ist, verwenden Einträge den Literal-Block-Skalar von YAML (|), damit Zeilenumbrüche und Einrückung den Hin- und Rückweg überstehen:

spec:
workloads:
BatchJob: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]

Der Wert eines Eintrags muss ein String-Skalar sein. Eine Map oder eine Sequenz dort zu schreiben, wo der Rumpf hingehört, wird abgelehnt — der Rumpf des Eintrags ist Template-Text, kein strukturiertes YAML, das der Compiler durchläuft.

Innerhalb eines Eintrags steht das vollständige Kompositionsvokabular von Go-Templates zur Verfügung: {{ define "name" }}...{{ end }} deklariert wiederverwendbare Blöcke innerhalb einer einzelnen Bibliothek, {{ template "name" . }} ruft sie auf, und Pipelines und Funktionen folgen dem Go-Standardpaket text/template. Der Säulenkontext, den ein Eintrag lesen darf — .values, .infra, .locals, .context, .features —, ist derselbe Kontext, den jedes Workload-Template liest, und ist auf der Seite Workload unter der Template-Auswertung dokumentiert.

Der Ziel-Provider muss die Arbeitslast-Synthese unterstützen. Ein Recipe, das einen Bibliothekseintrag importiert, aber an einen Provider gebunden ist, der keine Workload synthetisieren kann, bricht zur Renderzeit mit einem deutlichen Fehler ab, statt eine verminderte Form auszugeben; der Katalog der Standardbibliothek deklariert workloadSchema bei den Providern, die sie unterstützen, als dokumentierten Vertrag.

Ein einziger Authoring-Modus

Die WorkloadLibrary bietet genau einen Autorenmodus: Go-Templates. spec akzeptiert keine parallele Authoring-Oberfläche und keinen Ausweg für mehr Ausdrucksstärke auf Bibliotheksebene.

Der Grund ist die Einheitlichkeit der Verwendungsoberfläche. Recipes und FeatureRecipes sind durchgehend Go-Template, und ihr eigener Inhalt wird von derselben Go-Template-Engine ausgewertet, die ein importiertes Fragment auflöst. Eine parallele Authoring-Oberfläche würde Autoren zwingen, innerhalb des Renderings eines einzelnen Recipe das Auswertungsmodell zu wechseln — ein Modell für den eigenen Inhalt des Recipe, ein anderes für jeden importierten Bibliothekseintrag. Eine einheitliche Oberfläche bedeutet, dass Autoren ein einziges Auswertungsmodell lernen und es überall anwenden.

Autoren, die mehr Ausdrucksstärke brauchen, als das Kompositionsvokabular von Go-Templates bietet, komponieren auf einer höheren Ebene — Components oder Features, die die Bibliothekseinträge mit eigener substanzieller Variation umhüllen —, statt innerhalb der Bibliothek auf eine zweite Autorensprache auszuweichen.

Namenskonventionen

Bibliotheksnamen und die Schlüssel von Arbeitslast-Einträgen folgen PascalCase. Das JSON Schema der Entitätshülle erzwingt die Konvention an zwei Stellen über Pattern-Einschränkungen:

  • metadata.name entspricht ^[A-Z][A-Za-z0-9]*$.
  • Die Map-Schlüssel von spec.workloads entsprechen über propertyNames demselben Muster.

Eine WorkloadLibrary mit einem Schlüssel in spec.workloads, der nicht in PascalCase ist, scheitert beim Laden des Workspace an der Validierung der Hülle. Die Durchsetzung ist tragend: Die Schlüssel von Arbeitslast-Einträgen erscheinen im Referenzfragment #/workloads/<name>, sodass sich ein Schlüssel, der nicht in PascalCase ist, in jeden Konsumenten fortpflanzen würde, der den Eintrag importiert.

Die einheitliche Benennung hält das Fragment #/workloads/<name> lesbar: #/workloads/BatchJob erschließt sich auf einen Blick.

Auf Bibliothekseinträge verweisen

Recipe- und FeatureRecipe-Autoren referenzieren einen Arbeitslast-Eintrag innerhalb eines Blocks workload: { $import: ... } über seine Identität als bloßer Name:

# Inside a Recipe's spec:
spec:
workload:
$import: "BaseWorkloads#/workloads/SimpleServer"

Das Fragment #/workloads/<name> wählt den Eintrag aus und unterscheidet eine Arbeitslast-Referenz von #/mappings/<name> der MappingLibrary und #/schemas/<name> der SchemaLibrary. Die Referenz enthält keinen Registry-Host; eine Form oci://… mit Host wird sowohl vom Schema der Hülle als auch an der Verwendungsstelle abgelehnt, sodass ein physischer Registry-Ort nie in den verfassten Quelltext gelangt. Ein Autor kann eine optionale Mindestversion als <Library>:<version>#/workloads/<name> angeben — das Versionstrennzeichen ist :, passend zu den recipe/feature-Mappings und dem Lockfile-Pin, und wird stattdessen @ geschrieben, wird dies mit einer Diagnose abgelehnt, die die korrigierte Referenz nennt. Die aufgelöste Version liefert die Lockfile pro Release, die jede verwendete Bibliothek nach Name, Version und Inhalts-Digest festlegt; der physische Ort wird zur Auflösungszeit gebunden.

Dasselbe Feld workload: akzeptiert zwei weitere Formen — einen Inline-Go-Template-String und einen $import: eines lokalen Dateipfads relativ zum Recipe-Verzeichnis. Die drei Formen werden an der Gestalt des Inhalts unterschieden, und alle drei erzeugen nach dem Parsen dieselbe Workload. Unter Recipe steht, wie sich workload: mit den anderen Eingabearten des Recipe zusammensetzt, und unter vocabulary/cross-document-ref die umfassendere Unterscheidung $ref: / $import:.

Bibliotheksübergreifende Komposition

Ein WorkloadLibrary-Eintrag kann eine $import:-Umleitung an der Feldwurzel sein: Das erste Token seines Rumpfs ist $import: <Library>#/workloads/<entry>, das den gesamten Eintrag durch den Inhalt des referenzierten Eintrags ersetzt — Wiederverwendung über Identität, kein Templating an Ort und Stelle. Die Umleitung wird zum Zeitpunkt der Verwendung aufgelöst, nicht beim Laden der WorkloadLibrary, und sie wird rekursiv aufgelöst, sodass ein importierter Eintrag selbst ein $import: an der Feldwurzel sein kann. Eine Kette, die auf sich selbst zurückführt, bricht mit einer Diagnose ab, die den Zyklus nennt. $import: gilt nur für ganze Einträge; es ist keine Template-Funktion mitten im Fragment. Um Template-Text innerhalb eines einzelnen Eintrags zusammenzusetzen, verwenden Sie define / template von Go-Templates.

# In library A — alias an entry to a shared entry in another library:
spec:
workloads:
StandardServer: |
$import: PlatformWorkloads#/workloads/MetricsServer

Ein unbekannter Bibliotheksname und ein Eintragsname, der in einer auflösbaren Bibliothek fehlt, werden als unterschiedliche Diagnosen gemeldet, sodass ein Autor eine fehlende Abhängigkeit von einem falsch geschriebenen Eintrag unterscheiden kann.

Einordnung in die Tiers

Die WorkloadLibrary gehört im Dokumentationsmodell der Entitätsstufen zu Stufe 3 — optional für Kataloge, die eine Recipe-übergreifende Wiederverwendung von Arbeitslasten brauchen. Kataloge, deren Recipes eigene, unterschiedliche Arbeitslast-Inhalte tragen, kommen ganz ohne WorkloadLibrary-Entität aus; die Stufenmarkierung signalisiert „fortgeschritten; überspringen, wenn nicht benötigt“ für die Navigation in der Dokumentation, nicht für die Fähigkeit. Der Compiler behandelt die WorkloadLibrary einheitlich mit den anderen Katalog-Entitätsarten: dieselbe Validierung der Hülle beim Laden des Workspace, dieselbe OCI-Veröffentlichungspipeline beim Veröffentlichen einer Version, dasselbe Lockfile-Pinning nach Name, Version und Inhalts-Digest.

Die Bibliotheksart gehört zu einer Reihe auf Katalogebene — die SchemaLibrary enthält wiederverwendbare Schemadefinitionen, die MappingLibrary wiederverwendbare Mapping-Fragmente, die ArtifactLibrary wiederverwendbare Artefakt-Bundles, die WorkloadLibrary wiederverwendbare Arbeitslast-Inhalte. Jede ist unabhängig optional; Kataloge liefern die mit, die sie brauchen, und keine der anderen.

Was die WorkloadLibrary nicht ist

Einige häufige Missverständnisse, denen man vorbeugen sollte:

  • Kein Ersatz für inline workload:. Die meisten Recipes tragen Arbeitslast-Inhalte, die spezifisch genug sind, um inline zu stehen, wo der Autor sie zusammen mit dem Rest des Recipe liest. Eine WorkloadLibrary hilft, wenn DIESELBE Arbeitslast-Form in vielen Recipes auftritt; für einmalige Inhalte ist das Verfassen inline die richtige Wahl.

  • Kein Ort für Teilfragmente. Ein Eintrag wird zu einem vollständigen Workload-Dokument gerendert. Das Werte-Dokument eines Recipe gehört in eine MappingLibrary, eine Gruppe von Hilfsdateien in eine ArtifactLibrary und Schemadefinitionen in eine SchemaLibrary. Die Bibliotheksarten teilen sich nach Inhaltstyp auf, nicht nach Wiederverwendungsmuster.

  • Keine unabhängig bereitstellbare Entität. Ein Bibliothekseintrag ist Workload-Inhalt, und Workload-Inhalt ist nie für sich allein adressierbar — er existiert als die Eingabe, die ein Recipe oder ein FeatureRecipe verwendet. Das Veröffentlichen einer WorkloadLibrary macht ihre Einträge importierbar; es macht sie nicht bereitstellbar.

  • Keine parametrische Wiederverwendung über die Mechanismen von Go-Templates hinaus. Autoren, die parametrische Variation brauchen, verwenden die Mechanik {{ define }} + {{ template }} von Go-Templates innerhalb von Bibliothekseinträgen oder den Säulenkontext, den das verwendende Recipe bereitstellt. Die Bibliotheksentität selbst bringt keine Maschinerie für parametrische Helfer mit.