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

Recipe-Input-Komposition — drei Input-Arten, Workload, Artefakte

Ein Recipe erzeugt Manifestdateien für seinen Zielanbieter. Dieses Kapitel behandelt, wie Recipes ihre Ausgabe aus drei orthogonalen Eingabearten zusammensetzen – sourced, synthesized und artifacts –, wie jede Eingabeart aufgebaut ist und welcher Anbieter welche Ausgabe erzeugt. Die konzeptionelle Rolle der Recipe-Entität (die von Ops verfasste Übersetzungsvorlage, die die Absicht der Entwickler auf einen einzelnen physischen Anbieter abbildet) ist in 04-entity-taxonomy.md beschrieben; die Authoring-Oberfläche des Recipe auf Schlüsselwortebene in ../language-reference/entities/recipe.md.

Begründung

Das native Rendering-Werkzeug jedes Anbieters – Helm, Docker Compose – weiß bereits, wie anbieternative Manifeste gerendert werden. Die Aufgabe eines Recipe ist es zu deklarieren, WAS diese Manifeste aussagen sollen: welche Container-Images, welche Ports, welche Umgebungsvariablen, welche Volumes, welche Dienste, welche Ressourcenlimits.

Ein Recipe muss mehr ausdrücken, als ein fester Satz von Schlüsseln (z. B. image, environment, ports, replicas), abgebildet auf ein Deployment und einen Service, tragen kann, darunter:

  • resources (CPU-/Speicher-Requests/-Limits)
  • Liveness-, Readiness- oder Startup-Probes
  • volumeMounts / volumes
  • nodeSelector / affinity / tolerations
  • serviceAccount / securityContext
  • Pods mit mehreren Containern, Sidecars
  • ConfigMap-/Secret-/PVC-/CRD-Ressourcen
  • Services, die nicht vom Typ ClusterIP sind (LoadBalancer, NodePort, Headless)

Die Abstraktionsschicht muss die vollständige Form einer Arbeitslast beschreiben, nicht einen festen Satz von Schlüsseln. Die unten beschriebenen drei Eingabearten sind diese Abstraktion: Ein Recipe setzt seine Ausgabe additiv zusammen aus einem extern geladenen Chart oder Modul (source:), einer abstrakten Workload-Spezifikation, die der Anbieter zu anbieternativen Manifesten synthetisiert (workload:), und vorlagenbasierten anbieternativen Manifesten, die das Recipe direkt ausgibt (artifacts:).

Die drei Eingabearten

Komposition durch Addition

Es gibt drei Wege, anbieternative Manifestdateien aus einem Recipe zu erzeugen, und sie lassen sich durch Addition kombinieren, statt sich gegenseitig auszuschließen:

  1. source: – ein extern geladenes Artefakt (Helm-Chart, Compose-Datei), das der Anbieter nativ rendert, wobei valuesMapping: die Overlay-Werte liefert.
  2. workload: – eine abstrakte Workload-Spezifikation (eine Art im Besitz der Plattform), die der Anbieter zu anbieternativen Manifesten synthetisiert. Das Feld akzeptiert einen Inline-YAML-Blockskalar oder einen $import: auf eine einzelne lokale Datei oder einen Bibliothekseintrag; die Zuordnung richtet sich nach der Form des Inhalts.
  3. artifacts: – eine Map aus inline angegebenen oder per $import: geladenen anbieternativen Manifesten, die als Go-Vorlagen gegen den vollständigen Säulenkontext ausgewertet werden. Jeder Eintrag kann inline verfasst werden (der Wert des Eintrags ist ein Blockskalar) oder per $import: auf eine einzelne Datei oder einen Bibliotheksinhalt.

Alle drei erzeugen Dateien, die der Compiler in das Ausgabeverzeichnis der Boundary schreibt. Alle drei können in einem einzigen Recipe nebeneinander bestehen, vorbehaltlich der unten genannten Validierungsregeln. Die Zusammenführung erfolgt nur auf oberster Ebene: Jede Eingabeart erzeugt vollständige Dateien; die Dateien werden nebeneinander ausgegeben; eine Kollision beim Namen einer Ausgabedatei ist ein fataler Fehler.

Beschreibende Modusnamen

Die drei „Modi“ sind beschreibendes Vokabular für Dokumentation und Diagnosen. Recipe-Autoren deklarieren keinen Modus; sie schreiben die Schlüsselwörter, die sie benötigen. Ein Recipe wird durch seine dominierende Eingabe charakterisiert:

Dominierende(s) Schlüsselwort(e)Beschreibender Modusname
source: + valuesMapping: (kein workload:, keine Artefakte)sourced
workload: (kein source:, keine Artefakte)synthesized
artifacts: (kein source:, kein workload:)artifacts-only (informell: „inline“)
Jede Kombination aus zwei oder mehrexplizit beschrieben (z. B. „sourced mit artifacts“, „synthesized mit artifacts“)

Es gibt kein Schlüsselwort namens mode: und keine Enumeration. Der Modus ist eine emergente Eigenschaft davon, welche Eingaben vorhanden sind.

Die Form eines Recipe auf einen Blick

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: ...
version: 1.0.0
spec:
capability: helm | compose | helm-chart | ...
implements: core/...:1.0.0
locals: { ... }
provides: { ... }
# ─── Sourced input (optional, paired) ───
source: ...
valuesMapping: |
# Go template → YAML/JSON overlay values
# OR:
valuesMapping:
$import: ./mappings/api-server.tmpl # local file path
# OR:
valuesMapping:
$import: <Lib>#/mappings/<entry> # MappingLibrary entry
# ─── Synthesized input (optional) ───
workload: |
# Go template → YAML → parsed Workload
# OR (single-source $import for whole-content load from a file or library):
workload:
$import: ./workload.yaml
# ─── Artifacts input (optional, multiple entries permitted) ───
artifacts:
"filename.yaml": |
# Inline Go template → manifest YAML
"other.yaml":
$import: ./artifacts/other.yaml # per-entry $import: for file or library content

Jedes oben genannte Feld wird vom Recipe-Schema akzeptiert, und der Compiler verarbeitet alle drei Eingabearten – sourced Rendering, Workload-Synthese und die Ausgabe von artifacts. Unterschiedlich ist die Unterstützung pro Anbieter – welcher Anbieter welche Eingabeart rendert –, festgehalten in der Provider-Fähigkeitsmatrix am Ende dieses Kapitels.

Validierungsregeln zur Ladezeit

Das Recipe-Schema und die Validierung beim Laden setzen diese Kompositionsregeln durch:

  1. valuesMapping: erfordert source:. Ohne ein source:, über das gelegt werden kann, gibt es nichts, was die zugeordneten Werte aufnimmt. Ein Recipe mit valuesMapping: und ohne source: ist ein Fehler zur Ladezeit. (Ein source: ohne valuesMapping: ist zulässig – das Chart oder Modul wird mit seinen eigenen Standardwerten gerendert.)
  2. workload: akzeptiert eine Quelle – inline oder $import:, nicht beides. Ein Recipe gibt die Workload entweder als Inline-Blockskalar oder als $import: auf eine einzelne Datei an. Die $import:-Form hat gemäß dem einheitlichen Vokabular für Dateiimporte nur eine Quelle; eine Zusammenführung mehrerer Quellen wird bei workload: nicht unterstützt. Eine fehlerhafte Zuordnung ist ein Fehler zur Ladezeit.
  3. workload: erfordert einen synthesefähigen Anbieter. Die Unterstützung der Synthese ist eine Eigenschaft des Anbieters selbst, nicht eines deklarierten Feldes. Ein workload:-Recipe, das an einen Anbieter gebunden ist, der nicht synthetisieren kann, wird beim Rendern des Knotens abgelehnt – durch die Prüfung der Anbieterfähigkeiten (siehe die Provider-Fähigkeitsmatrix) – mit einer klaren Diagnose. Der Katalog der Standardbibliothek deklariert workloadSchema auf synthesefähigen Anbietern nach Konvention, als dokumentierten Übersetzungsvertrag, aber die Prüfung stützt sich auf die vom Anbieter selbst gemeldete Fähigkeit und nicht auf das Vorhandensein dieses Feldes.
  4. Mindestens eine Eingabeart muss vorhanden sein. Ein Recipe ohne source:+valuesMapping:, workload: oder artifacts: erzeugt keine Ausgabe und ist ein Fehler zur Ladezeit.
  5. Inline- und $import:-Artefakteinträge können nebeneinander bestehen. Ein Recipe kann einige artifacts:-Einträge inline und andere über eintragsweise $import:-Direktiven deklarieren. Der Schlüssel jedes Eintrags benennt seine eigene Ausgabe, sodass Einträge der beiden Formen nie miteinander kollidieren (siehe Was jede Ausgabedatei benennt).
  6. Kollisionen von Dateinamen über Eingabearten hinweg sind Fehler zur Renderzeit. Wenn zwei Eingabearten eines Recipe – aus der Quelle gerenderte Ausgabe, aus der Arbeitslast synthetisierte Ausgabe oder aus Artefakten ausgegebene Ausgabe – eine Datei mit demselben Namen erzeugen, gibt der Compiler einen fatalen Fehler aus, der jeden Beitragenden benennt. Diese Prüfung läuft nach der Workload-Übersetzung, daher findet sie zur Renderzeit und nicht zur Ladezeit statt.

