Импорт проекта Compose
Это пошаговое руководство импортирует небольшой проект Compose — API, базу данных PostgreSQL, в которой он хранит свои заметки, и кеш Redis — и собирает результат для Docker Compose. Импорт создаёт черновик каждого файла, который читает сборка, перенося то, что указано в файле Compose: соединения API с базой данных и кешем, пользователя и имя базы данных, пароль в виде ссылки на переменную и тег каждого образа. Каждый файл и каждый блок вывода ниже взяты из реального запуска; проект и каждый этап руководства находятся в примере import-compose, где скрипт проверки снова запускает импорт, сравнивает то, что он записывает, то, что он выводит, и блоки, которые цитирует эта страница, с хранящимися там файлами, а также проверяет и собирает то, что записал импорт.
Создание примера
Этот импорт можно выполнить командами с этой страницы или поручить его вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example import-composeЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку; следующая, ниже, переходит в её папку source, которая содержит то, что импортирует эта страница, и в которой выполняется импорт:
cd import-compose
Проект
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:Рядом с ним файл .aggrega-config.yaml делает папку рабочим пространством, поэтому импорт записывает свои черновики туда:
# 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Импорт сравнивает каждый сервис с сущностями Components каталога рабочего пространства, а --target создаёт черновик сущности Manifest из его сущностей Recipes. Рабочее пространство не указывает ни одной папки каталога, поэтому импорт читает каталог стандартной библиотеки из реестра, из которого получает свой импортер: подписанный снимок опубликованного каталога, который первый импорт получает, проверяет и сохраняет в кеше содержимого рабочего пространства и который назван по своему дайджесту в записи, которую импорт пишет рядом со своими черновиками. Рабочее пространство, которое указывает собственные папки каталога — в AGGREGA_CATALOG_DIRS или в workspace.catalog_dirs, — вместо этого импортирует относительно них.
Файл ответов
Сборке для Docker Compose не нужно ничего, чего не указывает файл Compose, поэтому этот импорт ни о чём не спрашивает. Сборке того же проекта для Kubernetes, с --target helm, нужно одно значение, которого нет ни в одном файле Compose: имя Secret в Kubernetes, из которого читается пароль базы данных, поскольку сборка для Kubernetes читает пароль из Secret, а не из вашей оболочки. Пример хранит этот ответ в import-answers.yaml, рядом с compose.yaml, где импорт его ищет:
# 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"Импорт сам записал этот файл, когда его впервые запустили с --target helm: он перечислил значение, которое не смог создать в черновике, с пустым ключом, и остановился. Ответ — это имя Secret, а не пароль. Импорту для Docker Compose такое значение не требуется: он сохраняет ответ в файле и не использует его. Файл ответов импорта описывает этот файл, вопросы, которые импорт вместо этого задаёт в терминале, и то, что он делает без того и другого.
aggrega import перечисляет все флаги, которые принимает команда, в том числе --answers, указывающий файл ответов, хранящийся в другом месте.
Перейдите в source:
cd sourceЗапуск импорта
aggrega import compose.yaml --target composeВ стандартный вывод он выводит список записанного:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonВ стандартный поток ошибок, где <workspace> обозначает папку, в которой вы его запустили:
[… 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)
- Строки
warnназывают каждое значение, которое черновики переносят в записанном виде, по его сервису и переменной и никогда по самому значению: Compose не помечает ни одно значение как учётные данные, и любое из них может их содержать. Здесь ни одно из двух не содержит. Переменные, которые API читает из другого сервиса, вообще не переносятся как значения — их передают соединения, — а две вида${POSTGRES_PASSWORD}— это лишь ссылка на переменную, поэтому ни одно предупреждение их не называет. - Строки
mappedсообщают, чем стал каждый сервис.apiзапускает собственный образ, поэтому он является экземпляром универсального сервера стандартной библиотеки,core/compute/server.dbиcacheзапускают те образы, которые Compose Recipes стандартной библиотеки запускают дляcore/datastore/postgresиcore/datastore/redis; каждый из них совпал с соответствующей сущностью Component на высоком уровне, с оценкой 0.9, и черновики ссылаются на неё. - Строка
Pull completeозначает, что импорт получает то, от чего зависит черновик сущности Release, как это делаетaggrega pull, вrelease.lock, чтобы черновики сразу проходили валидацию и сборку. С--offlineимпорт ничего не загружает и называет командуaggrega pull, которую следует выполнить.
Что он записывает
Сущности Aggregate, Release и Manifest получают имя imported/notes по name: проекта Compose — файл Compose без name: получает имя по своему файлу, compose, а содержащая его директория, импортированная как директория, получает имя по этой директории, так же как Compose называет проект — в пространстве имён, которое задаёт настройка target_namespace импортера, то есть imported, если вы не зададите другое (Настройки).
aggregate.yaml — по одной записи на сервис, соединения, из которых берёт значения окружение API, а также значения и пароли, которые задаёт файл 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/redisКаждая переменная API, которая называет другой сервис, становится блоком inject этого соединения: файл Compose задавал для DATABASE_HOST значение db, и соединение передаёт под этим именем опубликованный базой данных host, поэтому он следует за базой данных на любой цели, а не копируется. DATABASE_USER и DATABASE_NAME совпали с пользователем и базой данных, с которыми создаётся сервис PostgreSQL, поэтому они тоже передаются из того, что он публикует, а эти два значения становятся собственными values базы данных. Каждый пароль становится прикреплением core/secret-value, объявленным с ключом, под которым читается его переменная.
release.yaml — окружение, образ и порт API, версия движка каждого хранилища данных и откуда берётся каждый пароль:
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"Окружение, development, — это значение по умолчанию, которое записывает импорт, потому что ни один файл Compose его не называет; измените его там, где сущность Release развёртывается в другом месте. Теги образов становятся версиями движка, которые принимают сущности Components стандартной библиотеки. port API — это порт, который слушает его контейнер, а published_port — порт хоста, который публикует его запись ports; оба равны 8080, как их указывает файл Compose; как говорит его комментарий, любой процесс на этой машине достигает API по адресу http://127.0.0.1:8080, и ничто другое не может, а удаление строки оставляет API только в сети стека. То, что не принимает ни один ключ, остаётся комментарием над своей записью: запись ports из источника, которую уже несут port и published_port, и именованный том базы данных.
manifest.yaml — сущность Recipe для Compose каждого типа компонента и реализация, которая записывает ссылку на переменную пароля в файл Compose в записанном виде:
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 фиксирует по дайджесту сущности каталога, в которые разрешилась сущность Release, а .aggrega-import.json — это сведения о том, что записал импорт; их читает последующий aggrega import --sync.
Проверка и сборка
aggrega validate --release release.yamlaggrega build --release release.yaml

