Importare un progetto Compose
Questa guida passo passo importa un piccolo progetto Compose — un’API, il database PostgreSQL in cui conserva le sue note e una cache Redis — ed esegue la build del risultato per Docker Compose. L’importazione abbozza ogni file letto dalla build, riportando ciò che il file Compose dichiara: le connessioni dell’API al database e alla cache, l’utente e il nome del database, la password come riferimento a variabile e il tag di ogni immagine. Ogni file e ogni blocco di output riportati di seguito provengono da un’esecuzione reale; il progetto e ogni fase della guida si trovano nell’esempio import-compose, dove uno script di controllo esegue di nuovo l’importazione, confronta ciò che scrive, ciò che stampa e i blocchi citati in questa pagina con i file conservati lì, e convalida ed esegue la build di ciò che l’importazione ha scritto.
Generare l’esempio
Puoi eseguire questa importazione con i comandi di questa pagina, oppure farla eseguire al tuo assistente AI.
Scrivi l’esempio in una nuova cartella che porta il suo nome:
aggrega scaffold --example import-composePoi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella; quello successivo, qui sotto, ti porta nella cartella source della nuova cartella, che contiene ciò che questa pagina importa ed è dove viene eseguita l’importazione:
cd import-compose
Il progetto
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:Accanto a esso, un file .aggrega-config.yaml rende la cartella un’area di lavoro, così l’importazione vi scrive le sue bozze:
# 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.aiL’importazione confronta ogni servizio con i Components del catalogo dell’area di lavoro, e --target abbozza un Manifest a partire dalle Recipes del catalogo. L’area di lavoro non indica alcuna cartella di catalogo, quindi l’importazione legge il catalogo della libreria standard dal registry da cui scarica il proprio importer: uno snapshot firmato del catalogo pubblicato, scaricato, verificato e conservato nella cache dei contenuti dell’area di lavoro dalla prima importazione, e indicato tramite il suo digest nel registro che l’importazione scrive accanto alle proprie bozze. Un’area di lavoro che indica proprie cartelle di catalogo — in AGGREGA_CATALOG_DIRS, o sotto workspace.catalog_dirs — importa invece rispetto a quelle.
Il file delle risposte
Una build per Docker Compose non ha bisogno di nulla che il file Compose non dichiari, quindi questa importazione non chiede nulla. Una build dello stesso progetto per Kubernetes, con --target helm, ha bisogno di un valore che nessun file Compose contiene: il nome del Secret Kubernetes da cui viene letta la password del database, poiché una build Kubernetes legge una password da un Secret anziché dalla tua shell. L’esempio conserva questa risposta in import-answers.yaml, accanto a compose.yaml, dove l’importazione la cerca:
# 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"L’importazione ha scritto il file da sé, la prima volta che è stata eseguita con --target helm: ha elencato il valore che non poteva abbozzare, con la sua chiave vuota, e si è fermata. La risposta è il nome di un Secret, mai la password. L’importazione per Docker Compose non deve fornire alcun valore di questo tipo, conserva la risposta nel file e non la usa. Il file delle risposte dell’importazione descrive il file, le domande che un’importazione pone invece in un terminale e che cosa fa in assenza di entrambi.
aggrega import elenca ogni flag accettato dal comando, tra cui --answers, che indica un file delle risposte conservato altrove.
Entra in source:
cd sourceEseguire l’importazione
aggrega import compose.yaml --target composeSullo standard output elenca ciò che ha scritto:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonSullo standard error, dove <workspace> sta per la cartella in cui l’hai eseguita:
[… 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)
- Le righe
warnindicano ogni valore che le bozze riportano così come è scritto, tramite il suo servizio e la sua variabile e mai tramite il suo valore: Compose non contrassegna alcun valore come credenziale, e ognuno di essi potrebbe contenerne una. Qui nessuno dei due ne contiene. Le variabili che l’API legge da un altro servizio non sono affatto riportate come valori — le forniscono le connessioni — e le due che riportano${POSTGRES_PASSWORD}sono un riferimento a una variabile e nient’altro, quindi nessun avviso le nomina. - Le righe
mappeddicono che cosa è diventato ogni servizio.apiesegue un’immagine propria, quindi è un’istanza del server generico della libreria standard,core/compute/server.dbecacheeseguono le immagini che le Recipes Compose della libreria standard eseguono percore/datastore/postgresecore/datastore/redis; ciascuno ha corrisposto a quel Component nella fascia alta, con 0.9, e le bozze vi fanno riferimento. - La riga
Pull completeè l’import che recupera ciò da cui dipende la Release generata in bozza, come faaggrega pull, inrelease.lock, così che le bozze si validino e si compilino subito. Con--offlinel’import non recupera nulla e indica il comandoaggrega pullda eseguire.
Cosa scrive
L’Aggregate, la Release e il Manifest si chiamano imported/notes, dal name: del progetto Compose — un file Compose senza name: prende il nome dal suo file, compose, e la directory che lo contiene, importata come directory, da quella directory, così come Compose dà il nome a un progetto — nel namespace definito dall’impostazione target_namespace dell’importatore, imported a meno che tu non ne imposti un altro (Impostazioni).
aggregate.yaml — una voce per servizio, le connessioni da cui attinge l’ambiente dell’API, e i valori e le password che il file Compose imposta:
# 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/redisOgni variabile dell’API che nomina un altro servizio diventa il blocco inject di quella connessione: il file Compose impostava DATABASE_HOST su db, e la connessione fornisce con quel nome il valore host pubblicato dal database, così segue il database su qualsiasi target anziché essere copiato. DATABASE_USER e DATABASE_NAME corrispondevano all’utente e al database con cui viene creato il servizio PostgreSQL, quindi anch’essi vengono forniti a partire da ciò che questo pubblica, e quei due valori diventano i values propri del database. Ogni password diventa un allegato core/secret-value, dichiarato con la chiave con cui viene letta la sua variabile.
release.yaml — l’ambiente, l’immagine e la porta dell’API, la versione del motore di ogni datastore, e la provenienza di ogni password:
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"L’ambiente, development, è un valore predefinito che l’importazione scrive perché nessun file Compose ne indica uno; cambialo dove la Release viene distribuita altrove. I tag delle immagini diventano le versioni del motore che i Components della libreria standard accettano. Il port dell’API è la porta su cui il suo container è in ascolto, e published_port la porta dell’host che la sua voce ports pubblica, entrambe 8080 come le indica il file Compose; come dice il suo commento, qualsiasi processo su questa macchina raggiunge l’API su http://127.0.0.1:8080 e nient’altro può farlo, ed eliminando la riga la si mantiene solo sulla rete dello stack. Ciò che nessuna chiave accetta resta un commento sopra la sua voce: la voce ports della sorgente, che port e published_port già riportano, e il volume con nome del database.
manifest.yaml — la Recipe Compose di ogni tipo di componente, e la realizzazione che scrive nel file Compose il riferimento a variabile di una password così come è scritto:
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 registra, per digest, le entità del catalogo in cui la Release si è risolta, e .aggrega-import.json è il registro di ciò che l’importazione ha scritto, che un successivo aggrega import --sync legge.
Convalidare e compilare
aggrega validate --release release.yamlaggrega build --release release.yaml

