ArtifactLibrary
Eine ArtifactLibrary ist eine Katalogentität, die wiederverwendbare Artefakt-Bundles enthält — benannte Mengen zusammengehöriger zusätzlicher Ausgabedateien. Recipes und FeatureRecipes, die dieselben unterstützenden Ressourcen ausgeben — eine CRD mit ihrem RBAC und einer ConfigMap, eine NetworkPolicy zusammen mit einem HPA —, deklarieren diese Menge einmal in einer Bibliothek und verweisen zum Zeitpunkt der Nutzung über einen artifacts:-Eintrag darauf, dessen Wert eine $import:-Direktive ist. Die Bibliotheksentität gehört zu Tier 3: optional für Kataloge, die Artefakte Recipe-übergreifend wiederverwenden müssen. Kataloge, deren Recipes jeweils ihre eigenen zusätzlichen Dateien mitbringen, kommen ohne jede ArtifactLibrary aus.
Die Rolle der ArtifactLibrary
Plattformarchitekten verfassen ArtifactLibraries, um die zusätzlichen Manifeste zu zentralisieren, die in den Recipes und FeatureRecipes des Katalogs wiederkehren. Eine Bibliothek ist keine deploybare Build-Anweisung; sie ist ein Namensraum für Definitionen. Autoren von Recipes und FeatureRecipes verweisen über eine $import:-Direktive auf ein Bundle, die einmal geschrieben und überall genutzt wird, wo der Import aufgelöst wird.
Was diese Bibliotheksart von den anderen drei unterscheidet, ist die Granularität eines Eintrags. Ein SchemaLibrary-Eintrag ist ein Schema, ein MappingLibrary-Eintrag ist ein Template-Fragment und ein WorkloadLibrary-Eintrag ist ein Workload-Dokument — jeweils ein einzelner Inhalt, der an einer einzigen Stelle genutzt wird. Ein ArtifactLibrary-Eintrag ist eine Menge von Dateien, weil die Ressourcen, die er gruppiert, nur zusammen nützlich sind: Eine CRD ohne ihr RBAC zu importieren, ergibt eine Manifestmenge, die nicht funktioniert. Deshalb ist ein Bundle die Einheit der Wiederverwendung, und eine einzige Nutzungsstelle expandiert zu mehreren Ausgaben.
Entitätshülle
Eine ArtifactLibrary-Entität trägt die Standardhülle des Katalogs. apiVersion: aggrega.ai/v1beta1 und kind: ArtifactLibrary kennzeichnen die Entitätsart; metadata.name ist ein PascalCase-Bezeichner; metadata.version folgt strikter semantischer Versionierung. Beide sind Pflichtfelder. 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.artifacts, einer Pflicht-Map, die mindestens ein Bundle 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/v1beta1kind: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: artifacts: OperatorSupport: crd.yaml: | apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: widgets.platform.example.com spec: group: platform.example.com scope: Namespaced rbac.yaml: | apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: "{{ .context.instance_id }}-operator" rules: - apiGroups: ["platform.example.com"] resources: ["widgets"] verbs: ["get", "list", "watch"]Artefakt-Bundles verfassen
spec.artifacts ist zwei Ebenen tief, und jede Ebene hat eine eigene Aufgabe. Der äußere Schlüssel ist der Bundle-Name — der Bezeichner, auf den ein Nutzer verweist. Die inneren Schlüssel sind Dateinamen, und jeder innere Wert ist der Go-Template-Inhalt, der in diese Datei ausgegeben wird. Ein Bundle muss mindestens eine Datei deklarieren.
spec: artifacts: NetworkBaseline: deny-all.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-deny-all" spec: podSelector: {} policyTypes: ["Ingress"] allow-dns.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-allow-dns"Ein Dateiinhalt ist ein Go-Template-Fragment, das als YAML-String verfasst wird. Da ein Manifest mehrzeilig ist, verwenden Dateiinhalte den Literal-Skalarstil von YAML (|), damit Zeilenumbrüche und Einrückung den Round-Trip überstehen. Der Wert eines Bundle-Eintrags muss eine Zuordnung von Dateiname zu String-Inhalt sein; ein bloßer String an der Stelle des Bundles oder eine Sequenz wird zurückgewiesen — die Ebene, die ein Nutzer importiert, ist das Bundle, nicht eine einzelne Datei.
Der Inhalt ist für die Entitätshülle opak. Der Compiler speichert jeden String beim Laden der ArtifactLibrary unverändert und parst das Template dort nicht; der Template-Parser läuft zum Zeitpunkt der Nutzung, wenn ein Recipe oder ein FeatureRecipe das Bundle importiert. Das unveränderte Speichern der Inhalte bewahrt die Treue zum Verfassten für die erneute Ausgabe, und es bedeutet, dass ein Template-Fehler dort auftritt, wo das Bundle genutzt wird und sein Säulenkontext bekannt ist, statt in der Bibliothek.
Die Reihenfolge der Dateien in einem Bundle ist die vom Autor geschriebene, die über Laden und Nutzung hinweg erhalten bleibt, sodass die ausgegebene Menge über Builds hinweg stabil ist.
Das vollständige Kompositionsvokabular von Go-Templates steht in einem Dateiinhalt zur Verfügung: {{ define "name" }}...{{ end }} deklariert wiederverwendbare Blöcke, {{ template "name" . }} ruft sie auf, und Pipelines und Funktionen folgen dem Standard-Go-Paket text/template. Der Säulenkontext, den ein Dateiinhalt lesen darf — .values, .infra, .locals, .context, .features sowie .workload und .source, wo das nutzende Recipe sie deklariert —, ist der Kontext, den die eigenen artifacts:-Einträge des nutzenden Recipe lesen, dokumentiert auf der Seite Recipe unter dem Feld artifacts:. Ein Inhalt, der .workload liest, wo das nutzende Recipe kein workload: deklariert, oder .source, wo es kein source: deklariert, bricht mit einer Diagnose ab, die die Referenz nennt, die nicht erfüllt werden konnte — jede Säule wird für sich geprüft, sodass die Deklaration der einen nicht zum Lesen der anderen berechtigt.
Ein einziger Authoring-Modus
ArtifactLibrary bietet einen einzigen Authoring-Modus: Go-Templates. spec akzeptiert keine parallele Authoring-Oberfläche und keinen Ausweg für mehr Ausdruckskraft auf Bibliotheksebene.
Der Grund ist die Einheitlichkeit der Nutzungsoberfläche. Recipes und FeatureRecipes sind durchgängig Go-Template, und ihr eigener Inhalt wird von derselben Go-Template-Engine ausgewertet, die ein importiertes Bundle auflöst. Eine parallele Authoring-Oberfläche würde Autoren zwingen, innerhalb des Renderings eines einzigen Recipe zwischen Auswertungsmodellen zu wechseln — ein Modell für den eigenen Inhalt des Recipe, ein anderes für jedes importierte Bundle. Eine einheitliche Oberfläche bedeutet, dass Autoren ein einziges Auswertungsmodell lernen und es überall anwenden.
Autoren, die mehr Ausdruckskraft benötigen, als das Kompositionsvokabular von Go-Templates bietet, komponieren auf einer höheren Ebene — Components oder Features, die die Bibliotheks-Bundles mit eigener inhaltlicher Variation umschließen —, statt innerhalb der Bibliothek auf eine zweite Authoring-Sprache auszuweichen.
Namenskonventionen
Bibliotheksnamen und Bundle-Namen folgen PascalCase. Das JSON Schema der Entitätshülle setzt die Konvention an zwei Stellen über Pattern-Constraints durch:
metadata.nameentspricht^[A-Z][A-Za-z0-9]*$.- Die Map-Schlüssel von
spec.artifactsentsprechen überpropertyNamesdemselben Muster.
Eine ArtifactLibrary mit einem Bundle-Namen, der nicht in PascalCase ist, besteht die Validierung der Hülle beim Laden des Workspace nicht. Die Durchsetzung ist tragend: Bundle-Namen erscheinen im Referenzfragment #/artifacts/<name>, sodass sich ein Name, der nicht in PascalCase ist, in jeden Nutzer fortpflanzen würde, der das Bundle importiert.
Die einheitliche Benennung hält das Fragment #/artifacts/<name> lesbar: #/artifacts/OperatorSupport ist auf einen Blick verständlich.
Dateinamen innerhalb eines Bundles sind frei wählbar, sofern jeder eine Datei benennt. Sie sind nicht in PascalCase, und kein Schema-Muster schränkt sie ein, weil sie die Dateien benennen, die die Ausgabe eines Builds am Ende enthält — crd.yaml, deny-all.yaml, values-override.json sind alle gültig. Ein Dateiname muss ein gewöhnlicher relativer Dateiname sein, schlicht geschrieben; der Build weist einen Namen zurück, der keine eigene Datei benennt, wie Auf Bibliothekseinträge verweisen beschreibt. Die beiden Ebenen sind unterschiedlich eingeschränkt, weil sie unterschiedlichen Lesern dienen: Der Bundle-Name ist ein Bezeichner, den andere Entitäten zitieren, und die Dateinamen sind die Namen, die ein Nutzer in dem Verzeichnis sieht, in das das Bundle importiert wird.
Auf Bibliothekseinträge verweisen
Autoren von Recipes und FeatureRecipes verweisen innerhalb eines artifacts:-Eintrags, dessen Wert eine $import:-Map ist, über die Identität des Bundles als bloßer Name auf ein Bundle:
# Inside a Recipe's spec:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport"Das Fragment #/artifacts/<name> wählt das Bundle aus und unterscheidet eine Artefaktreferenz von #/mappings/<name> der MappingLibrary, #/schemas/<name> der SchemaLibrary und #/workloads/<name> der WorkloadLibrary. Die Referenz enthält keinen Registry-Host; eine Form mit Host oci://… wird sowohl vom Hüllenschema als auch an der Nutzungsstelle zurückgewiesen, sodass ein physischer Registry-Ort nie in den verfassten Quelltext gelangt. Ein Autor kann eine optionale Mindestversion als <Library>:<version>#/artifacts/<name> angeben — das Versionstrennzeichen ist :, wie bei den anderen Bibliotheksarten und beim Lockfile-Pin, und wird stattdessen @ geschrieben, wird dies mit einer Diagnose zurückgewiesen, die die korrigierte Referenz nennt. Die aufgelöste Version liefert das Lockfile pro Release, das jede genutzte Bibliothek nach Name, Version und Inhalts-Digest fixiert; der physische Ort wird zum Zeitpunkt der Auflösung gebunden.
Das Bundle besitzt seine Dateinamen, und der nutzende Schlüssel besitzt das Verzeichnis, in dem sie landen. Ein artifacts:-Eintrag, der ein Bundle importiert, expandiert zu einer Ausgabe pro Datei in diesem Bundle, jeweils unter dem Nutzungsschlüssel als <key>/<filename> verschachtelt. Der Schlüssel an der Nutzungsstelle — oben operator-support — benennt die gesamte Nutzung statt einer einzelnen Datei; das Beispiel gibt operator-support/crd.yaml und operator-support/rbac.yaml aus. Ein Bundle-Name wird also für die Lesbarkeit an der Referenz gewählt, die Dateinamen für den Leser des Ausgabeverzeichnisses, und keiner muss mit dem anderen übereinstimmen. Der Nutzungsschlüssel ist selbst auf einen einzigen Dateinamen beschränkt — ein führender Buchstabe oder eine Ziffer, dann Buchstaben, Ziffern, Punkte, Bindestriche und Unterstriche, wobei ein Schlüssel außerhalb dieses Alphabets die Validierung der Hülle nicht besteht —, sodass er genau ein Verzeichnissegment benennt und alles unterhalb dieses Segments aus dem Bundle stammt. Das erlaubt es, dass die Dateinamen eines Bundles frei bleiben, während der Schlüssel strikt bleibt: Ein Dateiname ist innerhalb seines Bundles eindeutig, ein Schlüssel innerhalb seines Dokuments, und der Schlüssel ist das erste Segment jedes Pfades, den der Eintrag ausgibt, sodass keine zwei artifacts:-Einträge dieselbe Ausgabe benennen. Frei bedeutet frei innerhalb dieses Segments: Ein Dateiname kann eine eigene verschachtelte Struktur haben — crds/widget.yaml landet unter <key>/crds/widget.yaml —, muss aber ein gewöhnlicher relativer Dateiname unterhalb des Schlüssels sein, schlicht geschrieben, und ein Dateiname, der das nicht ist, bricht den Build ab, statt die Datei an einem Ort abzulegen, den das nutzende Recipe nie benannt hat. Zurückgewiesen werden damit ein Name, der über den Schlüssel hinaufsteigt oder einen absoluten Ort benennt; . oder ./ sowie ein Name, der wieder auf den Schlüssel zusammenfällt, etwa x/.., die das Verzeichnis des Schlüssels selbst statt einer Datei darin benennen; und ein Name mit einem abschließenden oder doppelten / oder einem Teil . oder .. — x/, a//b, ./a, a/../b —, der eine zweite Schreibweise einer Datei ist, die auch ein anderer Name tragen kann, sodass a//b neben a/b zwei Dateien an einen Pfad legen würde. Die Diagnose nennt die Bundle-Datei und den Schlüssel, unter dem sie importiert wurde. Zwei Ausgaben, die tatsächlich denselben Dateinamen tragen, brechen den Build ab, wenn der Knoten gerendert wird, was geschieht, wenn zwei verschiedene Eingabearten denselben Dateinamen beisteuern. Unter Recipe erfahren Sie, wie sich artifacts: mit den anderen Eingabearten des Recipe zusammensetzt und welche zwei Authoring-Modi ohne Bibliothek es gibt, und unter vocabulary/cross-document-ref die allgemeinere Unterscheidung zwischen $ref: / $import:.
Bibliotheksübergreifende Komposition
Ein Bundle-Dateiinhalt ist terminaler Inhalt. Anders als ein Eintrag einer MappingLibrary oder WorkloadLibrary kann eine Bundle-Datei keine $import:-Umleitung an der Feldwurzel sein: Ein einzelner Datei-Slot hat keinen Platz für die mehreren Dateien, die ein anderes Bundle mitbringen würde, daher weist der Compiler diese Form zurück, statt sie in etwas aufzulösen, das der Autor nicht geschrieben hat. Ein Inhalt, dessen erstes Token $import: ist, bricht mit einer Diagnose ab, die das Bundle und die Datei nennt.
Die Komposition findet stattdessen an der Nutzungsstelle statt, wo Platz dafür ist. Ein Recipe, das zwei Bundles benötigt, deklariert zwei artifacts:-Einträge, und jeder expandiert unabhängig:
# Inside a Recipe's spec — compose bundles where the outputs land:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport" network-baseline: $import: "PlatformArtifacts#/artifacts/NetworkBaseline"Ein unbekannter Bibliotheksname und ein Bundle-Name, der in einer auflösbaren Bibliothek fehlt, werden als unterschiedliche Diagnosen gemeldet, sodass ein Autor eine fehlende Abhängigkeit von einem falsch geschriebenen Bundle-Namen unterscheiden kann.
Einordnung in die Tiers
ArtifactLibrary gehört im Dokumentationsmodell der Entitäts-Tiers zu Tier 3 — optional für Kataloge, die Artefakte Recipe-übergreifend wiederverwenden müssen. Kataloge, deren Recipes ihre eigenen zusätzlichen Dateien mitbringen, kommen ohne jede ArtifactLibrary-Entität aus; die Tier-Kennzeichnung signalisiert „fortgeschritten; überspringen, wenn nicht benötigt“ für die Navigation in der Dokumentation, nicht für den Funktionsumfang. Der Compiler behandelt ArtifactLibrary genauso wie die anderen Katalog-Entitätsarten: dieselbe Validierung der Hülle beim Laden des Workspace, dieselbe OCI-Veröffentlichungspipeline zum Release-Zeitpunkt, dasselbe Lockfile-Pinning nach Name, Version und Inhalts-Digest.
Diese Bibliotheksart vervollständigt eine Menge auf Katalogebene — SchemaLibrary enthält wiederverwendbare Schemadefinitionen, MappingLibrary wiederverwendbare Mapping-Fragmente, WorkloadLibrary wiederverwendbaren Workload-Inhalt und ArtifactLibrary wiederverwendbare Artefakt-Bundles. Jede ist unabhängig optional; Kataloge liefern die aus, die sie benötigen, und keine der anderen.
Was ArtifactLibrary nicht ist
Einige häufige Missverständnisse, denen man vorbeugen sollte:
-
Kein Ersatz für inline geschriebene
artifacts:. Die meisten Recipes tragen zusätzliche Dateien, die spezifisch genug sind, um inline zu stehen, wo der Autor sie zusammen mit dem Rest des Recipe liest. Eine ArtifactLibrary hilft, wenn DIESELBE Menge von Dateien viele Recipes begleitet; für einmalige Inhalte ist das Inline-Verfassen die richtige Wahl. -
Keine Möglichkeit, die Dateien innerhalb eines Bundles umzubenennen. Die Dateinamen gehören dem Bundle. Ein Nutzer wählt das Verzeichnis, in dem sie landen — das leistet der Nutzungsschlüssel —, aber nicht, wie eine einzelne davon heißt: Ein Nutzer, der einen anderen Dateinamen braucht, verwendet entweder ein Bundle, das ihn deklariert, oder verfasst die Datei inline.
-
Kein Ort für Workload-, Mapping- oder Schemainhalte. Ein Workload-Dokument gehört in eine WorkloadLibrary, das Werte-Dokument eines Recipe in eine MappingLibrary und Schemadefinitionen in eine SchemaLibrary. Die Bibliotheksarten sind nach Inhaltstyp aufgeteilt, nicht nach Wiederverwendungsmuster.
-
Nicht der Mechanismus für querschnittliche Ressourcen. Zusätzliche Ressourcen, die für viele Komponenten gelten, unabhängig davon, welches Recipe sie realisiert — ein Backup-Sidecar an jedem Datenspeicher —, gehören zur Ressourcengenerierung des FeatureRecipe, die per Feature statt per Recipe anbindet. Siehe entities/featurerecipe.md. Eine ArtifactLibrary fasst Dateien zusammen, die mehrere Recipes jeweils in eigener Sache ausgeben.
-
Keine eigenständig deploybare Entität. Ein Bundle ist Artefaktinhalt, und Artefaktinhalt ist nie für sich allein adressierbar — er existiert als die Eingabe, die ein Recipe oder ein FeatureRecipe nutzt. Das Veröffentlichen einer ArtifactLibrary macht ihre Bundles importierbar; es macht sie nicht deploybar.