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

Aggrega-Schema für das Entitäts-Lock

Generierte Referenz. Nicht von Hand bearbeiten — aus dem veröffentlichten JSON Schema neu generieren.

Schema-ID: https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json

Die Datei entity.lock, die neben einer Entität liegt und die Inhalts-Pins für die Eingaben verzeichnet, auf die diese Entität außerhalb ihres eigenen Dokuments zugreift: die Dateien, die ihre Artefakte importieren, die Dateien einer lokalen Quelle und die entfernten Quellen, deren Identität die Entität vollständig ausschreibt — und, für eine lokale Quelle, die ein Verzeichnis ist, die Regeln, die entschieden haben, welche ihrer Dateien zur Entität gehören. Ein einziger Schritt schreibt sie: aggrega pin, den der Autor der Entität ausführt und der kein Release benötigt. aggrega pull und aggrega push führen denselben Schritt aus und schreiben dieselben Bytes, wenn sie dazu aufgefordert werden — mit --pin-sources oder mit pin_sources_at_pull oder pin_sources_at_push des Workspace. Ein Pull, der nicht zum Pinnen aufgefordert ist, schreibt hier nichts: Bei einer Entität in den eigenen Katalogverzeichnissen des Workspace vergleicht er, was der Schritt verzeichnen würde, mit dem, was die Datei enthält, und bricht ab, wobei er aggrega pin nennt, wenn ein Pin fehlt oder nicht mehr zu seiner Eingabe passt — bei einer lokalen Quelle bricht eine seit dem Pin hinzugefügte, geänderte oder entfernte Datei den Pull ab wie jeder andere veraltete Pin. aggrega build liest sie zurück und bricht ab, wenn das, was auf der Festplatte liegt, nicht mehr den verzeichneten Digest ergibt. Ihr Geltungsbereich ergibt sich aus dem Verzeichnis, in dem sie liegt — sie pinnt die Eingaben der Entität in diesem Verzeichnis —, sodass ein einziger Dateiname jeder Art dient, statt dass jede Art eine eigene Schreibweise trägt. Der Schritt entfernt das Lock einer Entität, die keine solche Eingabe liest, statt ein leeres zurückzulassen. Das Entitätsdokument selbst wird nie maschinell geschrieben: Was ein Autor getippt hat, bleibt genau so, wie es getippt wurde, und was die Maschine abgeleitet hat, steht hier. Diese Trennung macht das Lock sicher zum Committen und als Diff lesbar, weil jede Zeile eine Eingabe nennt und ein veränderter Digest die Eingabe nennt, die sich verändert hat. Sie enthält keinen Zeitstempel und keine Auflösungsmetadaten, sodass ein erneutes Ausführen des Schritts über unveränderte Eingaben die Datei Byte für Byte identisch lässt. Eine einzige Zeilenform dient jeder Art, die einen Pin verzeichnen kann, sodass ein Pin gleich gelesen wird, welcher Art er auch angehört. Die Übertragungsform ist geschlossen (additionalProperties: false). Disziplin der Schemaentwicklung: Das Hinzufügen eines neuen optionalen Feldes ist SemVer-MINOR (additiv); das Entfernen eines Feldes oder das Verschärfen einer Einschränkung ist SemVer-MAJOR.

Typ der obersten Ebene: object

Eigenschaften