La convalida stampa:
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)e la build, dove <workspace> indica la cartella in cui l’hai eseguita:
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>/distLa riga notice è solo informativa: la Feature della password accetta il suo origin dai values dell’Aggregate o da infra della Release, e l’avviso segnala che una foglia è dichiarata in entrambi. Non cambia alcun verdetto.
Il servizio api in dist/compose/docker-compose.yaml legge l’ambiente che il progetto Compose gli assegnava, fornito dalle connessioni e dall’allegato della password:
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]e il database e la cache eseguono le immagini indicate dal file Compose:
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]Due differenze rispetto al progetto di partenza sono visibili nel file generato. La porta è pubblicata solo sull’indirizzo di loopback, come la pubblica la Recipe Compose del server generico. E il volume con nome che il file Compose montava per i dati del database non compare da nessuna parte: la bozza lo elenca in un commento sopra la voce del database, nessuna chiave del Component PostgreSQL lo accetta, e il servizio del database generato non monta alcun volume.
Con un assistente AI
Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.
Usa solo gli strumenti di Aggrega e non creare alcuna cartella da solo. Se la cartella del Workspace non contiene ancora una cartella `import-compose`, chiama una volta lo strumento `scaffold` con `example` impostato su `import-compose` e senza `dir`: scrive l’esempio in una nuova cartella `import-compose`, la cui cartella `source` contiene ciò che questa pagina importa. Poi chiama lo strumento `import` con `workspace_root` impostato su `import-compose/source`, `source` impostato su `compose.yaml` e `target` impostato su `compose`: legge le risposte di cui ha bisogno da `import-answers.yaml` accanto a `compose.yaml`, scrive le sue bozze in `import-compose/source` e scarica ciò di cui hanno bisogno. Poi chiama lo strumento `validate` con `workspace_root` impostato su `import-compose/source` e `release` impostato su `release.yaml`, e lo strumento `build` con `workspace_root` impostato su `import-compose/source`, `release` impostato su `release.yaml` e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `import-compose/source/dist/`.Aprilo in VS Code
Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code la cartella import-compose/source, dove l’importazione ha scritto le sue bozze. La cartella contiene una sola Release, il release.yaml in bozza, quindi l’editor la seleziona per te e controlla le bozze rispetto a quella Release mentre le modifichi, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i suoi file in dist/ all’interno della cartella. Usare Aggrega in Visual Studio Code tratta il resto.
Esecuzione
ghcr.io/example/notes-api:2.3.0 rappresenta l’immagine della tua API. È un segnaposto, e Docker Compose si ferma su di esso con Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Indica l’immagine della tua API in infra.image di api in release.yaml. Finché la tua API non è pronta, può sostituirla un’immagine che risponde in HTTP sulla porta 8080. L’esecuzione qui sotto ha usato mendhak/http-https-echo:39, che risponde a ogni richiesta con una descrizione della richiesta ricevuta:
api: infra: image: "mendhak/http-https-echo:39" port: 8080Esegui di nuovo la build con la modifica. La Release non corrisponde più al release.lock scritto dall’importazione, quindi la build richiede --auto-pull, che la risolve di nuovo; senza, la build si ferma e indica aggrega pull. Docker Compose valorizza entrambi i riferimenti ${POSTGRES_PASSWORD} dalla tua shell, quindi imposta la password prima di avviare lo stack: se non è impostata, Compose avvisa The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. e scrive al suo posto un valore vuoto.
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 assegna il nome al progetto, come spiega il passo di esecuzione di Come si svolge un’importazione. --wait ritorna quando il database e la cache superano i controlli di integrità che la build assegna loro e il container dell’API è in esecuzione: la build non assegna all’API alcun controllo di integrità.
Eseguire il test
Interroga l’API su http://127.0.0.1:8080, l’indirizzo che published_port pubblica:
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]}Ciò che le connessioni consegnano si trova nell’ambiente del servizio dell’API, sotto i nomi che la tua API legge:
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOSTdbnotesnotescacheArresta lo stack con:
docker compose -p notes -f dist/compose/docker-compose.yaml downSu Kubernetes
Lo stesso progetto si importa per Kubernetes con --target helm, e l’importazione legge il nome del Secret, notes-db-password, dal file delle risposte visto sopra. Le bozze per Docker Compose si trovano già in source, quindi genera queste in una cartella a sé, indica l’immagine dell’API nel suo release.yaml come per Docker Compose ed esegui la build da lì:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pullLa build scrive semplici manifest Kubernetes in dist/helm/ alla radice del workspace, source, che da helm è ../dist/helm/. Crea il Secret notes-db-password nel namespace in cui applichi, con la password sotto la chiave di dati value, e applica la cartella come spiega il passo di esecuzione di Come si svolge un’importazione. Il Service dell’API è api-default: inoltra una porta locale verso di esso e lascia il comando in esecuzione:
kubectl port-forward -n <namespace> svc/api-default 8080:8080Da un altro terminale, la richiesta vista sopra raggiunge l’API allo stesso indirizzo, invariata, e l’immagine sostitutiva risponde allo stesso modo, "host": "127.0.0.1:8080". Le connessioni forniscono i nomi dei Service: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST stampa db-default, notes, notes e cache-default. Su Kubernetes l’API non riceve ancora la password del suo database: il Secret notes-db-password raggiunge soltanto il database, quindi DATABASE_PASSWORD non è impostata nel container api.
Quando il file Compose cambia
Conserva .aggrega-import.json accanto alle bozze e, dopo che il file Compose è cambiato, esegui:
aggrega import compose.yaml --syncIl comando modifica solo ciò che l’importazione ha scritto, e legge lo stesso file di risposte. Una parte che la sorgente non ha toccato resta com’è su disco, modificata o no; dove la sorgente ha cambiato una parte che hai modificato, si ferma, indica la parte e non scrive nulla, perché tu la riconcili a mano. aggrega import descrive per intero le regole e ogni flag.