Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

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:

Terminal window
aggrega scaffold --example import-compose

Poi 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:

Terminal window
cd import-compose

La cartella source dell’esempio generato aperta in Visual Studio Code, che mostra il suo file Compose: l’API di un servizio di note, il suo database PostgreSQL e la sua cache Redis.

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.ai

L’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:

Terminal window
cd source

Eseguire l’importazione

Terminal window
aggrega import compose.yaml --target compose

Sullo standard output elenca ciò che ha scritto:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Sullo 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 empty
warn: 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 empty
mapped api (ghcr.io/example/notes-api) to core/compute/server as a reference, NONE
mapped db (postgres) to core/datastore/postgres as a reference, HIGH at 0.9
mapped cache (redis) to core/datastore/redis as a reference, HIGH at 0.9
Pull complete: <workspace>/release.lock (entities=10, source_artifacts=0, external_inputs=0)

L’importazione eseguita dall’editor: l’Aggregate, la Release e il Manifest in bozza compaiono accanto al file Compose, l’output di Aggrega elenca come è stato mappato ciascun servizio e i file scritti, e una notifica indica che l’importazione ha prodotto 3 file in bozza, riconosciuti come compose.

  • Le righe warn indicano 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 mapped dicono che cosa è diventato ogni servizio. api esegue un’immagine propria, quindi è un’istanza del server generico della libreria standard, core/compute/server. db e cache eseguono le immagini che le Recipes Compose della libreria standard eseguono per core/datastore/postgres e core/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 fa aggrega pull, in release.lock, così che le bozze si validino e si compilino subito. Con --offline l’import non recupera nulla e indica il comando aggrega pull da 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/v1beta1
kind: Aggregate
metadata:
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/redis

Ogni 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/v1beta1
kind: Release
metadata:
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/v1beta1
kind: Manifest
metadata:
name: imported/notes
version: 0.1.0
spec:
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-secret

release.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

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

La Release in bozza aperta nell’editor dopo averla validata, con l’output di Aggrega e una notifica che segnalano entrambi che non sono stati trovati problemi.

La build della Release in bozza: nell’Explorer compare una cartella dist, l’output di Aggrega elenca il file Docker Compose scritto e una notifica indica che è stato scritto 1 file.

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>/dist

La 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: 8080

Esegui 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.

Terminal window
aggrega build --release release.yaml --auto-pull
export 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:

Terminal window
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:

Terminal window
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST
db
notes
notes
cache

Arresta lo stack con:

Terminal window
docker compose -p notes -f dist/compose/docker-compose.yaml down

Su 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ì:

Terminal window
aggrega import compose.yaml --target helm --output-dir helm
cd helm
aggrega build --release release.yaml --auto-pull

La 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:

Terminal window
kubectl port-forward -n <namespace> svc/api-default 8080:8080

Da 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:

Terminal window
aggrega import compose.yaml --sync

Il 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.