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

aggrega inspect

aggrega inspect erzeugt eine menschenlesbare Ansicht jeder Aggrega-Entität – einer Katalog-Component, einer verfassten Entitätsdatei, einer in einer Registry veröffentlichten Entität oder eines vollständig aufgelösten Release. Es ist die kanonische Debug-Oberfläche, um zu verstehen, was der Compiler erzeugen wird: welche Components welche Basen erweitern, welche Recipe jedem Typ zugeordnet ist, welche Features an jeden Knoten angebunden sind und woher genau die Beiträge jedes Feature stammen.

Jede Entitätsart hat eine natürliche „Vertrags“-Ansicht. inspect zeigt diesen Vertrag – das Schema, das eine Component veröffentlicht, die Zuordnungen, die ein Manifest deklariert, die Topologie, die ein Aggregate aufbaut, die Feature-Anbindungen pro Knoten, zu denen ein Release aufgelöst wird. Tutorials und konzeptionelles Material finden sich an anderer Stelle; inspect beantwortet die Frage „wozu wird diese Entität tatsächlich aufgelöst?“

Ein einzelnes Positionsargument wird anhand der Form seines Inhalts geleitet; es ist kein Unterbefehl nötig. Der Befehl verzweigt nach folgender Heuristik:

Form des BezeichnersVerzweigungAusgabe
Beginnt mit ./, ../ oder / oder endet mit .yaml / .ymlDatei-ZweigDateibezogene Untersuchung anhand des kind:-Kopfs der Datei.
Beginnt mit oci://Registry-ZweigDie unter dieser Koordinate veröffentlichte Entität, aus ihrer Registry gelesen und mit der Ansicht dargestellt, die eine Datei ihrer Art erhält. Siehe Eine veröffentlichte Entität lesen.
Alles andereKatalog-ZweigDen Bezeichner im Katalog-Suchstapel über alle Entitätsarten hinweg nachschlagen; extends:-Ketten auflösen; die eigene Ansicht der gefundenen Art darstellen.

Drei Detailstufen

--list, die Standardstufe und --detail bilden eine einheitliche dreistufige Ausführlichkeitsdisziplin, die jede Art einhält. --list und --detail schließen sich gegenseitig aus – die Angabe beider wird abgelehnt, statt stillschweigend aufgelöst zu werden.

  • --list – nur Bezeichner. Eine Component listet ihren Namen und die Namen ihrer uses-Sockets auf; eine MappingLibrary listet die Namen ihrer Zuordnungen auf; ein Aggregate listet die Namen seiner Komponenten mit ihren Typen auf.
  • Standard – eine strukturierte Übersicht, abgestimmt auf die interaktive Nutzung. Sie beginnt mit der Identität der Entität und, für jede Art außer einem Manifest und einem Release, mit ihrer Beschreibung, wo die Entität eine verfasst; eine Entität ohne Beschreibung gibt keine aus statt einer Leerzeile. Der Rest der Form ist artspezifisch: Eine Component zeigt ihr Schema und ihre Sockets; ein Aggregate zeigt Komponenten, ihre Werte und Kanten mit den Anbindungen, die jede Verbindung trägt, sowie den Abhängigkeitsgraphen; ein Release zeigt den Knotenbaum pro Boundary mit Feature-Anbindungen, wobei jede auf einer Verbindung geschriebene unter dieser Verbindung aufgeführt ist.
  • --detail – vollständige Feldinhalte. Alles, was die Art enthält: Eine Component ergänzt ihre Self-Inject-Mechanismen, erforderlichen Features und Labels; eine MappingLibrary erweitert den vollständigen Template-Inhalt jeder Zuordnung; eine Recipe ergänzt ihren Workload-Inhalt, provides und Assertions.

Einige Arten nutzen die Stufen, um schrittweise mehr von einem verfassten Inhalt sichtbar zu machen. Eine MappingLibrary zeigt bei --list die Namen der Zuordnungen; auf der Standardstufe ergänzt sie das synthetisierte Anwendungsbeispiel jeder Zuordnung; bei --detail erweitert sie den vollständigen Template-Inhalt.

Auflösung: --raw und --resolved

Jede Art hat eine natürliche Standard-Auflösungstiefe (siehe die Tabelle unten). --raw und --resolved sind stets verfügbare Übersteuerungen, und sie schließen sich gegenseitig aus – die Angabe beider wird abgelehnt, statt stillschweigend aufgelöst zu werden:

  • --raw verzichtet auf jede Auflösung – die Entität wird wie verfasst ausgegeben, direkt aus der Datei.
  • --resolved aktiviert die volle Auflösungstiefe der Art.

Bei Arten, die standardmäßig wie verfasst dargestellt werden, ist --raw wirkungslos, und --resolved löst die Auflösung aus, die die Art unterstützt. Bei Arten, die standardmäßig aufgelöst werden, ist --raw die Umgehung zur verfassten Form.

--raw gibt die Datei wieder, sodass ein Wert, den ein Autor als sensibel deklariert hat, darin genau so erscheint, wie er verfasst wurde. Das ist der Vertrag, keine Lücke – eine Ansicht wie verfasst, die stillschweigend einen Teil von sich zurückhielte, wäre nicht wie verfasst. Behandeln Sie die Ausgabe von --raw so, wie Sie die Entitätsdatei behandeln, aus der sie stammt. --output yaml gibt die Datei auf dieselbe Weise wieder, für jede Art einschließlich eines Release.

Ein Release beantwortet zwei weitere Fragen, und jede ist ein anderes Dokument mit eigenem Flag. Der kompilierte Graph, zu dem ein Release aufgelöst wird, ist --ir-graph; seine Abhängigkeitshülle ist --closure. Siehe Maschinenlesbare Ausgabe und Die Abhängigkeitshülle: --closure weiter unten.

Standardwerte pro Art

inspect kennt die eigenständig untersuchbaren Arten in der folgenden Tabelle. Die Katalogarten werden standardmäßig wie verfasst dargestellt – ihre Dateien sind in sich geschlossene Verträge. Die Instanzarten verwenden standardmäßig eine aufgelöste Ansicht, weil ihr verfasstes YAML nur der Ausgangspunkt für eine Kaskade oder eine Pipeline ist.

ArtStandardWas „aufgelöst“ bedeutet
Componentwie verfasstDie Datei ist ein in sich geschlossener Vertrag; die Auflösung erfolgt gegen eine Manifest-Bindung und wird über --show-implements sichtbar gemacht.
Featurewie verfasstWie bei Component.
Recipewie verfasst--show-implements löst die Component-Referenz in spec.implements auf.
FeatureRecipewie verfasst--show-implements löst die Feature-Referenz in spec.implements auf.
MappingLibrarywie verfasstEinträge sind opake Go-Template-Zeichenketten; das Rendern erfolgt zum Zeitpunkt der Verwendung.
SchemaLibrarywie verfasstEinträge sind wiederverwendbare Schema- und Template-Definitionen, die zum Zeitpunkt der Verwendung aufgelöst werden.
WorkloadLibrarywie verfasstEinträge sind wiederverwendbare Workload-Körper, die ein Recipe importiert, ausgewertet zum Zeitpunkt der Verwendung.
ArtifactLibrarywie verfasstEinträge sind wiederverwendbare Artefakt-Bundles, die ein Recipe importiert, gerendert zum Zeitpunkt der Verwendung.
Pluginwie verfasstDie Datei ist ein in sich geschlossener Plugin-Vertrag: Socket-Typen, Fähigkeiten pro Export, Laufzeitbeschränkungen und Signaturverweis. Adressierbar über den Dateipfad oder über ihre Koordinate <pluginType>/<name> im Katalog.
ManifestaufgelöstDie extends:-Kette wird angewendet; die aufgelösten Komponenten- und Feature-Zuordnungen werden dargestellt.
AggregateaufgelöstDie Topologie wird aufgebaut – der uses-Graph und die Reihenfolge werden berechnet.
ReleaseaufgelöstDie vollständige Pipeline läuft: auflösen, Annotationen erweitern, Guards ausführen, Topologie aufbauen, IR aufbauen.

Eine Datei, deren kind: Workload ist, wird abgelehnt: Eine Workload existiert nur eingebettet in einer Recipe und ist keine eigenständig untersuchbare Entität. Untersuchen Sie eine Recipe, um ihre Workload zu sehen.

Auflösungstiefe pro Art

