Перейти к содержимому
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 полностью описывает правила и каждый флаг.