Ein Compose-Projekt importieren
Diese Anleitung importiert ein kleines Compose-Projekt — eine API, die PostgreSQL-Datenbank, in der sie ihre Notizen ablegt, und einen Redis-Cache — und baut das Ergebnis für Docker Compose. Der Import entwirft jede Datei, die der Build liest, und übernimmt dabei, was die Compose-Datei angibt: die Verbindungen der API zur Datenbank und zum Cache, den Benutzer und den Namen der Datenbank, das Passwort als Variablenreferenz und den Tag jedes Images. Jede Datei und jeder Ausgabeblock unten stammt aus einem echten Lauf; das Projekt und jeder Schritt der Anleitung liegen im Beispiel import-compose, wo ein Prüfskript den Import erneut ausführt, vergleicht, was er schreibt, was er ausgibt und die von dieser Seite zitierten Blöcke mit den dort abgelegten Dateien, und validiert und baut, was der Import geschrieben hat.
Das Beispiel generieren
Sie können diesen Import mit den Befehlen auf dieser Seite ausführen oder ihn von Ihrem KI-Assistenten ausführen lassen.
Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:
aggrega scaffold --example import-composeDanach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner; der folgende, unten, wechselt in den Ordner source des neuen Ordners, der enthält, was diese Seite importiert, und in dem der Import läuft:
cd import-compose
Das Projekt
compose.yaml:
# A small notes service: its API, the PostgreSQL database it keeps the notes in,# and the Redis cache in front of it.name: notes
services: api: image: ghcr.io/example/notes-api:2.3.0 ports: - "8080:8080" environment: DATABASE_HOST: db DATABASE_USER: notes DATABASE_NAME: notes DATABASE_PASSWORD: ${POSTGRES_PASSWORD} CACHE_HOST: cache depends_on: - db - cache db: image: postgres:16 environment: POSTGRES_USER: notes POSTGRES_DB: notes POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - db-data:/var/lib/postgresql/data cache: image: redis:7
volumes: db-data:Daneben macht eine .aggrega-config.yaml den Ordner zu einem Arbeitsbereich, sodass der Import seine Entwürfe dort schreibt:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside compose.yaml.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.aiDer Import gleicht jeden Dienst mit den Components des Katalogs des Arbeitsbereichs ab, und --target entwirft ein Manifest aus den Recipes des Katalogs. Der Arbeitsbereich nennt keinen Katalogordner, daher liest der Import den Katalog der Standardbibliothek aus der Registry, aus der er seinen Importer holt: einen signierten Snapshot des veröffentlichten Katalogs, den der erste Import holt, verifiziert und im Content-Cache des Arbeitsbereichs ablegt und der über seinen Digest in der Aufzeichnung benannt wird, die der Import neben seine Entwürfe schreibt. Ein Arbeitsbereich, der eigene Katalogordner nennt — in AGGREGA_CATALOG_DIRS oder unter workspace.catalog_dirs —, importiert stattdessen gegen diese.
Die Antwortdatei
Ein Build für Docker Compose benötigt nichts, was die Compose-Datei nicht angibt, daher fragt dieser Import nichts ab. Ein Build desselben Projekts für Kubernetes mit --target helm benötigt einen Wert, den keine Compose-Datei enthält: den Namen des Kubernetes-Secrets, aus dem das Passwort der Datenbank gelesen wird, da ein Kubernetes-Build ein Passwort aus einem Secret statt aus Ihrer Shell liest. Das Beispiel hält diese Antwort in import-answers.yaml neben compose.yaml, wo der Import sie sucht:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.db.features.password.infra.origin: "notes-db-password"Der Import hat die Datei selbst geschrieben, als er zum ersten Mal mit --target helm ausgeführt wurde: Er listete den Wert auf, den er nicht entwerfen konnte, mit leerem Schlüssel, und hielt an. Die Antwort ist der Name eines Secrets, niemals das Passwort. Der Import für Docker Compose schuldet keinen solchen Wert, behält die Antwort in der Datei und verwendet sie nicht. Die Antwortdatei des Imports beschreibt die Datei, die Fragen, die ein Import stattdessen in einem Terminal stellt, und was er ohne beides tut.
aggrega import listet jedes Flag auf, das der Befehl annimmt, darunter --answers, das eine anderswo abgelegte Antwortdatei nennt.
Wechseln Sie in source:
cd sourceDen Import ausführen
aggrega import compose.yaml --target composeAuf der Standardausgabe listet er auf, was er geschrieben hat:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonAuf der Standardfehlerausgabe, wobei <workspace> für den Ordner steht, in dem Sie ihn ausgeführt haben:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the compose format, with drafted paths relative to <workspace>warn: the value of environment.POSTGRES_USER of node db is carried as written in the drafts: its format marks the field as no credential, though it can carry one, and setting empty_credentials to all writes it emptywarn: the value of environment.POSTGRES_DB of node db is carried as written in the drafts: its format marks the field as no credential, though it can carry one, and setting empty_credentials to all writes it emptymapped api (ghcr.io/example/notes-api) to core/compute/server as a reference, NONEmapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9mapped cache (redis) to core/datastore/redis as a reference, HIGH at 0.9Pull complete: <workspace>/release.lock (entities=10, source_artifacts=0, external_inputs=0)
- Die
warn-Zeilen nennen jeden Wert, den die Entwürfe unverändert übernehmen, über seinen Dienst und seine Variable und nie über seinen Wert: Compose kennzeichnet keinen Wert als Zugangsdaten, und jeder davon könnte welche enthalten. Hier enthält keiner der beiden welche. Die Variablen, die die API aus einem anderen Dienst liest, werden überhaupt nicht als Werte übernommen — die Verbindungen liefern sie —, und die beiden, die${POSTGRES_PASSWORD}lauten, sind ein Variablenverweis und nichts weiter, daher nennt keine Warnung sie. - Die
mapped-Zeilen sagen, was aus jedem Dienst geworden ist.apiführt ein eigenes Image aus, ist also eine Instanz des generischen Servers der Standardbibliothek,core/compute/server.dbundcacheführen die Images aus, die die Compose-Recipes der Standardbibliothek fürcore/datastore/postgresundcore/datastore/redisausführen; jeder passte in der hohen Stufe, mit 0.9, zu dieser Component, und die Entwürfe verweisen auf sie. - Die Zeile
Pull completezeigt, dass der Import das, wovon das entworfene Release abhängt, wieaggrega pullinrelease.lockabruft, sodass die Entwürfe sofort validiert und gebaut werden können. Mit--offlineruft der Import nichts ab und nennt den auszuführenden Befehlaggrega pull.
Was er schreibt
Das Aggregate, das Release und das Manifest heißen imported/notes, nach dem name: des Compose-Projekts — eine Compose-Datei ohne name: wird nach ihrer Datei benannt, compose, und das Verzeichnis, das sie enthält, als Verzeichnis importiert, nach diesem Verzeichnis, so wie Compose ein Projekt benennt —, unter dem Namespace, den die Einstellung target_namespace des Importers festlegt, imported, sofern Sie keinen anderen festlegen (Einstellungen).
aggregate.yaml — ein Eintrag pro Dienst, die Verbindungen, aus denen die Umgebung der API schöpft, sowie die Werte und Passwörter, die die Compose-Datei setzt:
# Not carried, since the draft reads the services and the models alone: volumes.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/notes version: 0.1.0 description: Draft Aggregate imported from a source in the compose format.spec: components: api: type: core/compute/server features: # For the compose target, the lines below declare database_password on api: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. database_password: type: core/secret-value values: key: DATABASE_PASSWORD uses: cache: cache: target: cache # The variables the source sets to what cache publishes, delivered from it under the names the source gives them. inject: env: - in: "CACHE_HOST" from: host db: db: target: db # The variables the source sets to what db publishes, delivered from it under the names the source gives them. inject: env: - in: "DATABASE_HOST" from: host - in: "DATABASE_USER" from: user - in: "DATABASE_NAME" from: database db: type: core/datastore/postgres # The values of core/datastore/postgres the source sets as POSTGRES_USER, POSTGRES_DB, the variables its Compose Recipes set from them. values: user: "notes" database: "notes" features: # For the compose target, the lines below declare password on db: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. password: type: core/secret-value values: key: POSTGRES_PASSWORD cache: type: core/datastore/redisJede Variable der API, die einen anderen Dienst nennt, wird zum inject-Block dieser Verbindung: Die Compose-Datei setzte DATABASE_HOST auf db, und die Verbindung liefert den veröffentlichten host der Datenbank unter diesem Namen, sodass er der Datenbank auf jedem Ziel folgt, statt kopiert zu werden. DATABASE_USER und DATABASE_NAME stimmten mit dem Benutzer und der Datenbank überein, mit denen der PostgreSQL-Dienst angelegt wird, daher werden auch sie aus dem geliefert, was er veröffentlicht, und diese beiden Werte werden zu den eigenen values der Datenbank. Jedes Passwort wird zu einer core/secret-value-Anbindung, deklariert mit dem Schlüssel, unter dem seine Variable gelesen wird.
release.yaml — die Umgebung, Image und Port der API, die Engine-Version jedes Datenspeichers und woher jedes Passwort stammt:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/notes # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the compose format.spec: aggregate: imported/notes manifest: imported/notes components: # The source also states, for the Release to carry where core/compute/server takes it: # ports: # - "8080:8080" api: infra: image: "ghcr.io/example/notes-api:2.3.0" port: 8080 # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 8080 features: database_password: type: core/secret-value infra: # Attached by reference, never as a value: the value api reads as DATABASE_PASSWORD, read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" # The source states, for the Release to carry where core/datastore/postgres takes it: # volumes: # - "db-data:/var/lib/postgresql/data" db: infra: # The tag of the image the source runs, postgres:16, the engine_version of core/datastore/postgres its Compose Recipes run. engine_version: "16" features: password: type: core/secret-value infra: # Attached by reference, never as a value: the password of db, which the source sets as POSTGRES_PASSWORD, read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${POSTGRES_PASSWORD}" cache: infra: # The tag of the image the source runs, redis:7, the engine_version of core/datastore/redis its Compose Recipes run. engine_version: "7"Die Umgebung, development, ist ein Standardwert, den der Import schreibt, weil keine Compose-Datei eine nennt; ändern Sie ihn, wo das Release anderswo bereitgestellt wird. Die Image-Tags werden zu den Engine-Versionen, die die Components der Standardbibliothek annehmen. Der port der API ist der Port, auf dem ihr Container lauscht, und published_port der Host-Port, den ihr Eintrag in ports veröffentlicht, beide 8080, wie die Compose-Datei sie angibt; wie ihr Kommentar sagt, erreicht jeder Prozess auf diesem Rechner die API unter http://127.0.0.1:8080 und nichts sonst kann es, und wird die Zeile gelöscht, bleibt sie allein im Netzwerk des Stacks. Was kein Schlüssel aufnimmt, bleibt ein Kommentar über seinem Eintrag: der Eintrag in ports der Quelle, den port und published_port bereits tragen, und das benannte Volume der Datenbank.
manifest.yaml — das Compose-Recipe jedes Komponententyps und die Realisierung, die den Variablenverweis eines Passworts unverändert in die Compose-Datei schreibt:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/notes version: 0.1.0spec: mappings: components: type: core/compute/server: compose/server core/datastore/postgres: compose/postgres core/datastore/redis: compose/redis features: type: core/secret-value: compose/dotenv-secretrelease.lock hält per Digest die Katalog-Entitäten fest, zu denen das Release aufgelöst wurde, und .aggrega-import.json ist die Aufzeichnung dessen, was der Import geschrieben hat, und wird von einem späteren aggrega import --sync gelesen.
Validieren und bauen
aggrega validate --release release.yamlaggrega build --release release.yaml