Die meisten Arten haben keine Pipeline – inspect liest die Datei und stellt sie dar. Drei Instanzarten werden in einem nennenswerten Umfang aufgelöst:

  • Manifest wendet seine extends:-Kette an – dem Dateiimport folgend – und stellt die zusammengeführten Komponenten- und Feature-Zuordnungen dar. --raw zeigt die Datei wie verfasst.
  • Aggregate baut seine Topologie auf: Der uses-Graph wird erstellt und die Abhängigkeitsreihenfolge berechnet. Die Standardansicht zeigt Komponenten mit ihren Werten und Kanten, gefolgt vom Abhängigkeitsgraphen. --raw zeigt den verfassten Subsystembaum.
  • Release führt die gesamte Kompilierungs-Pipeline bis zur IR aus – auflösen, Annotationen erweitern, Guards ausführen, Topologie aufbauen, IR aufbauen – und stellt den Knotenbaum pro Boundary mit den Feature-Anbindungen jedes Knotens und ihrer Herkunft dar. Die Governance-Anbindungen, die den Graphen formen, laufen in dieser Pipeline, statt für eine Ansicht übersprungen zu werden, sodass das, was Sie lesen, ihre Entscheidungen widerspiegelt: Die Labels einer label-transform-Anbindung sind gesetzt, bevor irgendetwas mit ihnen abgeglichen wird, und die injizierten Annotationen einer annotation-transform-Anbindung werden genau so zu Feature-Anbindungen erweitert wie eine von Ihnen verfasste Annotation. Eine Anbindung, deren Plugin dieser Befehl nicht auflösen kann, bricht ihn ab, statt Ihnen einen Graphen zu hinterlassen, der ohne die Entscheidungen dieses Plugin gezeichnet ist. Ein Release, das ein anderes erweitert, wird in dieser Ansicht und in --ir-graph als das Release dargestellt, zu dem seine extends:-Kette zusammengesetzt wird – dasjenige, das ein Build davon liest –, sodass ein Release, das nur sein übergeordnetes Release nennt, das Aggregate, das Manifest und die Boundaries dieses übergeordneten Release unter seinem eigenen Namen zeigt. Auch das Manifest, das ein Release nennt, wird über seine eigene extends:-Kette zusammengesetzt, unabhängig davon, ob das Release etwas erweitert, sodass eine Anbindung, deren Zuordnung dieses Manifest erbt, die Realisierung zeigt, die ein Build verwendet. --raw gibt die Release-Datei wörtlich ohne Pipeline aus. --closure stellt eine andere Frage zum selben Release und führt überhaupt keine Pipeline aus; siehe Die Abhängigkeitshülle: --closure.

Es gibt kein separates Tiefen-Flag; der Schalter --raw / --resolved ist die einzige Steuerung der Auflösung, aufgesetzt auf den natürlichen Standard jeder Art.

Fehlerverhalten

Eine referenzierte benachbarte Datei, die nicht geladen werden kann, bricht den Befehl sofort ab – ein Release, das auf ein fehlendes Aggregate verweist, eine defekte Katalogentität im Suchstapel. Er bricht mit einer klaren Meldung ab, statt eine unvollständige Ausgabe darzustellen, und es gibt keinen Continue-on-Error-Modus für einen Ladefehler: Sobald ein für die Auflösung benötigtes Dokument unlesbar ist, gibt es nichts weiter aufzulösen. Wo die Auflösung eines Namens an einem Katalogdokument abbricht, das der Ladevorgang ablehnt, nennt die Meldung diese Ablehnung einmal: einen Kopf mit der Kategorie und, wo die Ablehnung eine Bedingung nennt, deren Kurzcode, dann das Dokument, dann, was daran falsch ist – bei einem Dokument, das das Schema seiner Art ablehnt, die Zeile und die verletzte Einschränkung. Sie enthält keinen Vorschlag, die Datei zu verschieben – der Katalog hat sie gelesen, und deshalb wurde sie abgelehnt.

Ein Release, dessen Zusammensetzung die Prüfungen des Compilers zurückweisen, wird abgelehnt, statt dargestellt zu werden. Das Auflösen eines Release baut den Graphen auf, und die Prüfungen, die ein Build über den fertigen Graphen durchführt – eine uses:-Kante, deren Ziel den selector: ihres Sockets nicht erfüllt, ein Feature, das an eine Komponente angebunden ist, die sein appliesTo: nicht zulässt, und die übrigen –, werden auch hier durchgeführt, mit der Diagnose, die ein Build derselben Dokumente ausgibt. Die Ablehnung nennt jeden Befund in einem einzigen Lauf, statt beim ersten anzuhalten, sodass ein Durchgang Ihnen die ganze zu korrigierende Liste zeigt statt nur deren ersten Eintrag. Das hält diesen Befehl ehrlich gegenüber einem Deployment: Eine Ansicht, die eine Zusammensetzung darstellte, die der Build ablehnt, würde einen Workspace als in Ordnung melden, obwohl er es nicht ist. Die Auswahlen, die nichts auflösen, sind nicht betroffen – --raw, --output yaml und --closure geben wieder oder lösen auf, was Sie verfasst haben, ohne einen Graphen aufzubauen.

Ein Release, dessen Lockfile nicht mehr dem entspricht, wozu es aufgelöst wird, wird mit dem Abbruch abgelehnt, den aggrega build ausgibt. Wo neben dem Release ein Lockfile liegt, gleicht jede Auswahl, die das Release auflöst — die Standardansicht, --resolved, --ir-graph und --closure — es mit dem ab, wozu das Release aufgelöst wird, mit dem Drift-Vergleich, den ein Build vor dem Rendern durchführt. Ein Lockfile, das nicht mehr übereinstimmt, stoppt den Befehl mit der Ablehnung E0130 des Builds: jeder Eintrag, der abgewichen ist, dann das aggrega pull --release <release>, das sie behebt. Nichts wird auf die Standardausgabe geschrieben, und der Befehl endet mit einem Exit-Code ungleich null, denn ein Bild, das aus dem Katalog in seinem aktuellen Stand gezeichnet wird, würde zeigen, was kein Build dieses Release rendert. --raw und --output yaml allein lesen weder das Lockfile noch den Katalog und sind nicht daran gebunden. Ein Release ohne Lockfile daneben wird über den Katalog in seinem aktuellen Stand aufgelöst.

Eine Datei, deren kind: nicht erkannt wird, meldet die unbekannte Art und die Datei, aus der sie stammt. Eine Workload-Datei meldet, dass die Art nur eingebettet vorkommt, und nennt die Entität, in die sie eingebettet wird. Ein oci://-Bezeichner, der nicht gelesen werden kann, wird mit der Bedingung abgelehnt, die den Grund nennt; Eine veröffentlichte Entität lesen listet sie auf.

Katalogauflösung

Der Katalog-Suchstapel wird mit einer geschichteten Rangfolge zusammengestellt: Zuerst kommen --catalog-Flags (vorangestellt, in Reihenfolge), dann die catalog_dirs des Workspace aus .aggrega-config.yaml – für ein Release, dem die Konfiguration unter workspace.releases eigene Verzeichnisse zuweist, an deren Stelle die dieses Release –, dann das Verzeichnis catalog an der Workspace-Wurzel, das gelesen wird, ob es irgendwo angegeben ist oder nicht. Ein Workspace, dessen catalog_dirs als leere Liste geschrieben ist, liest überhaupt keinen lokalen Katalog. Der Stapel ist First-Win – das früheste Verzeichnis, das eine Entitätsidentität deklariert, besitzt sie; die Kopie eines späteren Verzeichnisses wird verdeckt. Der Katalog-Zweig löst den Bezeichner gegen diesen Stapel über alle Entitätsarten hinweg in einer festen Rangfolge auf und stellt den ersten Treffer über die eigene Ansicht dieser Art dar; der Datei- und der Release-Zweig laden daraus referenzierte Katalogentitäten, wenn eine Manifest-Zuordnung oder ein extends:-Elternteil aufgelöst werden muss. Ein extends:-Elternteil, das der Stapel nicht enthält, wird dort gelesen, wo ein Build es liest: aus dem Artefakt-Cache, unter dem Pin, den die Lockfile eines Release dafür aufzeichnet – die des genannten Release oder, wenn keines genannt ist, die jedes Release, das der Workspace enthält. Eine in einer Registry veröffentlichte Basis wird hier also aufgelöst, sobald aggrega pull sie abgerufen und gepinnt hat, und bis dahin wird der Befehl unter Angabe von aggrega pull --release <release> abgelehnt. Es wird nichts abgerufen.

Einen Namen in den Begriffen eines Release nachschlagen

Ein allein angegebener Name wird im eigenen Stapel des Workspace nachgeschlagen. Geben Sie --release <release-path> daneben an, und der Name wird stattdessen im Stapel dieses Release nachgeschlagen – den Verzeichnissen, die die Workspace-Konfiguration diesem Release zuweist, mit vorangestellten --catalog-Angaben –, also in dem, was ein Build dieses Release liest. Ein Workspace, der eine Katalogvariante pro Release führt, die jeweils dieselbe Entität deklariert, beantwortet einen Namen daher mit der Variante, mit der dieses Release gebaut wird:

