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

aggrega pin

aggrega pin <entity-path> verzeichnet in der entity.lock neben einem Recipe oder FeatureRecipe den Inhalts-Pin für jede Eingabe, die die Entität von außerhalb ihres eigenen Dokuments liest. Es ist der Schritt des Entitätsautors: Führen Sie ihn aus, bevor die Entität konsumiert oder veröffentlicht wird, und committen Sie die Lock-Datei, die er schreibt.

aggrega pin catalog/recipe/helm/server/1.0.0/recipe.yaml

Was er verzeichnet

Eine Entität kann von Bytes außerhalb ihres eigenen Dokuments abhängen, und die Lock-Datei enthält für jede einen Pin:

  • Eine entfernte source:, deren Koordinaten Sie vollständig ausgeschrieben haben — kein Template in kind, url, chart, module_subdir, version oder ref. Der Schritt lädt sie herunter und verzeichnet die Version, zu der sie aufgelöst wurde — bei einer Git-Quelle den Commit, den ihr ref benannt hat — und den Inhalts-Digest des Heruntergeladenen.
  • Eine Datei, die ein artifacts-Eintrag mit $import importiert. Der Schritt bildet den Digest der Datei so, wie sie in Ihrem Workspace vorliegt.
  • Jede Datei einer source:, die ein Verzeichnis oder eine Datei neben der Entität benennt. Es wird nichts heruntergeladen: Der Schritt bildet den Digest jeder Datei, die die Quelle zu dem beiträgt, was eine Veröffentlichung der Entität mitführt — jede Datei unter dem benannten Verzeichnis, die die Ignore-Regeln der Entität behalten, oder die eine Datei — und verzeichnet sie mit ihrem Pfad neben der Entität. Eine Datei neben dem Recipe, die die Quelle nicht beiträgt, etwa eine README, wird nicht gepinnt. Eine als Template geschriebene Quelle, etwa ./charts/{{ .values.flavour }}, benennt ihr Verzeichnis erst, wenn ein Release sie ausfüllt, und trägt daher jede Datei im Verzeichnis der Entität bei, die die Regeln behalten, und jede davon wird gepinnt. Ein Build vergleicht die Quelle mit diesen Pins, bevor sein Provider sie liest, sodass eine seit dem Pin hinzugefügte, geänderte oder entfernte Datei den Build anhält — A local source no longer matches the pins recorded beside its Recipe (Eine lokale Quelle entspricht nicht mehr den neben ihrem Recipe verzeichneten Pins).
  • Die Ignore-Regeln selbst, für eine source:, die ein Verzeichnis ist. Der Schritt verzeichnet, welches Plugin die Capability der Entität bedient hat, und die exakten Regeln, die es zusammengesetzt hat, wie der nächste Abschnitt beschreibt.

Was er nicht verzeichnet: eine entfernte Quelle, deren Koordinaten aus einem Template ausgefüllt werden, die ein Artefakt erst benennt, wenn ein Release sie ausfüllt, und die von aggrega pull in der Lockfile jedes Release gepinnt wird; sowie einen Inline-Eintrag in artifacts oder einen, der aus einer ArtifactLibrary stammt. Die Datei selbst ist Feld für Feld im Schema der Entitäts-Lock-Datei beschrieben.

Es wird kein Release benötigt. Eine vollständig ausgeschriebene Quelle benennt dasselbe Artefakt für jedes Release, das die Entität je verwenden wird, daher braucht ihre Auflösung nichts, was ein Release liefert. Das erlaubt es einem Autor, eine Entität in einem Workspace zu pinnen, der überhaupt kein Release hat.

Die Entitätsdatei wird nie geschrieben. Was der Schritt ableitet, kommt neben die Entität; was Sie eingegeben haben, bleibt genau so, wie Sie es eingegeben haben. Ein erneuter Lauf über unveränderte Eingaben lässt die Lock-Datei byte-identisch, und bei einer Entität, die nichts mehr liest, was eine Lock-Datei verzeichnet, wird die Lock-Datei entfernt. Eine Component, ein Feature oder jede andere Art, die keine solche Eingabe liest, wird als ohne zu pinnende Elemente gemeldet, und nichts daneben wird angetastet.

Welche Dateien mit einer Entität ausgeliefert werden

