Імпорт проєкту 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 повністю описує правила та кожен прапорець.