aggrega inspect core/datastore/mariadb --release release-helm-synth.yaml

Ein Name, den der Stapel dieses Release nicht auflöst, wird abgelehnt, und die Angabe, woher lokale Entitäten gelesen werden, nennt den Eintrag dieses Release unter workspace.releases, da diesen Eintrag die Suche gelesen hat. --release wählt den Stapel, in dem ein Name nachgeschlagen wird, und gilt daher nur für einen Namen allein: Ein Dateipfad und eine Registry-Referenz werden so gelesen, wie sie sind, und lehnen es ab. Ein --release, das eine nicht existierende Datei oder ein Verzeichnis angibt, wird abgelehnt, bevor irgendetwas nachgeschlagen wird.

Eine veröffentlichte Entität lesen

aggrega inspect oci://<host>/<repository>:<tag> liest die unter dieser Koordinate veröffentlichte Entität; @<digest> anstelle von :<tag> benennt genau ein Manifest. So betrachten Sie eine Entität, die nur in einer Registry existiert – das Repository ist das Art-Segment, gefolgt von der Identität der Entität, wie Katalog und Registry §6 darlegt, und aggrega push gibt die Referenz aus, unter der es veröffentlicht hat, die hier mit vorangestelltem oci:// gelesen wird.

Was Sie sehen, ist die Entität, wie sie veröffentlicht wurde. Eine Entität, die mit den von ihr deklarierten Dateien veröffentlicht wurde – eine Recipe mit ihrem lokalen Chart oder ihrem Lock, eine Component mit einem Schema, das sie importiert –, wird als Archiv ausgeliefert, und die Entität wird daraus entpackt: das Dokument an der Wurzel des Archivs, das eine veröffentlichbare Art deklariert, sodass ein daneben ausgeliefertes Chart-Template oder Compose-Fragment nicht mit ihr verwechselt wird. Eine Entität, die keine Datei deklariert, wird als ihr unverändertes Dokument ausgeliefert, und die Entität eines Plugin wird aus seinem Manifest gelesen statt aus der mit ihm veröffentlichten ausführbaren Datei. Das Dokument wird dann mit derselben Ansicht dargestellt, die eine Datei dieser Art erhält, mit denselben Detailstufen und denselben --raw und --output yaml. Es wird keine Vererbung angewendet: Die Ansicht zeigt, was der Herausgeber unter dieser Koordinate abgelegt hat. Die lesbaren Layouts enden mit dem, was gelesen wurde: der Koordinate, ob sie die Entität als Archiv oder als das Dokument selbst enthielt, dem Medientyp, den ihr Manifest deklariert, und dem Digest dieses Manifests, der dieselben Bytes erneut liest, wenn er als @<digest> anstelle von :<tag> geschrieben wird; --output yaml gibt das Dokument aus und danach nichts.

Was geprüft wird und was nicht. Die abgerufenen Bytes werden gegen den Digest geprüft, den das eigene Manifest des Artefakts für sie erfasst, was feststellt, dass es die Bytes sind, die dieses Manifest benennt. Das ist eine Prüfung gegen das, was die Registry ausgeliefert hat, nicht gegen etwas zuvor Erfasstes: Keine an das Artefakt angehängte Signatur wird verifiziert, und keine dafür erfasste Rücknahme wird gemeldet. Es wird nichts geschrieben – kein Cache-Eintrag und kein Lockfile –, sodass das Lesen einer Koordinate nichts daran ändert, was ein späterer Build auflöst.

Es greift auf das Netzwerk zu. Die Registry wird mit den Anmeldedaten kontaktiert, die dieser Rechner für sie hält, aus demselben Speicher, den aggrega push und aggrega pull lesen, und eine Registry auf diesem Rechner wird über einfaches HTTP kontaktiert. Ein Workspace, der offline ist, lehnt das Lesen ab, bevor eine Verbindung aufgebaut wird.

Ein Lesevorgang, der keine Antwort liefern kann, endet mit einem Exit-Code ungleich null und gibt nichts auf der Standardausgabe aus. Jeder der folgenden Fehler nennt seine Bedingung zusammen mit dem, was zu tun ist; eine Registry, die überhaupt nicht erreicht werden kann, wird mit dem Netzwerkfehler gemeldet, der das Lesen abgebrochen hat:

Was passiert istBedingung
Unter der Referenz ist nichts veröffentlichtE0137
Die Registry hat die Anmeldedaten abgelehnt, oder für sie sind keine gespeichertE0138
Der Workspace ist offlineE0125
Das Artefakt ist ein Archiv, das nicht entpackt werden kannE0300
Das Archiv enthält an seiner Wurzel kein EntitätsdokumentE0298
Das Archiv enthält an seiner Wurzel mehr als ein EntitätsdokumentE0299
Das Dokument ist keine Entität einer Art, die eine Registry veröffentlichtE0301

Jeder Code ist in der Fehlerreferenz aufgeführt. Eine Referenz, die kein Repository oder weder ein Tag noch einen Digest nennt, wird mit der stattdessen zu schreibenden Form abgelehnt. --ir-graph und --closure werden abgelehnt, bevor irgendetwas abgerufen wird, weil keine Art, die eine Registry veröffentlicht, ein Release ist.

Hinweise zu Veraltung und Rücknahme

Ein Herausgeber kann nach der Veröffentlichung einen Marker für ein Artefakt erfassen, der besagt, dass die veröffentlichte Version veraltet oder zurückgenommen ist. Wenn der Katalog-Zweig eine Entität auflöst, meldet inspect jeden solchen Marker unterhalb der eigenen Ansicht der Entität – für jede Art, die er über den Namen auflöst, nicht nur für eine Component.

Der Hinweis nennt den Schweregrad, den der Herausgeber erfasst hat – warning, error oder retracted –, zusammen mit der Version, für die der Marker erfasst wurde, dem Grund, dem Ersatz, sofern einer genannt ist, und dem Ausstellungsdatum. Alle drei Schweregrade werden gemeldet. Das ist mehr als die Menge, die ändert, wozu ein Build aufgelöst wird: Eine als retracted markierte Version wird von der Versionsauswahl ausgeschlossen, während warning und error empfehlend sind und weiterhin ausgewählt werden. inspect zeigt Ihnen, was ein Herausgeber mitgeteilt hat; es entscheidet nicht, was Sie erhalten.

Der Hinweis wird aus dem lokalen Index der Registry gelesen, aus der die Entität aufgelöst wird und den aggrega registry update aufbaut – daher benötigt er kein Netzwerk und funktioniert in einem Offline-Workspace. Da der Index eine Momentaufnahme ist, endet der Hinweis mit der Angabe, wann diese Momentaufnahme erstellt wurde, und nennt den Befehl, der sie aktualisiert. Ein Workspace ohne aufgebauten Index meldet nichts, und ein fehlender Hinweis bedeutet daher „nichts in dieser Momentaufnahme erfasst“ und nicht „nichts erfasst“.

Ein Marker wird nur gemeldet, wenn seine eigene Signatur gegen die Unterzeichner verifiziert wird, die die Vertrauensrichtlinie der Registry anerkennt. Ein unsignierter Marker oder einer, dessen Signatur nicht verifiziert wird, wird nicht gemeldet: Eine Behauptung, die nicht authentifiziert werden kann, wird nicht als Tatsache dargestellt.

Der Hinweis begleitet die menschenlesbaren Ansichten. Weder --output yaml noch --ir-graph hängt einen an, sodass ein Konsument, der eines davon parst, ein Dokument und sonst nichts erhält.

Ausgearbeitete Beispiele

Component-Suche im Katalog

$ aggrega inspect core/server:1.0.0 --catalog ./catalog
Component: core/server:1.0.0
Schema:
|
values: { port?: int | *8080 }
Uses sockets:
db: selector="component.aggrega.ai/type=stateful-server"

Die Standardansicht zeigt die Beschreibung der Component, sofern sie eine verfasst, dann das aufgelöste Schema (nach einem etwaigen extends:-Merge) und die deklarierten uses-Sockets. Die obige Component verfasst keine Beschreibung, weshalb das Protokoll direkt mit dem Schema beginnt. --detail fügt die Self-Inject-Mechanismen, die erforderlichen Features und die Labels hinzu; --list zeigt nur den Bezeichner der Component und die Namen ihrer Sockets.

Feature

$ aggrega inspect ./features/metrics.yaml
Feature: core/metrics:1.0.0
Schema:
|
values: { port?: int | *9090 }
Uses sockets:
backend: selector="component.aggrega.ai/type=stateful-server"
inject: [env]
Secret slots:
token (required)
Targeting:
appliesTo: component.aggrega.ai/type=server
Labels:
feature.aggrega.ai/category: observability

Recipe mit --show-implements