Ein Recipe oder FeatureRecipe, dessen source: ein Verzeichnis daneben benennt — ein mitgeführtes Chart, ein Modul —, führt bei der Veröffentlichung die Dateien dieses Verzeichnisses mit. Nicht jede Datei darin gehört dorthin: ein Versionskontrollverzeichnis, ein Abhängigkeitscache, Überbleibsel eines Editors. Welche Dateien dazugehören, entscheiden Ignore-Regeln in der Syntax, die .gitignore verwendet, und Sie steuern sie. Sie stammen aus zwei Quellen:

  • Das Plugin, das die Capability der Entität rendert, deklariert, was sein eigenes Ökosystem nie ausliefert. Die Chart-Plugins lassen die Versionskontrollverzeichnisse (.git/, .hg/, .svn/, .bzr/) und die versteckten Dateien unter templates/ eines Charts weg und beachten die eigene .helmignore des Charts: Wo immer der Durchlauf der Quelle auf eine trifft, werden ihre Zeilen als weitere Regeln für das Verzeichnis gelesen, das sie enthält. Das Terraform-Plugin lässt die Versionskontrollverzeichnisse und das Arbeitsverzeichnis .terraform/ weg — nicht die Abhängigkeits-Lock-Datei, die mit dem Modul mitreisen soll — und beachtet .terraformignore auf dieselbe Weise. Ein Plugin, das nichts deklariert, lässt alles drin.
  • Ihre eigene .aggregaignore, eine Datei neben dem Entitätsdokument, in derselben Syntax. Ihre Zeilen gelten nach denen des Plugins und nach jeder Ignore-Datei, die das Plugin benennt, sodass Sie bei jedem Pfad, den Sie benennen, das letzte Wort haben: Eine Zeile wie .venv/ lässt ein Verzeichnis weg, von dem das Plugin nichts weiß, und eine Zeile wie !.git/ holt eines zurück, das das Plugin weggelassen hat. Die Datei selbst reist nie mit; ihre Regeln schon, innerhalb der Lock-Datei.
catalog/recipe/helm/server/1.0.0/.aggregaignore
.venv/
*.bak
!notes.bak

Jede Regel wird relativ zu dem Verzeichnis gelesen, zu dem sie gehört. Eine vom Plugin deklarierte Regel wird vom Stamm des Quellverzeichnisses aus gelesen; eine Zeile einer .helmignore von dem Verzeichnis aus, das diese Datei enthält; eine Zeile Ihrer .aggregaignore vom eigenen Verzeichnis der Entität aus. Eine Regel ohne Schrägstrich oder nur mit einem abschließenden trifft auf einen Namen in beliebiger Tiefe zu; ein abschließender Schrägstrich trifft nur auf ein Verzeichnis zu; ein führendes ! holt zurück, was eine frühere Regel weggelassen hat. Ein Verzeichnis, das eine Regel weglässt, wird nicht betreten, sodass eine Datei darin erst zurückkommt, wenn das Verzeichnis selbst zurückkommt — !.git/HEAD allein holt die Datei nicht zurück, solange .git/ weggelassen ist, !.git/ dagegen schon.

Das Plugin, dessen Regeln gelesen werden, ist dasjenige, das beim Pinnen die Capability in Ihrem Workspace bedient: die Provider-Bindung Ihres Workspace für diese Capability oder andernfalls das in aggrega eingebaute Plugin. Der Schritt verzeichnet dieses Plugin in der entity.lock allein mit seinem Namen, etwa provider/terraform, ohne Version, sowie die exakten Regeln, die es zusammengesetzt hat; erneutes Pinnen mit einem neueren aggrega, dessen Plugin dieselben Regeln deklariert, lässt die Lock-Datei unverändert. Von da an wendet jedes Lesen des Verzeichnisses die verzeichneten Regeln an und keine anderen: eine Veröffentlichung der Entität, der Vergleich, an dem ein Pull oder ein Push die Lock-Datei misst, die Zeile der Entität in einer Lockfile, der Vergleich eines Builds, das Rendern, das das Verzeichnis einem Provider übergibt, und aggrega pull --verify. So ist das, was Sie veröffentlichen, genau das, was Ihr eigener Build rendert, und eine geänderte Bindung, eine bearbeitete .aggregaignore oder ein neueres aggrega ändern nichts, bis Sie erneut pinnen — woraufhin der Diff der Lock-Datei zeigt, was sich bewegt hat. Eine Datei, die ein Plugin als Ignore-Datei benennt, etwa eine .helmignore, ist selbst eine der Dateien der Quelle und wird wie jede andere gepinnt, sofern keine Regel sie weglässt; sie ohne erneutes Pinnen zu bearbeiten, wird daher beim nächsten Pull oder Build erkannt. Eine Lock-Datei, die keine Regeln verzeichnet, behält jede Datei unter dem Verzeichnis.