Die Workload-Art

Zuständigkeit und Ort

Workload ist eine Art im Besitz der Plattform unter apiVersion: aggrega.ai/v1beta1. Ihre Deklaration in JSON Schema 2020-12 wird beim Build in das Compiler-Binary eingebettet; Katalogautoren bearbeiten das Workload-Schema nicht und verfassen auch keine eigenständigen Workload-YAML-Dateien als Katalogentitäten. Die Workload-Grammatik wird innerhalb des workload:-Feldes eines Recipe oder FeatureRecipe verarbeitet (inline oder per $import: auf eine einzelne Datei oder einen WorkloadLibrary-Eintrag) und nirgendwo sonst.

Workload ist eine Plattformart und ein Compiler-Konzept, keine eigene Entität in der Entitätstaxonomie. Das Recipe ist die Authoring-Entität; die Workload ist die Form, die die synthetisierte Eingabe des Recipe annimmt.

Eine Workload pro Recipe

Ein Recipe deklariert höchstens ein workload:. Die Workload stellt die einzelne Recheneinheit dar, die zu der Component gehört, die dieses Recipe implementiert. Ebenso deklariert ein FeatureRecipe höchstens ein eigenes workload: – eine Recheneinheit im Besitz des Feature, synthetisiert über dieselbe Workload-Art –, siehe FeatureRecipe. Anwendungsfälle, die zusätzliche Neben-Arbeitslasten erfordern, werden ausgedrückt über:

  • artifacts: – zusätzliche Manifeste neben der Arbeitslast, im selben Recipe (inline oder per eintragsweisem $import:).
  • Features mit Ressourcenerzeugung – querschnittliche Neben-Arbeitslasten (z. B. ein an Datenbanken angebundener Backup-Sidecar), die als eigene Katalogentitäten deklariert sind, wobei das FeatureRecipe sein eigenes workload: synthetisiert (oder über source: / artifacts: rendert). Siehe 14-extensibility.md zur Ressourcenerzeugung durch FeatureRecipe.

Dies bewahrt das Modell einer Recheneinheit pro Autor: Ein Recipe synthetisiert die Arbeitslast der Component; ein FeatureRecipe synthetisiert seine eigene.

Die vollständige Oberfläche

Der Feldsatz der Workload ist groß und wächst. Statt ihn hier zu wiederholen, wo eine Kopie hinter den Vertrag zurückfallen würde, ohne dass etwas dies meldet, verweist dieses Kapitel auf die beiden Oberflächen, die ihn vollständig enthalten:

  • Die generierte Referenz des Workload-Schemas – jedes Feld, sein Typ, sein Standardwert und seine Einschränkungen, generiert aus dem veröffentlichten JSON Schema und bei jedem Build damit abgeglichen, sodass sie keine Form beschreiben kann, die der Compiler nicht akzeptiert.
  • Die Authoring-Seite der Workload – Authoring-Hinweise auf Feldebene: was jedes Feld bedeutet, wozu jeder Anbieter es rendert und welche Kombinationen der Build ablehnt.

Die Deklaration der Workload in JSON Schema 2020-12 ist maßgeblich und wird eingebettet im Compiler-Binary ausgeliefert. Die Provider helm und compose synthetisieren das workload: eines Recipe, inline oder per $import: geladen; zur Unterstützung pro Anbieter siehe die Provider-Fähigkeitsmatrix.

Secrets-Integration mit featuresSchema

Der Block containers.<name>.attachments der Workload verweist auf Slots, die im featuresSchema der Component deklariert sind; er deklariert keine neuen Slots. Siehe ../language-reference/entities/component.md zur Authoring-Oberfläche von featuresSchema.

Der Validierungsvertrag:

  • Jeder attachments.<KEY>.from-Wert muss einem Slot-Namen entsprechen, der im featuresSchema der Component deklariert ist – oder, bei einem Eintrag, der mit connection: <alias> eine Verbindung benennt, einem Slot, den der Socket dieser Verbindung in usesSchema.<socket>.featuresSchema deklariert. Ein solcher Eintrag wird auf den Namen umgeschrieben, den die Anbindung der Verbindung an der Komponente annimmt (<alias>.<slot>), bevor eine dieser Regeln greift, sodass jede der folgenden Regeln ihn so liest wie einen Eintrag, der einen eigenen Slot der Component benennt.
  • Der Zustellmechanismus as: (env oder file) muss im inject:-Array dieses Slots zugelassen sein.
  • Slots, die im featuresSchema der Component mit inject: [] (Blackbox) markiert sind, dürfen nicht in attachments:-Blöcken der Workload erscheinen – diese Slots werden über die interne Verdrahtung des Recipe zugestellt (z. B. über Helms existingSecret), nicht über eine Freigabe in der Workload.

Beispiel:

# In the Component
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
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected — root_password is blackbox

Health-Probes: Absicht, nicht Mechanismus

Kubernetes-Probes und Docker-Compose-Healthchecks haben unterschiedliche Formen. Eine einzige abstrakte Absichtsform lässt sich sauber in beide übersetzen:

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

Providers übersetzen jede Absicht in ihre native Form:

AbsichtHelm (K8s)Compose
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"
exec: [cmd]exec.command: [cmd]CMD [cmd]

Die Portauflösung für http: ohne expliziten Port nimmt den alphabetisch ersten Portnamen, den der Container unter containers.<name>.ports deklariert, auf beiden Zielen. Ein Container, der keinen benannten Port deklariert, kann keine HTTP-Probe tragen, und der Build bricht ab und nennt die Probe.

Compose reduziert HTTP/TCP-Probes auf Healthcheck-Shell-Befehle, und ein Compose-Service trägt einen einzigen Healthcheck: Wo mehr als eine Probe deklariert ist, wird eine übersetzt, und eine Warnung nennt die verworfenen.

Volume-Typen

Fünf Volume-Typen; keine zusammengesetzten:

TypSemantikK8s (helm)Compose
ephemeralTmpfs / emptyDir; endet mit dem PodemptyDir: { sizeLimit }tmpfs:-Mount ohne Größenangabe (eine Warnung meldet ein verfasstes sizeLimit)
configmapSchreibgeschützte KonfigurationsdateienVerweis auf ein ConfigMap-Volumeconfigs:-Verweis auf Dienstebene auf eine Konfiguration der obersten Ebene, die die artifacts: des Recipe deklarieren
secretSchreibgeschützte Secret-DateienVerweis auf ein Secret-Volumeschreibgeschützte, per Bind-Mount eingebundene Secret-Datei
persistentEinzelner PVC; übersteht Pod-NeustartsPVC-Ressource + volume.persistentVolumeClaimbenanntes Volume
persistentTemplatePVC pro Replikat; Gegenstück zu form: statefulStatefulSet.volumeClaimTemplatesbenanntes Volume (herabgestuft; Warnung wird ausgegeben)