Die Standardansicht eines Recipe zeigt einen Abschnitt pro deklariertem Eingabemodus, seine Fähigkeit und seine Werte-Zuordnung. --show-implements löst die Referenz spec.implements gegen den Katalog auf und rendert die gebundene Component zusammen mit den Anbindungen, die diese Component erfordert:

$ aggrega inspect ./recipes/api-server-recipe.yaml --show-implements --catalog ./catalog
Recipe: core/api-server-recipe:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Synthesized
workload: inline
valuesMapping: (none)
Implements Component: core/api-server:1.0.0
requires attachment (observability): core/metrics

Recipe, das mehrere Eingabemodi deklariert

Die Eingabemodi eines Recipe setzen sich durch Addition zusammen: Ein zu renderndes source:, ein zu synthetisierendes workload: und eine artifacts:-Map tragen jeweils Ausgabe bei, und ein Recipe kann eine beliebige Kombination davon deklarieren. inspect meldet jeden Modus, den das Recipe deklariert, statt einen auszuwählen, sodass Sie genau die Menge sehen, die Sie verfasst haben:

$ aggrega inspect ./recipes/api-server-composed.yaml
Recipe: core/api-server-composed:1.0.0
Implements: core/api-server:1.0.0
Capability: helm
## Sourced
source: oci://charts.example.com/api-server:2.1.0
## Synthesized
workload: inline
valuesMapping: inline template
Artifacts: 2
- servicemonitor.yaml
- networkpolicy.yaml

Die Abschnitte sind in der Reihenfolge source: → workload: → artifacts: angeordnet, derselben Reihenfolge, die ein Build anwendet, wenn er ein Recipe zu einem einzelnen Modusnamen auflöst und wenn er meldet, welchen deklarierten Modus der gebundene Provider nicht erfüllen kann — daher nennen diese Ansicht und die Diagnosen eines Builds die Modi in derselben Reihenfolge. Ein Recipe, das weder ein source: noch ein workload: deklariert, wird als reines Artifacts-Recipe gemeldet; das ist der einzige Fall, in dem die Ansicht einen einzelnen Modus nennt.

Manifest (standardmäßig aufgelöst)

$ aggrega inspect ./prod-manifest.yaml
Manifest: prod-manifest:1.0.0
Component Mappings:
Type → Recipe
core/compute/api-server helm-api-server-synthesized-with-artifacts:1.0.0
core/compute/web-ui helm-web-ui-synthesized-with-artifacts:1.0.0
core/datastore/postgres helm-postgres-synthesized-with-artifacts:1.0.0
Feature Mappings:
Type → FeatureRecipe
core/k8s-dns-resolver k8s-dns-patcher:1.0.0
Annotation Bindings:
(none)

Die Standardansicht wendet die extends:-Kette des Manifest an und stellt die aufgelösten Komponenten- und Feature-Zuordnungen sowie die Annotations-Bindungen dar. --raw zeigt die Datei so, wie sie verfasst wurde, vor der Auflösung von extends.

Aggregate (standardmäßig aufgelöst)

$ aggrega inspect ./fullstack-app.yaml
Aggregate: fullstack-app:1.0.0
Components:
backend (type: core/compute/api-server)
Values: (none)
Uses:
databases:
- data.main-db
frontend (type: core/compute/web-ui)
Values: (none)
Uses:
apis:
- my-api → backend
main-db (type: core/datastore/postgres)
Values:
database_name: app_production
Uses: (none)
Dependency Graph:
data.main-db
↑ backend
backend
↑ frontend

Die Standardansicht baut die Topologie auf und zeigt jede Komponente mit ihren Werten und uses-Kanten, gefolgt vom berechneten Abhängigkeitsgraphen. Der Subsystembaum wird verschachtelt dargestellt; --flat rendert einen Abschnitt pro Knoten, jeweils mit seinem vollständigen gepunkteten Pfad als Schlüssel.

Auf eine in der Langform geschriebene Verbindung folgen die Anbindungen, die sie trägt, jede unter dem Namen, den sie auf der konsumierenden Komponente annimmt — Alias der Verbindung und Slot, durch einen Punkt verbunden —, mit dem Feature-Typ, den sie nennt, und einer Klausel, die den Slot angibt, den sie füllt, und ob sie als sensibel deklariertes Material verarbeitet:

gateway (type: conn/gateway)
Values:
region: eu
Uses:
models:
- gpt → model
- gpt.credential (feature.conn/token) [slot: credential, sensitive]

Der Slot und die Markierung sind die Fakten, die ein Build eines Release, das dieses Aggregate bereitstellt, für die Anbindung festhält, und werden genauso gelesen wie in der Release-Ansicht (siehe Verbindung, Slot und Sensibilitätsklausel einer Anbindung); sie stammen aus der Slot-Deklaration des Sockets und aus der des Feature selbst und hängen daher nicht davon ab, welches Release das Aggregate bereitstellt. Ein Aggregate nennt kein Manifest, daher wird die Realisierung, die das Manifest eines Release für die Anbindung wählt, hier nicht angezeigt. Diese Ansicht listet die Verbindungen einer Komponente und das, was sie tragen; die Anbindungen des eigenen Blocks einer Komponente erscheinen in der Release-Ansicht.

Release (standardmäßig aufgelöst)

Die Release-Ansicht ist die Inspektion, bei der am meisten auf dem Spiel steht. Sie führt die vollständige Pipeline aus und rendert pro Grenze jeden Component-Knoten, seine uses-Kanten und jedes an diesen Knoten angebundene Feature — eines, das auf einer Verbindung geschrieben ist, unter der Kante dieser Verbindung —, jeweils mit dem Anbindungs-Slot, den es füllt, ob es als sensibel deklariertes Material verarbeitet und dem FeatureRecipe, das es realisiert, sowie einer Herkunftsklammer, die zeigt, woher die Anbindung stammt:

$ aggrega inspect ./prod-release.yaml --catalog ./catalog
Release: prod-release:1.0.0
Boundary: backend-ns
Directory: ./dist/backend
Annotations (provider-consumed):
aggrega.ai/namespace: backend-zone
Component: backend (type: core/compute/api-server:1.0.0)
Uses:
data.main-db → data.main-db [cross-boundary]
Features: (none)
Boundary: frontend-ns
Directory: ./dist/frontend
Annotations (provider-consumed):
aggrega.ai/namespace: frontend-zone
Component: frontend (type: core/compute/web-ui:1.0.0)
Uses:
my-api → backend [cross-boundary]
Features:
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]
Boundary: data-ns
Directory: ./dist/data
Annotations (provider-consumed):
aggrega.ai/namespace: database-zone
Component: data.main-db (type: core/datastore/postgres:1.0.0)
Features: (none)

Jede Grenze trägt ihr Ausgabeverzeichnis und ihre vom Provider konsumierten Annotationen; jede Komponente unter einer Grenze trägt ihren Komponententyp aus dem Aggregate, ihre uses-Kanten (grenzüberschreitende Kanten markiert), auf die jeweils die Anbindungen folgen, die diese Verbindung trägt, und ihre eigenen Feature-Anbindungen, jede Anbindung mit ihrer Faktenklausel und Herkunftsklammer. --flat reduziert den Grenzbaum auf einen Abschnitt pro Grenze mit ihrem vollständigen Pfad als Schlüssel. --raw gibt die Release-Datei wörtlich und ohne Pipeline aus.

YAML-Ausgabe

$ aggrega inspect core/server:1.0.0 --output yaml --catalog ./catalog
apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/server
version: 1.0.0
labels:
component.aggrega.ai/type: server
spec:
usesSchema:
db:
selector: component.aggrega.ai/type=stateful-server
schema:
values:
port: {type: integer, default: 8080}

Eine aus dem Katalog benannte Component wird als die Entität ausgegeben, die der Katalog aufgelöst hat, sodass Sie nach einem extends:-Merge die zusammengeführte Entität sehen statt der verfassten Datei; eine Component-Datei wird so ausgegeben, wie sie verfasst wurde.

Maschinenlesbare Ausgabe

Zwei Flags erzeugen maschinenlesbare Ausgabe, und sie beantworten unterschiedliche Fragen. --output wählt ein Format für das Dokument, das dieser Befehl ohnehin rendert; --ir-graph fordert zusätzlich ein anderes Dokument an — den kompilierten Graphen, zu dem ein Release aufgelöst wird. Sie sind unabhängig voneinander: Wenn Sie beide übergeben, erhalten Sie den Graphen und das YAML in verfasster Form, jeweils einmal.

--output yaml gibt die Entität so aus, wie sie verfasst wurde, geeignet für Pipes und Diffs. Diese Ausgabe ist wörtlich, und das schließt Werte ein, die ein Autor als sensibel deklariert hat — eine Ausgabe, die vorgibt, die Eingabe wiederzugeben, kann keinen Teil davon zurückhalten und sie dennoch wiedergeben. Leiten Sie sie weiter, speichern und teilen Sie sie so, wie Sie es mit der Entitätsdatei tun würden, aus der sie stammt.

