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

Ein Vertrag, drei Realisierungen

Eine PostgreSQL-Datenbank und die Anwendung, die sie liest, auf drei verschiedene Arten aus einem unveränderten Aggregate bereitgestellt: PostgreSQL im Cluster, PostgreSQL als verwaltete Cloud-Instanz und ein PostgreSQL-Server, der schon existierte, bevor dieses Release bereitgestellt wurde.

Die Lektion ist, was sich nicht ändert. Die Anwendung benennt einmal die Schlüssel, die sie von der Datenbank will, und wie sie heißen sollen. Sie erfährt nie, welche der drei geantwortet hat. Auch der Compiler erfährt es nie: Er liest die Schlüssel, die das ausgewählte Recipe veröffentlicht hat, und leitet die Strings weiter.

Das eine, was variiert

.-- helm/postgres ---------- a StatefulSet in the cluster
/
core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform
one Component \
one contract '- helm/postgres-external -- a server that already exists

Drei Recipes implementieren dieselbe Component. Jedes veröffentlicht dieselben Schlüssel in provides — host, port, user, database, protocol und die Schlüssel, die angeben, wo ein Scraper die Metriken der Datenbank findet, bei allen dreien leer. Welches läuft, ist eine einzige Zeile im Manifest.

Dateien

  • aggregate.yaml — Entwicklerabsicht und dasselbe Dokument für alle drei Releases: eine Komponente db vom Typ core/datastore/postgres, eine app, die sie über uses nutzt, und die fünf Schlüssel, die die Anwendung anfordert. Nichts hier benennt ein Ziel, eine Cloud oder ein Recipe.
  • manifest-selfhosted.yaml, manifest-managed.yaml, manifest-external.yaml — die Ops-Zuordnungen. Jede wählt ihre Realisierung in einer Zeile: welches Recipe der PostgreSQL-Komponententyp bindet. Die verwaltete bindet zusätzlich das Backup-Feature, das ihre Releases anbinden.
  • release-selfhosted.yaml, release-managed.yaml, release-external.yaml — die Dimensionierung durch den Betreiber in jedem Release: Speicher und Engine-Version für das clusterinterne, Speicher, HA und eine Anbindung core/backup für das verwaltete und die Adresse des bestehenden Servers für das referenzierte.
  • release-managed-dns.yaml — noch einmal das verwaltete Release, mit dem DNS-Namen, den der Betreiber der Instanz gibt, sodass der Anwendung ein Name übergeben wird, den sie auflösen kann.
  • catalog/ — die eigene Component der Anwendung und das eine Recipe, das sie rendert. Alles auf der Datenbankseite stammt unverändert aus der Standardbibliothek.

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

Terminal window
aggrega scaffold --example postgres-three-realizations

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd postgres-three-realizations

Build

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull schreibt die Lockfile jedes Release bei seinem ersten Build; spätere Builds brauchen kein Flag. Jeder schreibt nach dist/, und ein Build ergänzt seine Dateien, statt zu leeren, was ein früherer hinterlassen hat. Entfernen Sie dist/ zwischen den Läufen, um die Ausgabe einer Realisierung für sich zu lesen:

Terminal window
rm -rf dist && aggrega build --release release-managed.yaml

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `postgres-three-realizations` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `postgres-three-realizations` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `postgres-three-realizations`. Rufen Sie dann das Tool `build` einmal für jedes Release auf, in dieser Reihenfolge — `release-selfhosted.yaml`, `release-managed.yaml`, `release-managed-dns.yaml` und `release-external.yaml` — jedes Mal mit `workspace_root` auf `postgres-three-realizations`, `release` auf die jeweilige Datei, `auto_pull` auf true und `write` auf true gesetzt. Nennen Sie mir die Dateien, die jeder Build geschrieben hat; sie liegen unter `postgres-three-realizations/dist/`.

Was jede rendert

Selbst gehostet — das Release betreibt den Server

helm/postgres synthetisiert die Datenbank im Cluster: ein StatefulSet, einen ClusterIP-Service und einen Headless-Service. provides.host ist der bloße Name dieses Service, daher erreicht die Anwendung ihn über clusterinternes DNS.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db-default