Compose kann keine Vorlagen pro Replikat ausdrücken. Wenn persistentTemplate nach Compose übersetzt wird, wird es zu einem einzelnen benannten Volume herabgestuft, das alle Replikate gemeinsam nutzen, und eine Warnung meldet die Herabstufung. Ein persistentTemplate-Volume erfordert form: stateful; wird es auf einer anderen Form deklariert, bricht der Build ab.

Freigaben mehrerer Dienste

Jeder Dienst ist eine unabhängige Freigabe. Ein gängiges Muster: ein HTTP-Dienst auf Port 8080 (ClusterIP intern) + ein Metrikdienst auf Port 9090 (ClusterIP) + ein Admin-Endpunkt auf Port 9901 (LoadBalancer):

services:
http:
type: ClusterIP
ports:
web: 8080
metrics:
type: ClusterIP
ports:
prom: 9090
admin:
type: LoadBalancer
ports:
admin: 9901

Jeder wird beim Rendern mit dem helm-Anbieter zu einem eigenen Kubernetes-Service-Objekt; bei einem Loopback-Eintrag bricht dieser Anbieter dagegen ab. In Compose veröffentlichen NodePort- und LoadBalancer-Dienste ihre Ports auf jeder Host-Schnittstelle des Compose-Dienstes, Loopback-Dienste nur auf der Loopback-Adresse des Hosts, und ClusterIP- und Headless-Dienste veröffentlichen nichts.

Dienstnamen in der K8s-Ausgabe erhalten zur Eindeutigkeit die instance_id der Komponente als Präfix. Portnamen müssen den Container-Portnamen entsprechen, die in containers.<name>.ports deklariert sind.

Übersetzungsvertrag auf Provider-Seite: workloadSchema

Ein Plugin, das als Anbieter rendert (pluginType: provider), deklariert ein spec.provider.workloadSchema – eine Deklaration in JSON Schema 2020-12, die dokumentiert, wie Workload-Felder in die native Ausgabe dieses Anbieters übersetzt werden. Dies ist der selbstdokumentierende Übersetzungsvertrag. Siehe ../language-reference/entities/plugin.md zur Authoring-Oberfläche des Plugin, einschließlich des Blocks spec.provider.

apiVersion: aggrega.ai/v1beta1
kind: Plugin
metadata:
name: helm-renderer
version: 1.0.0
pluginType: provider
spec:
abiVersion: v1beta1
provider:
workloadSchema: | # how Workload translates to K8s manifests
// Each Workload produces: 1 controller object chosen by workload.form
// (stateless -> Deployment, stateful -> StatefulSet, daemon -> DaemonSet, task -> Job)
// + 1..N Services (one per workload.services entry)
// + 1..N PVCs (one per workload.volumes.*.persistent entry)
// + 1..N ConfigMap volume refs (from workload.volumes.*.configmap.source)
// ...

Das Feld workloadSchema vermittelt Katalogautoren und IDE-Werkzeugen die Übersetzungsabsicht. Es ist der dokumentierte Übersetzungsvertrag, nach Konvention auf synthetisierenden Anbietern deklariert – aber die Unterstützung der Synthese wird vom Anbieter selbst bestimmt, nicht vom Vorhandensein dieses Feldes. Ein Recipe, das mit workload: auf einen Anbieter zielt, der nicht synthetisieren kann, wird beim Rendern des Knotens abgelehnt – durch die Prüfung der Anbieterfähigkeiten – mit einem klaren Fehler, unabhängig davon, ob der Anbieter workloadSchema deklariert.

Das Plugin-Schema deklariert spec.provider.workloadSchema – sein Inhalt wird beim Laden des Plugin zu JSON Schema 2020-12 kompiliert –, und die Verarbeitung von workload: auf Recipe-Seite wird ausgeliefert. Die Unterstützung der Synthese wird zur Renderzeit durch die Prüfung der Anbieterfähigkeiten durchgesetzt, die sich auf die gemeldete Fähigkeit des gebundenen Anbieters stützt; workloadSchema ist der dokumentierte Vertrag, den der Katalog der Standardbibliothek mit dieser Fähigkeit synchron hält, nicht selbst die Eingabe der Prüfung. aggrega validate, über den gesamten Katalog ausgeführt, meldet zusätzlich frühzeitig, vor einem Build, ein workload:-Recipe, das an einen nicht synthetisierenden Anbieter gebunden ist, sofern der Katalog die Plugin-Entität dieses Anbieters enthält.

Hilfsressourcen liegen außerhalb der Workload

Die Workload-Spezifikation hat kein Feld additionalResources, kein extras und keine Inline-Deklarationen von ConfigMap/Secret/CRD. Die Workload modelliert nur die Form der Arbeitslast: Container, Volumes, Dienste, Replikate, Scheduling, Sicherheitskontext, Service-Account – alles, was beschreibt, wie die einzelne Recheneinheit läuft.

Hilfsressourcen haben zwei legitime Orte außerhalb der Workload:

  1. Features + FeatureRecipes – der Mechanismus für querschnittliche Belange. Ein ServiceMonitor, der an „jeden Server mit freigegebenen Metriken“ angebunden ist, ist core/prometheus-exporter als Feature. Auch die Routing-Ressource, die einen Server unter einem Hostnamen veröffentlicht, ist ein Feature, und die Routing-Form entscheidet, welches: core/public-ingress, wo das Ziel einen Ingress abgleicht, core/http-route, wo es die Gateway API betreibt – jeweils umgesetzt durch ein FeatureRecipe, das das Manifest pro Release auswählt. Eine auf allen Produktionsarbeitslasten durchgesetzte NetworkPolicy ist ein Feature, das das Produktions-Release über die gesamte Boundary hinweg anbindet. Features lassen sich orthogonal kombinieren und über Recipes hinweg wiederverwenden. Siehe 14-extensibility.md zur Ressourcenerzeugung durch FeatureRecipe.
  2. artifacts: auf Recipe-Ebene – für Ressourcen, die zur Implementierung genau dieses Recipe gehören und für die sich kein eigenes Feature lohnt. Eine einmalige CRD-Registrierung, die das Recipe benötigt. Ein Recipe-spezifisches PodDisruptionBudget, das nur gilt, wenn dieses Recipe verwendet wird. Eine ConfigMap, auf die die Workload des Recipe verweist. Jeder Eintrag ist inline oder per $import: geladen; siehe den Abschnitt zum Artefaktmechanismus weiter unten.

Die Grenze zwischen Feature und Artefakt ist eine soziale Konvention. Ist eine Hilfsressource querschnittlich (gilt sie für viele Recipes oder wird sie bedingt über Selektoren angebunden), ist sie ein Feature. Ist sie diesem einen Recipe eigen (das Recipe kann seine Aufgabe nicht erfüllen, ohne diese Ressource auszugeben), ist sie ein Artefakt. Autoren entscheiden anhand von Wiederverwendung und Anbindungssemantik; der Compiler überwacht die Wahl nicht.

Features und Recipe-Artefakte decken zusammen die Hilfsressourcen ab, die ein Recipe benötigt.

Der Artefaktmechanismus

Inline und aus Dateien geladene Artefakte

Die Eingabeart artifacts gibt vorlagenbasierte anbieternative Manifestdateien direkt in die Ausgabe der Boundary aus, neben jeder aus der Quelle gerenderten oder aus der Arbeitslast synthetisierten Ausgabe. Autoren deklarieren sie über zwei Oberflächen:

spec:
artifacts:
"servicemonitor.yaml": |
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: {{ .context.instance_id }}-monitor
spec:
endpoints:
- port: {{ .workload.services.metrics.ports.prom }}
"networkpolicy.yaml":
$import: ./artifacts/networkpolicy.yaml
"crd-registration.yaml":
$import: ./artifacts/crd-registration.yaml

Die $import:-Pfade sind relativ zum Recipe-Verzeichnis und müssen darin bleiben, denn jede Datei, die eine Veröffentlichung des Recipe mitführt, wird aus diesem Verzeichnis genommen – jede Datei, die ein Import benennt, reist mit ihr –, und eine Datei außerhalb würde das nicht. Eine typische Konvention legt sie in einem Unterverzeichnis ./artifacts/ ab, auch wenn der Compiler dies nicht erzwingt. Der Map-Schlüssel benennt jede ausgegebene Datei – der nächste Abschnitt behandelt, was das in jeder der drei Formen bedeutet.

Jeder Eintrag (inline oder per $import: geladen) wird als Go-Vorlage gegen den vollständigen Vorlagenkontext ausgewertet, bevor er in das Ausgabeverzeichnis geschrieben wird.

Was jede Ausgabedatei benennt

Die Map ist nach Eintragsnamen geschlüsselt, und der Schlüssel benennt in jeder Authoring-Form, was der Eintrag ausgibt. Bei einem Inline-Eintrag ist der Schlüssel der Name der Ausgabedatei, so verwendet, wie er geschrieben ist:

artifacts:
"configmap-config.yaml": |
...
"pdb.yaml": |
...

Erzeugt configmap-config.yaml und pdb.yaml. Der Schlüssel legt den Dateinamen fest; wo die Datei landet, entscheidet das Ziel, und der Abschnitt zur Ausgabe pro Anbieter weiter unten behandelt dies.

Bei einem $import:-Eintrag für eine Datei ist der Schlüssel ebenfalls der Name der Ausgabedatei. Die importierte Datei liefert den Inhalt; sie liefert nicht den Namen, daher schreibt ein Autor, der einen bestimmten Ausgabedateinamen möchte, diesen Namen als Schlüssel:

artifacts:
"monitor.yaml":
$import: ./artifacts/monitor.yaml
"netpol.yaml":
$import: ./artifacts/subdir/some-other-name.yaml

Erzeugt .../monitor.yaml und .../netpol.yaml. Die importierte Datei des zweiten Eintrags heißt some-other-name.yaml, und dieser Name erreicht die Ausgabe nicht – der Schlüssel tut es. Zwei Einträge, die unterschiedliche Dateien mit zufällig gleichem Namen importieren, ./extras/shared.yaml und ./overrides/shared.yaml, sind daher zwei verschiedene Ausgaben, jede nach ihrem eigenen Schlüssel benannt.

Bei einem $import:-Eintrag für eine Bibliothek, der ein Bündel von Dateien als eine Einheit einbindet, wird der Eintrag zu einer Ausgabe pro Datei des Bündels erweitert, jede unter dem Schlüssel als <key>/<filename> verschachtelt. Ein Schlüssel benennt viele Dateien, daher kann der Schlüssel allein sie nicht benennen: Er ist das Verzeichnis, in dem die Dateien des Bündels landen, und nicht der Name einer einzelnen von ihnen.

Da jede Form ihre Ausgabe nach dem Schlüssel benennt, ist der Schlüssel an der Authoring-Oberfläche auf das beschränkt, was ein einzelner Dateiname sein kann: ein führender Buchstabe oder eine führende Ziffer, dann Buchstaben, Ziffern, Punkte, Bindestriche und Unterstriche. Die Punkte tragen die Erweiterung, die ein Konsument erwartet, und das macht einen Schlüssel direkt als Dateinamen verwendbar; und das Alphabet enthält kein / und keinen führenden ., sodass ein Schlüssel nie mehr als ein Pfadsegment bilden und nie das Segment des übergeordneten Verzeichnisses sein kann. Ein Schlüssel außerhalb des Alphabets scheitert an der Envelope-Validierung beim Laden des Workspace, bei aggrega validate und in den Diagnosen des Editors.

Zwei artifacts:-Ausgaben mit demselben Dateinamen lassen den Build beim Rendern des Knotens abbrechen, gleich welche Formen sie erzeugt haben. Zwei Einträge einer artifacts:-Map benennen nie dieselbe Ausgabe: Ein Schlüssel ist innerhalb eines Dokuments eindeutig und ist ein einzelner Dateiname, daher ist der Ausgabename eines Einzeldatei-Eintrags sein Schlüssel, und die Ausgaben eines Bündel-Eintrags liegen alle unter einem nach seinem Schlüssel benannten Verzeichnis. Das erste Segment jedes ausgegebenen Pfades ist daher der Schlüssel, der ihn erzeugt hat, und unterschiedliche Schlüssel bleiben unterschiedliche Ausgabenamen. Was der Abbruch abdeckt, ist der Fall über Eingabearten hinweg – ein Dateiname, den zwei von ihnen beitragen, etwa eine Chart-Vorlage und ein Artefakteintrag, die beide servicemonitor.yaml erzeugen –, mit einer Diagnose, die jede beitragende Herkunft benennt.

Vorlagenkontext für Artefakte

Artefaktvorlagen haben Zugriff auf den vollständigen Säulenkontext:

  • .values, .infra, .context.*, .locals, .provides, .features, .metadata – die Standardsäulen von Aggrega, beschrieben in 06-data-taxonomy-and-composition.md.
  • .workload – die geparste Workload-Spezifikation dieses Recipe (falls vorhanden). Ermöglicht es Artefakten, ohne Duplizierung auf Workload-Werte zu verweisen, z. B. ein ServiceMonitor, der auf .workload.services.metrics.ports.prom verweist.
  • .source – der aufgelöste Inhalt des Feldes source: (falls vorhanden).

Artefakte werden ausgewertet, nachdem die Workload geparst wurde, daher ist .workload verfügbar, wenn vorhanden. Bei Recipes ohne workload: ist .workload nil; eine Vorlage, die versucht, es zu dereferenzieren, schlägt mit einem klaren Fehler fehl. Bei Recipes ohne source: ist .source nil, mit demselben Fehlerverhalten.

Die Invariante der Abgeschlossenheit

Artefakte müssen in sich abgeschlossen sein. Sie dürfen nur auf die deklarierten Eingaben des Recipe verweisen: den Säulenkontext, die eigene Workload des Recipe (falls vorhanden) und den eigenen source:-Wert des Recipe. Sie dürfen nicht verweisen auf:

  • Ausgaben anderer Recipes in derselben Boundary.
  • Im Umfeld vorhandene Kubernetes-Ressourcen, die das Recipe nicht deklariert hat.
  • Secrets, ConfigMaps oder andere Ressourcen, deren externe Existenz vorausgesetzt wird (sofern nicht über eine deklarierte Säule auf sie verwiesen wird).

Ein ConfigMap-Artefakt, auf das volumes.*.configmap.source der Workload verweist, muss von DIESEM Recipe (über artifacts:, die diese ConfigMap erzeugen) oder von einem an diesen Knoten angebundenen Feature ausgegeben werden. Abhängigkeiten zwischen Recipe-Entitäten innerhalb einer Boundary werden nicht unterstützt.

Diese Invariante bewahrt die Wiederverwendbarkeit von Recipes: Ein Recipe kann in jede Kombination aus Aggregate + Release eingesetzt werden, die seinen Säulenvertrag erfüllt, ohne versteckte Abhängigkeiten.

Herkunftslabels