Der kompilierte Graph: --ir-graph

aggrega inspect <release> --ir-graph schreibt den Graphen, zu dem der Lauf aufgelöst wurde, als JSON auf die Standardausgabe, vor der Ansicht, die der Befehl ohnehin rendert. Ein JSON-Dokument, ein abschließender Zeilenumbruch, sodass ein Konsument, der den Stream dekodiert, den Graphen liest und aufhört.

Es gilt für ein Release, die einzige Art, die zu einem Graphen aufgelöst wird. Wird es für eine andere Art oder für eine Katalogentität per Name angefordert, verweigert der Befehl dies und sagt es, statt die eigene Ansicht dieser Entität zu rendern und die Anforderung stillschweigend fallen zu lassen.

Eine Komposition, die die Prüfungen des Compilers ablehnen, erzeugt keinen Graphen. Die unter Fehlerverhalten beschriebene Ablehnung erfolgt, bevor irgendetwas in diesen Stream geschrieben wird, sodass eine Pipeline, die ihn liest, nie einen Graphen erhält, den ein Build derselben Dokumente ablehnen würde — sie erhält dieselben Befunde, die ein Build melden würde, und einen Exit-Code ungleich null.

Dasselbe Flag mit derselben Bedeutung gibt es bei aggrega build und aggrega validate: Jeder gibt den Graphen zurück, den dieser Lauf berechnet hat, zusätzlich zu allem anderen, was dieser Befehl erzeugt. Eine Editor-Integration liest denselben Graphen über das Protokoll des Daemons.

--output yaml gibt den Graphen nicht aus. Es gibt das verfasste Release wieder, genau wie bei jeder anderen Art. Eine Pipeline, die den Graphen benötigt, liest ihn stattdessen aus --ir-graph und erhält JSON statt YAML.

Der Graph hält zurück. Er ist keine Datei, die jemand geschrieben hat — er ist das, was die Kompilierung aus dem Aggregate, dem Release und dem Katalog berechnet hat —, daher gibt es keine Zusage zur verfassten Form einzuhalten, und dieselben Deklarationen, die die lesbaren Layouts steuern, steuern auch ihn. Wo immer der Graph ein Blatt trägt, das ein Autor als sensibel deklariert hat, wird der Wert durch ein Objekt mit einem einzigen Schlüssel ersetzt, das ihn als zurückgehalten kennzeichnet:

"values": {
"secretName": "db-creds",
"vault": {
"token": { "aggrega_withheld": "declared" }
}
}

Der Schlüssel bleibt erhalten, sodass der Graph weiterhin beantwortet, welche Blätter ein Knoten und seine Anbindungen tragen; nur der Wert fehlt. Ein nicht deklariertes Geschwisterelement in derselben Nutzlast wird in verfasster Form ausgegeben — secretName oben ist ein öffentlicher Locator, den sein Autor nicht deklariert hat, und er wird ausgegeben. Der Grund, der die Markierung begleitet, sagt, warum der Wert fehlt: declared für ein Blatt, das eine Deklaration abdeckt, und unreadable, wenn die Nutzlast in einer Form ankam, die dieser Befehl nicht lesen konnte; in diesem Fall wird die gesamte Nutzlast zurückgehalten, statt einen Teil davon zu erraten.

Die eigene Konfiguration einer Verbindung wird auf dieselbe Weise zurückgehalten. Die verbindungsbezogenen values, die ein Aggregate in einen uses-Eintrag schreibt, und die verbindungsbezogene infra, die ein Release in einen solchen schreibt, werden vom Socket der konsumierenden Komponente bestimmt – dem valueSchema und dem infraSchema, die er deklariert, den Verträgen, gegen die diese Konfiguration validiert wird –, nie von den Deklarationen des Ziels. Ein Blatt, das einer der beiden Verträge mit sensitive: true deklariert, wird in den values und der infra der Kante durch die Markierung ersetzt, ebenso im uses-Eintrag des konsumierenden Knotens, der die Werte so trägt, wie der Autor sie geschrieben hat; jede Kante listet die Blätter, die sie zurückhält, unter sensitive_payload_leaves auf, dem Feld, das ein Knoten für seine eigenen verwendet. Ein gleichnamiges Blatt auf einer Verbindung, deren Socket es als lesbar deklariert, wird so ausgegeben, wie es geschrieben ist.

Übergeben Sie --unredacted, wenn eine Pipeline die Werte tatsächlich benötigt, und behandeln Sie das Ergebnis so, wie Sie die Entitätsdateien selbst behandeln. aggrega build und aggrega validate akzeptieren dasselbe Flag neben --ir-graph unter denselben Bedingungen: Der Graph, den sie zurückgeben, hält Werte zurück, sofern es nicht übergeben wird.

Das Protokoll des Daemons liefert denselben Graphen nach derselben Regel. aggrega/irGraph antwortet mit zurückgehaltenen Werten und gibt sie nur dann im Klartext zurück, wenn eine Anfrage ihr Feld unredacted setzt — die Schreibweise dieses Flags im Protokoll. So folgt das, was ein Editor-Panel darstellt, denselben Deklarationen, und ein Client, der die Werte anzeigt, tut dies, weil er sie angefordert hat.

Der Abhängigkeitsabschluss: --closure

aggrega inspect <release> --closure meldet den Abhängigkeitsabschluss des Release: jede Katalogentität, die es erreicht, in der Version, zu der sie jeweils aufgelöst wurde, zusammen mit den Identitäten von Aggregate und Manifest, zu denen seine beiden Zeiger aufgelöst wurden, und den gemeinsam genutzten Dokumenten, auf die diese Entitäten zurückgreifen. Es wird nichts gerendert und kein Artefakt erzeugt — der Abschluss wird aufgelöst, nicht gebaut, daher wird kein Provider geladen, um ihn zu beantworten.

Der Abschluss und die aufgelöste Ansicht sind verschiedene Dokumente, und keines lässt sich aus dem anderen gewinnen. Die aufgelöste Ansicht — das, was dieser Befehl standardmäßig für ein Release rendert — sagt, wie das Deployment aussieht: seine Grenzen, seine Komponentenknoten, was mit was verbunden ist und was an jeden Knoten angebunden ist. Der Abschluss sagt, was hinzugezogen wurde, um es zu bauen, und in welchen Versionen. Eine Entität kann erreicht werden, ohne je als Knoten zu erscheinen — das Recipe, dem ein Manifest einen Komponententyp zuordnet, wird von jedem Build erreicht und ist in keinem davon ein Knoten —, und ein Knoten hält den Komponententyp fest, als der er deklariert wurde, nicht die Version, zu der dieser Typ aufgelöst wurde. Wer also fragt „Warum hat sich diese Version geändert?“, „Was würde eine Änderung dieses gemeinsam genutzten Dokuments betreffen?“ oder „Wovon hängt dieses Deployment tatsächlich ab?“, fragt nach dem Abschluss, und wer die aufgelöste Ansicht vor sich hat, erhält ihn nicht durch genaueres Lesen.

Dasselbe Wort fordert auf jeder Oberfläche dasselbe Dokument an. --closure hier, aggrega/releaseClosure über das Protokoll des Daemons (siehe aggrega serve, „Eine Hülle ist nicht der Graph“) und der Release-Modus des Tools describe über das Assistenten-Tool-Protokoll beantworten alle diese Frage zu einem Release; ein Release-Name erreicht über jede von ihnen dieselbe Auflösung, sodass die drei nicht zu unterschiedlichen Aussagen darüber kommen können, wovon ein Release abhängt. Bei einem Lockfile, das nicht mehr zu dem passt, wozu das Release aufgelöst wird, lehnen dieser Befehl und das Tool describe mit dem Drift-Abbruch des Builds ab; der Daemon, der einen Editor während der Bearbeitung bedient, antwortet.

Es ist ein einzelnes Dokument und wird daher für sich allein angefordert. --closure wählt den Abschluss anstelle der aufgelösten Ansicht und kann nicht mit --raw, --resolved, --output oder --ir-graph kombiniert werden — jedes davon fordert ein anderes Dokument zum selben Release an, und ein Befehl, der zwei Anforderungen akzeptierte, müsste stillschweigend nur eine davon beantworten. Eine Kombination wird unter Nennung des Paares abgelehnt.

Es gilt für ein Release und für nichts anderes. Eine Katalogentität, eine Aggregate-Datei, ein Manifest — keines davon löst einen Abschluss auf, daher wird die Anforderung abgelehnt, statt sie zu beantworten, indem die eigene Ansicht dieses Gegenstands gerendert und die Anforderung fallen gelassen wird. Eine fallen gelassene Anforderung sieht für den Aufrufer genauso aus wie ein Gegenstand, dessen Abschluss leer ist.

