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

Die Dateien eines Builds

Diese Seite erklärt eine einzige Idee, welche Datei eines Builds was aussagt, und ist kein ausführbarer Arbeitsbereich. Eine Web-App mit PostgreSQL, Schritt für Schritt aufgebaut zeigt sie in einem Arbeitsbereich, den Sie bauen; schreiben Sie ihn in einen eigenen Ordner mit:

Terminal window
aggrega scaffold --example quickstart-web

Danach gibt er die als Nächstes auszuführenden Befehle aus:

Terminal window
cd quickstart-web
cd 1
aggrega build --release release.yaml --auto-pull
export QUICKSTART_DB_PASSWORD=choose-a-password
docker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait
# then open http://127.0.0.1:8080/ in your browser

Fünf Dateiarten, jede mit einem Autor

Ein Build liest fünf Dateiarten. Jede sagt eine Sache aus, und in einem typischen Team hat jede ihren eigenen Autor:

  • eine Component sagt, was eine Art von Komponente ist: die Werte, die ein Entwickler setzen darf, die Infrastruktureinstellungen, die ein Operator setzen darf, was sie an die Komponenten veröffentlicht, die sich mit ihr verbinden, und die Sockets, über die sie sich verbindet. Der Katalog der Standardbibliothek enthält die Components, die die meisten Anwendungen brauchen, etwa core/datastore/postgres und core/compute/server, sodass ein Arbeitsbereich meist keine schreibt;
  • ein Aggregate gehört dem Entwickler: welche Komponenten die Anwendung hat und womit sich jede verbindet;
  • ein Recipe macht aus einer Art von Komponente Dateien für ein Werkzeug — einen Compose-Dienst, ein Helm-Chart, ein Terraform-Modul;
  • ein Manifest wählt, welches Recipe jede Art von Komponente für ein Ziel realisiert;
  • ein Release nennt ein Aggregate und ein Manifest und liefert die Einstellungen einer Umgebung. Es ist das, was Sie bauen: aggrega build --release release.yaml.

Die Aufteilung ist eine Orientierung: Eine Person darf alle fünf schreiben, und der Build akzeptiert jede davon, solange jede gültig ist.

Das Aggregate: Komponenten und ihre Verbindungen

Der erste Schritt des Beispiels ist eine Webanwendung und ihre Datenbank. Ihr Aggregate, aus 1/aggregate.yaml ohne die Kommentare:

spec:
components:
web:
type: core/compute/server
features:
db_password:
type: core/secret-value
values:
key: PGPASSWORD
origin: "${QUICKSTART_DB_PASSWORD}"
uses:
database:
db:
target: db
inject:
env:
- in: PGHOST
from: host
- in: PGPORT
from: port
- in: PGUSER
from: user
- in: PGDATABASE
from: database
db:
type: core/datastore/postgres
features:
password:
type: core/secret-value
values:
key: POSTGRES_PASSWORD
origin: "${QUICKSTART_DB_PASSWORD}"

Nichts hier nennt einen Port, einen Host, einen Namespace oder ein Werkzeug. web verbindet sich über sein Socket database mit db, und die Liste inject gibt an, welche Variable der Anwendung jeden Eintrag erhält, den die Datenbank veröffentlicht: from: nennt den Eintrag, in: die Variable.

Eine Verbindung ist ein String, durchgeleitet

Das Recipe der Datenbank veröffentlicht host, port, user und database, damit die Verbindung sie liest. Welche Adresse host enthält, folgt aus dem Recipe, das das Manifest gewählt hat: der Name eines Dienstes, wo die Datenbank neben der Anwendung läuft, ein Zeiger-String, den ein Provisioning-Werkzeug für eine verwaltete Datenbank auflöst, oder die Adresse eines Servers, der bereits existiert. Der Build kopiert jeden veröffentlichten String in die Variable, die das Aggregate genannt hat, und interpretiert ihn nicht: Er löst nie eine Adresse auf und prüft nie, ob sie erreichbar ist.

Das Manifest und das Release

Das Manifest aus 1/manifest.yaml bindet jede Art von Komponente und die Passwort-Anhänge an das Recipe, das sie auf Docker Compose realisiert:

spec:
mappings:
components:
type:
core/compute/server:1.1.0: compose/server:2.0.0
core/datastore/postgres:1.0.0: compose/postgres:1.0.0
features:
type:
core/secret-value:1.0.0: compose/dotenv-secret:1.0.0

Das Release aus 1/release.yaml nennt das Aggregate und das Manifest und liefert, was nur eine Umgebung weiß, hier das Image, das die Anwendung ausführt, den Port, auf dem sie lauscht, und den Port, auf dem Docker Compose sie auf der Loopback-Adresse Ihres Rechners veröffentlicht (der Digest des Images gekürzt):

spec:
aggregate: quickstart-web
manifest: quickstart-web-compose
components:
web:
infra:
image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:…
port: 8080
published_port: 8080
db: {}

Die späteren Schritte des Beispiels erweitern es: ein Redis-Cache neben der Datenbank, dann dieselben Komponenten auf AWS über Terraform, dann die Backups der Datenbank.

Parameter: ein Aggregate, viele Umgebungen

Ein Wert, der sich zwischen Umgebungen unterscheidet, wird im Aggregate als typisierter Parameter deklariert, dort referenziert, wo er verwendet wird, und von jedem Release angegeben. In Ein bei Bedarf ausgeführter Task deklariert das Aggregate den Zeitplan seines Berichts:

spec:
parameters:
report_schedule:
type: string
default: ""
components:
report:
type: core/compute/task
values:
schedule: "{{ .parameters.report_schedule }}"

und ein Release erfüllt ihn:

spec:
parameters:
report_schedule: "30 2 * * 1-5"

Der Build prüft jeden Wert, den ein Release angibt, gegen den Typ des Parameters, bevor er die Vorlage füllt. Ein Release schreibt die values einer Komponente nie selbst: Es erfüllt die Parameter, die das Aggregate bereitstellt, sodass das Aggregate der einzige Ort bleibt, der sagt, welche Werte je nach Umgebung variieren. Ein Release kann seine Parameter auch aus einer eigenen Datei lesen, parameters: { $import: ./env/prod-values.yaml }.