EigenschaftTypErforderlichBeschreibung
versionconst 1jaVersion des Entitäts-Lock-Schemas: 1. Eine SemVer-MAJOR-Änderung am Schema erhöht sie. Konstante: 1
sourceDigestsobject[]neinInhalts-Pins für die entfernten Quellen, auf die diese Entität verweist und deren Identität die Entität vollständig ausschreibt, bei der Auflösung aus den abgerufenen Bytes eingefroren und beim Build zurückgelesen, um zu prüfen, dass die zwischengespeicherte Quelle nicht abgewichen ist. Jeder Eintrag spiegelt die Identität der aufgelösten Quelle {kind, url, chart, moduleSubdir, version} sowie den Inhalts-Digest (und, für eine per OCI verteilte Quelle, den Manifestdigest). Eine Quelle, deren Identität aus einem Template ausgefüllt wird — etwa eine Version, die aus den Infrastrukturwerten eines Release gelesen wird —, hat hier keinen Eintrag: Welches Artefakt sie benennt, entscheidet jedes Release, das die Entität verwendet, daher wird jede Identität, zu der sie aufgelöst wird, stattdessen im Lockfile dieses Release gepinnt. Auch eine lokale (dateisystemrelative) Quelle hat hier keinen Eintrag: Sie benennt einen Pfad statt etwas Abgerufenem, daher gibt es kein bezogenes Archiv zu pinnen, und ihre Dateien werden stattdessen einzeln in localSourceDigests gepinnt.
artifactDigestsobject[]neinInhalts-Pins für die Dateien, die die Artefakte dieser Entität über $import importieren — bei einem Recipe auch diejenigen, die seine Einträge in boundary.artifacts importieren —, bei der Auflösung eingefroren und beim Build zurückgelesen, um zu prüfen, dass die importierte Datei nicht abgewichen ist. Ein Eintrag pro Artefakt, dessen Wert ein Dateiimport ist; ein inline (wörtlich) angegebenes Artefakt ist bereits Teil der Entität und trägt keinen eigenen Pin, und ein Artefakt aus einer Bibliothek wird durch die Version gepinnt, zu der diese Bibliothek aufgelöst wurde. Ein Build vergleicht einen Eintrag jedes der beiden Blöcke auf dieselbe Weise mit seinem Pin und lehnt unter derselben Bedingung eine Datei ab, die nicht mehr dazu passt.
localSourceDigestsobject[]neinInhalts-Pins für die Dateien der lokalen Quelle dieser Entität — einer Quelle, die als Pfad neben der Entität geschrieben statt abgerufen wird —, eingefroren, wenn die Entität gepinnt wird, und beim Build zurückgelesen, um zu prüfen, dass die Dateien nicht abgewichen sind. Ein Eintrag pro Datei, die die Quelle zu dem beiträgt, was eine Veröffentlichung der Entität trägt: jede Datei unter dem Verzeichnis, das die Quelle benennt, die die unter ignore verzeichneten Regeln behalten, oder die eine Datei, die sie benennt. Eine als Template geschriebene lokale Quelle benennt ihr Verzeichnis erst, wenn ein Release das Template ausfüllt, daher trägt sie jede Datei im eigenen Verzeichnis der Entität bei, die die verzeichneten Regeln behalten, und jede davon wird gepinnt. Das Entitätsdokument, die .aggregaignore des Autors daneben und diese Datei sind nie Einträge: Das Dokument ist die Entität selbst, die Regeln der Ignorierdatei werden unter ignore verzeichnet, und das Lock kann seinen eigenen Digest nicht verzeichnen. Sobald das Lock hier einen Eintrag verzeichnet, lehnt ein Build eine Quelle ab, die eine Datei ohne Eintrag enthält, eine Datei, deren Inhalt nicht mehr den Digest ihres Eintrags ergibt, oder der eine Datei fehlt, die ein Eintrag nennt.
ignoreobjectneinDie Regeln, die entscheiden, welche Dateien unter dem Verzeichnis der lokalen Quelle dieser Entität zu ihr gehören, verzeichnet, wenn die Entität gepinnt wird. Jedes spätere Lesen dieses Verzeichnisses wendet diese Regeln an und nichts anderes: eine Veröffentlichung der Entität, der Vergleich, an dem ein Pull oder eine Veröffentlichung das Lock misst, die Entitätszeile des Autors, der Vergleich eines Builds und sein Rendern sowie ein prüfender Pull. Daher verschiebt eine Änderung an der .aggregaignore des Autors, an der Provider-Bindung des Workspace oder am aggrega-Binary keinen Digest, bis die Entität erneut gepinnt wird, und das erneute Pinnen zeigt die Änderung hier als Diff. Nur vorhanden, wo die Entität eine lokale Quelle deklariert, die ein Verzeichnis ist, oder eine, die als Template geschrieben ist. Ein Lock, das keine Regeln verzeichnet, behält jede Datei unter diesem Verzeichnis. Ein symbolischer Link irgendwo darunter wird abgelehnt statt verfolgt.

Zusätzliche Eigenschaften sind nicht zulässig.

entity-lock.sourceDigests[]

