Importar un proyecto de Compose
Esta guía paso a paso importa un pequeño proyecto de Compose — una API, la base de datos PostgreSQL en la que guarda sus notas y una caché Redis — y construye el resultado para Docker Compose. La importación esboza cada archivo que lee la compilación, trasladando lo que indica el archivo Compose: las conexiones de la API a la base de datos y a la caché, el usuario y el nombre de la base de datos, la contraseña como referencia a una variable y la etiqueta de cada imagen. Cada archivo y cada bloque de salida que aparecen a continuación provienen de una ejecución real; el proyecto y cada etapa de la guía están en el ejemplo import-compose, donde un script de comprobación vuelve a ejecutar la importación, compara lo que escribe, lo que imprime y los bloques que cita esta página con los archivos guardados allí, y valida y construye lo que escribió la importación.
Generar el ejemplo
Puedes ejecutar esta importación con los comandos de esta página o pedir a tu asistente de IA que la ejecute por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example import-composeDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva; el siguiente, más abajo, entra en la carpeta source de la carpeta nueva, que contiene lo que esta página importa y es donde se ejecuta la importación:
cd import-compose
El proyecto
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:A su lado, un archivo .aggrega-config.yaml convierte la carpeta en un espacio de trabajo, de modo que la importación escribe allí sus borradores:
# 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.aiLa importación compara cada servicio con los Components del catálogo del espacio de trabajo, y --target esboza un Manifest a partir de las Recipes del catálogo. El espacio de trabajo no nombra ninguna carpeta de catálogo, así que la importación lee el catálogo de la biblioteca estándar del registro del que obtiene su importador: una instantánea firmada del catálogo publicado, que la primera importación obtiene, verifica y guarda en la caché de contenido del espacio de trabajo, y que se nombra por su digest en el archivo de registro que la importación escribe junto a sus borradores. Un espacio de trabajo que nombra sus propias carpetas de catálogo — en AGGREGA_CATALOG_DIRS o bajo workspace.catalog_dirs — importa frente a ellas en su lugar.
El archivo de respuestas
Una compilación para Docker Compose no necesita nada que el archivo de Compose no indique, así que esta importación no pregunta nada. Una compilación del mismo proyecto para Kubernetes, con --target helm, necesita un valor que ningún archivo de Compose contiene: el nombre del Secret de Kubernetes del que se lee la contraseña de la base de datos, ya que una compilación para Kubernetes lee una contraseña de un Secret en lugar de tu shell. El ejemplo guarda esa respuesta en import-answers.yaml, junto a compose.yaml, donde la importación la busca:
# 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"La importación escribió el archivo por sí misma la primera vez que se ejecutó con --target helm: listó el valor que no podía esbozar, con su clave vacía, y se detuvo. La respuesta es el nombre de un Secret, nunca la contraseña. La importación para Docker Compose no debe ningún valor de ese tipo, conserva la respuesta en el archivo y no la usa. El archivo de respuestas de la importación describe el archivo, las preguntas que una importación hace en su lugar en una terminal y lo que hace sin ninguno de los dos.
aggrega import enumera cada opción que admite el comando, entre ellas --answers, que nombra un archivo de respuestas guardado en otro lugar.
Entra en source:
cd sourceEjecutar la importación
aggrega import compose.yaml --target composeEn la salida estándar enumera lo que escribió:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonEn la salida de error estándar, donde <workspace> representa la carpeta en la que la ejecutaste:
[… 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)
- Las líneas
warnnombran cada valor que los borradores llevan tal como está escrito, por su servicio y su variable y nunca por su valor: Compose no marca ningún valor como credencial, y cualquiera de ellos podría contener una. Aquí ninguno de los dos la contiene. Las variables que la API lee de otro servicio no se llevan como valores en absoluto — las entregan las conexiones — y las dos que dicen${POSTGRES_PASSWORD}son una referencia a una variable y nada más, por lo que ninguna advertencia las nombra. - Las líneas
mappedindican en qué se convirtió cada servicio.apiejecuta una imagen propia, así que es una instancia del servidor genérico de la biblioteca estándar,core/compute/server.dbycacheejecutan las imágenes que las Recipes de Compose de la biblioteca estándar ejecutan paracore/datastore/postgresycore/datastore/redis; cada uno coincidió con ese Component en el nivel alto, con 0.9, y los borradores hacen referencia a él. - La línea
Pull completees la importación obteniendo aquello de lo que depende la Release redactada, como haceaggrega pull, enrelease.lock, para que los borradores se validen y se compilen de inmediato. Con--offline, la importación no obtiene nada e indica el comandoaggrega pullque hay que ejecutar.
Lo que escribe
El Aggregate, la Release y el Manifest se llaman imported/notes, por el name: del proyecto Compose — un archivo Compose sin name: recibe el nombre de su archivo, compose, y el directorio que lo contiene, importado como directorio, el de ese directorio, igual que Compose nombra un proyecto — bajo el namespace que fija el ajuste target_namespace del importador, imported salvo que fijes otro (Ajustes).
aggregate.yaml — una entrada por servicio, las conexiones de las que se nutre el entorno de la API, y los valores y las contraseñas que establece el archivo de Compose:
# 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/redisCada variable de la API que nombra otro servicio se convierte en el bloque inject de esa conexión: el archivo de Compose fijaba DATABASE_HOST en db, y la conexión entrega con ese nombre el host publicado de la base de datos, de modo que sigue a la base de datos en cualquier destino en lugar de copiarse. DATABASE_USER y DATABASE_NAME coincidían con el usuario y la base de datos con los que se crea el servicio de PostgreSQL, así que también se entregan a partir de lo que este publica, y esos dos valores pasan a ser los values propios de la base de datos. Cada contraseña se convierte en un adjunto core/secret-value, declarado con la clave bajo la que se lee su variable.
release.yaml — el entorno, la imagen y el puerto de la API, la versión del motor de cada almacén de datos y de dónde procede cada contraseña:
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"El entorno, development, es un valor predeterminado que la importación escribe porque ningún archivo de Compose nombra uno; cámbialo donde la Release se despliegue en otro lugar. Las etiquetas de imagen pasan a ser las versiones de motor que aceptan los Components de la biblioteca estándar. El port de la API es el puerto en el que escucha su contenedor, y published_port el puerto del host que publica su entrada ports, ambos 8080 tal como los indica el archivo de Compose; como dice su comentario, cualquier proceso de esta máquina llega a la API en http://127.0.0.1:8080 y nada más puede hacerlo, y al eliminar la línea se mantiene solo en la red del stack. Lo que ninguna clave acepta queda como comentario encima de su entrada: la entrada ports del origen, que port y published_port ya llevan, y el volumen con nombre de la base de datos.
manifest.yaml — la Recipe de Compose de cada tipo de componente, y la realización que escribe en el archivo de Compose, tal como está escrita, la referencia a variable de una contraseña:
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, por digest, las entidades del catálogo a las que se resolvió la Release, y .aggrega-import.json es el registro de lo que escribió la importación, que lee un aggrega import --sync posterior.
Validar y compilar
aggrega validate --release release.yamlaggrega build --release release.yaml

