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

aggrega build

aggrega build kompiliert ein Paar aus Aggregate + Release in Provider-native Artefakte (Helm-Manifeste, weiterverteilbare Helm-Charts, docker-compose-YAML) unter dist/ im Workspace-Stammverzeichnis, wie Output darlegt. Das Release ist der einzige Einstiegspunkt: Es benennt das Aggregate und das Manifest, deklariert Grenzen und leitet Komponenten an Provider weiter.

Gängige Flags

Zwei Flags haben ein Verhalten, das die Flag-Referenz unten allein nicht vermitteln kann:

  • --catalog <dir> — ein Verzeichnis mit Katalogentitäten — den Authoring-Arten Component, Feature, Recipe und FeatureRecipe zusammen mit den Bibliotheksarten, Aggregates und Plugins —, das rekursiv geladen wird. Jedes --catalog-Verzeichnis wird vor den konfigurierten durchsucht, in der angegebenen Reihenfolge. Um einen projektlokalen Katalog neben einem gemeinsam genutzten zu durchsuchen, übergeben Sie beide (--catalog ./catalog --catalog ../shared-catalog) oder führen Sie sie unter catalog_dirs auf. Mit --detail wird jede Entität, die ein Verzeichnis mit höherem Vorrang verdeckt, auf stderr gemeldet, zusammen mit den anderen Build-Warnungen. Ein --catalog-Verzeichnis, das nicht existiert, hält den Build an und nennt es. Ebenso ein unter catalog_dirs aufgeführtes Verzeichnis, das kein Verzeichnis ist, bevor irgendetwas gelesen oder geschrieben wird, unter Nennung des Eintrags sowie der Konfigurationsdatei und der Zeile, in der er steht — siehe Woher lokale Entitäten gelesen werden. Ein Build, der anhält, weil eine Referenz zu nichts aufgelöst wurde, nennt in der Notiz unter dem Halt jede Datei in diesen Verzeichnissen, die eine Aggrega-apiVersion deklariert — eine Zeile, die ohne Einrückung mit apiVersion: beginnt, mit einem Wert, der mit aggrega.ai/ anfängt — und nicht geladen werden konnte, etwa weil sie sich nicht als YAML parsen lässt, mit der eigenen Begründung des Parsers, unter den beim Laden übersprungenen Katalogdateien; eine YAML-Datei, die eine andere apiVersion oder keine deklariert, ist kein Aggrega-Dokument und wird dort nie genannt.
  • --detail — meldet, was der Pull-Schritt getan hat, dieselbe flüchtige Diagnose der Pull-Ereignisse, die aggrega pull --detail ausgibt. Ob es etwas zu melden gibt, entscheidet sich daran, ob ein Pull-Schritt angefordert wurde — mit --auto-pull oder durch Aktivieren von auto_pull — und nicht daran, ob bereits eine Lockfile vorhanden ist: Ein angeforderter Pull-Schritt läuft in beiden Fällen, füllt eine fehlende Lockfile und respektiert die Pins einer vorhandenen. Wenn kein Pull-Schritt läuft, gibt das Flag einen einzeiligen Hinweis auf stdout aus und fährt fort — es erfindet nie eine Auflösungsstufe, die die committete Lockfile nicht enthält. Für den Zustand der Auflösung der Abhängigkeiten eines Release nach dem Pull verwenden Sie aggrega inspect.

--dry-run wird in Einen Build in der Vorschau ansehen, ohne ihn zu schreiben behandelt, --trace und --trace-unredacted in Trace-Ausgabe und Die zurückgehaltenen Werte anzeigen weiter unten.

Die Lockfile als Teil des Builds füllen

Standardmäßig ist der Build in Bezug auf Abhängigkeiten schreibgeschützt: Er benötigt eine Lockfile und schreibt keine. --auto-pull und die Workspace-Einstellung auto_pull fügen dem Build den Pull-Schritt hinzu, sodass ein einziger Befehl die Abhängigkeiten des Release auflöst und gegen das Aufgelöste kompiliert.

Eine Änderung am Release bemerkt die Lockfile. Die Lockfile erfasst das Release — und jedes Release, das es erweitert — über den Digest seines Inhalts, sodass ein schreibgeschützter Build über ein seit dem Pull bearbeitetes Release anhält, bevor irgendetwas gerendert wird, die Datei nennt und Sie auffordert, aggrega pull --release <release> auszuführen, das die Änderung erfasst und dabei jeden anderen Pin respektiert. Auch ein Kommentar oder eine Änderung an Leerzeichen zählt, weil der Digest die Bytes so abdeckt, wie sie sind. Ein Build mit Auto-Pull führt diesen Pull-Schritt selbst aus, erfasst also die Änderung und baut.

Das Release wird einmal gerendert. Welche externen Eingaben ein Release verwendet, ergibt sich aus seinem Rendering und nicht aus etwas, das seine Dokumente deklarieren, daher rendert der Pull-Schritt das Release, um es herauszufinden — und dieses Rendering ist das des Builds. Ein Build mit Auto-Pull kostet daher ein Rendering, genauso viel wie ein einfacher Build über eine bereits vorhandene Lockfile.

Die Flags, die ein Rendering beeinflussen, gelten dafür. --trace, --verify-determinism, --disable-plugin-cache und --no-unsupported-field-warnings erreichen das Rendering, das ein Build mit Auto-Pull ausführt, unter denselben Bedingungen wie das eines einfachen Builds, sodass Sie einen Trace oder eine Determinismusprüfung erhalten, wenn Sie bei einem Build mit einem einzigen Befehl danach fragen. --dry-run ist die Ausnahme, und zwar eine Ablehnung statt eines Schweigens: Ein Dry Run schreibt nichts, während der Pull-Schritt schreibt, daher hält die Kombination vor jeder Arbeit an (siehe Einen Build in der Vorschau ansehen, ohne ihn zu schreiben).

Wie ein Build liest, was die Lockfile festlegt

Ein Lockfile-Pin benennt einen Inhalt — einen Digest — statt eines Ortes. Für eine Entität ist es der Digest dessen, was eine Veröffentlichung von ihr enthält, ihr Dokument und die Dateien, die es nennt, sodass eine Kopie einer Entität in einem Katalogverzeichnis und ein Cache-Eintrag mit ihrer Veröffentlichung denselben Pin tragen, wie Die Lockfile beschreibt. Ein Build liest jede festgelegte Abhängigkeit aus den Quellen, die bereits auf dem Rechner vorhanden sind: zuerst die Katalogverzeichnisse, wie überall sonst, dann den Inhalts-Cache unter .aggrega/cache. Das Lesen fragt keine Registry an; nur der Pull-Schritt, sofern ein Build einen ausführt, lädt herunter.

Ein Cache-Eintrag, der seinen Pin nicht mehr enthält, wird übergangen. Eine an Ort und Stelle bearbeitete Entität — ein neuer Inhalt unter derselben version — hinterlässt im Inhalts-Cache den früheren Inhalt unter diesem Namen und dieser Version. Wo ein Katalogverzeichnis eine Kopie enthält, deren Inhalt den Pin als Digest ergibt, liest der Build diese Kopie und nie den Eintrag, und er meldet dies auf der Standardfehlerausgabe, wobei er den Eintrag und beide Digests nennt:

reuse: cache entry for <name>:<version> holds <digest the entry holds>, not the pinned <pinned digest>; passed over for <catalog file>, which holds the pinned bytes

Wo kein Katalogverzeichnis die Entität enthält, wird ein vollständiger Cache-Eintrag mit genau den festgelegten Bytes als Abhängigkeit gelesen, sodass eine Entität, die aus ihrem Katalogverzeichnis entfernt wurde, nachdem ihre veröffentlichte Kopie heruntergeladen wurde, weiterhin aus dieser Kopie gebaut wird.

Wo keine Quelle die festgelegten Bytes enthält, hält der Build an, bevor irgendetwas gerendert wird, mit E0135 — oder E0133, wo das Manifest des Cache-Eintrags nicht das ist, das die Lockfile festlegt. Der Abbruch nennt den Pin, den Cache-Eintrag und den Digest, den er enthält, sowie jede Kopie der Entität in einem Katalogverzeichnis mit ihrem Digest oder dass kein Katalogverzeichnis sie enthält. Abhilfe schafft ein Pull bei erreichbarer Registry, der die festgelegte Version erneut herunterlädt und das Heruntergeladene am Pin prüft; siehe Respektieren vs. Aktualisieren, was der Pull tut, wenn die Registry diese Bytes nicht mehr ausliefert.