EigenschaftTypErforderlichBeschreibung
kindenumjaDie Art der aufgelösten Quelle. Eine aus einer geschlossenen Menge — derselben Menge, die das kind des Quellartefakts im Lockfile und das kind der Cache-Metadaten tragen —, weil alle drei dieselben Identitäten aufgelöster Quellen verzeichnen und ein Build die Art liest, um den Loader zu wählen. terraform-module-oci gehört zur Menge, und kein Quelladapter bedient sie: Ein Recipe oder FeatureRecipe, das sie nennt, wird beim Lesen abgelehnt. Zulässige Werte: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci"
urlstringjaDie verfasste Quell-URL, die der Digest pinnt — die Identitäts-URL, wie sie in spec.source.url geschrieben ist (eine Repository-Wurzel oder eine direkte .tgz bei helm-https-chart). Der Build rekonstruiert dieselbe URL offline, daher ist sie die stabile Identität, nach der der Pin geschlüsselt ist, kein aufgelöster Artefaktort.
chartstringneinDer Chart-Name für eine helm-Quelle mit Repository-Wurzel (spec.source.chart), Teil der Identität der aufgelösten Quelle, sodass zwei Charts, die aus einer Repository-Wurzel in derselben Version ausgeliefert werden, getrennt gepinnt werden. Fehlt bei einer direkten .tgz-, OCI-, compose- oder git-Quelle, von denen keine ein Chart innerhalb der URL auswählt.
moduleSubdirstringneinDas Verzeichnis innerhalb eines aus git bezogenen Repositorys, das das Artefakt ist (spec.source.module_subdir), Teil der Identität der aufgelösten Quelle, sodass zwei Verzeichnisse eines Repositorys beim selben Commit getrennt gepinnt werden. Fehlt, wenn das ganze Repository das Artefakt ist, und bei jeder Art, die ihr Artefakt über eine URL erreicht statt durch Absteigen in einen Klon.
versionstringjaDie konkrete gepinnte Version, zu der die Quelle aufgelöst wurde — eine Chart-Version bei einer Art helm-*, der Commit, zu dem eine git-repository-Referenz aufgelöst wurde. Als einzelnes Pfadsegment verzeichnet, weil sie den Cache-Slot bildet, aus dem der Build die Quelle zurückliest, daher enthält sie kein /, kein \ und kein ... Muster: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringjaDer Inhalts-Digest des abgerufenen Quellarchivs, als sha256:, gefolgt von 64 kleingeschriebenen Hexadezimalzeichen, beim Build gegen die zwischengespeicherten Bytes geprüft. Muster: ^sha256:[a-f0-9]{64}$.
manifestDigeststringneinDer OCI-Manifestdigest für eine per OCI verteilte Quelle — die unabhängige Vertrauenswurzel — als sha256:, gefolgt von 64 kleingeschriebenen Hexadezimalzeichen. Nur bei einer OCI-Quelle vorhanden (einem helm-oci-chart); fehlt bei einer https- oder git-Quelle, die konstruktionsbedingt keine Manifestdatei trägt. Muster: ^sha256:[a-f0-9]{64}$.

Zusätzliche Eigenschaften sind nicht zulässig.

entity-lock.artifactDigests[]

EigenschaftTypErforderlichBeschreibung
namestringjaDas Artefakt, dessen $import-Datei dieser Eintrag pinnt: der Map-Schlüssel in artifacts: für einen Eintrag von artifacts und boundary/, gefolgt vom Schlüssel, für einen Eintrag von boundary.artifacts eines Recipe — sodass ein Eintrag jedes Blocks, der unter demselben Schlüssel geschrieben ist, getrennt gepinnt wird.
digeststringjaDer Inhalts-Digest der Bytes der importierten Datei, als sha256:, gefolgt von 64 kleingeschriebenen Hexadezimalzeichen, beim Build geprüft. Muster: ^sha256:[a-f0-9]{64}$.

Zusätzliche Eigenschaften sind nicht zulässig.

entity-lock.localSourceDigests[]

EigenschaftTypErforderlichBeschreibung
pathstringjaDer Pfad der Datei relativ zum Verzeichnis, das das Entitätsdokument enthält, mit Schrägstrichen geschrieben — zum Beispiel charts/app/templates/deployment.yaml.
digeststringjaDer Inhalts-Digest der Bytes der Datei, als sha256:, gefolgt von 64 kleingeschriebenen Hexadezimalzeichen, beim Build geprüft. Muster: ^sha256:[a-f0-9]{64}$.

Zusätzliche Eigenschaften sind nicht zulässig.

entity-lock.ignore

Die Regeln, die entscheiden, welche Dateien unter dem Verzeichnis der lokalen Quelle dieser Entität zu ihr gehören, verzeichnet, wenn die Entität gepinnt wird. Jedes spätere Lesen dieses Verzeichnisses wendet diese Regeln an und nichts anderes: eine Veröffentlichung der Entität, der Vergleich, an dem ein Pull oder eine Veröffentlichung das Lock misst, die Entitätszeile des Autors, der Vergleich eines Builds und sein Rendern sowie ein prüfender Pull. Daher verschiebt eine Änderung an der .aggregaignore des Autors, an der Provider-Bindung des Workspace oder am aggrega-Binary keinen Digest, bis die Entität erneut gepinnt wird, und das erneute Pinnen zeigt die Änderung hier als Diff. Nur vorhanden, wo die Entität eine lokale Quelle deklariert, die ein Verzeichnis ist, oder eine, die als Template geschrieben ist. Ein Lock, das keine Regeln verzeichnet, behält jede Datei unter diesem Verzeichnis. Ein symbolischer Link irgendwo darunter wird abgelehnt statt verfolgt.