Jedes Ergebnis ist von den anderen unterscheidbar. Ein Release, das sich auflösen lässt, wird mit der Auflistung beantwortet. Ein Release-Pfad, der keine Datei bezeichnet, wird mit dem Hinweis abgelehnt, dass die Datei nicht vorhanden ist. Ein vorhandenes Release, dessen Abschluss nicht aufgelöst werden kann, wird abgelehnt, mit Angabe dessen, was nicht aufgelöst werden konnte und woher die Referenz stammte, gefolgt von allen Dateien, die das Laden des Katalogs abgelehnt hat — denn eine abgelehnte Datei ist der übliche Grund, warum eine Entität, die das Release erreicht, fehlt. Ein Plug-in-Vertrauenseintrag neben dem Release, der vorhanden ist und nicht gelesen werden kann, wird abgelehnt, mit Angabe dessen, was nicht gelesen werden konnte, denn eine Auflistung, die ihn übergangen hätte, würde kein zurückgezogenes Plug-in melden, wo keines geprüft werden konnte. Ein Release, dessen Lockfile nicht mehr zu dem passt, wozu es aufgelöst wird, wird mit dem Drift-Abbruch abgelehnt, den ein Build ausgibt, wie Fehlerverhalten beschreibt, denn die aufgelisteten Versionen wären solche, die kein Build dieses Release verwendet. Eine leere Auflistung ist nie die Antwort auf einen dieser Fälle: Sie würde einen vertippten Pfad oder einen defekten Workspace als Release melden, das von nichts abhängt.

Die drei Detailstufen gelten wie für jede Art. --list gibt nur die Referenzen aus, eine pro Zeile, zum Weiterleiten per Pipe. Die Standardstufe fügt die aufgelösten Identitäten hinzu, die Version, zu der jede Referenz aufgelöst wurde, die herangezogenen gemeinsam genutzten Dokumente, jede Manifest-Zuordnung, deren Ziel den Typ, dem es zugeordnet ist, nicht implementiert, und jeden Hinweis auf Veraltung oder Rückzug, der für das festgehalten wurde, wovon das Release abhängt — in seiner Lockfile gegen eine gepinnte Referenz und im Plug-in-Vertrauenseintrag daneben gegen ein Plug-in, das in einer Rolle angebunden ist, die ein Urteil aus Annahme oder Ablehnung zurückgibt —, in den Worten, die aggrega build für dieselbe Markierung ausgibt. --detail fügt die Art jeder Referenz hinzu, sofern die Referenzstelle eine festgehalten hat — manche Positionen in einem Dokument sagen, auf welche Art sie verweisen, andere nicht, daher wird sie gemeldet, wo sie bekannt ist, statt aus der Form des Namens erraten zu werden.

$ aggrega inspect ./release.yaml --catalog ./catalog --closure
Release: prod-release:1.0.0
Aggregate: fullstack-app
Manifest: prod-manifest
Environment: production
Entities (11):
./aggregate.yaml
./manifest.yaml
core/compute/api-server (1.0.0)
core/compute/web-ui (1.0.0)
core/datastore/postgres (1.0.0)
core/k8s-dns-resolver (1.0.0)
db-module (1.0.0)
helm-api-server-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-postgres-synthesized-with-artifacts:1.0.0 (1.0.0)
helm-web-ui-synthesized-with-artifacts:1.0.0 (1.0.0)
k8s-dns-patcher:1.0.0 (1.0.0)

Wo ein Workspace festgehalten hat, zu welchen Versionen ein Release aufgelöst wird, dient dieser Eintrag als Ausgangspunkt der Auflösung, sodass die gemeldeten Versionen diejenigen sind, aus denen dieses Deployment gebaut wird, und nicht das, was der Katalog heute zufällig enthält. Ein Workspace ohne einen solchen Eintrag löst gegen den Katalog in seinem aktuellen Zustand auf.

Verbindung, Slot und Sensibilitätsklausel einer Anbindung

Jede Feature-Anbindung in der Release-Ansicht trägt eine Klausel, die die Fakten nennt, die der Compiler über die Anbindung selbst festhält: welchen Anbindungs-Slot sie füllt, ob sie als sensibel deklariertes Material verarbeitet, und das FeatureRecipe, das sie realisiert — sowie, bei einer Anbindung, die auf einer der Verbindungen der Komponente geschrieben ist, die Verbindung, auf der sie geschrieben wurde. Die Klausel steht zwischen dem Namen der Anbindung und ihrer Herkunftsklammer und liest sich in beiden unten beschriebenen Herkunftsformen identisch.

Eine auf einer Verbindung geschriebene Anbindung wird unter der Zeile dieser Verbindung in Uses: aufgeführt, nicht unter Features:, sodass Features: nur die eigenen Anbindungen der Komponente enthält. Die Zeile darüber nennt die Verbindung über ihren Alias und die Komponente, die sie erreicht, und ihre eigene Klausel sagt den Rest:

  • [socket: <socket>] — der Socket, über den die Verbindung geführt wird und den die Zeile der Verbindung nicht nennt. Er steht am Anfang der Klausel, weil er ändert, wie der Rest gelesen wird: Die folgende Slot-Hälfte nennt einen Slot, den der Socket der Verbindung deklariert, nicht einen, den die Komponente für ihre eigenen Anbindungen deklariert.
  • [connection: <alias> through socket <socket>] — derselbe Fakt für eine Anbindung, für deren Verbindung der Uses:-Block keine Zeile zeigt; sie wird dann unter Features: aufgeführt und nennt ihre Verbindung stattdessen hier. In beiden Fällen wird eine Verbindung einmal pro Anbindung genannt, nie zweimal.
  • [slot: <name>] — die Anbindung füllt den Slot namens <name>. Ein Slot wird gefüllt, indem ein Feature unter dem eigenen Namen des Slots angebunden wird, daher ist <name> der Name, unter dem die Anbindung geschrieben wurde, abgeglichen mit den deklarierten Slots: dem featuresSchema der Host-Component für eine ihrer eigenen Anbindungen und dem featuresSchema, das der Socket der Verbindung für eine auf einer Verbindung geschriebene Anbindung deklariert.
  • [free] — die Anbindung füllt keinen deklarierten Slot: Die aufgelöste Component deklariert keinen featuresSchema-Slot dieses Namens. Dies ist ein Befund, keine Diagnose. Eine Anbindung in freier Form wird akzeptiert, und ein Operator, der sie verbieten möchte, drückt das als Governance-Richtlinie aus, statt sich darauf zu verlassen, dass das Tool sie ablehnt.
  • [sensitive] — die Anbindung verarbeitet Material, das ein Autor als sensibel deklariert hat, weil das angebundene Feature ein sensibles Blatt deklariert, weil der Slot, den sie füllt, sensitive: true deklariert, oder beides.
  • [realization: <name>:<version>] — das FeatureRecipe, das das Manifest des Release für die Anbindung bindet: über den eigenen Namen der Anbindung, wenn das Manifest diesen Namen zuordnet — bei einer auf einer Verbindung geschriebenen Anbindung Alias und Slot, durch einen Punkt verbunden —, andernfalls über ihren Feature-Typ. Es ist die Realisierung, mit der ein Build derselben Dokumente die Anbindung rendert, und derselbe Wert, den der kompilierte Graph auf der Anbindung als realization trägt (siehe --ir-graph), sodass diese Ansicht und der Graph keine unterschiedlichen nennen können. Sie steht zuletzt in der Klausel.

Wenn mehrere Fakten zutreffen, teilen sie sich eine Klausel. core/storage/s3-object-store deklariert einen Slot secret_access_key, der mit sensitive: true markiert ist, sodass ein unter diesem Namen angebundener Berechtigungsnachweis beide Fakten meldet, während ein Feature, das unter einem Namen angebunden ist, für den die Component keinen Slot deklariert, weder Slot noch Sensibilität meldet. Mit einem Manifest, das jeden Feature-Typ einem FeatureRecipe zuordnet, nennt jede Zeile auch ihre Realisierung:

Features:
- secret_access_key (core/generated-secret:1.0.0) [slot: secret_access_key, sensitive, realization: generated-secret:1.0.0] [explicit]
- cross-namespace-routing (core/k8s-dns-resolver:1.0.0) [free, realization: k8s-dns-patcher:1.0.0] [explicit]

Eine Komponente, deren Socket models einen mit sensitive: true markierten Slot credential deklariert und die unter dem Alias gpt eine Verbindung herstellt, die ihn füllt, listet diese Anbindung unter der Verbindung auf — neben einem eigenen Berechtigungsnachweis, der unter Features: bleibt:

Uses:
gpt → model
- gpt.credential (feature.conn/token:1.0.0) [socket: models, slot: credential, sensitive, realization: conn-token-compose:1.0.0] [explicit]
Features:
- db_password (feature.conn/token:1.0.0) [slot: db_password, sensitive, realization: conn-token-compose:1.0.0] [explicit]

Eine auf einer Verbindung geschriebene Anbindung meldet nie [free]: Ein Socket lässt nur die Slots zu, die er deklariert, und eine Verbindung, die einen anderen Namen trägt, wird beim Laden des Builds abgelehnt.

Die Klausel entfällt vollständig, wenn keiner der Fakten zutrifft, und jede Hälfte entfällt unabhängig:

  • Keine Socket- oder Verbindungshälfte bedeutet, dass die Anbindung auf dem eigenen Block der Komponente geschrieben wurde oder sie aus einem weiteren Geltungsbereich oder durch annotationsgesteuerte Erweiterung erreicht hat.
  • Keine Slot-Hälfte bedeutet, dass die deklarierte Slot-Menge der Host-Component nicht aufgelöst werden konnte — zum Beispiel, weil ihr Typ keiner Katalogentität entspricht. Dies unterscheidet sich bewusst von [free]: [free] beantwortet „Es ist kein Slot dieses Namens deklariert“, während eine fehlende Hälfte bedeutet, dass die Frage überhaupt nicht beantwortet werden konnte.
  • Kein sensitive hält fest, dass keine Deklaration die Anbindung markiert hat. Das ist enger als ein Urteil, dass die Anbindung nichts Geheimes trägt; die Achse meldet Deklarationen, und aus dem Namen oder Wert eines Feldes wird nichts abgeleitet.
  • Keine Realisierungshälfte bedeutet, dass das Manifest die Anbindung an kein FeatureRecipe bindet, das der Katalog enthält.

Ein Slot, dessen deklarierter Name wörtlich free lautet, wird ebenfalls als [free] dargestellt und ist von einer Anbindung in freier Form nicht zu unterscheiden — nichts reserviert dieses Wort im Slot-Namensraum.

Grammatik der IR-Herkunftsklammer

Jede Feature-Anbindung in der Release-Ansicht trägt eine Herkunftsklammer. Die Klammer kann eine kompakte Form annehmen (eine Klammer pro Feature, wenn die Herkunft der Anbindung über alle Blätter einheitlich ist) oder eine Form pro Blatt (eine Klammer pro Blatt, wenn die Blätter der Anbindung aus heterogenen Quellen stammen). Es gibt drei Klammerinhalte; sie gelten für beide Formen identisch.

Die drei Klammerinhalte

  • [explicit] — die Feature-Anbindung ist vom Autor deklariert. Das Aggregate oder Release hat das Feature auf dem betroffenen Knoten explizit genannt. Explizite Anbindungen sind die Quelle mit der höchsten Priorität; sie setzen sich am selben Blatt immer gegen annotationsgesteuerte Beiträge durch.

  • [annotation: <key> from <source>] — die Feature-Anbindung ist annotationsgesteuert. Der Compiler hat sie synthetisiert, weil eine Annotation auf <source> einer Manifest-Bindung entsprach, die dieses Feature deklariert. <key> ist der Annotationsschlüssel, der die Bindung ausgelöst hat (z. B. business.aggrega.ai/team); <source> ist die Entität, die die Annotation trug (aggregate, release, component oder manifest). Die synthetisierte Anbindung ist strukturell identisch mit einer expliziten — das nachgelagerte Rendering behandelt beide gleich —, aber die Herkunftsklammer unterscheidet sie, damit das Debugging entscheidbar bleibt.

  • [explicit; overrides annotation: <key> from <source>] — eine Form pro Blatt, die greift, wenn eine explizite Deklaration des Autors an einem Blatt einen Annotationsbeitrag unterdrückt, der sonst dasselbe Blatt gesetzt hätte. Seitenübergreifende Komposition erzeugt diesen Fall: Eine Aggregate-Annotation könnte die values:-Säule eines Feature liefern, eine Release-Annotation liefert dessen infra:-Säule, und eine explizite Release-Deklaration auf demselben Feature überschreibt ein infra-Blatt. Die Blattklammer hält sowohl den expliziten Autor als auch die unterdrückte Annotation fest; die unterdrückte Annotation trägt nicht zur gerenderten Ausgabe bei, aber ihr Vorhandensein erscheint in der inspect-Ansicht, sodass der Operator sehen kann, welche Annotation wo überschrieben wurde.

Kompakte Form und Form pro Blatt

Der Compiler wählt zwischen kompakter Darstellung und Darstellung pro Blatt, indem er die blattweise Herkunft der Anbindung durchläuft und auf Einheitlichkeit prüft. Die Herkunft einer Anbindung ist einheitlich, wenn jedes belegte Blatt (über die Säulen values: und infra: des Feature hinweg) denselben Ursprung (explizit oder Annotation), bei annotationsgesteuerter Herkunft denselben Annotationsschlüssel und dieselbe Quellentität hat und kein Blatt eine „overrides annotation“-Markierung trägt. Wenn die Herkunft einheitlich ist, gibt der Compiler eine Klammer pro Anbindung aus:

- core/rate-limiter [annotation: business.aggrega.ai/team from aggregate]

Wenn die Herkunft abweicht — ein typischer Fall ist die seitenübergreifende Komposition, bei der eine Aggregate-Annotation values: und eine Release-Annotation infra: auf demselben Feature liefert —, gibt der Compiler eine Klammer pro belegtem Blatt aus:

- core/pii-redaction
values.fields_to_mask: ["ssn", "card_number"] [annotation: compliance.aggrega.ai/data-class from aggregate]
values.classifier_endpoint: "redact-v2" [explicit; overrides annotation: compliance.aggrega.ai/data-class from aggregate]
infra.audit_bucket: "s3://..." [annotation: compliance.aggrega.ai/audit-bucket from release]

Die Durchlaufreihenfolge ist zuerst die values-Säule (in Autorenreihenfolge), dann die infra-Säule (nach demselben Prinzip). Das Säulenpräfix (values. / infra.) und der gepunktete Pfad innerhalb der Säule bestimmen genau, welches Blatt jede Klammer annotiert.

Als sensibel deklarierte Werte

Ein Blatt, dessen Schema sensitive: true deklariert, gibt anstelle seines Werts den festen Text <redacted> aus. Schlüssel, Säulenpräfix und Herkunftsklammer bleiben alle erhalten — nur der Wert wird ersetzt —, sodass das Layout weiterhin beantwortet, welche Blätter eine Entität trägt und woher jedes stammt. Zwei lesbare Oberflächen sind betroffen: der knotenweise Values:-Block eines Aggregate und der blattweise Anbindungsblock eines aufgelösten Release — einschließlich einer auf einer Verbindung geschriebenen Anbindung, die unter der Zeile dieser Verbindung ausgegeben wird und genau die Blätter zurückhält, die dasselbe Feature zurückhält, wenn die Komponente es selbst hält. Der kompilierte Graph eines Release unter --ir-graph hält dieselben Blätter in der strukturierten Form zurück, die unter Maschinenlesbare Ausgabe beschrieben ist.

Components:
app (type: core/app)
Values:
appName: demo
dbPassword: <redacted>
tuning.poolSize: 25
tuning.adminToken: <redacted>

Nur ein deklariertes Blatt wird zurückgehalten, und die [sensitive]-Klausel auf Anbindungsebene ist keine Anweisung zum Zurückhalten: Sie sagt, dass die Anbindung geheimes Material verarbeitet, nicht, welche ihrer Blätter es tragen. Die veröffentlichten Locators eines Berechtigungsnachweis-Feature — der Ressourcenname und der Datenschlüssel — sind öffentlich und bleiben im Katalog der Standardbibliothek bewusst undeklariert, sodass sie im Klartext neben dem Material ausgegeben werden, das es nicht ist:

- credentials (feature.test/db-credential)
values.secretName: db-creds [explicit]
values.literalPassword: <redacted> [annotation: feature.test/pw from aggregate.yaml:components.app.annotations.feature.test/pw]

Aus dem Namen eines Feldes wird nichts abgeleitet: Ein Feld namens password, das keine Deklaration trägt, gibt seinen Wert aus, und ein deklariertes Feld namens key nicht. Die Schwärzung betrifft das, was das Tool ausgibt; sie erreicht nie ein gerendertes Artefakt, und dist/ wird genau so ausgegeben, wie das Rendering es erzeugt hat. Das Schlüsselwort und die vollständige Obergrenze dessen, was seine Deklaration bewirkt, finden Sie unter vocabulary/compact-form-authoring.md, „Ein Blatt als sensibel deklarieren“.

Die zurückgehaltenen Werte anzeigen

