Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Імпорт проєкту Compose

Цей покроковий посібник імпортує невеликий проєкт Compose — API, базу даних PostgreSQL, у якій він зберігає свої нотатки, і кеш Redis — і збирає результат для Docker Compose. Імпорт створює чернетку кожного файлу, який читає збірка, переносячи те, що зазначає файл Compose: з’єднання API з базою даних і кешем, користувача й назву бази даних, пароль як посилання на змінну і тег кожного образу. Кожен файл і кожен блок виводу нижче взято з реального запуску; проєкт і кожен етап посібника містяться в прикладі import-compose, де скрипт перевірки знову запускає імпорт, порівнює те, що він записує, те, що він виводить, і блоки, які цитує ця сторінка, з файлами, що там зберігаються, а також перевіряє і збирає те, що записав імпорт.

Створення прикладу

Цей імпорт можна виконати командами з цієї сторінки або доручити його вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

Terminal window
aggrega scaffold --example import-compose

Потім вона виводить команди, які слід виконати далі. Перша переходить у нову теку; наступна, нижче, переходить у її теку source, яка містить те, що імпортує ця сторінка, і де виконується імпорт:

Terminal window
cd import-compose

Тека source згенерованого прикладу, відкрита у Visual Studio Code, з її файлом Compose: API сервісу нотаток, його база даних PostgreSQL і його кеш Redis.

Проєкт

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:

Terminal window
cd source

Запуск імпорту

Terminal window
aggrega import compose.yaml --target compose

У стандартний вивід він виводить перелік записаного:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .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 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)

Імпорт, запущений з редактора: чернетки сутностей Aggregate, Release і Manifest з’являються поруч із файлом Compose, вивід Aggrega перелічує, як зіставлено кожен сервіс, і записані файли, а сповіщення повідомляє, що імпорт створив 3 чернетки файлів, розпізнані як compose.

  • Рядки 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/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

Кожна змінна API, що називає інший сервіс, стає блоком inject цього з’єднання: файл Compose задавав для DATABASE_HOST значення db, і з’єднання передає під цим іменем опублікований базою даних host, тож він слідує за базою даних на будь-якій цілі, а не копіюється. DATABASE_USER і DATABASE_NAME збіглися з користувачем і базою даних, з якими створюється сервіс PostgreSQL, тож їх також передають із того, що він публікує, а ці два значення стають власними values бази даних. Кожен пароль стає прикріпленням core/secret-value, оголошеним із ключем, під яким читається його змінна.

release.yaml — середовище, образ і порт API, версія рушія кожного сховища даних і звідки береться кожен пароль:

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"

Середовище, 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/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 фіксує за дайджестом сутності каталогу, до яких розв’язалася сутність Release, а .aggrega-import.json — це відомості про те, що записав імпорт; їх читає пізніший aggrega import --sync.

Перевірка та збирання

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

Чернетка сутності Release, відкрита в редакторі після валідації; вивід Aggrega і сповіщення обидва повідомляють, що проблем не знайдено.

Збірка чернетки сутності Release: у Провіднику з’являється тека dist, вивід Aggrega перелічує записаний файл Docker Compose, а сповіщення повідомляє, що записано 1 файл.

Перевірка виводить:

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. і записує замість нього порожнє значення.

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 задає назву проєкту, як пояснює крок запуску в розділі Як виконується імпорт. --wait повертає керування, щойно база даних і кеш пройдуть перевірки стану, які їм надає збірка, а контейнер API працюватиме: збірка не надає API жодної перевірки стану.

Тестування

Зверніться до API за адресою http://127.0.0.1:8080, яку публікує published_port:

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]
}

Те, що доставляють з’єднання, міститься в середовищі сервісу API, під назвами, які читає ваш API:

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

Зупиніть стек командою:

Terminal window
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, і виконайте збірку з неї:

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

Збірка записує звичайні маніфести Kubernetes у dist/helm/ у корені робочого простору, source, що з helm є ../dist/helm/. Створіть Secret notes-db-password у просторі імен, до якого застосовуєте, з паролем під ключем даних value, і застосуйте теку, як пояснює крок запуску в розділі Як виконується імпорт. Service API — це api-default: перенаправте на нього локальний порт і залиште команду працювати:

Terminal window
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 виконайте:

Terminal window
aggrega import compose.yaml --sync

Команда змінює лише те, що записав імпорт, і читає той самий файл відповідей. Частина, якої джерело не торкалося, залишається на диску такою, як є, відредагована чи ні; якщо джерело змінило частину, яку ви відредагували, команда зупиняється, називає цю частину й нічого не записує, щоб ви узгодили її вручну. aggrega import повністю описує правила та кожен прапорець.