Nach der Übersetzung trägt jede ausgegebene Datei in ihren Metadaten eine aggrega.ai/*-Herkunft – ob sie aus der Quelle gerendert, aus der Arbeitslast synthetisiert oder aus einer Artefaktvorlage ausgegeben wurde. Jede ausgebende Oberfläche stempelt sie aus einem gemeinsamen Satz von Buildern, sodass dieselbe Datei immer dieselbe Herkunft trägt, gleich welche Eingabeart sie erzeugt hat. Der Satz teilt sich danach, ob ein Wert dem Zeichensatz für Kubernetes-Labelwerte genügt: labelsichere Schlüssel sind Labels (abfragbar); für den Zeichensatz unsichere Schlüssel – recipe-uri (enthält ein :), boundary-path (ein verschachtelter Pfad enthält /) und sync-wave (das führende - einer negativen Welle) – sind Annotationen, deren Werte keinen Einschränkungen unterliegen. Ein Identitätswert, den der Build nicht an die Labelregeln bindet – der Name des Aggregats, die Umgebung, der Providername, die Compiler- und Providerversionen –, ist ein Label in einer Form, die ein Label zulässt, und wo diese Form vom Wert abweicht, ist der unveränderte Wert zusätzlich eine Annotation unter demselben Schlüssel (ein Aggregate namens imported/flow erhält das Label imported-flow und die Annotation imported/flow). Alle Dateien, die die Ausgabe desselben Recipe tragen, teilen dieselbe Herkunft:

metadata:
labels:
aggrega.ai/component-id: api
# ... plus the recommended app.kubernetes.io/name label
annotations:
aggrega.ai/recipe-uri: api-server-helm:1.0.0
aggrega.ai/boundary-path: production

Diese Aufteilung ist über alle drei Eingabearten einheitlich. (Der Compose-Anbieter kennt kein Annotationskonzept, und seine Labelwerte unterliegen keinen Einschränkungen, daher gibt er den gesamten Satz als Dienstlabels aus.) Siehe 11-governance-and-compliance.md zum Stempeln der Herkunft zur Kompilierzeit.

Da ein Anbieter die Herkunft dort stempelt, wo sein eigenes Ausgabeformat sie aufnimmt, gibt ein Anbieter, dessen Format für eine bestimmte Datei keinen solchen Ort bietet, diese Datei unverändert aus und meldet dies. Compose ist der Fall, den man kennen sollte: Sein Ort für die Herkunft ist der labels:-Block eines Dienstes, daher trägt ein Compose-Artefaktfragment, das nur volumes:, configs: oder models: auf oberster Ebene beiträgt, keine Herkunft, und der Build gibt eine Warnung „skipped provenance label injection (Injektion der Herkunftslabels übersprungen)“ aus, die das Artefakt nennt. Diese Warnung ist für ein Fragment dieser Form zu erwarten und kein Zeichen für ein Problem – die Dienste, die dieselbe Komponente ausgibt, tragen den vollständigen Satz, und an den ausgegebenen Bytes ändert sich nichts. Was sie ausschließt, ist die dritte Möglichkeit: eine Datei, die den Build ungestempelt verlässt, ohne genannt zu werden.

CloudFormation ist der andere Fall, den man kennen sollte, und er unterscheidet sich darin, wo die Herkunft landet, nicht darin, ob sie landet. Eine CloudFormation-Vorlage hat keinen Metadatenblock auf Dokumentebene, der mit einer Ressource mitreist, daher kommt die Herkunft in das eigene Metadata-Attribut jeder Ressource, unter einem einzigen Schlüssel aggrega.ai/provenance, der den gesamten Satz enthält:

"StoreBucket": {
"Type": "AWS::S3::Bucket",
"Metadata": {
"aggrega.ai/provenance": {
"aggrega.ai/component-id": "store",
"aggrega.ai/recipe-uri": "store-recipe:1.0.0",
"aggrega.ai/boundary-path": "stack"
}
}
}

Aus diesem Ort folgen drei Eigenschaften. Das Metadata-Attribut ist auf jeder Ressource verfügbar, gleich welchen Typs, daher wird jede Ressource, die ein zusammengesetzter Stack enthält, gestempelt – einschließlich der vielen Ressourcentypen, die überhaupt keine Tags akzeptieren und auf denen ein tagbasierter Stempel keinen Platz gehabt hätte. Der Stempel wird zu jedem vom Autor geschriebenen Metadata hinzugefügt, statt es zu ersetzen, sodass die eigenen Einträge des Autors daneben bestehen bleiben. Und weil er pro Ressource statt pro Vorlage gilt, trägt ein Stack, zu dem mehrere Komponenten beitragen, die eigene beitragende Identität jeder Ressource – ihre Komponente, ihr Recipe und ihre Boundary –, was ein einzelner vorlagenweiter Eintrag nicht ausdrücken könnte.

Der gesamte Satz reist gemeinsam unter diesem Schlüssel. Ein Metadata-Wert ist uneingeschränktes JSON, daher ist keine Aufteilung nach Zeichensatz nötig; die beiden Schlüssel, die nur eine Kubernetes-Laufzeit liest – der Name des empfohlenen Standardlabels und die Annotation zur Deployment-Reihenfolge, die ein GitOps-Controller verarbeitet –, werden weggelassen, da keiner von beiden etwas in einem Stack benennt. Der einfache Herkunftseintrag aggrega.ai/sync-wave bleibt, weil er die von der Komponente deklarierte Welle festhält, statt einen Controller anzuweisen.

Die Form, die hier keinen Ort hat, ist eine Vorlage oder ein Fragment, das keine Ressource deklariert – eines, das nur Parameters, Mappings, Conditions oder Rules beiträgt. Es trägt keine Herkunft, erreicht den zusammengesetzten Stack mit unverändertem Inhalt, und der Build gibt eine Warnung „skipped provenance injection (Herkunftsinjektion übersprungen)“ aus, die es nennt. Wie bei Compose ist diese Warnung für einen Beitrag dieser Form zu erwarten: Die Ressourcen, die dieselbe Komponente an anderer Stelle beiträgt, tragen den vollständigen Satz, und die ausgegebenen Bytes sind dieselben, ob nun etwas zuhört oder nicht.

Artefakt-Semantik pro Provider

Die folgende Semantik pro Provider beschreibt, wie jeder Provider Artefakte in seine native Ausgabe integriert.

helm-Provider: Artefakte sind Kubernetes-YAML-Dokumente, die in ein Verzeichnis geschrieben werden, das nach der Komponente benannt ist, die sie deklariert hat, innerhalb des Ausgabeverzeichnisses, das die aus dem Chart gerenderten und aus der Workload synthetisierten Manifeste enthält. Der Grund ist die Benennung: Ein gerendertes oder synthetisiertes Manifest wird vom Provider nach der Komponente benannt, zu der es gehört, während ein Artefakt nach dem Schlüssel benannt wird, den sein Autor geschrieben hat, und dieser sagt nichts darüber aus, um welche Komponente es sich handelt — zwei Komponenten, die an ein Recipe gebunden sind, würden also einen einzigen Pfad schreiben, ohne dass einer der beiden Autoren sie trennen könnte. Das Verzeichnis trägt den eigenen Namen der Komponente, sodass die Datei, die der Autor in der Ausgabe wiederfindet, den Namen trägt, den er geschrieben hat, eine Ebene tiefer.

Ein Operator, der ein anderes Layout wünscht, verfügt über das subDirectory:-Template der Boundary, das jede Datei verschiebt, die ein Beitragender ausgibt, und nicht nur die Artefakte. Siehe ../language-reference/path-template-variables.md.

compose-Provider: Artefakte sind Compose-Fragmente. Schlüssel der obersten Ebene (services:, volumes:, configs:, models:) werden im Kompositionsschritt der Boundary in die kombinierte docker-compose.yaml der jeweiligen Boundary zusammengeführt.

helm-chart-Provider (Sonderfall): Artefakte werden nicht als eigenständige Dateien in das Ausgabeverzeichnis geschrieben — Helm besitzt die Render-Pipeline. Stattdessen platziert der helm-chart-Provider jeden artifacts:-Eintrag im Chart selbst, und die Form, in der der Eintrag verfasst ist, entscheidet, wo er landet. Jeder Eintrag wird ZUERST, vor jeder Platzierung, mit dem Säulen-Kontext von Aggrega als Go-Template verarbeitet; ab dort gehen die beiden Formen auseinander. Ein per $import: geladener Eintrag ist eine Pre-Helm-Template-Datei: Er wird VOR dem Helm-Rendering in das templates/-Verzeichnis des Charts injiziert, sodass Helm ihn zusammen mit den eigenen Templates des eingebundenen Charts rendert. Ein Inline-Blockskalar ist eine lose Chart-Datei: Er wird im Chart-Stammverzeichnis unter seinem verfassten Schlüssel abgelegt, ohne templates/-Präfix und ohne zusammengeführte Provenienz-Labels, sodass die eigenen Templates des Charts ihn über Helms .Files.Get / .Files.Glob lesen können — das ConfigMap-aus-Dateien-Muster. Damit erhält der helm-chart-Provider einen Erweiterungsmechanismus, der dem entspricht, was artifacts: für den einfachen helm-Provider bietet, und respektiert dabei das Chart-Modell von Helm.

Die injizierte Datei landet unter boundaries/<bp>/charts/<nodeID>/templates/<authored-key> — die Dateien eines Bundles unter diesem Schlüssel verschachtelt —, sodass sie neben den Templates des eingebundenen Charts liegt und Helm sie im nachgelagerten Render-Durchlauf aufnimmt. Ein Inline-Blockskalar landet unter boundaries/<bp>/charts/<nodeID>/<authored-key> — dem Chart-Stammverzeichnis, eine Ebene über templates/ —, weil eine über .Files gelesene Datei dort liegen muss, wo das Chart nach ihr sucht, und eine unter templates/ abgelegte Datei stattdessen als Manifest gerendert wird. Beide Formen werden nach dem Schlüssel benannt, unter dem sie verfasst sind; was sie unterscheidet, ist das Verzeichnis, in das der Provider sie legt.

Delimiter-Konvention von helm-chart. Der Pre-Template-Durchlauf von Aggrega für helm-chart-Artefakteinträge, per $import: geladene wie inline geschriebene, verwendet die Delimiter [[ ]] statt der standardmäßigen {{ }}, sodass Helms eigene {{ ... }}-Syntax in der Datei unverändert in Helms Render-Durchlauf gelangt. Autoren schreiben Ersetzungen auf Aggrega-Seite als [[ .context.instance_id ]], [[ .values.name ]] usw.; Ersetzungen auf Helm-Seite bleiben {{ .Values.x }}, {{ .Release.Name }}, {{- include "common.labels" . }} usw. Das Mischen der beiden Delimiter-Paare in einer Datei ist die unterstützte Form des Verfassens.

Provenienz und helm-chart-Artefakte. Die Provenienz wird in metadata.labels und metadata.annotations (gemäß der oben beschriebenen Aufteilung nach Zeichensatz) für per $import: geladene Dateien zusammengeführt, die einen YAML-Round-Trip mit erhaltenen Helm-Tokens überstehen — Dateien, die nur [[ ]]-Kontext von Aggrega verwenden oder Helm-{{ }} nur an Positionen von Skalaren in Anführungszeichen. Dateien mit strukturellen Helm-Template-Aktionen ({{- include ... }}, {{- if ... }}, {{- range ... }}, {{- with ... }} an Positionen, an denen sie YAML-Struktur statt skalarer Blätter ausgeben) oder Dateien mit {{ ... }} ohne Anführungszeichen an Wertpositionen überstehen den YAML-Round-Trip von Aggrega nicht; der Build gibt eine Warnung „skipped provenance label injection (Injektion der Provenienz-Labels übersprungen)“ aus, die das Artefakt nennt, und reicht die Datei unverändert durch. Diese Warnung ist für jede per $import: geladene helm-chart-Artefaktdatei zu erwarten, die strukturelle Helm-Template-Aktionen oder Helm-Wertersetzungen ohne Anführungszeichen verwendet — das ist der Regelfall beim Verfassen von Helm in der Produktion, nicht der Randfall. Autoren, die Provenienz-Labels in solchen Dateien benötigen, injizieren sie über ein benanntes Template, das sie in der eigenen _helpers.tpl des Charts schreiben (zum Beispiel eines namens aggrega.commonLabels), oder über einen gleichwertigen Mechanismus auf Helm-Seite, nicht über die Pre-Template-Injektion von Aggrega.

Kollisionen mit Dateinamen im Chart-Stammverzeichnis. Ein per $import: geladenes Artefakt, dessen verfasster Schlüssel mit einem Dateinamen im Chart-Stammverzeichnis kollidiert (Chart.yaml, values.yaml, .helmignore usw.), wird von der Dateinamen-Kollisionsprüfung von Aggrega nicht erkannt — das Artefakt landet unter templates/<authored-key>, während die Stammdatei im Chart-Stammverzeichnis landet, und das Pfadpräfix macht sie aus Sicht von Aggrega verschieden. Autoren vermeiden diese Schlüsselnamen; die Folge ihrer Verwendung ist, dass Helm beide Dateien sieht (eine im Chart-Stammverzeichnis, eine in templates/) und die Kopie auf der templates-Seite unerwartet rendern kann.

terraform-Provider: Artefakte sind Terraform-Konfigurationsdateien, die unverändert in das eigene Verzeichnis der Komponente unter dem modules/-Baum der Boundary ausgegeben werden. HCL (main.tf) ist der ergonomische Standard, und Terraform JSON (.tf.json) wird gleichwertig akzeptiert; keines von beiden wird transpiliert oder neu formatiert. Die Stammkonfiguration der Boundary deklariert diese Komponente als module-Block, dessen source auf dieses Verzeichnis zeigt, sodass eine ganze Boundary ein einziger Abhängigkeitsgraph bleibt; es ist dasselbe Verzeichnis, das die Dateien eines vendorten Moduls belegen, sodass ein Recipe, das sowohl source: als auch artifacts: deklariert, sie nebeneinander schreibt. Die Provenienz wird als führender Terraform-Kommentarblock mitgeführt; wo eine Komponente einen JSON-Body beiträgt, der keine Kommentarsyntax hat, wird jeder Body unverändert ausgegeben, und die Provenienz reist in einer begleitenden, nur aus Kommentaren bestehenden .tf-Datei daneben, sodass der Stempel nie über beide hinweg dupliziert wird. Siehe die Seite des terraform-Providers.

cloudformation-Provider: Artefakte sind Stack-Fragmente — die Ressourcen, die eine Komponente beiträgt, statt eines ganzen Templates. Der Provider normalisiert jedes Fragment zu reinen JSON-Intrinsics in Langform und führt es in den einzigen Stack zusammen, der für dieses Ausgabeverzeichnis assembliert wird, wo die Ressourcen in eine gemeinsame Resources-Map eingehen und die provides der Komponente als Stack-Outputs unter Namen erscheinen, die auf die veröffentlichende Komponente beschränkt sind. Welche anderen Abschnitte der obersten Ebene eines Fragments die Assemblierung überstehen, steht unter Was ein zusammengeführtes Dokument aus artifacts: übernimmt. Siehe die Seite des cloudformation-Providers.

Der Boundary-Bereich: Dateien für die gemeinsame Ausgabe einer Boundary

Der Artefakt-Mechanismus hat einen zweiten Bereich. Alles oben Beschriebene wird an die eigene Position der Komponente in der Ausgabe ihrer Boundary geschrieben; spec.boundary.artifacts eines Recipe ist dieselbe Map — dieselben drei Formen, dieselbe Regel von Schlüssel zu Dateiname, derselbe Template-Kontext —, die stattdessen einmal für die Boundary als Ganzes geschrieben wird. Sie existiert für eine Datei, die das Ziel einmal für alles liest, was eine Boundary bereitstellt, und die keine eigene Position einer Komponente aufnehmen kann: Die Terraform-Dokumentation besagt, dass ein Modul, das aufgerufen werden soll, keine provider-Blöcke enthalten darf und dass ein Modul, das welche enthält, nicht mit depends_on, count oder for_each aufgerufen werden kann; die Konfiguration eines Providers gehört daher in die Stammkonfiguration der Boundary und nicht in das Modul einer Komponente.

Wo sie landet. In dem Verzeichnis, das die assemblierte Ausgabe der Dispatch-Gruppe enthält, neben den Dateien, die die eigene Assemblierung des Providers dort schreibt — bei terraform neben der Stammkonfiguration. Der Compiler wertet jeden Eintrag einmal pro Komponente aus, die das Recipe rendert, gegen den Kontext dieser Komponente, und schreibt die Datei selbst: Dem Provider wird keine dieser Dateien übergeben, und in keine wird gestempelt, von welcher Komponente sie stammt, weil sie jedem Beitragenden gehört, der sie deklariert hat.

Wie Beitragende zusammentreffen. Die Dateien, die jeder Beitragende zu einer Dispatch-Gruppe deklariert hat, werden nach Namen zusammengeführt. Ein Name, der mit identischen Bytes deklariert ist, ergibt eine Datei; ein Name, der mit unterschiedlichen Bytes deklariert ist, oder ein Name, den die Assemblierung des Providers selbst schreibt, stoppt den Build unter Nennung der Datei und jedes Beitragenden — dieselbe Ablehnung, auf die zwei Beitragende stoßen, die einen Ausgabepfad schreiben. Eine Provider-Konfiguration, die zwei Recipes benötigen, wird also von beiden unter einem Namen geschrieben, und der Build prüft, dass sie übereinstimmen.

Wer sie akzeptiert. Ob eine neben der assemblierten Ausgabe einer Boundary abgelegte Datei etwas bedeutet, ist eine Eigenschaft des Ziels des Providers; es ist daher die eigene Angabe des Providers, die wie seine Input-Arten aus der eigenen Deklaration des Providers gelesen wird. Ein Recipe, das den Block für einen Provider deklariert, der diese Angabe nicht macht, wird abgelehnt, bevor irgendetwas gerendert wird. Das Raster unten führt die Angabe in seiner letzten Spalte; von den mit dem Compiler ausgelieferten Providern macht terraform sie.

Was Artefakte nicht sind

Drei strukturelle Unterscheidungen:

Nicht providerübergreifend innerhalb eines einzelnen Recipe. Ein Recipe deklariert genau eine capability: am Anfang seiner spec. Alles, was das Recipe erzeugt — aus der Quelle gerenderte Ausgabe, aus der Workload synthetisierte Ausgabe und Artefakt-Ausgaben —, liegt im nativen Format dieses Providers vor. Die Artefakte eines helm-Recipe enthalten Kubernetes-YAML. Die Artefakte eines compose-Recipe enthalten Compose-Fragmente. Ein Recipe zielt auf einen Provider; jede Ausgabe liegt im nativen Format dieses Providers vor.

Die Komposition mehrerer Provider erfolgt auf Release-Ebene. Boundaries enthalten Komponenten mit gemischten Providern; die Beitragenden jedes Providers am ausgewerteten Pfad einer Boundary werden unabhängig pro (Pfad, Provider) verteilt und assembliert. Ein Release mit Komponenten, die jeweils auf helm, helm-chart und compose zielen, kann alle drei in einer Boundary platzieren; die Dispatch-Gruppierung partitioniert sie pro Provider, die Beitragenden jedes Providers landen in ihrer eigenen assemblierten Ausgabe unter dem Pfad der Boundary, und der Operator verfasst die providerübergreifende Koordination über die Boundary-Struktur, die er wählt. Die providerübergreifende Koordination liegt in der Verantwortung des Release-Autors.

Keine Recipes in Recipes. Artefakte laden oder komponieren keine anderen Recipes. Sie sind Inline-Manifeste (oder Dateipfade zu Inline-Manifesten), mit den Säulen dieses Recipe als Template verarbeitet und in die Ausgabe dieses Recipe ausgegeben. Die Wiederverwendung eines Recipe erfolgt über drei Mechanismen: das extends: einer Component (ein für eine Basis-Component geschriebenes Recipe bedient jede Component, die sie erweitert; vererbt werden Metadaten und Schemas, nicht Ausgabedateien — ein Recipe selbst deklariert kein extends:); die flache URI-Zuordnung des Manifest (dieselbe Component kann in verschiedenen Katalogen zu verschiedenen Recipes aufgelöst werden — siehe ../language-reference/entities/manifest.md); und Features + FeatureRecipes (querschnittliche Belange, orthogonal angehängt).

Keine Recipe-übergreifende Verbindungsschicht. Artefakte können nicht auf Namen, Ressourcen oder Zustände verweisen, die das Recipe nicht selbst deklariert hat. Ein ConfigMap-Artefakt, auf das die Workload des Recipe verweist, muss von diesem Recipe ausgegeben werden. Ein Artefakt, das ein extern bereitgestelltes Secret erwartet, muss den Namen dieses Secret über die Säule .features erhalten — aus den aufgelösten provides des Attachments, das es ausgibt —, statt anzunehmen, dass es existiert. Dies ist die Invariante der Abgeschlossenheit (siehe oben), aus der Perspektive des Verfassens von Artefakten formuliert: Jedes Recipe gibt Dateien in einem Format aus, die von einem Werkzeug angewendet werden, in das Ausgabeverzeichnis einer Boundary.

Provider-Fähigkeitsmatrix

Jeder Provider deklariert, welche Input-Arten er rendert; ein zentrales Input-Art-Gate akzeptiert die unterstützten Kombinationen und lehnt die übrigen beim Rendern des Knotens mit einer einheitlichen Diagnose ab. Die Fähigkeit ist eine Eigenschaft des Providers, nicht des Recipe — ein Provider rendert eine Teilmenge der drei Arten. Die Spalte artifacts: unterscheidet Artefakte, die neben einem primären sourced/synthesized Input mitlaufen, von einem eigenständigen reinen Artefakt-Recipe (kein source:, kein workload:). Die letzten beiden Spalten sind die Angaben des Providers, dass er omits: beachtet und dass er die Dateien akzeptiert, die ein Recipe unter boundary.artifacts: zur gemeinsamen Ausgabe seiner Boundary beiträgt (oben); keine von beiden ist eine Input-Art.

Lesen Sie jede Spalte für sich. Eine Zeile gibt an, welche Arten ein Provider rendert, jeweils einzeln betrachtet. Sie besagt nicht, dass zwei angehakte Arten zusammen deklariert werden dürfen. Weil sich die Arten durch Addition zusammensetzen, wird jede deklarierte Art getrennt verteilt und ausgegeben, sodass ein Paar aus einem Grund abgelehnt werden kann, den keine der beiden Spalten wiedergibt — meist, weil beide Arten eine Datei unter demselben Ausgabenamen erzeugen. Welche Kombinationen jeder Provider tatsächlich akzeptiert, ist im Fließtext unter Was jeder Provider akzeptiert, vollständig beschrieben.

Providersource: + valuesMapping:workload:artifacts: (daneben)nur Artefakte (eigenständig)omits:boundary.artifacts:
helm✅✅✅✅✅❌
compose✅✅✅✅✅❌
helm-chart✅❌✅ als Template mit den Delimitern [[ ]] verarbeitet❌❌❌
terraform✅❌✅✅❌✅
cloudformation✅❌✅✅✅❌

Dieses Raster umfasst die mit dem Compiler ausgelieferten Provider. Ein separat bereitgestellter Provider deklariert auf dieselbe Weise, welche Input-Arten er akzeptiert, ob er omits: beachtet und ob er boundary.artifacts: akzeptiert, und der Compiler liest diese Deklaration auf demselben Weg — er ist hier nicht aufgeführt, weil eine veröffentlichte Seite keine Provider aufzählen kann, die sie nie gesehen hat.

Mit ✅ markierte Zellen werden gerendert; ❌ ist eine vom Gate gemeldete Ablehnung aufgrund der Provider-Fähigkeit. Die Compose-Fragmente pro Knoten werden pro Assemblierungspfad zusammengeführt, sodass Boundaries, die sich ein directory: teilen, sich eine Datei teilen.

Was jeder Provider akzeptiert, vollständig

helm — jede Kombination. source: + valuesMapping:, workload:, artifacts:, zwei beliebige davon oder alle drei. Er ist der einzige mit dem Compiler ausgelieferte Provider, der keine Kombination ablehnt, und der Grund liegt darin, wie er die Ausgabe benennt: Jede ausgegebene Datei wird nach der Ressource benannt, die sie enthält, sodass die gerenderten Manifeste eines Charts und die Manifeste einer synthetisierten Workload nie unter einem Namen landen. Ein Recipe, das alle drei deklariert, gibt die Dateien des Charts, die Dateien der Workload und die Artefaktdateien nebeneinander im Ausgabeverzeichnis der Boundary aus.

compose — jede Kombination außer den beiden, in denen source: und workload: zusammen vorkommen. Jede Art für sich wird gebaut, und artifacts: kann neben jeder der beiden mitlaufen. source: mit workload: kann nicht gebaut werden, ebenso wenig alle drei zusammen; Warum compose keine Quelle mit einer Workload kombinieren kann erklärt den Grund, und es handelt sich nicht um eine Ablehnung aufgrund der Fähigkeit.

helm-chart — source: + valuesMapping:, allein oder mit artifacts: daneben. Sonst nichts. Er synthetisiert kein workload:, und er hat keine reine Artefakt-Form: Ein Recipe, dessen einzige Input-Art artifacts: ist, bricht ab. Der Grund ist, wo dieser Provider ein Artefakt ablegt — im eigenen Chart der Komponente —, sodass ein Recipe ohne source: ihm kein Chart lässt, in das er es legen könnte.

terraform — drei Formen: source: + valuesMapping: für sich, artifacts: für sich oder beide zusammen. Er synthetisiert kein workload:.

cloudformation — dieselben drei Formen wie terraform, mit demselben einzigen Ausschluss. source: + valuesMapping: für sich, artifacts: für sich oder beide zusammen; kein workload:.

Wie eine abgelehnte Input-Art aussieht

Ein Recipe, das eine Input-Art deklariert, die sein gebundener Provider nicht rendert, bricht den Build beim Rendern des Knotens ab, und zwar unabhängig davon, was das Recipe sonst neben dieser Art deklariert — ein workload: mit einem source: zu kombinieren, das der Provider rendern kann, bringt die Workload nicht durch. Der Abbruch nennt den Provider, die Art, die er nicht rendern kann, und die Arten, die er rendert:

[CATALOG_ERROR E0265] instance unit
provider does not support the node's input kind (node "unit"). provider "terraform" does not support synthesized recipes (this provider supports: sourced, artifacts-only); declare one of the supported input kinds, or target a provider that supports synthesized

Die Ablehnung der reinen Artefakt-Form liest sich genauso und nennt diese Form: provider "helm-chart" does not support artifacts-only recipes (this provider supports: sourced). E0265 ist der Bezeichner, den Sie festhalten sollten, wenn dieser Abbruch dauerhaft benannt werden muss — in einem Continuous-Integration-Gate, einem Issue oder einem Runbook; die Tabelle aller Bedingungen löst ihn auf.

Warum compose keine Quelle mit einer Workload kombinieren kann

Der compose-Provider erzeugt ein Fragment pro Komponente und benennt dieses Fragment nach der Komponente. Das Rendern aus einer Quelle und die Workload-Synthese erzeugen jeweils das Fragment dieser Komponente unter diesem einen Namen, sodass ein Recipe, das beides deklariert, zwei gleichnamige Dateien erzeugt, und der Build bricht bei der Kollision ab:

[CATALOG_ERROR E0211] instance unit
rendering node "unit"
caused by: [CATALOG_ERROR] aggregate.yaml at .spec.components.unit
filename collision across input kinds: two input-kind blocks produced a file under one output name (output name "unit.compose-fragment.yaml", produced by "source, workload")

Der Name des Fragments stammt aus dem eigenen Bezeichner der Komponente, und es gibt keine Möglichkeit, ihn zu verfassen, sodass keine Änderung am Inhalt des Recipe die Kollision vermeidet. Der Abbruch ist eine Eigenschaft des Paares und nicht einer der beiden Arten — compose rendert eine Quelle, und compose synthetisiert eine Workload, und das Raster hakt zu Recht beide an. Um beide Formen für eine Komponente unter compose zu nutzen, teilen Sie sie auf zwei Komponenten auf oder überführen Sie den Inhalt der Quelle in die Workload.

Was ein zusammengeführtes Dokument aus artifacts: übernimmt

Zwei Provider führen ihre Beitragenden pro Assemblierungspfad in ein einziges Dokument zusammen: compose in eine docker-compose.yaml, cloudformation in ein Stack-Template. Ein zusammengeführtes Dokument kann nur die Abschnitte tragen, die sein Assembler modelliert, daher sagt ein Haken bei artifacts:, wo der Inhalt eines Fragments platziert wird, und nicht, dass jeder Schlüssel im Fragment erhalten bleibt.

compose übernimmt aus einem Artefakt-Fragment services:, volumes:, configs: und models:, zusammen mit seinen Erweiterungsschlüsseln mit dem Präfix x-. Ein Fragment, das auf oberster Ebene etwas anderes deklariert, hält den Build an und nennt dabei den Schlüssel — networks:, weil Netzwerke pro Boundary abgeleitet und nicht von Beitragenden gesammelt werden, und ebenso ein secrets:-Block oder ein name: auf oberster Ebene. Die Seite des compose-Providers nennt die Zusammenführungsregeln pro Schlüssel und die Alternative für netzwerkübergreifendes Routing.

cloudformation übernimmt Resources, Outputs, Parameters, Mappings, Conditions, Metadata und Rules und baut Transform aus denen aller Beitragenden. Die Transforms werden in der von CloudFormation dokumentierten Reihenfolge verbunden, wobei die Globals von SAM neben dem Transform mitreisen, der sie liest, und ein Transform, der ändern würde, wie der Inhalt eines anderen Beitragenden bereitgestellt wird, bricht den Build unter Nennung seines Namens ab. Description wird nicht übernommen, und der Build sagt das: Er gibt eine Warnung über ein nicht unterstütztes Feld aus, die den Abschnitt und die Komponente nennt, ebenso wie für jeden anderen Schlüssel der obersten Ebene, den der Stack nicht übernimmt, sodass nichts stillschweigend verworfen wird. Die Warnung ist ein Hinweis — das ausgegebene Template ist Byte für Byte dasselbe wie ohne sie, und --no-unsupported-field-warnings bringt die Klasse zum Schweigen. Outputs wird unter einem Namen übernommen, den der Provider auf die beitragende Komponente beschränkt, sodass zwei Komponenten, die einem Stack eine gleichnamige Ausgabe beitragen, diese getrennt halten. Abschnitte der obersten Ebene im assemblierten Stack gibt über jeden Abschnitt einzeln Auskunft.

Die anderen drei Provider führen nicht zusammen, sodass kein Artefakt-Schlüssel Gefahr läuft, von einem Assembler verworfen zu werden. helm assembliert nichts: Die Manifeste jeder Komponente erreichen das Ausgabeverzeichnis der Boundary unverändert. terraform und helm-chart verschachteln — die Dateien jeder Komponente landen in einem eigenen Verzeichnis, einem Terraform-Modulverzeichnis oder einem Subchart, und ein Stammdokument an der Boundary verweist auf sie —, sodass ein Artefakteintrag als ganze Datei platziert und nicht in ein gemeinsames Dokument eingelesen wird. Wo ein helm-chart-Artefakteintrag landet und warum sein Delimiter-Paar abweicht, steht unter Artefakt-Semantik pro Provider.