EigenschaftTypErforderlichBeschreibung
pluginobjectneinDas Plugin, das die Fähigkeit der Entität im Workspace des Autors bediente, als die Entität gepinnt wurde — die Provider-Bindung des Workspace für diese Fähigkeit oder andernfalls das in das aggrega-Binary eingebaute Plugin —, ohne Version benannt, und die Ignorierregeln, die es deklariert hat. Weder eine Version noch ein Digest des Plugins wird verzeichnet: Die Regeln sind das, was jedes Lesen anwendet, daher lässt erneutes Pinnen unter einer anderen Version desselben Plugins das Lock unverändert, sofern sich die Regeln nicht geändert haben. Ein Pull, dessen eigenes Plugin für die Fähigkeit andere Regeln deklariert, meldet dies in einem Hinweis, nennt beide Plugins und den Unterschied und bricht deswegen nie ab. Fehlt, wo kein Plugin die Fähigkeit bediente.
rulesobject[]neinDie exakten zusammengesetzten Regeln in der Reihenfolge, in der sie gelten: die Muster des Plugins, dann die Zeilen jeder Ignorierdatei, die das Plugin nennt und die der Durchlauf gefunden hat, die eigene Datei eines Verzeichnisses vor denen darunter, dann die Zeilen der .aggregaignore des Autors neben der Entität. Ein späterer Treffer überschreibt einen früheren, daher hat die Datei des Autors das letzte Wort über jeden Pfad, den sie nennt, und eine Zeile, die mit ! beginnt, holt zurück, was eine frühere Regel ausgeschlossen hat. Ein Verzeichnis, das eine Regel ausschließt, wird nicht betreten, daher kommt eine Datei darunter erst zurück, wenn das Verzeichnis zurückkommt.

Zusätzliche Eigenschaften sind nicht zulässig.

entity-lock.ignore.plugin

Das Plugin, das die Fähigkeit der Entität im Workspace des Autors bediente, als die Entität gepinnt wurde — die Provider-Bindung des Workspace für diese Fähigkeit oder andernfalls das in das aggrega-Binary eingebaute Plugin —, ohne Version benannt, und die Ignorierregeln, die es deklariert hat. Weder eine Version noch ein Digest des Plugins wird verzeichnet: Die Regeln sind das, was jedes Lesen anwendet, daher lässt erneutes Pinnen unter einer anderen Version desselben Plugins das Lock unverändert, sofern sich die Regeln nicht geändert haben. Ein Pull, dessen eigenes Plugin für die Fähigkeit andere Regeln deklariert, meldet dies in einem Hinweis, nennt beide Plugins und den Unterschied und bricht deswegen nie ab. Fehlt, wo kein Plugin die Fähigkeit bediente.

EigenschaftTypErforderlichBeschreibung
namestringjaDas Plugin, das die Fähigkeit der Entität bediente, als sie gepinnt wurde, als <pluginType>/<name>, ohne Version: Die Regeln darunter sind das, was ein Lesen anwendet, und der Name sagt, wessen sie waren. Mindestens 1 Zeichen lang.
patternsstring[]neinDie Ignoriermuster, die das Plugin deklariert hat, so wie es sie deklariert hat.
filesstring[]neinDie Namen der Ignorierdateien, von denen das Plugin deklariert hat, dass sein Ökosystem sie innerhalb einer Quelle beachtet.

Zusätzliche Eigenschaften sind nicht zulässig.

entity-lock.ignore.rules[]
EigenschaftTypErforderlichBeschreibung
patternstringjaEin Ignoriermuster in gitignore-Syntax.
withinstringjaDas Verzeichnis, auf das sich der Geltungsbereich des Musters erstreckt, relativ zum Verzeichnis, das das Entitätsdokument enthält, und mit Schrägstrichen geschrieben; . benennt dieses Verzeichnis selbst. Ein Muster, das das Plugin deklariert, gilt für das Verzeichnis der lokalen Quelle, eine Zeile einer Ignorierdatei für das Verzeichnis, das diese Datei enthält, und eine Zeile der .aggregaignore des Autors für das Verzeichnis der Entität.
fromstringjaWo das Muster deklariert wurde: plugin für eines, das das Plugin deklariert hat, und andernfalls der Pfad der Ignorierdatei, aus der es gelesen wurde, relativ zum Verzeichnis, das das Entitätsdokument enthält.

Zusätzliche Eigenschaften sind nicht zulässig.