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

Ausführbare Beispiele

Zum Einstieg installiert Erste Schritte Aggrega und geht zwei dieser Beispiele Schritt für Schritt durch.

Vollständige, forkbare Workspaces, die Sie mit der CLI aggrega kompilieren können. Jeder ist ein eigenständiges Verzeichnis — ein vom Entwickler geschriebenes Aggregate und ein oder mehrere Paare aus Release/Manifest —, das ohne weitere Einrichtung als die auf seiner Seite genannte baut. Um eines nach dem Produkt, das es bereitstellt, oder nach dem, was es zeigt, zu finden, verwenden Sie Beispiele nach Produkt und Fähigkeit, wo jedes Beispiel hier aufgeführt ist.

Die Beispiele gibt es in zwei Modi — den beiden Enden eines einzigen Lehrplans:

  • Konsum — der Workspace referenziert Katalogentitäten der Standardbibliothek und schreibt lokal nur seine eigenen lehrspezifischen Inhalte. Er baut ohne das Flag --catalog:

    Terminal window
    aggrega build --release release.yaml

    Woher diese referenzierten Entitäten gelesen werden, hängt vom Workspace ab. Ein Verzeichnis catalog/ im Stammverzeichnis des Workspace wird gelesen, ob etwas es nennt oder nicht, sodass ein Workspace, der eigene Lehrinhalte schreibt, sie einfach dort ablegen kann. Ein Workspace, der eine .aggrega-config.yaml enthält, liest außerdem jedes unter catalog_dirs aufgeführte Verzeichnis, jeweils ein Verzeichnis, in dem er Entitäten hält. Die aufgeführten Verzeichnisse werden zuerst durchsucht und catalog/ zuletzt, und im Stapel gewinnt der erste Treffer, sodass eine Entität in einem früher durchsuchten Verzeichnis eine mit derselben Identität in einem späteren verdeckt. Was kein lokales Verzeichnis deklariert — die Entitäten der Standardbibliothek —, wird aus der Registry aufgelöst, die die Konfiguration als default_registry nennt, hub.aggrega.ai. Ein Workspace, der lokal nichts schreibt, braucht keinen lokalen Eintrag, und einer, der weder ein Verzeichnis catalog/ noch eine .aggrega-config.yaml enthält, wird vollständig über die konfigurierte Registry aufgelöst. catalog_dirs als leere Liste zu schreiben besagt, dass der Workspace überhaupt keinen lokalen Katalog hat. Jeder Pfad in catalog_dirs nennt ein Verzeichnis innerhalb des Workspace, sodass eine an einen anderen Ort mitgenommene Kopie des gesamten Workspace so, wie sie ist, baut.

    Ein Workspace mit mehreren Zielen, der je Ziel einen eigenen Katalog hält, nennt die Verzeichnisse jedes Ziels unter workspace.releases, mit der jeweiligen Release-Datei als Schlüssel, sodass jedes Release gegen seinen eigenen Katalog baut.

  • Authoring — der Workspace baut die Katalogentitäten (Components, Features, Recipes) von Grund auf in lokalen Verzeichnissen catalog-*/. mariadb-adminer ist das ausgearbeitete Authoring-Beispiel; die Entitäten, die es baut, sind von derselben Art wie die, die die Konsum-Beispiele konsumieren.

Bauen Sie pro Lauf ein Release mit aggrega build --release <release file>; die Seite jedes Beispiels nennt ihre eigenen Befehle. Der Workspace liefert seinen Katalog wie oben beschrieben; übergeben Sie --catalog selbst für ein Katalogverzeichnis, das der Workspace nicht nennt, wie die Seiten zeigen, die es brauchen.

Lockfiles werden erzeugt statt mitgeliefert, daher hat ein frischer Klon keine, und der erste Build braucht eine. aggrega build arbeitet standardmäßig nur lesend: Ohne Lockfile bricht es ab und nennt die beiden möglichen Wege. Übergeben Sie für diesen ersten Build --auto-pull — aggrega build --release release.yaml --auto-pull —, um das Lockfile während des Builds aufzulösen; einmal vorher aggrega pull --release <release file> auszuführen, bewirkt dasselbe und lässt jeden späteren Build ohne Flag laufen.

In einem Checkout des Dokumentations-Repositorys enthalten die meisten Workspaces außerdem ein Hilfsskript build-release.sh, über das die eigenen Prüfungen des Repositorys bauen. Es führt aggrega build für ein Release aus, gibt den Befehl zuvor aus und meldet, welches Binary aggrega es verwendet hat und woher dieses Binary stammt; setzen Sie AGGREGA_BIN, um das Binary zu wählen. Eine von aggrega scaffold --example geschriebene Kopie enthält das Hilfsskript ohne das gemeinsame Skript, das es aufruft, daher bauen Sie eine solche Kopie direkt mit aggrega build.

