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 existsDrei 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 Komponentedbvom Typcore/datastore/postgres, eineapp, die sie überusesnutzt, 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 Anbindungcore/backupfü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:
aggrega scaffold --example postgres-three-realizationsDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:
cd postgres-three-realizationsBuild
aggrega build --release release-selfhosted.yaml --auto-pullaggrega build --release release-managed.yaml --auto-pullaggrega build --release release-managed-dns.yaml --auto-pullaggrega 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:
rm -rf dist && aggrega build --release release-managed.yamlMit 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.
- name: DB_HOST value: db-defaultVerwaltet — 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.
- 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.netDas Recipe veröffentlicht diesen Namen als host anstelle der Terraform-Referenz, und die Anwendung empfängt ihn:
- name: DB_HOST value: db.internal.example.net| Variable | release-managed.yaml | release-managed-dns.yaml |
|---|---|---|
DB_HOST | ${module.db.address} | db.internal.example.net |
DB_PORT | 5432 | 5432 |
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:
[… 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: 5432Kein 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- name: DB_HOST value: postgres.data.example.netEinen 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 ofPostgreSQL, which addresses a server it does not provision, but no address wassupplied: set infra.overrides.host on this component in the Release to the DNSname or IP literal the existing server answers onDer Vergleich, um den es geht
Die gerenderte Umgebung der Anwendung, alle drei nebeneinander:
| Variable | selbst gehostet | verwaltet | extern |
|---|---|---|---|
POOL_SIZE | 10 | 10 | 10 |
DB_HOST | db-default | ${module.db.address} | postgres.data.example.net |
DB_NAME | appdb | appdb | appdb |
DB_PORT | 5432 | 5432 | 5432 |
DB_PROTOCOL | postgres | postgres | postgres |
DB_USER | appuser | appuser | appuser |
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.