Die Validierung gibt aus:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)und der Build, wobei <workspace> für den Ordner steht, in dem Sie ihn ausgeführt haben:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distDie notice-Zeile ist rein informativ: Das Passwort-Feature nimmt sein origin aus den values des Aggregate oder aus dem infra des Release entgegen, und der Hinweis meldet, dass ein Blatt in beiden deklariert ist. Er ändert kein Urteil.
Der Dienst api in dist/compose/docker-compose.yaml liest die Umgebung, die das Compose-Projekt ihm gab, geliefert über die Verbindungen und die Passwort-Anbindung:
api: image: ghcr.io/example/notes-api:2.3.0 environment: CACHE_HOST: cache DATABASE_HOST: db DATABASE_NAME: notes DATABASE_PASSWORD: ${POSTGRES_PASSWORD} DATABASE_USER: notes ports: - 127.0.0.1:8080:8080 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] networks: - compose depends_on: - cache - db [… omitted: the CPU and memory the server's defaults reserve]und die Datenbank und der Cache führen die Images aus, die die Compose-Datei nannte:
db: image: postgres:16 environment: POSTGRES_USER: notes POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: notes [… omitted: the labels, the network and a health check running PostgreSQL's pg_isready] cache: image: redis:7 [… omitted: the labels, the network and a health check running redis-cli ping]Zwei Unterschiede zum Ausgangsprojekt zeigen sich in der gerenderten Datei. Der Port wird nur auf der Loopback-Adresse veröffentlicht, so wie das Compose-Recipe des generischen Servers ihn veröffentlicht. Und das benannte Volume, das die Compose-Datei für die Daten der Datenbank einhängte, taucht nirgends auf: Der Entwurf führt es in einem Kommentar über dem Eintrag der Datenbank auf, kein Schlüssel der PostgreSQL-Component nimmt es entgegen, und der gerenderte Datenbankdienst hängt kein Volume ein.
Mit einem KI-Assistenten
Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie diesen Prompt dort ein.
Verwenden Sie nur die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `import-compose` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `import-compose` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `import-compose`, dessen Ordner `source` enthält, was diese Seite importiert. Rufen Sie dann das Tool `import` auf, mit `workspace_root` auf `import-compose/source`, `source` auf `compose.yaml` und `target` auf `compose` gesetzt: Es liest die benötigten Antworten aus `import-answers.yaml` neben `compose.yaml`, schreibt seine Entwürfe nach `import-compose/source` und lädt, was sie benötigen. Rufen Sie dann das Tool `validate` auf, mit `workspace_root` auf `import-compose/source` und `release` auf `release.yaml` gesetzt, und das Tool `build`, mit `workspace_root` auf `import-compose/source`, `release` auf `release.yaml` und `write` auf true gesetzt. Sagen Sie mir, welche Dateien der Build geschrieben hat; sie liegen unter `import-compose/source/dist/`.In VS Code öffnen
Ist die Aggrega-Erweiterung für Visual Studio Code installiert, öffnen Sie in VS Code den Ordner import-compose/source, in den der Import seine Entwürfe geschrieben hat. Der Ordner enthält ein einziges Release, das entworfene release.yaml, daher wählt der Editor es für Sie aus und prüft die Entwürfe beim Bearbeiten gegen dieses Release, wobei er seine Befunde in der Datei und im Bereich „Probleme“ markiert. Aggrega: Show topology graph in der Befehlspalette zeichnet die Komponenten des Release und die Verbindungen zwischen ihnen. Aggrega: Build, Aggrega: Preview build und Aggrega: Pull wirken auf dasselbe Release, und jeder davon ist auch eine Schaltfläche im Bereich Commands der Ansicht Aggrega in der Aktivitätsleiste; Build schreibt seine Dateien in dist/ im Ordner. Aggrega in Visual Studio Code verwenden behandelt den Rest.
Ausführen
ghcr.io/example/notes-api:2.3.0 steht für das Image Ihrer eigenen API. Es ist ein Platzhalter, und Docker Compose bricht daran mit Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied ab. Geben Sie das Image Ihrer API in infra.image von api in release.yaml an. Bis Ihre API bereit ist, kann ein Image, das auf Port 8080 per HTTP antwortet, an ihre Stelle treten. Der folgende Lauf verwendete mendhak/http-https-echo:39, das jede Anfrage mit einer Beschreibung der empfangenen Anfrage beantwortet:
api: infra: image: "mendhak/http-https-echo:39" port: 8080Bauen Sie mit der Änderung erneut. Das Release stimmt nicht mehr mit der release.lock überein, die der Import geschrieben hat, daher braucht der Build --auto-pull, das es erneut auflöst; ohne die Option hält der Build an und nennt aggrega pull. Docker Compose füllt beide Referenzen ${POSTGRES_PASSWORD} aus Ihrer Shell, setzen Sie das Passwort daher, bevor Sie den Stack starten: Bleibt es ungesetzt, warnt Compose The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. und schreibt an seiner Stelle einen leeren Wert.
aggrega build --release release.yaml --auto-pullexport POSTGRES_PASSWORD='a password of your own'docker compose -p notes -f dist/compose/docker-compose.yaml up -d --wait-p benennt das Projekt, wie der Ausführungsschritt von Wie ein Import abläuft erklärt. --wait kehrt zurück, sobald die Datenbank und der Cache die Health-Checks bestehen, die der Build ihnen gibt, und der Container der API läuft: Der Build gibt der API keinen Health-Check.
Testen
Fragen Sie die API unter http://127.0.0.1:8080 ab, der Adresse, die published_port veröffentlicht:
curl -sS http://127.0.0.1:8080/notes{ "path": "/notes", "headers": { "host": "127.0.0.1:8080", [… omitted: the user agent and the media types the client sent] }, "method": "GET", [… omitted: the rest of the request as the stand-in received it, the client's address and the container's host name]}Was die Verbindungen liefern, steht in der Umgebung des API-Service, unter den Namen, die Ihre API liest:
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOSTdbnotesnotescacheBeenden Sie den Stack mit:
docker compose -p notes -f dist/compose/docker-compose.yaml downAuf Kubernetes
Dasselbe Projekt wird mit --target helm für Kubernetes importiert, und der Import liest den Namen des Secrets, notes-db-password, aus der obigen Antwortdatei. Die Entwürfe für Docker Compose liegen bereits in source, entwerfen Sie diese daher in einen eigenen Ordner, nennen Sie das Image der API in dessen release.yaml wie für Docker Compose und bauen Sie von dort aus:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pullDer Build schreibt einfache Kubernetes-Manifeste unter dist/helm/ im Stammverzeichnis des Workspace, source, was von helm aus ../dist/helm/ ist. Erstellen Sie das Secret notes-db-password in dem Namespace, in den Sie anwenden, mit dem Passwort unter dem Datenschlüssel value, und wenden Sie den Ordner an, wie der Ausführungsschritt von Wie ein Import abläuft erklärt. Der Service der API ist api-default: Leiten Sie einen lokalen Port an ihn weiter und lassen Sie den Befehl laufen:
kubectl port-forward -n <namespace> svc/api-default 8080:8080Von einem anderen Terminal aus erreicht die obige Anfrage die API unverändert unter derselben Adresse, und das Ersatz-Image antwortet auf dieselbe Weise, "host": "127.0.0.1:8080". Die Verbindungen liefern die Namen der Services: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST gibt db-default, notes, notes und cache-default aus. Auf Kubernetes erhält die API ihr Datenbankpasswort noch nicht: Das Secret notes-db-password erreicht nur die Datenbank, daher ist DATABASE_PASSWORD im Container api nicht gesetzt.
Wenn sich die Compose-Datei ändert
Bewahren Sie .aggrega-import.json neben den Entwürfen auf, und führen Sie nach einer Änderung der Compose-Datei Folgendes aus:
aggrega import compose.yaml --syncDer Befehl ändert nur, was der Import geschrieben hat, und liest dieselbe Antwortdatei. Ein Teil, den die Quelle nicht angetastet hat, bleibt, wie er auf der Festplatte ist, bearbeitet oder nicht; wo die Quelle einen Teil geändert hat, den Sie bearbeitet haben, hält er an, nennt den Teil und schreibt nichts, damit Sie ihn von Hand abgleichen. aggrega import beschreibt die Regeln und jedes Flag vollständig.