Das Rendering, das aggrega pull ausführt, um externe Eingaben zu ermitteln, sowie ein Build oder eine Vorschau über aggrega serve oder aggrega mcp lesen ihre Pins auf dieselbe Weise.

Externe Eingaben zur Build-Zeit

Ein Rendering kann Inhalte von einer entfernten URL anfordern — etwa das Values-Schema eines Charts mit einer entfernten Referenz —, und ein Build lädt nie eine herunter, um sie dem hinzuzufügen, was das Rendering lesen darf. Eine Anforderung für eine URL, die die Lockfile bereits festlegt, wird aus dem Eingabespeicher des Workspace bedient und am erfassten Digest geprüft, bevor ein Byte das Rendering erreicht. Eine Anforderung für eine nicht festgelegte URL hält an und nennt die URL und den Schritt, der sie festlegt; es gibt keine Einstellung, die diesen Abbruch in einen Download verwandelt, denn die Menge der Eingaben, die ein Build liest, stillschweigend zu erweitern, ist das Einzige, was ein reproduzierbarer Build nicht tun darf.

Wo die Kopie einer festgelegten Eingabe im Speicher verloren gegangen ist, wird genau diese eine Eingabe über den Digest, den die Lockfile bereits erfasst, erneut heruntergeladen und daran geprüft, bevor etwas geschrieben oder zurückgegeben wird. Das kann nicht ändern, was das Rendering sieht — der Digest wurde festgeschrieben, als die Eingabe festgelegt wurde —, daher repariert es den Speicher, statt die Hülle zu erweitern, und die Lockfile bleibt Byte für Byte unverändert. Im Offline-Modus gibt es selbst dafür keinen Transport, und die fehlende Kopie führt stattdessen zu einem Abbruch, der den Modus nennt.

Das Festlegen geschieht, wenn die Abhängigkeiten des Release aufgelöst werden, sodass feststeht, was ein Build lesen darf, bevor der Build beginnt. aggrega pull ist dieser Schritt, und es ist der einzige.

Der Plugin-Vertrauensdatensatz

Mehrere Verhaltensweisen eines Builds hängen von plugins-trust.yaml ab, der committeten Datei neben der Lockfile des Release, die festhält, zu welchem Plugin jede urteilsliefernde Anbindung aufgelöst wurde — eine plugins.governance-Anbindung in einer ir-verdict- oder render-verdict-Rolle und jede plugins.linter-Anbindung. aggrega pull schreibt sie, und das Schema des Plugin-Vertrauensdatensatzes beschreibt ihre Felder; im Folgenden geht es nur darum, was ein Build selbst damit tut.

Ein Build wird am Datensatz gemessen, bevor eines dieser Plugins läuft. Ein aus dem Cache bereitgestelltes Plugin, dessen Artefakt-Digest nicht der erfasste ist, wird abgelehnt statt ausgeführt — das ist die Auflösung, die eine solche Anbindung normalerweise nimmt, und aggrega pull legt dar, welche anderen Arten, eine aufzulösen, der erfasste Digest nicht regelt. Und ein erfasster Eintrag, für den keine Anbindung in .aggrega-config.yaml mehr steht, hält den Build an: Das Entfernen einer Prüfinstanz ändert kein gerendertes Byte, sodass eine ohne geprüfte Prüfinstanz erzeugte Ausgabe genauso aussieht wie eine von dieser Prüfinstanz genehmigte. Der Abbruch nennt das Plugin und bietet die beiden Abhilfen an, die sich danach unterscheiden, was Sie gemeint haben — es erneut anbinden, wenn das Entfernen ein Versehen war, oder das Entfernen ausdrücklich anfordern, wenn nicht —, und er gibt den ausführbereiten Befehl aus. Eine Anbindung, die der Datensatz noch nicht enthält, ist eine Erstsichtung, und keiner der beiden Vergleiche hält bei ihr an.

Ein Build misst jedes dieser Plugins an der Signatur, die sein Eintrag erfasst, genau so, wie er einen Lockfile-Eintrag an der misst, die dieser Eintrag erfasst. Wo ein Eintrag eine verifizierte signature erfasst, berechnet der Build vor jedem Rendering den Hash des Signatur-Bundles neu, das diese Angabe im Cache benennt, und stoppt mit E0144, wo das Bundle fehlt oder abweicht. Für ein Plugin, das er aus dem Inhalts-Cache liest, liest er aus diesem Bundle außerdem, für welches Artefakt die Signatur erstellt wurde, und stoppt mit E0332, wo sie für ein anderes Plugin erstellt wurde als das, das der Build gelesen hat — so sieht eine aus einem anderen Eintrag kopierte signature aus —, unabhängig davon, was die Signaturanforderung besagt. Für ein vom Inhalts-Cache bereitgestelltes Plugin nennt jede der beiden Ablehnungen aggrega pull --release <release>: Der nächste Pull verifiziert die Signatur des Plugins erneut, erfasst die des Plugins selbst und legt das Bundle, das sie nennt, im Cache ab, wobei er eine zwischengespeicherte Kopie neu schreibt, die nicht mehr zu ihrem Digest passt. Wo die Vertrauenskonfiguration des Workspace eine Signatur für ein Plugin verlangt, das der Build aus dem Inhalts-Cache liest — unter denselben Einstellungen, unter denen aggrega pull es unsigniert ablehnen würde, sodass skip_signature_verification und eine advisory-Registry den Build so fortfahren lassen, wie sie den Pull fortfahren lassen —, stoppt ein Eintrag ohne Signatur, oder das Fehlen jedes Eintrags für das Plugin, den Build mit E0331 und nennt das Plugin, plugins-trust.yaml und die Einstellungen, die die Signatur verlangen. Abhilfe schafft aggrega pull --release <release>, das die Signatur des Plugins bei jedem Lauf an seiner Registry verifiziert und erfasst. Ein Plugin, das aus einem Ihrer Katalogverzeichnisse oder aus der Kopie im Compiler-Binary bereitgestellt wird, unterliegt dieser Anforderung nie. Wie der Rest des Builds liest dies Dateien, die bereits auf dem Rechner liegen, und fragt keine Registry an.

Ein Build nennt jede Zurückziehung, die der Datensatz enthält, neben jeder, die die Lockfile enthält. Eine Markierung, die aggrega pull für eines dieser Plugins festgehalten hat, wird als deprecation:-Zeile gemeldet, die das Plugin, den festgehaltenen Schweregrad und die Nachricht des Herausgebers nennt, bei jedem Schweregrad, und build.halt_on_deprecated_severity entscheidet, ob sie auch den Build anhält, nach derselben Regel, die es auf eine gepinnte Referenz anwendet. Jede andere Oberfläche, die über ein Release berichtet, nennt dieselbe Menge mit denselben Worten, und keine davon hält deswegen an: aggrega validate --release, aggrega lint --release, aggrega inspect --closure, die Validierung und die Closure-Antwort des Language Servers sowie die Assistentenwerkzeuge describe und validate. Ein vorhandener Datensatz, der sich nicht lesen lässt, hält den Build an, statt als einer durchzugehen, der nichts festhält.

aggrega build --upgrade schreibt diese Datei neu. Es impliziert --auto-pull und führt eine argumentlose vollständige Aktualisierung aus, die jede Abhängigkeit neu auflöst und daher jede erfasste Identität neu auflöst und neu schreibt sowie jeden Eintrag verwirft, für den keine Anbindung steht. Wenn diese Datei also nach einem Upgrade-Build geändert erscheint, ist das der Grund: Die Reichweite des Flags ist jede Abhängigkeit, und die erfassten Identitäten gehören zu dem, was neu aufgelöst wird, auch wenn sie keine Lockfile-Pins sind. Anders als aggrega pull --upgrade nimmt das Build-Flag kein Ziel an und lässt sich daher nicht auf ein einzelnes Plugin eingrenzen: Um eine einzelne Identität zu übernehmen oder zu verwerfen, führen Sie stattdessen aggrega pull --upgrade --release <release> <plugin> aus, das jeden anderen Pin und jede andere erfasste Identität unberührt lässt.