La validación imprime:
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)y la compilación, donde <workspace> representa la carpeta en la que la ejecutaste:
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 línea notice es solo informativa: la Feature de la contraseña acepta su origin desde los values del Aggregate o desde el infra de la Release, y el aviso indica que una hoja está declarada en ambos. No cambia ningún veredicto.
El servicio api en dist/compose/docker-compose.yaml lee el entorno que le daba el proyecto de Compose, entregado por las conexiones y el adjunto de la contraseña:
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]y la base de datos y la caché ejecutan las imágenes que nombraba el archivo de 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]Dos diferencias respecto al proyecto de partida se ven en el archivo renderizado. El puerto se publica solo en la dirección de loopback, como lo publica la Recipe de Compose del servidor genérico. Y el volumen con nombre que el archivo de Compose montaba para los datos de la base de datos no aparece en ninguna parte: el borrador lo enumera en un comentario encima de la entrada de la base de datos, ninguna clave del Component de PostgreSQL lo admite, y el servicio de base de datos renderizado no monta ningún volumen.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pega en él este prompt.
Usa solo las herramientas de Aggrega y no crees ninguna carpeta por tu cuenta. Si la carpeta del Workspace aún no contiene una carpeta `import-compose`, llama una vez a la herramienta `scaffold` con `example` establecido en `import-compose` y sin `dir`: escribe el ejemplo en una nueva carpeta `import-compose`, cuya carpeta `source` contiene lo que importa esta página. Después llama a la herramienta `import` con `workspace_root` establecido en `import-compose/source`, `source` establecido en `compose.yaml` y `target` establecido en `compose`: lee las respuestas que necesita de `import-answers.yaml`, junto a `compose.yaml`, escribe sus borradores en `import-compose/source` y descarga lo que estos necesitan. Después llama a la herramienta `validate` con `workspace_root` establecido en `import-compose/source` y `release` establecido en `release.yaml`, y a la herramienta `build` con `workspace_root` establecido en `import-compose/source`, `release` establecido en `release.yaml` y `write` establecido en true. Dime qué archivos escribió la compilación; están en `import-compose/source/dist/`.Ábrelo en VS Code
Con la extensión de Aggrega para Visual Studio Code instalada, abre en VS Code la carpeta import-compose/source, donde la importación escribió sus borradores. La carpeta contiene una sola Release, el release.yaml en borrador, así que el editor la selecciona por ti y comprueba los borradores con respecto a esa Release mientras los editas, marcando lo que encuentra en el archivo y en el panel Problemas. Aggrega: Show topology graph, en la paleta de comandos, dibuja los componentes de la Release y las conexiones entre ellos. Aggrega: Build, Aggrega: Preview build y Aggrega: Pull actúan sobre la misma Release, y cada uno es también un botón del panel Commands de la vista Aggrega en la barra de actividades; Build escribe sus archivos en el dist/ de la carpeta. Usar Aggrega en Visual Studio Code cubre el resto.
Ejecución
ghcr.io/example/notes-api:2.3.0 representa la imagen de tu propia API. Es un marcador de posición, y Docker Compose se detiene en él con Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Indica la imagen de tu API en infra.image de api en release.yaml. Hasta que tu API esté lista, una imagen que responda por HTTP en el puerto 8080 puede sustituirla. La ejecución siguiente usó mendhak/http-https-echo:39, que responde a cada solicitud con una descripción de la solicitud recibida:
api: infra: image: "mendhak/http-https-echo:39" port: 8080Vuelve a compilar con el cambio. La Release ya no coincide con el release.lock que escribió la importación, así que la compilación necesita --auto-pull, que la resuelve de nuevo; sin esa opción, la compilación se detiene y nombra aggrega pull. Docker Compose rellena las dos referencias ${POSTGRES_PASSWORD} desde tu shell, así que define la contraseña antes de iniciar la pila: si no está definida, Compose avisa The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. y escribe un valor vacío en su lugar.
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 nombra el proyecto, como explica el paso de ejecución de Cómo se ejecuta una importación. --wait regresa en cuanto la base de datos y la caché superan las comprobaciones de estado que la compilación les asigna y el contenedor de la API está en ejecución: la compilación no asigna ninguna comprobación de estado a la API.
Probarlo
Consulta la API en http://127.0.0.1:8080, la dirección que publica published_port:
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]}Lo que entregan las conexiones está en el entorno del servicio de la API, con los nombres que lee tu API:
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOSTdbnotesnotescacheDetén el stack con:
docker compose -p notes -f dist/compose/docker-compose.yaml downEn Kubernetes
El mismo proyecto se importa para Kubernetes con --target helm, y la importación lee el nombre del Secret, notes-db-password, del archivo de respuestas anterior. Los borradores para Docker Compose ya están en source, así que redacta estos en una carpeta propia, indica la imagen de la API en su release.yaml como para Docker Compose y compila desde ella:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pullLa compilación escribe manifiestos simples de Kubernetes en dist/helm/ en la raíz del workspace, source, que desde helm es ../dist/helm/. Crea el Secret notes-db-password en el namespace en el que aplicas, con la contraseña bajo la clave de datos value, y aplica la carpeta como explica el paso de ejecución de Cómo se ejecuta una importación. El Service de la API es api-default: reenvía un puerto local hacia él y deja el comando en ejecución:
kubectl port-forward -n <namespace> svc/api-default 8080:8080Desde otra terminal, la solicitud anterior llega a la API en la misma dirección, sin cambios, y la imagen sustituta responde de la misma manera, "host": "127.0.0.1:8080". Las conexiones entregan los nombres de los Services: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST imprime db-default, notes, notes y cache-default. En Kubernetes, la API todavía no recibe la contraseña de su base de datos: el Secret notes-db-password solo llega a la base de datos, así que DATABASE_PASSWORD no está definida en el contenedor api.
Cuando cambia el archivo de Compose
Conserva .aggrega-import.json junto a los borradores y, cuando cambie el archivo de Compose, ejecuta:
aggrega import compose.yaml --syncEl comando solo cambia lo que escribió la importación, y lee el mismo archivo de respuestas. Una parte que la fuente no tocó queda tal como está en el disco, editada o no; donde la fuente cambió una parte que editaste, se detiene, nombra la parte y no escribe nada, para que la concilies a mano. aggrega import describe por completo las reglas y cada opción.