Ein Konsument rendert die Dateien, die Ihre Regeln behalten haben. Ein Plugin kann ein für seine Capability veröffentlichtes Recipe rendern, wenn es dieselbe ABI-Version spricht, sein Vertrag dem Anspruch seiner Entität entspricht und es keine Datei außerhalb der veröffentlichten Menge benötigt. Ein Plugin, das eine Datei benötigt, die die Menge weggelassen hat, muss seinen Build deutlich fehlschlagen lassen und die Datei benennen; die Aufgabe des Hosts ist es, jedes Packen oder Lesen einer Datei, die die Menge nicht enthält, unter Nennung der Datei abzulehnen. Wenn das Plugin, das der Workspace eines Konsumenten für die Capability bindet, andere Regeln deklariert als die, die Ihre Lock-Datei verzeichnet, meldet das aggrega pull des Konsumenten dies in einer Warnung, die beide Plugins und den Unterschied benennt, und fährt fort.

Ein symbolischer Link unter den Dateien einer Entität wird abgelehnt, wohin er auch zeigt und ob er sich auflöst oder nicht — siehe A symbolic link sits among the files an entity carries (Ein symbolischer Link befindet sich unter den Dateien, die eine Entität mitführt). Ein Link, den Ihre Regeln weglassen, wird wie jede andere weggelassene Datei übergangen. Ein von der Entität benannter Pfad, der durch ein Verzeichnis führt, das ein aus dem Verzeichnis der Entität hinausführender Link ist, wird ebenfalls abgelehnt, bevor irgendetwas gepinnt wird — siehe A path names content outside the entity’s own directory (Ein Pfad benennt Inhalt außerhalb des eigenen Verzeichnisses der Entität).

Wohin die Lock-Datei kommt

Die Lock-Datei wird neben das von Ihnen benannte Dokument geschrieben, in dasselbe Verzeichnis, daher braucht die Entität einen beschreibbaren Ort: ein Dokument in einem Ihrer Verzeichnisse. Eine Entität, die ein Pull aus dem Inhaltscache aufgelöst hat, hat keinen solchen Ort und wird von nichts je gepinnt.

Ein Verzeichnis, eine Entität. Ein Verzeichnis enthält eine entity.lock, daher lehnt der Schritt ein Recipe oder FeatureRecipe ab, das sein Verzeichnis mit irgendeiner anderen Entität teilt, unabhängig davon, ob eine von beiden etwas zu pinnen hat, und benennt jede im Weg stehende Entität — die Ablehnung ist An entity shares its directory with another entity (Eine Entität teilt ihr Verzeichnis mit einer anderen Entität). Jede Art hat ein eigenes Verzeichnis außer Aggregate, Release und Manifest, die nebeneinander liegen dürfen; ein Push hält die Entität, die er veröffentlicht, an dieselbe Regel, wie Eine Entität pro Verzeichnis darlegt. Der Schritt beurteilt nur das, wofür er eine Lock-Datei schreibt, daher wird eine Component oder jede andere Art, für die er nichts zu pinnen hat, als ohne zu pinnende Elemente gemeldet, und die Ablehnung erreicht diese Entität bei ihrer Veröffentlichung. Eine Datei neben der Entität, die kein Entitätsdokument ist — eine Chart-Datei, die importierte Datei selbst —, steht nicht im Weg. Jedes Dokument neben der Entität wird nur aus dem Workspace heraus gelesen oder, bei einem von Ihnen benannten Dokument außerhalb davon, aus seinem eigenen Verzeichnis heraus — wo auch die Lock-Datei liegt —, sodass eines, das ein hinausführender Link ist, den Schritt anhält und den Link ungelesen benennt, wie die Workspace-Grenze darlegt.