Wo ein Beispiel hier einen Checkout des Katalogs der Standardbibliothek nennt, sagt Import, woher Sie einen bekommen.

Diese ergänzen die Konzeptseiten, die in Beispielübersicht beschrieben sind: Eine Konzeptseite erklärt eine Idee und verlinkt den Workspace, der sie zeigt; die Workspaces hier sind vollständige Stacks, die Sie bauen, lesen und anpassen können.

Wo eine Seite ausgibt, was ein Build erzeugt hat, ist dieser Block aus einem echten Lauf kopiert, damit Sie Ihre eigene Ausgabe damit vergleichen können — und ausgelassene Zeilen sind markiert. Die Ausgabe auf diesen Seiten lesen legt diese Konvention und die verwendete Markierung dar.

Nicht jedes Verzeichnis hier ist ein einzelner Workspace. Die Quickstart-Beispiele enthalten einen Workspace pro Schritt und die Import-Beispiele einen pro Phase eines Imports, wie der nächste Absatz beschreibt. Ein Verzeichnis enthält überhaupt keinen Workspace: policy-in-ci enthält zwei Regelskripte, die das Ausgabeverzeichnis eines Builds lesen und es zurückweisen, wenn es gegen eine Regel verstößt, jeweils mit dem zugehörigen Pipeline-Schritt. Sie laufen über die Ausgaben der Workspaces hier und über Ihre.

Jedes import-*-Beispiel — aufgeführt unter der Fähigkeit import in Beispiele nach Produkt und Fähigkeit — bewahrt ein in einem anderen Format geschriebenes Projekt so auf, wie aggrega import es vorfindet, in zwei Ordnern: source/, das Projekt, die .aggrega-config.yaml, die es zu einem Workspace macht, und die Antwortdatei, aus der der Import die Werte liest, die keine Quelle enthalten kann; und draft/, die Dateien, die der Import geschrieben hat, unverändert, ein Workspace, der sich so bauen lässt, wie er geschrieben ist, mit dem, was er auf die Standardausgabe (stdout.txt) und die Standardfehlerausgabe (import.txt) geschrieben hat. Seine Schritt-für-Schritt-Anleitung unter Import erklärt jede Phase. Sein check.sh führt das gemeinsame scripts/check-import-example.sh dieses Repositorys aus, das erneut importiert, vergleicht, was es schreibt und ausgibt, mit draft/ und die Blöcke, die die Anleitung zitiert, mit den Dateien des Beispiels, und dann das entworfene Release validiert und baut.

Die Lernreihenfolge

Jedes Beispiel hier hat einen Platz in einer einzigen Lernreihenfolge, gegeben durch tier und position in seinem Header: Stufe für Stufe, in der Reihenfolge, die die Stufenliste angibt, und innerhalb jeder Stufe das einfachste zuerst. In Lernreihenfolge listet jedes Beispiel auf diese Weise auf, und der Beispiele-Abschnitt der Seitenleiste folgt derselben Reihenfolge. Lesen Sie die Stufen von oben nach unten, oder springen Sie zu der, die zu dem passt, was Sie gerade tun; um ein Beispiel stattdessen danach zu finden, was es bereitstellt oder was es zeigt, listet dieselbe Seite die Beispiele nach Produkt und nach Fähigkeit auf.

Ein Build kann auch Plugins über das ausführen, was er rendert — siehe Wann ein Pipeline-Schritt angebracht ist.

Der Header jedes Beispiels

Die README jedes Beispiels beginnt mit einem kurzen Header, geschrieben als YAML-Front-Matter, der sagt, was das Beispiel ist: seine Stufe, sein Platz in der Lernreihenfolge, die Produkte, die es bereitstellt, und was es zeigt. Beispiele nach Produkt und Fähigkeit wird aus diesen Headern erzeugt.

---
example:
level: start
tier: catalog-only
position: 1
products: [core/datastore/mariadb, core/devtool/adminer]
shows: [connections, credentials]
---

level ist eine dieser Stufen:

  • start — die Stufe Nur Katalog: aus Katalogentitäten zusammengesetzt, wobei nichts außer dem Aggregate, dem Manifest und dem Release geschrieben wird.
  • authoring — die Stufe Authoring: schreibt eine Component, ein Feature oder ein Recipe oder zeigt, wie eines aufgebaut ist.
  • advanced — die Stufe Fortgeschritten: Boundaries, Governance-Richtlinien, annotationsgesteuerte Features und zusammengesetzte Cloud-Stacks.