Verwaltet — ein Cloud-Anbieter betreibt den Server

terraform/postgres-rds gibt eine aws_db_instance als Terraform-HCL aus, und die Dimensionierung ha und die Anbindung core/backup des Betreibers werden auf die nativen Einstellungen der Instanz abgebildet: Das retention_days: 14 der Anbindung wird zum backup_retention_period = 14 der Instanz. Die Anwendung wird weiterhin für Kubernetes gerendert: Die beiden Seiten dieses Release treffen sich am veröffentlichten Vertrag der Datenbank, nicht an einem gemeinsamen Ziel.

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: ${module.db.address}

Dieser Wert ist kein Hostname, und nichts in diesem Build macht einen daraus. Die Adresse einer RDS-Instanz existiert erst, wenn die Instanz erstellt ist, daher gibt es für einen Compiler, der vorab läuft, nichts nachzuschlagen. Was das Recipe veröffentlicht, ist eine Terraform-Referenz auf eine Ausgabe des eigenen Moduls der Datenbank; der Compiler leitet sie unverändert über die Kante, das Recipe der Anwendung empfängt sie wörtlich, und sie wird als die oben gezeigten literalen Zeichen in das Kubernetes-Manifest gerendert. Dem Container wird dieser Text übergeben.

DB_PORT ist anders: Es wird als "5432" gerendert, weil das Recipe den Port der Instanz aus dem Release setzt und denselben Wert veröffentlicht, der bekannt ist, bevor irgendetwas existiert.

Native Verdrahtung zwischen zwei Komponenten ist etwas, das ein Ziel innerhalb seiner eigenen Ausgabe tut, daher gibt es hier keine. Die beiden Enden dieser Kante werden über verschiedene Ziele gerendert — die Datenbank in Terraform-HCL, die Anwendung in ein Kubernetes-Manifest —, und eine Terraform-Referenz hat nur innerhalb einer Terraform-Konfiguration eine Bedeutung. Über diese Nahtstelle hinweg wird der veröffentlichte Wert als Text zugestellt wie jeder andere String. Ein Konsument, der auf Terraform als Recipe mit source: gerendert wird, in derselben Root-Konfiguration wie die Datenbank, erhält dieselbe Referenz als eines der Argumente seines Moduls, und dort löst Terraform sie auf.

Das ist die allgemeine Regel und kein Sonderfall für RDS: Alles, was vom Zustand eines laufenden Systems abhängt, wird als deterministischer Zeiger ausgedrückt, den die Laufzeit auflöst, nie als Wert, den der Compiler abruft. Die Aufgabe des Compilers ist es, den Zeiger unverändert zuzustellen. Dafür zu sorgen, dass er sich dort auflöst, wo er ankommt, ist Sache des Recipe-Autors: eine Adresse veröffentlichen, die die konsumierende Seite verwenden kann, oder beiden Komponenten Recipes geben, die in dasselbe Ziel rendern.

Der Instanz einen Namen geben, den die Anwendung auflösen kann

terraform/postgres-rds nimmt die erste davon als Option, die der Betreiber setzt. release-managed-dns.yaml ist das verwaltete Release mit einer Ergänzung, dem DNS-Namen, den der Betreiber der Instanz gibt:

db:
infra:
overrides:
host: db.internal.example.net

Das Recipe veröffentlicht diesen Namen als host anstelle der Terraform-Referenz, und die Anwendung empfängt ihn:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
Variablerelease-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

Das ist die einzige Zeile der Ausgabe, die sich ändert. Das Recipe gibt keinen DNS-Eintrag und keinen Alias für den Namen aus, und der Build schlägt ihn nicht nach: Der Compiler leitet ihn genau so weiter, wie er die Referenz weitergeleitet hat. db.internal.example.net auf die Instanz zeigen zu lassen, sobald sie existiert — ein Eintrag in der eigenen DNS-Zone des Betreibers, der auf die Adresse der Instanz zielt —, ist Sache des Betreibers, außerhalb des Release. Der Schlüssel ist derjenige, den die weiter unten referenzierte Realisierung für dieselbe Adresse liest; dieses Recipe nimmt ihn als bloßen Namen oder IP-Literal an, und ein Wert, der ein Schema, einen Pfad, einen Benutzer oder einen Port enthält, bricht den Build ab, da der Port das infra.port des Release ist und ein Konsument seine Verbindung aus beiden zusammensetzt.