Wer pinnt, und wann

Pinnen ist eine Authoring-Pflicht. Eine Entität, deren Eingaben nicht gepinnt sind, ist noch nicht bereit, konsumiert zu werden, daher verzeichnet ein Pull standardmäßig keinen Pin: Bei einem Recipe oder FeatureRecipe in einem Ihrer Katalogverzeichnisse, das das Release baut, vergleicht er, was dieser Schritt verzeichnen würde, mit dem, was die Lock-Datei enthält, und hält an, wenn ein Pin fehlt oder nicht mehr zu seiner Eingabe passt. Der Halt benennt die Entität, jede Eingabe und ob es sich um eine entfernte Quelle, eine importierte Datei oder eine Datei einer lokalen Quelle handelt, sowie diesen Befehl. Es ist An entity reads an input the lock beside it records no pin for (Eine Entität liest eine Eingabe, für die die Lock-Datei daneben keinen Pin verzeichnet). Ein Push hält die Entität, die er veröffentlicht, an denselben Vergleich und lehnt mit demselben Halt ab, sodass eine Entität eine Registry über aggrega push nicht mit einem unverzeichneten Pin erreichen kann — Pinnen vor dem Veröffentlichen legt das dar. Eine lokale Quelle wird als eine Menge von Dateien behandelt: Eine Lock-Datei, die keine davon verzeichnet, hält einen Pull oder einen Push an, ebenso wie eine seit dem Pin hinzugefügte, geänderte oder entfernte Datei, wie jeder andere fehlende oder veraltete Pin.

Einen Halt beim ersten Pull muss der Herausgeber beheben, nie der Konsument. Wenn Sie einen Katalog konsumieren, den jemand anderes verfasst — etwa einen Checkout davon in einem eigenen Verzeichnis — und eine Entität dort nicht gepinnt ist, hat der Autor diesen Schritt nie ausgeführt. Ihre Abhilfe ist nicht, dessen Verzeichnis von Hand zu bearbeiten: Setzen Sie den unten beschriebenen Workspace-Schlüssel, sodass Ihre Pulls die Pins selbst verzeichnen.

Zwei Befehle führen genau diesen Schritt für Sie aus und schreiben dieselben Bytes:

  • aggrega pull --pin-sources führt ihn über die Entitäten aus, die das Release baut, statt anzuhalten.
  • aggrega push --pin-sources führt ihn vor dem Bündeln auf der Entität aus, sodass die geschriebene Lock-Datei Teil dessen ist, was veröffentlicht wird, statt abzulehnen.

Jeder hat einen Workspace-Schlüssel, der das Pinnen zu seinem Standard macht, pin_sources_at_pull und pin_sources_at_push, beide standardmäßig aus und jeder nur für seinen eigenen Befehl maßgeblich. Das Flag überschreibt seinen Schlüssel in beide Richtungen: --pin-sources pinnt für einen Lauf, was immer der Schlüssel sagt, und --pin-sources=false tut es nicht. So kann ein zum Pinnen konfigurierter Workspace den Halt für einen Pull dennoch zurückbekommen. Ein Build, der seine eigene Lockfile füllt, ist ein Pull und folgt daher pin_sources_at_pull. Die Schlüssel sind in der Konfigurationsreferenz beschrieben.

Eine veröffentlichte Entität ändern

Best Practice: Eine Änderung an einer bereits veröffentlichten Entität gehört in eine neue Version und danach in einen Pin — nie in ein erneutes Pinnen der bereits veröffentlichten Version. Kopieren Sie die Entität in ein neues Versionsverzeichnis, nehmen Sie die Änderung dort vor und führen Sie aggrega pin auf der neuen Version aus. Die veröffentlichte Version beschreibt weiterhin genau die Bytes, mit denen sie veröffentlicht wurde, und ein Konsument, der zur neuen wechselt, wechselt bewusst.