--unredacted gibt die als sensibel deklarierten Werte aus, statt sie zurückzuhalten, und zwar auf jeder inspect-Oberfläche zugleich — den obigen lesbaren Layouts ebenso wie dem kompilierten Graphen eines Release. Es existiert, weil der zurückgehaltene Wert manchmal genau der ist, der untersucht wird: Ein Berechtigungsnachweis, der von der falschen Anbindung kommt, sieht genauso aus wie der richtige, wenn beide als zurückgehalten erscheinen.

Es wirkt nur auf den Befehl, dem es übergeben wird. aggrega build und aggrega validate akzeptieren es ebenfalls; dort erreicht es den Graphen, den --ir-graph zurückgibt, und nichts anderes, und sie lehnen es ab, wenn kein Graph angefordert wurde. aggrega build --trace-unredacted ist dieselbe Idee für die Trace-Dateien des Builds, und keines der beiden Flags des Builds erreicht die Ausgabe des anderen; ein gerendertes Artefakt unter dist/ ist von keinem davon betroffen, weil es unabhängig von den übergebenen Flags genau so ausgegeben wird, wie das Rendering es erzeugt hat.

Was auch immer die Ausgabe dann erreicht, trägt diese Werte im Klartext — ein Terminal, eine Pipe, eine Datei, eine Bildschirmaufnahme, ein eingefügter Fehlerbericht. Anders als die Trace-Dateien, die jeweils mit einem Header beginnen, der besagt, dass sie ungeschwärzt erfasst wurden, trägt die Ausgabe in einem Terminal keine solche Kennzeichnung: Nur die Befehlszeile zeigt, dass es übergeben wurde.

Wann inspect zum Einsatz kommt

  • Debugging von „Warum ist dieses Feature hier?“ — annotationsgesteuerte Anbindungen sind in den YAML-Dateien von Aggregate und Release unsichtbar (die Annotationen sind dort, aber die Feature-Anbindungen, die sie synthetisieren, existieren nur in der IR). Inspect macht sie mit ihrer Herkunft sichtbar.
  • Schema-Vererbung überprüfen — aggrega inspect <ComponentName> zeigt das zusammengeführte Schema nach Auflösung der extends:-Kette; die verfasste Datei allein zeigt nur das lokale Delta.
  • Überraschungen bei seitenübergreifender Komposition diagnostizieren — wenn eine Aggregate-Annotation und eine Release-Annotation beide Säulen-Nutzlasten auf demselben Feature liefern, können die aufgelösten Blätter gedanklich schwer zu rekonstruieren sein. Die Klammerform pro Blatt macht die Auflösung explizit.
  • Verifikationsprüfung vor dem Deployment — aggrega inspect ./prod-release.yaml listet jedes Feature auf jeder Component auf, bevor aggrega build Artefakte erzeugt; der Operator kann bestätigen, dass die Topologie der Absicht entspricht, bevor er die gerenderten Manifeste in GitOps committet.

Zu den zugrunde liegenden Mechanismen — wie Annotationen kaskadieren, wie die Aufteilung nach Seite und Säule Annotationswerte in Feature-Säulen leitet und wie das Prinzip „explizite Anbindung gewinnt“ mit annotationsgesteuerten Beiträgen zusammenwirkt — siehe providers/well-known-annotations.md und entities/manifest.md, „Annotationsgesteuerte Feature-Bindungen“.

Übersicht

aggrega inspect [identifier] [flags]

Beschreibung

Render a readable view of any Aggrega entity — a catalog entity by name, an
authored entity file by path, an entity published in a registry, or a
fully-resolved Release.
It answers "what does this entity actually resolve to?": which entities extend
which bases, which Recipe maps to each type, which Features attach to each node,
and where each Feature's contributions came from.
A single argument routes by its shape. A path — anything starting with ./, ../
or /, or ending in .yaml or .yml — is read as a file and inspected by its own
kind: header. A registry reference — oci://<host>/<repository>:<tag>, or
@<digest> in place of :<tag> — is read from the registry that publishes it.
Anything else is looked up by name in the catalog search stack: the
workspace's own, or, with --release, the one the workspace configuration
gives that Release, so a name several catalog variants declare, one per
Release, resolves to the variant that Release builds with.
A registry reference shows the entity exactly as it was published: unpacked
from the archive its kind is published as where it is one, and rendered by the
same view a file of that kind gets. Reading it reaches the network, using the
credentials this machine holds for that registry, and an offline workspace
refuses it. The fetched bytes are checked against the digest the artifact's
own manifest records for them, which establishes that they are the bytes that
manifest names and nothing more: no signature attached to the artifact is
verified, no withdrawal recorded against it is reported, and nothing is
written — no cache entry and no lockfile.
Three verbosity levels apply to every kind: --list for identifiers only, the
default for a structured overview, and --detail for full field bodies. --list
and --detail are mutually exclusive. Resolution depth has its own pair, --raw
for the entity exactly as authored and --resolved for the kind's full depth,
also mutually exclusive.
Note that --raw reproduces the file as written, so a value the author declared
sensitive appears as authored. That is what as-authored means; handle such
output as you would the entity file itself. --output yaml reproduces the file
the same way for every kind, a Release included.
A Release answers two further questions, and each has its own flag because
neither answer contains the other. --ir-graph asks for the IR graph a Release
resolves to — what the Release looks like, as JSON on stdout in addition to
whatever else this command produces. --closure asks for the Release's dependency
closure — every catalog entity it reaches and the version each resolved to,
which is what was pulled in to build the Release. An entity can be reached
without appearing as a node, and a node does not carry the version its type
resolved to, so holding one of the two is not holding the other.
--ir-graph is orthogonal to --output, which picks the format of the command's
own view. Values an author declared sensitive are withheld from the graph, as
they are from the readable layouts. Pass --unredacted to print them instead.

Flags

FlagStandardBeschreibung
--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.
--closurefalseMeldet den Abhängigkeitsabschluss des Release — jede Katalogentität, die es erreicht, in der Version, zu der sie jeweils aufgelöst wurde — anstelle der Ansicht der aufgelösten Knoten. Gilt für ein Release, die einzige Art, die einen Abschluss auflöst; jede andere Art lehnt die Anforderung ab, statt sie stillschweigend fallen zu lassen.
--colorautoAusgabe einfärben: auto|always|never.
--detailfalseVollständige Feldinhalte rendern.
--flatfalseEine baumförmige Entität (Aggregate, Release) als flache Liste rendern, jeder Knoten mit seinem vollständigen gepunkteten Pfad als Präfix. Keine Wirkung bei tabellarischen Arten.
--ir-graphfalseZusätzlich den IR-Graphen, den dieser Lauf berechnet hat, als JSON auf stdout schreiben, neben allem, was dieser Befehl ohnehin erzeugt. Werte, die ein Autor als sensibel deklariert hat, werden darin zurückgehalten; übergeben Sie —unredacted, um sie stattdessen auszugeben. Gilt für ein Release, die einzige Art, die zu einem Graphen aufgelöst wird; jede andere Art lehnt die Anforderung ab, statt sie stillschweigend fallen zu lassen
--listfalseNur Bezeichner rendern.
--no-colorfalseFarbige Ausgabe deaktivieren (Alias für —color=never).
--output, -otextAusgabeformat: text|yaml.
--plugin—Dateisystempfad zu einem rohen <file.wasm>-Artefakt; ermittelt die Host-Funktionen, die es importiert, und gibt sie aus, bevor aggrega plugin sync sie in einer Plugin-Entität festhält. Akzeptiert kein Bezeichner-Argument.
--rawfalseDie Entität so rendern, wie sie verfasst wurde, ohne Auflösung.
--release—Einen Katalognamen in den Begriffen dieser Release-Datei nachschlagen: über die Katalogverzeichnisse, die die Workspace-Konfiguration diesem Release zuweist, mit vorangestelltem —catalog. Gilt für einen Namen; eine Datei oder eine Registry-Referenz wird so inspiziert, wie sie ist, und lehnt es ab. Ein relativer Pfad wird gegen das Verzeichnis aufgelöst, in dem Sie den Befehl ausführen, nicht gegen das Workspace-Stammverzeichnis. Liegt dieses Verzeichnis in keinem Workspace und ist kein Stammverzeichnis angegeben, findet ein absoluter Pfad den Workspace ausgehend vom eigenen Ordner des Release
--resolvedfalseDie Entität vollständig aufgelöst rendern.
--show-implementsfalseFür ein Recipe oder FeatureRecipe spec.implements gegen den Katalog auflösen und die gebundene Component bzw. das gebundene Feature rendern.
--unredactedfalseDie Werte, die ein Autor als sensibel deklariert hat, ausgeben, statt sie zurückzuhalten. Alles, was die Ausgabe erreicht — ein Terminal, eine Pipe, eine Datei, eine Bildschirmaufnahme —, trägt diese Werte dann im Klartext.