tier ist der Teil der Lernreihenfolge, zu dem das Beispiel gehört, eine dieser Gruppen, die in dieser Reihenfolge vermittelt werden:

  • start-here — Hier beginnen: die zwei Beispiele, die der Leitfaden „Erste Schritte“ Schritt für Schritt ausbaut, dann die zwei Einstiegsbeispiele für die Cloud.
  • catalog-only — Nur Katalog: aus Katalog-Entitäten zusammengesetzt, wobei nichts außer dem Aggregate, dem Manifest und dem Release selbst geschrieben wird.
  • authoring — Erstellung: schreibt eine eigene Component, ein eigenes Feature oder ein eigenes Recipe oder zeigt, wie eines aufgebaut ist.
  • advanced — Fortgeschritten: Grenzen, Governance-Richtlinien, annotationsgesteuerte Features und zusammengesetzte Cloud-Stacks, mehrere davon in einem Build kombiniert.
  • importers — Importer: ein in einem anderen Format geschriebenes Projekt, von aggrega import als Entwurf in Aggrega-Dateien überführt, dann überprüft und gebaut.

position ist der Platz des Beispiels innerhalb seiner Gruppe, eine positive ganze Zahl, die kein anderes Beispiel dieser Gruppe belegt; eine Gruppe listet ihre Beispiele von der niedrigsten Position aufwärts, das einfachste zuerst.

products listet jede Katalog-Component auf, die das Beispiel bereitstellt, unter dem Namen, den ihr Katalogeintrag trägt. Eine generische Compute-Komponente (etwa core/compute/server) und eine Entität, die das Beispiel für sich selbst deklariert, werden nicht aufgeführt, daher kann ein Beispiel auch keine auflisten.

shows listet auf, was das Beispiel demonstriert, wobei jeder Eintrag aus dieser Liste stammt:

  • multi-target — ein Aggregate, für zwei oder mehr Ziele gebaut oder auf zwei oder mehr Arten realisiert.
  • recipe-selection — das Manifest wählt, welches Recipe eine Komponente realisiert oder welches FeatureRecipe eine Anbindung realisiert: pro Typ, pro Instanz oder pro Ziel.
  • modules — ein Katalog-Aggregate, als Modul importiert.
  • connections — über Sockets uses verbundene Komponenten, wobei Werte über jede Kante geleitet werden.
  • credentials — Zugangsdaten-Anbindungen und wie jedes Ziel sie zustellt.
  • parameters — in Parameter gehobene Werte, die ein Release erfüllt.
  • features — Features, die für etwas anderes als Zugangsdaten angebunden sind, etwa Routing, Monitoring, ein Budget, einen Cache oder Maskierung.
  • boundaries — in Boundaries platzierte Komponenten oder Module und was zwischen ihnen übertritt.
  • policy — Governance-Richtlinien, die einen Build annehmen oder zurückweisen, während des Builds oder über seine Ausgabe.
  • guardrails — ein Release, das abbrechen soll, und die Meldung, mit der es abbricht.
  • catalog-authoring — eine Component, ein Feature oder ein Recipe, für das Beispiel geschrieben und daneben aufbewahrt oder im Katalog veröffentlicht.
  • cloud-infrastructure — Terraform- oder CloudFormation-Ausgabe für verwaltete Cloud-Dienste.
  • external-sources — ein Recipe, das abruft, was es rendert: ein Upstream-Chart, ein Git-Repository oder ein Modul.
  • import — ein Projekt in einem anderen Format, von aggrega import als Entwurf in Aggrega-Dateien überführt, dann überprüft und gebaut.

Ein Beispiel listet mindestens ein Produkt oder eine Fähigkeit auf, damit der Index es einordnen kann. Seine README enthält außerdem einen Abschnitt ## Scaffold the example mit aggrega scaffold --example <name> in seinem ersten Befehlsblock und cd <name> in seinem zweiten, unmittelbar gefolgt von einem Abschnitt ## Build, dessen erster Befehlsblock das ist, was aggrega scaffold --example nach diesem cd als nächsten auszuführenden Schritt ausgibt. scripts/gen-examples-index.sh --check, aus dem Wurzelverzeichnis dieses Repository ausgeführt, prüft jeden Header gegen diese Listen, weist ein Beispiel zurück, dem einer der beiden Abschnitte fehlt, sowie eines, das weder ein ausführbares check.sh noch ein build-release.sh hat, und bestätigt, dass der Index aktuell ist; führen Sie es ohne --check aus, um den Index neu zu schreiben.