Das Produkt erzwingt die eine Hälfte davon: Geänderte Inhalte unter einer bereits veröffentlichten Version zu veröffentlichen, wird abgelehnt, sodass eine veröffentlichte Version nicht stillschweigend ersetzt werden kann. Die andere Hälfte erzwingt es in Ihrem eigenen Workspace nicht. Eine bestehende Version nach einer Änderung erneut zu pinnen, ist manchmal genau richtig — etwa bei einer Entität, die Sie innerhalb einer Anwendung konsumieren und nicht veröffentlicht haben —, daher hindert Sie nichts daran, und die Disziplin zu wahren liegt bei Ihnen.

Derselbe Schritt auf den anderen Oberflächen

Der Daemon bietet diesen Schritt als aggrega/pin an (aggrega serve) und das Tool-Protokoll als Tool pin (aggrega mcp); beide schreiben dieselben Bytes, die dieser Befehl schreibt. Über einen HTTP-Listener schreibt das Tool in den Workspace und erreicht die Hosts, die die Quellen einer Entität benennen, daher benötigt ein Aufrufer den Workspace-Schreib-Scope, um es aufzurufen — dieselbe Berechtigung, die ein Pull benötigt.

Siehe auch

  • aggrega-pull.md — die Entitäts-Lock-Datei, was ein Build mit ihr vergleicht, und der Halt.
  • aggrega-push.md — eine Entität veröffentlichen und eine Version nur einmal veröffentlichen.
  • configuration.md — pin_sources_at_pull und pin_sources_at_push.

Übersicht

aggrega pin <entity-path> [flags]

Beschreibung

Record, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every input
the entity reads from outside its own document: a remote source: whose coordinates you wrote out
in full, a file an artifacts entry imports with $import, and each file of a local source:.
Pinning is the entity author's step. Run it on an entity before it is consumed — before you
publish it, and after every change to one of its inputs — and commit the entity.lock it writes
beside the entity. A pull over an entity whose lock does not record these pins halts and names
this command, and so does a push of it; so does one whose local source has had a file added,
changed or removed since it was pinned.
No Release is needed. A source whose coordinates carry no template names one artifact for every
Release that uses the entity, so it is resolved and pinned here, with nothing supplied. A remote
source whose coordinates are filled in from a template is not pinned here: which artifact it names is
decided by each Release, and each identity it resolves to is pinned in that Release's lockfile.
A source that names a directory beside the entity is not fetched: each file it contributes to what
a publication of the entity carries is digested as it stands and pinned by its path, so a build
refuses a file added, changed or removed after the pin. A local source written as a template
contributes every file in the entity's directory, so each of those is pinned.
Which files a source directory contributes is decided here, once, and recorded. The step reads the
ignore rules the plugin serving the entity's capability declares — this workspace's provider binding
for that capability, or else the plugin built into aggrega — together with the ignore files that
plugin names inside the source, such as a chart's .helmignore, and the .aggregaignore beside the
entity, in gitignore syntax, whose lines come last and so have the final say. It records the plugin
and the composed rules in the entity.lock, and every publication, pull, build and render of the
entity applies the recorded rules and no others, so a changed binding or a newer binary moves
nothing until you pin again. A symbolic link among the files is refused rather than followed.
The step writes beside the entity, so the entity needs a writable home: the document you name is
read from its own directory and the lock lands next to it. The entity file itself is never
written to. Re-running over unchanged inputs leaves the lock byte-identical; an entity that reads
nothing a lock records has its lock removed. A Component, a Feature or any other kind that reads
no such input is reported as having nothing to pin, and nothing beside it is touched.
A directory holds one entity.lock, so the step refuses a Recipe or FeatureRecipe that shares its
directory with any other entity, naming the entity in the way, whether or not either has anything
to pin. Every kind has a directory of its own except Aggregate, Release and Manifest, which may sit
side by side; a push holds the entity it publishes to the same rule.
aggrega pull --pin-sources and aggrega push --pin-sources run this same step on your behalf, and
write the same bytes.

Flags

FlagStandardBeschreibung
--dry-runfalseDie Eingaben der Entität auflösen und die entity.lock, die der Schritt schreiben würde, ausgeben statt sie zu schreiben: Ihr Pfad und der Inhalt, den sie hätte, gehen nach stdout, und auf der Festplatte ändert sich nichts. Eine Lock-Datei, die der Schritt byte-identisch lassen würde, wird nicht ausgegeben. Die Auflösung läuft genau so wie sonst, daher wird der Inhaltscache trotzdem gefüllt