Проверка выводит:
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)и сборка, где <workspace> обозначает папку, в которой вы её запустили:
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Строка notice носит рекомендательный характер: сущность Feature для пароля принимает свой origin из values сущности Aggregate или из infra сущности Release, и уведомление сообщает, что один листовой узел объявлен в обоих местах. Оно не меняет ни одного вердикта.
Сервис api в dist/compose/docker-compose.yaml читает окружение, которое ему дал проект Compose, передаваемое соединениями и прикреплением пароля:
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]а база данных и кеш запускают образы, которые указал файл 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]Два отличия от исходного проекта видны в отрендеренном файле. Порт публикуется только на адресе loopback — так, как его публикует Compose Recipe универсального сервера. А именованный том, который файл Compose монтировал для данных базы данных, нигде не появляется: черновик перечисляет его в комментарии над записью базы данных, ни один ключ сущности Component PostgreSQL его не принимает, и отрендеренный сервис базы данных не монтирует ни одного тома.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используй только инструменты Aggrega и не создавай папки самостоятельно. Если папка Workspace ещё не содержит папку `import-compose`, один раз вызови инструмент `scaffold` с `example`, установленным в `import-compose`, и без `dir`: он записывает пример в новую папку `import-compose`, папка `source` которой содержит то, что импортирует эта страница. Затем вызови инструмент `import` с `workspace_root`, установленным в `import-compose/source`, `source`, установленным в `compose.yaml`, и `target`, установленным в `compose`: он читает нужные ответы из `import-answers.yaml` рядом с `compose.yaml`, записывает свои черновики в `import-compose/source` и загружает то, что им нужно. Затем вызови инструмент `validate` с `workspace_root`, установленным в `import-compose/source`, и `release`, установленным в `release.yaml`, и инструмент `build` с `workspace_root`, установленным в `import-compose/source`, `release`, установленным в `release.yaml`, и `write`, установленным в true. Сообщи мне, какие файлы записала сборка; они находятся в `import-compose/source/dist/`.Открытие в VS Code
Установив расширение Aggrega для Visual Studio Code, откройте в VS Code папку import-compose/source, в которую импорт записал свои черновики. Папка содержит одну сущность Release, черновик release.yaml, поэтому редактор сам выбирает её и при редактировании проверяет черновики относительно этой сущности Release, отмечая найденное в файле и на панели «Проблемы». Aggrega: Show topology graph в палитре команд рисует компоненты сущности Release и связи между ними. Aggrega: Build, Aggrega: Preview build и Aggrega: Pull действуют на ту же сущность Release, и каждая из них также является кнопкой на панели Commands представления Aggrega на панели действий; Build записывает свои файлы в dist/ папки. Остальное описано в разделе Использование Aggrega в Visual Studio Code.
Запуск
ghcr.io/example/notes-api:2.3.0 обозначает образ вашего собственного API. Это заполнитель, и Docker Compose останавливается на нём с Error Head "https://ghcr.io/v2/example/notes-api/manifests/2.3.0": denied. Укажите образ вашего API в infra.image для api в release.yaml. Пока ваш API не готов, его может заменить образ, отвечающий по HTTP на порту 8080. В запуске ниже использовался mendhak/http-https-echo:39, который отвечает на каждый запрос описанием полученного запроса:
api: infra: image: "mendhak/http-https-echo:39" port: 8080Выполните сборку ещё раз с этим изменением. Сущность Release больше не соответствует release.lock, который записал импорт, поэтому сборке нужен --auto-pull, который разрешает её заново; без него сборка останавливается и называет aggrega pull. Docker Compose заполняет обе ссылки ${POSTGRES_PASSWORD} из вашей оболочки, поэтому задайте пароль перед запуском стека: если он не задан, Compose выводит предупреждение The "POSTGRES_PASSWORD" variable is not set. Defaulting to a blank string. и записывает на его место пустое значение.
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 задаёт имя проекта, как объясняет шаг запуска в разделе Как выполняется импорт. --wait возвращает управление, как только база данных и кеш пройдут проверки работоспособности, которые им назначает сборка, а контейнер API будет запущен: сборка не назначает API никакой проверки работоспособности.
Тестирование
Обратитесь к API по адресу http://127.0.0.1:8080, который публикует 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]}То, что доставляют соединения, находится в окружении сервиса API, под именами, которые читает ваш API:
docker compose -p notes -f dist/compose/docker-compose.yaml exec api printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOSTdbnotesnotescacheОстановите стек командой:
docker compose -p notes -f dist/compose/docker-compose.yaml downВ Kubernetes
Тот же проект импортируется для Kubernetes с --target helm, и импорт читает имя Secret, notes-db-password, из приведённого выше файла ответов. Черновики для Docker Compose уже лежат в source, поэтому создайте эти черновики в отдельной папке, укажите образ API в её release.yaml, как для Docker Compose, и выполните сборку из неё:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pullСборка записывает обычные манифесты Kubernetes в dist/helm/ в корне рабочего пространства, source, что из helm соответствует ../dist/helm/. Создайте Secret notes-db-password в пространстве имён, в которое применяете, с паролем под ключом данных value, и примените папку, как объясняет шаг запуска в разделе Как выполняется импорт. Service API — это api-default: перенаправьте на него локальный порт и оставьте команду работать:
kubectl port-forward -n <namespace> svc/api-default 8080:8080Из другого терминала приведённый выше запрос достигает API по тому же адресу без изменений, и образ-заменитель отвечает так же, "host": "127.0.0.1:8080". Соединения передают имена объектов Service: kubectl exec -n <namespace> deploy/api -- printenv DATABASE_HOST DATABASE_USER DATABASE_NAME CACHE_HOST выводит db-default, notes, notes и cache-default. В Kubernetes API пока не получает пароль своей базы данных: Secret notes-db-password попадает только в базу данных, поэтому DATABASE_PASSWORD не задана в контейнере api.
Когда файл Compose меняется
Храните .aggrega-import.json рядом с черновиками, а после изменения файла Compose выполните:
aggrega import compose.yaml --syncКоманда меняет только то, что записал импорт, и читает тот же файл ответов. Часть, которую источник не трогал, остаётся на диске как есть, отредактирована она или нет; если источник изменил часть, которую вы отредактировали, команда останавливается, называет эту часть и ничего не записывает, чтобы вы согласовали её вручную. aggrega import полностью описывает правила и каждый флаг.