Ein Konsument, der in dieselbe Terraform-Konfiguration wie die Datenbank gerendert wird, erhält ebenfalls den Namen und verliert damit die Reihenfolge, die ihm die Referenz gab: Terraform verarbeitet ein Modul nach einem Modul, das es referenziert, und ein Name referenziert nichts. Diesen Konsumenten in eine eigene Boundary zu legen, die das directory: der Datenbank teilt und eine spätere syncWave: trägt, stellt die Reihenfolge wieder her.

Extern — niemand in diesem Release betreibt den Server

helm/postgres-external stellt überhaupt nichts bereit. Seine gesamte Ausgabe ist ein Service, der einen clusterinternen Namen auf die Adresse abbildet, die das Release liefert:

dist/stack/helm/db-service.yaml
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]
spec:
type: ExternalName
externalName: postgres.data.example.net
ports:
- port: 5432

Kein StatefulSet, kein Volume, kein Container — der Lebenszyklus des Servers liegt vollständig außerhalb dieses Release. Die Adresse kommt aus dem Release:

db:
infra:
overrides:
host: postgres.data.example.net
dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: postgres.data.example.net

Einen Server zu referenzieren ist nicht dasselbe, wie ihn zu übernehmen. Dieses Recipe erreicht einen Server, der in fremdem Besitz bleibt; nichts hier stellt ihn unter die Verwaltung des Release, und nichts hier wird ihn ändern.

Lassen Sie die Adresse weg, und der Build hält an und sagt es. Ein referenzierter Server hat eine Adresse oder gar nichts, daher weist das Recipe die Eingabe zurück, statt einen Service auszugeben, der einen leeren Namen als Alias verwendet:

[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]
assertion failed: the Manifest selects the referenced realization of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

Der Vergleich, um den es geht

Die gerenderte Umgebung der Anwendung, alle drei nebeneinander:

Variableselbst gehostetverwaltetextern
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

Dieselben Variablen, dieselbe Reihenfolge, jedes Mal. Nur der String hinter einer von ihnen ändert sich. Das Recipe der Anwendung benennt keine der Variablen DB_: Es gibt aus, was immer die Kante uses aufgelöst hat, weshalb ein einziges Recipe gegen alle drei Datenbanken unverändert rendert.

Und der Compiler weiß nicht, was irgendeiner dieser Strings ist. db-default ist ein Kubernetes-Service-Name, ${module.db.address} ist eine Terraform-Referenz, postgres.data.example.net ist ein DNS-Name — für den Compiler sind es drei Strings, die ein Recipe unter dem Schlüssel host veröffentlicht hat und die eine Kante als DB_HOST zugestellt haben wollte. Er prüft nicht, ob einer davon routbar ist, ob ein Port eine Zahl ist oder ob eine Komponente namens db eine Datenbank ist. Er hat die Kante anhand des Labels zugeordnet, das die Component trägt, den Schlüssel gelesen, den der Vertrag deklariert, und den Text bewegt.

Wo die Naht liegt

Jedes der drei Releases wurde durch eine Ops-Zuordnung gewählt, und das Entwicklerdokument blieb von dieser Wahl unberührt. Das ist die Trennung, die das ganze Beispiel greifbar machen soll:

  • der Entwickler sagt, was die Anwendung von einer Datenbank braucht;
  • Ops sagt, woraus eine Datenbank besteht — ein Recipe pro Realisierung;
  • der Betreiber sagt, welche dieses Release bekommt, und dimensioniert sie.

Fügen Sie morgen eine vierte Realisierung hinzu — eine andere Cloud, ein anderer Betreiber, ein Compose-Service für die lokale Arbeit — und es ist ein weiteres Recipe, das dieselben Schlüssel veröffentlicht, plus eine Manifest-Zeile. Das aggregate.yaml in diesem Verzeichnis ändert sich nicht.