Weil seine Reichweite alles umfasst, fragt es, bevor es beginnt. aggrega build --upgrade bestätigt die Aktualisierung unter denselben Bedingungen wie das argumentlose aggrega pull --upgrade — beide sind derselbe Vorgang, also stellen sie dieselbe Frage. Übergeben Sie --yes, um für die nicht interaktive Verwendung im Voraus zu antworten; ist die Standardeingabe kein Terminal und fehlt --yes, lehnt der Build ab, statt auf eine Antwort zu warten, die niemand geben kann. Ein Build, der nicht aktualisiert, fragt nichts.

Workspace-Auflösung und Determinismus

Die vom Schema verlangte manifest:-Referenz des Release wird relativ zur Release-Datei aufgelöst. Ein relativer catalog_dirs-Eintrag (und ein relativer Plugin-Pfad im Dateisystem) wird gegen das Verzeichnis der .aggrega-config.yaml aufgelöst, die ihn deklariert hat — „relativ“ bedeutet immer relativ zu der Datei, in die Sie es geschrieben haben, sodass ein Pfad dasselbe bedeutet, egal von wo aus Sie aggrega aufrufen. Ein --catalog-Flag, das keine deklarierende Datei hat, wird gegen das aktuelle Arbeitsverzeichnis aufgelöst. Registry-Referenzen (oci://…, eine Hub-Referenz) bleiben unverändert.

Das Workspace-Stammverzeichnis ist das Verzeichnis der nächstgelegenen übergeordneten .aggrega-config.yaml mit einem workspace:-Block oder das Verzeichnis, das --workspace-root nennt. Wenn das Stammverzeichnis auf diese Weise festgelegt ist, ist ein Build unabhängig vom Aufrufort: aggrega build aus dem Projektstamm und aus einem Unterverzeichnis auszuführen erzeugt Byte für Byte identische IR und gerenderte Artefakte, weil sich der durchsuchte Katalog und die in der Ausgabe erfassten Quellpfade nicht mit dem Arbeitsverzeichnis verschieben. (Ohne workspace:-Markierung und ohne --workspace-root ist das Arbeitsverzeichnis das Stammverzeichnis, sodass die Ausgabe stattdessen dort verankert ist — es sei denn, das Arbeitsverzeichnis verankert nichts und --release nennt das Release über einen absoluten Pfad: Das Stammverzeichnis wird dann erneut ausgehend vom eigenen Ordner des Release ermittelt, sodass der durchsuchte Katalog und die in der Ausgabe erfassten Pfade die des Projekts sind, zu dem das Release gehört, egal von wo aus Sie den Befehl ausführen. Siehe configuration.md.) Wo auch so kein Workspace gefunden wird und nichts einen nennt, warnt der Build auf der Standardfehlerausgabe, dass der Ordner, den er als Stammverzeichnis verwendet hat, in keinem Workspace liegt, und nennt den Befehl, der ihn zu einem macht; ein Build, der zuerst seine Abhängigkeiten auflösen soll, wird abgelehnt, bevor etwas heruntergeladen wird, weil der Cache, den diese Auflösung füllt, in diesen Ordner geschrieben würde und ihn zu einem Workspace machen würde. Ein Build, der zuvor nichts auflöst, rendert trotzdem, aber aus demselben Grund wird eine externe Eingabe, die die Lockfile festlegt und der Cache nicht mehr enthält, nicht erneut heruntergeladen: Dem Plugin, das sie anfordert, wird an ihrer Stelle der Satz der Ablehnung mitgeteilt, so wie ihm der des Offline-Modus mitgeteilt wird, und der Build meldet, was dieses Plugin daraus macht. Ein --workspace-root oder AGGREGA_WORKSPACE_ROOT, das einen nicht existierenden Ordner nennt, wird abgelehnt, bevor der Build irgendetwas anderes tut, wobei genannt wird, welches der beiden ihn angegeben hat.

Umgebungsvariablen

Die Workspace-Einstellungen, die der Build liest, lassen sich über die Umgebung überschreiben, oberhalb der committeten Konfiguration und unterhalb jedes Flags: AGGREGA_OFFLINE, AGGREGA_AUTO_PULL, AGGREGA_CATALOG_DIRS (getrennt wie die Pfadliste des Betriebssystems; geben Sie absolute Pfade an), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY und AGGREGA_WORKSPACE_ROOT. Siehe environment-variables.md für die vollständige Liste und das Prioritätsmodell.

Ausgabe

Gerenderte Artefakte landen unter dist/ unterhalb des Workspace-Stammverzeichnisses, egal aus welchem Ordner der Befehl ausgeführt wird — dem Stammverzeichnis selbst, einem Ordner darunter oder einem Ordner anderswo, wobei das Stammverzeichnis über --workspace-root oder AGGREGA_WORKSPACE_ROOT genannt wird —, und die abschließende Zeile nennt dieses Verzeichnis vollständig:

Build completed: 4 files written to <workspace>/dist

<workspace> steht hier für das Workspace-Stammverzeichnis, das die Zeile als vollständigen Pfad ausschreibt. Wo kein Workspace gefunden wird und nichts einen nennt, ist der Ordner, aus dem der Befehl ausgeführt wurde, das Stammverzeichnis, sodass dist/ dort geschrieben wird. Ein dist, das ein Link ist, der aus dem Workspace hinausführt, wird abgelehnt, bevor darin etwas entfernt oder geschrieben wird. Ein Release, das keine Grenzen deklariert, schreibt je Provider: dist/<provider>/<files>. Eine deklarierte Grenze ohne directory: schreibt je Grenze und je Provider: dist/boundaries/<boundary-path>/<provider>/<files>. Vom Betreiber verfasste Überschreibungen mit directory: und subDirectory: an den Grenzen des Release ändern den Zielpfad; das Zusammenführen je (path, provider) vereint Beitragende, die zum selben ausgewerteten Pfad aufgelöst werden.

Dateien, die der Build nicht geschrieben hat

Ein Build schreibt seine eigenen Dateien und entfernt nichts, was er nicht geschrieben hat, mit einer Ausnahme: dist/boundaries/, das ein Build vollständig neu erzeugt, wird vor dem Schreiben geleert, sodass eine Datei, die ein Build einer anderen Variante dort hinterlassen hat, nicht in einem Baum überlebt, der sie nicht mehr erzeugt. Alles andere in dist/ bleibt, wie es ist — eine Datei, die ein früherer Build geschrieben hat und die dieser nicht mehr erzeugt, eine Datei, die das directory: einer Boundary bei einem früheren Lauf dort abgelegt hat, und eine Datei, die Sie selbst dort abgelegt haben, gleichermaßen —, weil der Build einen Überrest nicht von einer Datei unterscheiden kann, die Sie absichtlich dort aufbewahren.

Stattdessen teilt er es Ihnen mit. Sobald seine Dateien geschrieben sind, sieht der Build in dist/ selbst nach und in jedem Verzeichnis darunter, in das er eine Datei geschrieben oder das er durchquert hat, um eine tiefer liegende zu schreiben, und nennt jede Datei dort, die er in diesem Lauf nicht geschrieben hat, in einer einzigen Warnung auf Standard Error. Die Dateien werden mit ihren Pfaden relativ zu dist/ genannt, sortiert, sodass derselbe Baum bei jedem Lauf auf dieselbe Weise gemeldet wird:

warning: the output directory holds 2 file(s) this build did not write, in directories it wrote into; nothing was removed, so they sit beside this build's output: "app/stale-from-earlier-run.yaml", "beside-the-tree.txt"

Die abschließende Zeile zählt sie dann:

Build completed: 1 file written to <workspace>/dist, beside 2 files this build did not write

In ein Verzeichnis, in das der Build nichts geschrieben hat, weder direkt noch darunter, wird nicht hineingesehen, sodass ein eigener Ordner, den Sie unter dist/ aufbewahren, nicht Datei für Datei aufgelistet wird. Ein Build, der keine solche Datei findet, gibt keine Warnung aus, und seine abschließende Zeile ist die unter Ausgabe gezeigte. So oder so sind die Dateien, die der Build schreibt, dieselben Bytes. Um zwei Builds zu vergleichen oder bei null anzufangen, entfernen Sie dist/ vor dem Build.

Die Anfrage aggrega/build von aggrega serve und das Werkzeug build des Assistenten (aggrega mcp) schreiben über denselben Schritt und nennen daher dieselben Dateien im selben Satz: der Daemon als einen der notices seiner Antwort und das Werkzeug als den letzten seiner advisories. Ein Probelauf schreibt nichts und meldet daher nichts davon.

YAML-Einrückung

Jedes gerenderte YAML-Artefakt — docker-compose-Dateien, Helm-Chart-Templates und -Values sowie Kubernetes-Manifeste — wird mit einer einheitlichen Einrückungsbreite ausgegeben. Die Breite wird über build.yaml_indent in .aggrega-config.yaml festgelegt und beträgt standardmäßig 2 (die konventionelle Breite für diese Formate):

build:
yaml_indent: 2 # default; accepts 2 through 9

Die Breite wird an einem einzigen, von allen Renderern gemeinsam genutzten Serialisierungspunkt angewendet, sodass die Ausgabe über Läufe mit derselben Eingabe hinweg Byte für Byte identisch bleibt. Werte außerhalb des Bereichs [2, 9] werden von der Validierung des Konfigurationsschemas abgelehnt.

Den kompilierten Graphen zurückgeben

--ir-graph schreibt den Graphen, den dieser Build aufgelöst hat, als JSON auf die Standardausgabe. Es ist additiv: Die Artefakte werden weiterhin nach dist/ geschrieben, die Zusammenfassung wird weiterhin ausgegeben, und die gerenderten Bytes bleiben unverändert. Der Graph wird vor allem anderen ausgegeben, was der Build dort ausgibt — ein JSON-Dokument und ein abschließender Zeilenumbruch —, sodass ein Konsument, der den Datenstrom dekodiert, ihn liest und aufhört.

Der zurückgegebene Graph ist derjenige, den das Rendering verwendet hat, sodass er genau den Build beschreibt, der die Artefakte daneben erzeugt hat, und keine zweite Auflösung desselben Release. Er lässt sich mit --dry-run kombinieren: Der Graph wird geschrieben und der Artefaktbericht folgt ihm, ohne dass etwas auf die Festplatte geschrieben wird.

Werte, die ein Autor als sensibel deklariert hat, werden darin zurückgehalten — einschließlich der values und infra einer Verbindung, wo der Socket der konsumierenden Komponente ein Blatt als sensibel deklariert —, in der strukturierten Form, die bei aggrega inspect beschrieben ist. --unredacted neben --ir-graph gibt sie stattdessen aus, unter den Bedingungen, die aggrega inspect --unredacted nennt: Es erreicht den Graphen und nichts anderes — die Trace-Dateien haben ihr eigenes --trace-unredacted, und die gerenderten Artefakte werden nie zurückgehalten —, und alles, was die Ausgabe erreicht, enthält diese Werte dann im Klartext. Ohne --ir-graph übergeben, wird es abgelehnt, weil es nichts gäbe, was es offenlegen könnte.

Dasselbe Flag mit derselben Bedeutung gibt es bei aggrega inspect und aggrega validate.

Einen Build in der Vorschau ansehen, ohne ihn zu schreiben

--dry-run führt dieselbe Kompilierung aus wie ein Build — dieselben Abhängigkeitsprüfungen, dasselbe Rendering, dieselben Provider — und gibt aus, was es erzeugen würde, statt es zu schreiben. Jedes Artefakt wird mit dem Pfad, den es belegen würde, und dem Inhalt, den es hätte, gemeldet:

aggrega build --release releases/production.yaml --dry-run
==> <workspace>/dist/main/helm/webapp-configmap-webapp.yaml <==
apiVersion: v1
kind: ConfigMap
...
Total build time: 2.5s
Dry run: 1 file would be written to <workspace>/dist; nothing was written

Die Artefakte werden in der Reihenfolge gemeldet, in der ein Build sie schreibt, sodass dieselbe Eingabe dieselben Bytes in derselben Abfolge meldet, und der gemeldete Pfad ist der Pfad, in den ein Build schreiben würde — unterhalb des Workspace-Stammverzeichnisses, vollständig ausgeschrieben, wo oben <workspace> steht.

Was nicht geschrieben wird. Das Ausgabeverzeichnis bleibt genau so, wie es ist — es wird auch nicht bereinigt, sodass die Ausgabe eines früheren Builds einen Dry Run unversehrt übersteht. Die Lockfile wird nicht geschrieben. Nach .trace/ wird nichts geschrieben.

Externe Eingaben verhalten sich genau wie bei einem gewöhnlichen Build, unter den Bedingungen, die Externe Eingaben zur Build-Zeit darlegt. Ein Dry Run liest daher dieselbe festgelegte Hülle, die der Build lesen würde, für den er steht, und was er zeigt, ist das, was dieser Build schreiben würde.

Wo eine Referenz abgelehnt wurde, nennt der Lauf jede, die er nicht erreichen konnte, und verweist auf den Befehl, der sie festlegt:

note: the lockfile does not pin every external reference this render requested, so the following were declined and the render stopped short of the artifacts it would otherwise emit:
- https://charts.example.com/values-schema.json
Run `aggrega pull --release releases/production.yaml` to pin the inputs the render needs, then run the dry run again

Führen Sie aggrega pull einmal aus, und der Dry Run hat alles, was er braucht; sonst ändert sich nichts an ihm.

Ein Dry Run benötigt eine Lockfile und füllt nie eine. Der Build ist standardmäßig schreibgeschützt, und ein Dry Run hält sich daran, auf welche Weise auch immer ein Füllen angefordert wurde. --auto-pull und --upgrade werden rundweg abgelehnt (siehe unten); die Workspace-Einstellung auto_pull wird für diesen einen Aufruf übergangen, sodass ein Workspace, der standardmäßig füllt, trotzdem in der Vorschau angesehen werden kann. Ohne Lockfile hält ein Dry Run mit derselben Abhilfe an, die ein gewöhnlicher schreibgeschützter Build gibt: Führen Sie zuerst aggrega pull aus.

Die Flags, die er ablehnt. Drei Flags schreiben, daher hat ihre Kombination mit einem Dry Run kein ehrliches Ergebnis — das Schreiben zu ignorieren, würde ein angefordertes Füllen verschwinden lassen, und es auszuführen, würde das einzige Versprechen brechen, das der Dry Run gibt. Jede Kombination hält vor jeder Arbeit an und nennt das übergebene Flag und den Schritt, der stattdessen auszuführen ist:

Kombiniert mitGrund der Ablehnung
--auto-pullfüllt die Lockfile; führen Sie aggrega pull als eigenen Schritt aus
--upgradelöst jede Abhängigkeit neu auf und schreibt die Lockfile neu; führen Sie aggrega pull --upgrade als eigenen Schritt aus
--traceschreibt Dateien je Knoten nach .trace/; führen Sie den Build mit Trace ohne --dry-run aus

Alles andere lässt sich normal kombinieren. --verify-determinism rendert jeden Knoten zweimal und vergleicht die Bytes, ohne eines davon zu schreiben, und --catalog, --quiet, --progress, --debug sowie die Warnungsfilter verhalten sich genau wie bei einem Build, der schreibt.

Wofür er gedacht ist und wofür nicht. Ein Dry Run beantwortet die Frage „was würde dieses Release erzeugen“, die nur ein Rendering beantworten kann — er ist also kein Ersatz für aggrega validate, das die Korrektheit ohne Rendering prüft, oder für aggrega inspect, das den Graphen vor dem Rendering abfragt. Greifen Sie zu einem Dry Run, wenn die gewünschte Antwort die Artefakte selbst sind: um zu prüfen, was eine Release-Änderung an der Ausgabe bewirkt, oder um eine Recipe-Bearbeitung zu prüfen, bevor etwas nach dist/ übernommen wird.

Trace-Ausgabe

Das Flag --trace aktiviert einen Debug-Dump je Knoten, der jeden Zwischenzustand des Compilers festhält. Die Ausgabe liegt in .trace/ unterhalb des Workspace-Stammverzeichnisses, neben dist/ (nie darunter; die nebeneinanderliegende Anordnung folgt der Konvention von .git/, .terraform/, node_modules/ und hält dist/ rein deploybar).

Die Verzeichnisstruktur ist je Grenze und je Instanz gegliedert:

.trace/
└── boundaries/
└── <boundary-path>/
└── <instance-id>/
├── 01-pillars-initial.yaml
├── 02-provides-evaluation.yaml
├── 03-inject-hydration.yaml
├── 04-inject-mapping.yaml
├── 05-source-resolution.yaml
├── 06-source-locals.yaml
├── 07-values-mapping.yaml
├── 08-workload-synthesis.yaml
├── 09-artifact-evaluation/
│ └── <per-artifact-file>.yaml
├── 09b-feature-rendering-boundary.yaml
├── 10-engine-synthesis/
│ └── <per-synthesized-file>.yaml
├── 11-engine-emission.log
└── 12-labels-injected.log

Jeder Slot hält einen bestimmten Zustand des Compilers fest:

  • 01-pillars-initial.yaml — der Snapshot je Knoten des Kontexts, den ein Template liest, aufgenommen nach der Auflösung und vor jeder Mutation je Phase. Enthält .values, .infra, .context, .parameters, .metadata.
  • 02-provides-evaluation.yaml — die aufgelösten provides:-Ausgaben nach der Auswertung der provides.
  • 03-inject-hydration.yaml — die zusammengeführte .context.inject-Pipe nach der Inject-Hydration (verbraucherseitige Sicht auf die vorgelagerten provides).
  • 04-inject-mapping.yaml — die .context.inject-Pipe nach den injectMapping-Umschreibungen des FeatureRecipe.
  • 05-source-resolution.yaml — der geparste source:-Inhalt, den der Provider verwenden wird. Nur vorhanden, wenn das Recipe source: deklariert.
  • 06-source-locals.yaml — der aufgelöste locals:-Block. Die Quellauflösung veröffentlicht .locals, bevor sie das source:-Template auswertet, weshalb dieser Slot geschrieben wird, unabhängig davon, ob das Recipe source: deklariert.
  • 07-values-mapping.yaml — die gerenderte Ausgabe von valuesMapping: (das Dictionary, das der Provider erhält). Nur vorhanden, wenn das Recipe valuesMapping: deklariert.
  • 08-workload-synthesis.yaml — der Kontext, wie er war, als das workload:-Template ausgewertet und seine Ausgabe geparst wurde. Nur vorhanden, wenn das Recipe workload: deklariert (inline oder über $import: geladen). Die geparste Workload selbst ist nicht in diesem Slot: Sie erscheint ab 09-artifact-evaluation/, sobald sie feststeht und nicht mehr in Bearbeitung ist.
  • 09-artifact-evaluation/ — eine Datei je ausgewertetem Artefakt. Nur vorhanden, wenn das Recipe artifacts: deklariert (mit Einträgen inline oder je Eintrag über $import: geladen).
  • 09b-feature-rendering-boundary.yaml — der Kontext, wie er am Ende des Renderns des Knotens vorliegt, nachdem die an ihn angehängten FeatureRecipes ihre Ressourcen erzeugt haben, mit dem geparsten workload daneben. Wird für jeden Knoten geschrieben.
  • 10-engine-synthesis/ — eine Datei je synthetisiertem Manifest, das der Provider aus der Workload erzeugt hat (Workload-Modus von helm/compose). Nur vorhanden, wenn der Provider einen Synthesepfad durchlaufen hat.
  • 11-engine-emission.log — die Zusammenfassung nach der Ausgabe (Anzahl der Dateien, Ausgabepfade) für den Knoten.
  • 12-labels-injected.log — die Herkunfts-Labels und -Annotationen, die für den Knoten in die gerenderte Ausgabe geschrieben wurden.

Ab 03-inject-hydration.yaml enthält ein Slot, der den Kontext des Knotens zeigt, den Block .context.inject, sobald die Pipe, die er erfasst, mindestens einen Schlüssel zustellt, über welchen Mechanismus auch immer: env, file, arg oder einen Mechanismus anderen Namens, in den ein inject-Mapping, das injectMapping eines FeatureRecipe oder der eigene inject:-Block der Komponente schreibt. Ein Knoten, dessen einzige Zustellung ein solcher benutzerdefinierter Mechanismus ist, zeigt den Block ebenfalls, mit diesem Mechanismus unter seinem eigenen Namen und seinen Schlüsseln in all, und ein als sensibel deklarierter Wert erscheint an beiden Stellen als <redacted>. Ein Slot, der erfasst wird, während die Pipe nichts zustellt, hat keinen .context.inject-Block.

Der Trace-Writer ist nicht blockierend: Der Trace wird neben der Kompilierung auf die Festplatte geschrieben statt in ihrem Pfad. Die Kompilierungslatenz wird durch Trace-I/O nicht beeinflusst — dieselbe Kompilierung endet in derselben Echtzeit, ob --trace aktiviert ist oder nicht.

Als sensibel deklarierte Werte im Trace

Ein Datum, das ein Autor als sensibel deklariert hat — ein Schema-Blatt mit sensitive: true oder ein Zustellschlüssel, dessen Material aus einem provides-Schlüssel stammt, der dies trägt —, wird als fester Text <redacted> in den Trace geschrieben. Der Schlüssel bleibt erhalten und nur der Wert wird ersetzt, sodass ein Slot weiterhin zeigt, welche Blätter und welche Zustellschlüssel ein Knoten trägt. Ein nicht deklariertes Geschwisterelement im selben Block gibt seinen Wert wörtlich aus; die Ersetzung folgt der Deklaration und nichts anderem.

Auch ein Wert, den ein FeatureRecipe über sein eigenes injectMapping zustellt, wird zurückgehalten. Das ist der Weg, dem ein Slot mit einer leeren inject-Liste die Zustellung übergibt, und der Weg, den eine reine Inject-Realisierung von Zugangsdaten nimmt. Der Zustellschlüssel, den ein solches Mapping schreibt, ist selbst ein Template, sodass keine Deklaration ihn benennt; gelesen wird stattdessen der eigene Text des Mappings. Wenn dieser Text auf ein values- oder infra-Blatt verweist, das das angebundene Feature mit sensitive: true deklariert, wird jeder vom Mapping erzeugte Zustellschlüssel als <redacted> gelesen — auch ein Schlüssel, der nichts Sensibles enthält, da die Auswertung je Anbindung und nicht je Schlüssel erfolgt. Ein Mapping, das auf nichts Deklariertes verweist, gibt seine Schlüssel wörtlich aus.

Auch ein Wert, den ein Template aus einem als sensibel deklarierten Datum berechnet hat, wird zurückgehalten, obwohl sein eigener Schlüssel keine Deklaration trägt. Was ihn kennzeichnet, ist die Referenz, die der Autor geschrieben hat: Ein locals:-Eintrag, dessen Template ein als sensibel deklariertes Blatt liest, wird zurückgehalten, ebenso ein source:-Feld, das dies tut. Die Auswertung ist konservativ — ein Template, das ein ganzes Objekt erreicht, erreicht jedes darunter deklarierte Blatt, sodass {{ range $k, $v := .values.creds }} seine Ausgabe zurückhält, wenn irgendetwas unter creds deklariert ist —, und ein locals:-Eintrag, der ein bereits zurückgehaltenes Geschwisterelement liest, wird seinerseits zurückgehalten. Ein Geschwistereintrag derselben Form, der nichts Deklariertes liest, wird wörtlich ausgegeben.

Ein Wert, der über eine uses-Kante wandert, wird anhand der Deklarationen des Ziels zurückgehalten, nicht des konsumierenden Knotens, und er wird auf beiden Oberflächen zurückgehalten, zu denen die Kante ihn trägt. .context.uses.<alias>.provides gibt wieder, was die Zielkomponente veröffentlicht hat, daher regelt das Schema des Ziels diese Werte: Ein provides-Schlüssel, den das Ziel als sensibel deklariert hat, wird im Slot des Konsumenten als <redacted> gelesen, selbst wenn der Konsument überhaupt nichts deklariert. Wenn der eigene inject-Block der Kante diesen Schlüssel auf einen Zustellschlüssel der konsumierenden Komponente leitet, hält .context.inject auch diesen Zustellschlüssel zurück — dieselbe Regel, der das inject-Mapping einer Anbindung bereits folgt, mit derselben Deklaration. Das Zurückhalten erfolgt je Kante, sodass zwei Kanten, die denselben provides-Schlüsselnamen veröffentlichen, unabhängig voneinander aufgelöst werden: Die, deren Ziel ihn deklariert hat, wird zurückgehalten, und die andere wird wörtlich ausgegeben. Der Rest der Kante — ihr Ziel, ihr Socket, ihre Labels und die eigenen Schlüsselnamen des inject-Mappings — ist nicht das, was eine provides-Deklaration des Ziels regelt, und wird wörtlich ausgegeben.

Die verbindungsbezogenen values und infra, die auf der Kante selbst verfasst sind, werden stattdessen vom Socket der konsumierenden Komponente geregelt: von dem valueSchema und dem infraSchema, die dieser Socket deklariert und gegen die diese Konfiguration validiert wird. Ein Blatt, das einer der beiden Verträge als sensitive: true deklariert, erscheint unter .context.uses.<alias>.values oder .context.uses.<alias>.infra als <redacted>, wobei der Schlüssel erhalten bleibt, und ebenso ein Blatt, das auf einem vom Vertrag deklarierten Standardwert steht; ein nicht deklariertes Geschwisterelement wird wörtlich ausgegeben. Die Deklarationen des Ziels spielen hier keine Rolle, und das Zurückhalten erfolgt je Verbindung, sodass ein gleichnamiges Blatt auf einer Verbindung, deren Socket es als lesbar deklariert, wörtlich ausgegeben wird.

Die auf einer Verbindung geschriebenen Anbindungen werden unter der Kante dieser Verbindung angezeigt, unter .context.uses.<alias>.features.<slot>, und jede wird anhand der Deklarationen ihres eigenen Feature zurückgehalten — derselben, die dieses Feature regeln, wenn eine Komponente es direkt hält. Ein values- oder infra-Blatt, das das Feature mit sensitive: true deklariert, wird als <redacted> gelesen, ebenso ein Schlüssel der aufgelösten provides der Anbindung, den das Feature als sensibel deklariert; jeder Schlüssel bleibt erhalten. Typ, Version und Labels der Anbindung sowie jedes Blatt und jeder provides-Schlüssel, den ihr Feature nicht deklariert, werden wörtlich ausgegeben, sodass ein veröffentlichter Locator neben dem Material, das er lokalisiert, lesbar bleibt. Das Zurückhalten erfolgt je Verbindung und Slot, sodass dasselbe Feature, auf zwei Verbindungen geschrieben, auf jeder aufgelöst wird. Ein Slot, der sensitive: true deklariert — auf der Komponente oder auf ihrem Socket —, besagt, dass die Anbindung geheimes Material verarbeitet, und hält von sich aus kein Blatt zurück: Welche Blätter zurückgehalten werden, deklariert das Feature. Die eigenen Anbindungen einer Komponente gehören nicht zu den Blöcken, die ein Slot zeigt, da der Trace keinen .features-Block enthält; was ein workload:-Template aus einer davon liest, deckt das unten beschriebene erneute Rendering ab.

Die geparste Workload ist ein erneutes Rendering, keine Erfassung des Dokuments, das der Build ausgegeben hat, und die Slots, die sie enthalten — 09-artifact-evaluation/, 10-engine-synthesis/ und 09b-feature-rendering-boundary.yaml —, sagen dies in einem workload_note-Eintrag daneben. Ein gerendertes Dokument hält nicht fest, aus welcher Deklaration ein bestimmtes Zeichen stammt, daher gibt es darin keinen Schlüssel, an dem ersetzt werden könnte. Stattdessen zeigt der Trace dasselbe workload:-Template, ein zweites Mal ausgewertet, gegen einen Kontext, dessen als sensibel deklarierte Daten bereits als <redacted> gelesen werden. Weil das Template eine Zeichenkette sieht, wo eine Zeichenkette war, behält das Ergebnis die Form des ausgegebenen Dokuments: dieselben Felder an denselben Stellen, wobei <redacted> genau an der Position des zurückgehaltenen Datums steht und der umgebende literale Text unverändert bleibt.

Zwei Arten, in denen sich dieses erneute Rendering vom Ausgegebenen unterscheidet, beide in der Notiz angegeben:

  • Ein Template, das anhand des Inhalts eines Werts verzweigt, rendert anders. Ein eq gegen einen bestimmten Wert, ein Längentest, ein Hash oder eine Kodierung des Werts: Jedes davon sieht <redacted> und liefert ein anderes Ergebnis — einen anderen Zweig, eine andere Länge, einen anderen Digest. Deshalb behauptet der Trace nie, das ausgegebene Dokument zu zeigen.
  • Daten, die keine Deklaration benennt, werden unverändert durchgereicht. Die Ersetzung deckt ab, was die Achse benennt — ein deklariertes values- / infra-Blatt, einen markierten Zustellschlüssel, einen provides-Schlüssel, den die eigene Component der Komponente als sensibel deklariert, die deklarierten provides eines konsumierten Ziels, ein Blatt der eigenen values oder infra einer Verbindung, das ihr Socket als sensibel deklariert, ein deklariertes Blatt oder einen deklarierten provides-Schlüssel einer Anbindung, die die Komponente selbst hält (gelesen unter .features.<name>), oder einer, die auf einer Verbindung geschrieben ist, sowie einen daraus berechneten locals:- oder source:-Wert. Das sind dieselben Daten, anhand derer eine vom Template ausgelöste Ablehnung zurückgehalten wird. Ein Datum, das das Template auf anderem Weg erreicht, etwa ein provides-Schlüssel, den keine Deklaration benennt und dessen Wert ein Recipe aus einem deklarierten Blatt berechnet hat, erscheint im erneuten Rendering genau so wie im ausgegebenen Dokument.

Wenn das erneute Rendering überhaupt nicht erzeugt werden kann, behält der Slot den Schlüssel workload: und ersetzt das Dokument durch eine Zeile, die dies sagt und --trace-unredacted nennt. Die Angabe ist bewusst: Eine Projektion, die einfach verschwunden wäre, ließe sich nicht von einem Recipe unterscheiden, das überhaupt kein workload: deklariert.

Eine Grenze sollte man kennen, bevor man .trace/ als sicher behandelt: dist/ wird nicht geschwärzt. Gerenderte Artefakte werden genau so ausgegeben, wie das Rendering sie erzeugt hat, weil sie das Deploybare sind, und das erneute Rendering des Trace erreicht sie nie — dieselbe Eingabe rendert Byte für Byte identisch, ob --trace aktiviert ist oder nicht.

Behandeln Sie .trace/ als Träger von sensiblem Material und gehen Sie damit so um, wie mit dist/ umgegangen wird.

Die zurückgehaltenen Werte anzeigen

--trace-unredacted schreibt zusammen mit --trace die als sensibel deklarierten Werte in die Trace-Dateien statt des Textes, der sie ersetzt. Es existiert, weil der zurückgehaltene Wert manchmal genau der ist, der gedebuggt wird — eine Anmeldeinformation, die aus dem falschen Attachment ankommt, sieht genauso aus wie die richtige, wenn beide als zurückgehalten erscheinen.

Es ist auch der Weg, das Dokument zu erfassen, das der Build tatsächlich ausgegeben hat: Wenn nichts zurückgehalten wird, gibt es nichts zu ersetzen, sodass die workload:-Slots das ausgegebene Dokument statt eines erneuten Renderings enthalten und der Eintrag workload_note fehlt.

Drei Eigenschaften begrenzen es:

  • Jede Datei, die es schreibt, sagt, was sie ist. Jede Trace-Datei, die der Lauf erzeugt, beginnt mit einem Kommentar, der das Flag nennt und angibt, dass als sensibel deklarierte Werte darunter im Klartext erscheinen, sodass eine Datei, die später an einen Fehlerbericht angehängt oder in einem gemeinsam genutzten Verzeichnis liegen gelassen wird, ihre eigene Warnung mitführt. Der Kommentar ist im Format der Datei selbst gültig, sodass die Datei weiterhin geparst werden kann.
  • Es erreicht .trace/ und nichts anderes. Gerenderte Artefakte sind mit und ohne es bytegleich — es ändert, was eine Debug-Datei zeigt, niemals, was ein Build erzeugt — und die Layouts von aggrega inspect sowie der Diagnosetext, den ein fehlgeschlagener Build ausgibt, sind in beiden Zuständen identisch.
  • Es existiert nur beim Aufruf. Es gibt keine Konfigurationseinstellung dafür, sodass es nicht einmal eingeschaltet und für alle, die den Workspace danach bauen, eingeschaltet gelassen werden kann. Wird es ohne --trace angefordert, hält der Build mit einer Meldung an, die beide Flags nennt, statt eine Anforderung anzunehmen, die er nicht erfüllen kann.

Unabhängig vom Trace gibt ein Build für jeden Zustellungsschlüssel, der als sensibel deklariertes Material als literalen Wert trägt, einen Hinweis aus, der die Komponente, das Ziel, das Attachment und den Zustellungsschlüssel nennt. Er hält den Build nie an, und --no-unsupported-field-warnings unterdrückt ihn nicht — dieses Flag deckt ab, was ein Ziel von dem, was Sie verfasst haben, nicht umsetzen kann, eine andere Klasse.

Das Schlüsselwort, seine beiden Stellen zum Verfassen, der genaue Wortlaut des Hinweises und die vollständige Grenze dessen, was seine Deklaration bewirkt, finden Sie unter vocabulary/compact-form-authoring.md „Ein Blatt als sensibel deklarieren“.

Wann --trace verwendet werden sollte

  • Diagnose, warum ein gerendertes Manifest einen erwarteten Wert nicht enthält: Gehen Sie die Dumps pro Durchlauf durch, um den ersten Slot zu finden, in dem der Wert fehlt.
  • Überprüfung des Determinismus nach einem Compiler-Upgrade: Zwei Kompilierungen derselben Eingabe mit --trace erzeugen bytegleiche Trace-Dumps; jeder Unterschied pro Slot lokalisiert die Regression.
  • Iteration beim Verfassen eines Katalogs: Ein Vergleich der Snapshots 04-inject-mapping.yaml und 06-source-locals.yaml zeigt, was die Templates des Recipe zum Zeitpunkt der Auswertung sehen.

Beispiele

Ein Release gegen den lokalen Katalog kompilieren:

aggrega build --release releases/production.yaml

Mit einem separaten Katalogverzeichnis kompilieren:

aggrega build --release releases/production.yaml --catalog ../platform-catalog/

Ansehen, was ein Release ausgeben würde, ohne etwas davon zu schreiben:

aggrega build --release releases/production.yaml --dry-run

Mit Trace-Dumps zum Debuggen kompilieren:

aggrega build --release releases/production.yaml --trace

Untersuchen Sie nach der Kompilierung .trace/boundaries/<boundary>/<instance>/ auf den Zustand pro Durchlauf. Das Verzeichnis .trace/ wird bei jedem --trace-Lauf überschrieben; der vorherige Trace-Zustand bleibt zwischen Kompilierungen nicht erhalten.

Querverweise

  • aggrega-pull — Katalogentitäten aus einer OCI-Registry in den lokalen Katalog abrufen.
  • aggrega-validate — die Korrektheit des Katalogs, des Release-Abschlusses oder einer einzelnen Entität prüfen, ohne Artefakte auszugeben; die Abhängigkeitsvalidierung, die ein Build ausführt, ohne das Rendering.
  • aggrega-lint — die Konventionen für die Veröffentlichung von Katalogen in denselben drei Geltungsbereichen prüfen.
  • aggrega-inspect — den IR-Graphen nach der Graph-Finalisierung abfragen, ohne mit dem Rendering fortzufahren.
  • Fehler — das kategorisierte Darstellungsformat für Fehler, das in der CLI erscheint.

Übersicht

aggrega build [flags]

Beschreibung

Compile an Aggregate and Release pair into provider-native artifacts under each
boundary's output directory.
The Release is the single entry point: it names the Aggregate and the Manifest,
declares the boundaries, and routes each component to a provider. What a
provider emits is the provider's own shape — Helm manifests, a redistributable
Helm chart, docker-compose YAML — so the output directory holds whatever the
providers this Release routes to produce.
The output directory is dist/ beneath the workspace root, whichever folder the
command is run from, and the closing line names it in full. A run that finds no
workspace uses the folder it was run from as the root, and writes dist/ there.
Build is read-only by default and needs a lockfile. Run "aggrega pull" first to
create one, or pass --auto-pull to fill it in-process for this build.
Given identical input, build writes byte-identical output, which is what makes
the rendered tree reviewable as a diff.

Flags

FlagStandardBeschreibung
--auto-pullfalseFührt vor dem Build den Pull-Schritt aus: löst die Abhängigkeiten des Release prozessintern in die Lockfile und den Cache auf und baut dann gegen sie. Dies ist dieselbe prozessinterne Befüllung, die die Workspace-Einstellung auto_pull durchführt, eingeschaltet für einen einzelnen Build, ohne die Workspace-Konfiguration zu bearbeiten. Allein ist es eine inkrementelle Befüllung — vorhandene Pins werden beachtet, und Referenzen ohne Pin werden aufgelöst und hinzugefügt
--catalog[]Katalogverzeichnis; wiederholbar. Jedes —catalog <dir> wird dem Katalog-Suchstapel vorangestellt (der erste Treffer gewinnt): den catalog_dirs des Workspace oder, für ein Release, dem die Workspace-Konfiguration unter workspace.releases eigene Verzeichnisse gibt, denen dieses Release; der Stapel endet mit dem Verzeichnis namens catalog im Workspace-Stammverzeichnis, sofern es eines gibt. Eine leer geschriebene catalog_dirs-Liste liest überhaupt keinen lokalen Katalog.
--debugfalseGibt menschenlesbare ausführliche Diagnosen auf stderr aus — Echtzeitmessung pro Phase und Anzahl der Entitäten/Abhängigkeiten. Hat Vorrang vor —quiet: ausführliche Ausgabe wird immer ausgegeben. Unterscheidet sich von —trace, das maschinenlesbare Zwischendateien pro Knoten nach .trace/ schreibt
--detailfalseDer Build ist standardmäßig schreibgeschützt und gibt keine Auflösungsdetails aus. Wenn der Pull-Schritt läuft — weil —auto-pull übergeben wurde oder der Workspace auto_pull aktiviert —, befüllt der Build die Lockfile prozessintern, unabhängig davon, ob bereits eine vorhanden ist, und dieses Flag gibt pro aufgelöster Entität aus, was diese Befüllung getan hat: frisch aus einer Registry abgerufen, einen Cache-Slot wiederverwendet, in einem lokalen Katalog gefunden, aus dem Compiler-Binary bereitgestellt oder extern (das eigene Aggregate oder Manifest des Release, gelesen aus der Datei oder dem Eintrag, den das Release nennt). Wenn kein Pull-Schritt läuft, gibt es stattdessen eine Zeile aus, die das sagt, anstelle der Zeilen pro Entität. Nur stdout; nicht persistiert
--disable-plugin-cachefalseÜberspringt für diesen Build den persistenten Plugin-Kompilierungscache auf der Festplatte und kompiliert Plugin-Guests neu in einem In-Memory-Cache, der am Ende des Builds verworfen wird. Standardmäßig aus, wodurch der gemeinsame Cache auf der Festplatte über Builds hinweg wiederverwendet wird. Ändert die gerenderte Ausgabe nicht
--dry-runfalseRendert das Release und gibt aus, was es ausgeben würde, statt es zu schreiben: der voraussichtliche Pfad jedes Artefakts und sein Inhalt gehen nach stdout, und das Ausgabeverzeichnis und die Lockfile bleiben unberührt. Externe Eingaben verhalten sich genau wie in einem gewöhnlichen Build — gepinnte Eingaben werden aus dem inhaltsadressierten Speicher bereitgestellt (und über den Digest neu befüllt, wenn der Blob fehlt), und ein Rendering, das eine nicht gepinnte externe URL anfordert, hält an und nennt sie —, sodass ein Probelauf genau das zeigt, was ein Build schreiben würde. Lässt sich nicht mit —auto-pull, —upgrade oder —trace kombinieren, die jeweils schreiben — führen Sie die Abhängigkeitsbefüllung oder einen Build mit Trace als eigenen Schritt aus. Lässt sich mit —policy-input kombinieren, dessen Dateien dann das Einzige sind, was er schreibt
--ir-graphfalseSchreibt zusätzlich den IR-Graphen, den dieser Lauf berechnet hat, als JSON nach stdout, ergänzend zu allem, was dieser Befehl bereits erzeugt. Werte, die ein Autor als sensibel deklariert hat, werden darin zurückgehalten; übergeben Sie —unredacted, um sie stattdessen auszugeben. Die Artefakte werden trotzdem geschrieben und die Zusammenfassung trotzdem ausgegeben; der Graph wird vor beiden geschrieben
--no-unsupported-field-warningsfalseUnterdrückt die Warnungsklasse für nicht unterstützte Felder: die Hinweise, die ein Ziel für etwas ausgibt, das Sie verfasst haben und das es nicht umsetzen kann — ein Workload-Feld, das es nicht ausdrücken kann (wie bei einem Ziel mit geringerer Wiedergabetreue wie compose), oder eine aggrega.ai/-Annotation, auf die es für die Eingabeart des Knotens nicht reagiert. Andere Rendering-Warnungen erscheinen weiterhin. Nur Anzeige; ändert die gerenderte Ausgabe nicht
--policy-input—Schreibt in dieses Verzeichnis den Payload, den jede Governance-Rolle einem dort angehängten Plugin übergibt, als eine Zeile JSON: genau das, was der Build dem Plugin übergibt, wobei jeder Wert, den der Build ihm vorenthält, auch hier vorenthalten wird. Für annotation-transform, label-transform und ir-verdict ist die Datei das input-Dokument, das eine Richtlinie in dieser Rolle liest. Für render-verdict formt die Richtlinien-Engine den Payload um, bevor eine Richtlinie ihn liest — die documents jedes Artefakts werden daraus geparst —, daher wird eine render-verdict-Richtlinie auf einer eingebauten Engine in einem Build getestet, so angehängt, dass sie mit warn oder info meldet; für ein Plugin, dessen .wasm Sie selbst gebaut haben, führt aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json es auf dieser Datei aus. Auch eine Rolle, an der nichts angehängt ist, wird geschrieben, als der Payload, den ein Anhang ohne Quellen und ohne Einstellungen erhalten würde, sodass eine Richtlinie geschrieben werden kann, bevor sie angehängt wird. Jede Rolle wird in <role>.json geschrieben (annotation-transform, label-transform, ir-verdict, render-verdict); wo die Anhänge einer Rolle unterschiedliche Payloads erhalten — einer trägt eigene Quellen oder Einstellungen, oder eine Transformation ändert, was der nächste liest —, wird jeder stattdessen in <role>.<position>.<plugin>.json geschrieben, wobei position die Anhänge dieser Rolle ab 1 in der Reihenfolge zählt, in der die Workspace-Konfiguration sie auflistet, und plugin das letzte Segment der Plugin-Referenz ohne Version ist, mit maskiertem Zeichen für jedes Zeichen, das ein Dateiname nicht enthalten kann. Bereits im Verzeichnis vorhandene Dateien mit diesen Namen werden ersetzt, und sonst wird dort nichts berührt. Die Dateien werden geschrieben, ob der Build abschließt oder anhält, und ein Build, der anhält, bevor eine Rolle ausgeführt wird, nennt jede Rolle, für die er keine Datei geschrieben hat. Das Anfordern der Dateien ändert kein Artefakt und kein Urteil. Lässt sich mit —dry-run kombinieren, das dann diese Dateien und sonst nichts schreibt: das Ausgabeverzeichnis und die Lockfile bleiben unberührt
--progressfalseErzwingt die Build-Fortschrittsanzeige auch dann, wenn stderr kein Terminal ist, und gibt pro abgeschlossenem Schritt eine einfache Zeile mit seiner Zeit aus. Der Standard ist auto: Die interaktive Phasen-Checkliste wird nur angezeigt, wenn stderr ein Terminal ist, das Escape-Sequenzen interpretiert; ein Terminal, das dies nicht tut, erhält dieselben einfachen Zeilen, und umgeleitete oder per Pipe weitergegebene Ausgabe erhält keine. —quiet und —debug haben beide Vorrang vor —progress
--quietfalseUnterdrückt die Build-Fortschrittsanzeige auf stderr. Wirkt sich nicht auf stdout aus. Hat Vorrang vor —progress
--release—Pfad zur Release-YAML-Datei (erforderlich). Ein relativer Pfad wird gegen das Verzeichnis aufgelöst, in dem Sie den Befehl ausführen, nicht gegen das Workspace-Stammverzeichnis. Wenn dieses Verzeichnis in keinem Workspace liegt und kein Stammverzeichnis angegeben ist, findet ein absoluter Pfad den Workspace vom eigenen Ordner des Release aus
--tracefalseschreibt Zwischendateien pro Knoten nach .trace/ unterhalb des Workspace-Stammverzeichnisses, neben dist/, zur nachträglichen Untersuchung
--trace-unredactedfalseSchreibt die als sensibel deklarierten Werte in die .trace/-Dateien statt des Textes , der sie ersetzt, und versieht jede Datei, die der Trace schreibt, mit einem Header, der dies angibt. Erfordert —trace. Es erreicht .trace/ und nichts anderes: gerenderte Artefakte, die Ausgabe von aggrega inspect und Diagnosetext sind mit und ohne es identisch. Nur beim Aufruf — es gibt keine Einstellung in der Workspace-Konfiguration dafür, sodass es nie für einen späteren Build eingeschaltet bleiben kann
--unredactedfalseGibt die Werte aus, die ein Autor als sensibel deklariert hat, statt sie zurückzuhalten. Alles, was die Ausgabe erreicht — ein Terminal, eine Pipe, eine Datei, eine Bildschirmaufnahme —, enthält diese Werte dann im Klartext. Erreicht den Graphen, den —ir-graph schreibt, und nichts anderes, daher erfordert es —ir-graph; die .trace/-Dateien verwenden stattdessen —trace-unredacted
--upgradefalseMacht den Auto-Pull-Schritt zu einer vollständigen Aktualisierung: verwirft die vorhandene Lockfile und löst jede Abhängigkeit anhand des aktuellen Registry-Zustands neu auf, wobei jede auf die höchste verfügbare Version angehoben wird, statt vorhandene Pins zu beachten. Impliziert —auto-pull — allein führt es vor dem Build einen Pull mit vollständiger Aktualisierung aus. Es nimmt kein Ziel an und kann daher nicht auf eine einzelne Abhängigkeit eingeschränkt werden: Um einen einzelnen Pin zu übernehmen oder zu verwerfen, führen Sie stattdessen aggrega pull —upgrade —release aus, das jeden anderen Pin unverändert lässt. Da es jeden aufgezeichneten Pin verwirft, fragt es zuerst nach einer Bestätigung; —yes antwortet im Voraus, und bei einem nicht interaktiven stdin verweigert es, statt auf eine Antwort zu warten, die niemand geben kann
--verify-determinismfalseRendert jeden Knoten zweimal und vergleicht die ausgegebenen Bytes; der Build hält an, wenn sich die beiden Renderings eines Knotens unterscheiden. Standardmäßig aus. Verwenden Sie es, um zu bestätigen, dass ein Provider deterministisch rendert — identische Eingabe ergibt bytegleiche Ausgabe —, worauf die Garantien für GitOps-Diffs und bytegleiche Ausgabe beruhen
--yesfalseBeantwortet die Bestätigung von —upgrade im Voraus, für die nicht interaktive Verwendung. Es erreicht diese eine Abfrage und nichts anderes: Ein Build, der keine Aktualisierung durchführt, fragt nichts, daher ändert die Übergabe dort kein Verhalten