导入 Compose 项目
本演练导入一个小型 Compose 项目——一个 API、它用来保存笔记的 PostgreSQL 数据库以及一个 Redis 缓存——并为 Docker Compose 构建结果。导入会为构建所读取的每个文件生成草稿,并沿用 Compose 文件所陈述的内容:API 到数据库和缓存的连接、数据库的用户和名称、作为变量引用的密码,以及每个镜像的标签。下面的每个文件和每段输出都来自一次真实运行;该项目和演练的每个阶段都位于 import-compose 示例中,其中的检查脚本会再次运行导入,将它写入的内容、打印的内容以及本页引用的各段内容与保存在那里的文件进行比较,并验证和构建导入所写的内容。
生成示例
你可以使用本页的命令运行此导入,也可以让你的 AI 助手替你运行。
将示例写入一个以其命名的新文件夹:
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 会根据目录中的 Recipes 起草一个 Manifest。该工作区没有指定任何目录文件夹,因此导入会从它获取导入器的那个注册表中读取标准库目录:这是已发布目录的一个签名快照,由第一次导入获取、验证并保存在工作区的内容缓存中,并在导入写在其草稿旁的记录中以其摘要指明。指定了自己的目录文件夹的工作区——在 AGGREGA_CATALOG_DIRS 中,或在 workspace.catalog_dirs 下——则改为与这些文件夹比对导入。
答案文件
面向 Docker Compose 的构建不需要任何 Compose 文件未说明的内容,因此这次导入不询问任何问题。同一项目面向 Kubernetes 的构建(使用 --target helm)需要一个任何 Compose 文件都不包含的值:读取数据库密码所用的 Kubernetes Secret 的名称,因为 Kubernetes 构建从 Secret 而不是从你的 shell 中读取密码。该示例将这个答案保存在 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运行的镜像;它们各自以 0.9 的分数在高档位匹配了对应的 Component,草稿引用的正是该 Component。Pull complete这一行表示导入正在像aggrega pull那样,将草拟的 Release 所依赖的内容获取到release.lock中,使草稿可以立即通过验证并构建。在--offline下,导入不拉取任何内容,并给出需要运行的aggrega pull。
它写出的内容
该 Aggregate、Release 和 Manifest 命名为 imported/notes,取自 Compose 项目的 name:——没有 name: 的 Compose 文件按其文件命名,即 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/redisAPI 中每个指向另一个服务的变量都会成为该连接的 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 所接受的引擎版本。API 的 port 是其容器监听的端口,published_port 是其 ports 条目所发布的主机端口,二者都是 Compose 文件所写的 8080;如其注释所说,这台机器上的任何进程都可以通过 http://127.0.0.1:8080 访问该 API,其他任何东西都不能,删除这一行则让它只留在该栈的网络上。没有任何键接受的内容会作为注释保留在其条目上方:源文件的 ports 条目(port 和 published_port 已经承载了它),以及数据库的命名卷。
manifest.yaml — 每种组件类型的 Compose Recipe,以及将密码的变量引用按原样写入 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>/distnotice 行仅供参考:密码 Feature 接受来自 Aggregate 的 values 或 Release 的 infra 的 origin,该通知报告有一个叶子在两处都有声明。它不改变任何裁决结果。
dist/compose/docker-compose.yaml 中的 api 服务读取 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]与最初的项目相比,有两处差异体现在渲染出的文件中。端口只在回环地址上发布,这正是通用服务器的 Compose Recipe 的发布方式。此外,Compose 文件为数据库数据挂载的命名卷没有出现在任何地方:草稿在数据库条目上方的注释中列出了它,PostgreSQL Component 没有任何键接受它,因此渲染出的数据库服务不挂载任何卷。
借助 AI 助手
配置了 Aggrega 工具的 AI 助手也可以完成同样的操作:将下面的提示词粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `import-compose` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `import-compose`,且不设 `dir`:它会把示例写入一个新的 `import-compose` 文件夹,其中的 `source` 文件夹包含本页导入的内容。然后调用 `import` 工具,将 `workspace_root` 设为 `import-compose/source`,`source` 设为 `compose.yaml`,`target` 设为 `compose`:它会从 `compose.yaml` 旁边的 `import-answers.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,并且每一个也是活动栏中 Aggrega 视图的 Commands 面板上的一个按钮;Build 把文件写入该文件夹的 dist/。其余内容见 在 Visual Studio Code 中使用 Aggrega。
运行
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。请在 release.yaml 中 api 的 infra.image 里填写你的 API 的镜像。在你的 API 就绪之前,可以用一个在 8080 端口上响应 HTTP 的镜像代替它。下面的运行使用了 mendhak/http-https-echo:39,它会对每个请求返回所收到请求的描述:
api: infra: image: "mendhak/http-https-echo:39" port: 8080带着这项修改重新构建。该 Release 不再与导入写入的 release.lock 相符,因此构建需要 --auto-pull 来重新解析它;没有该选项时,构建会停止并指明 aggrega pull。Docker Compose 会从你的 shell 中填充两处 ${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 设置健康检查。
测试
在 published_port 所发布的地址 http://127.0.0.1:8080 上访问该 API:
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 上
同一个项目可以用 --target helm 导入为 Kubernetes 版本,导入会从上面的回答文件中读取 Secret 的名称 notes-db-password。面向 Docker Compose 的草稿已经位于 source 中,因此把这些草稿生成到单独的文件夹中,像 Docker Compose 那样在其 release.yaml 中写明 API 的镜像,然后从该文件夹构建:
aggrega import compose.yaml --target helm --output-dir helmcd helmaggrega build --release release.yaml --auto-pull构建会在工作区根目录 source 下的 dist/helm/ 中写入普通的 Kubernetes 清单,从 helm 来看即 ../dist/helm/。在你要应用到的命名空间中创建 Secret notes-db-password,在数据键 value 下保存密码,然后按 导入如何运行 中运行步骤的说明应用该文件夹。API 的 Service 是 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 只送达数据库,因此 api 容器中没有设置 DATABASE_PASSWORD。
当 Compose 文件发生变化时
将 .aggrega-import.json 保留在草稿旁边,并在 Compose 文件变化后运行:
aggrega import compose.yaml --sync它只修改导入写入的内容,并读取同一个应答文件。源文件未改动的部分会保持磁盘上的现状,无论是否被编辑过;如果源文件修改了你编辑过的部分,它会停止、指明该部分且不写入任何内容,由你手动协调。aggrega import 完整描述了这些规则和每个标志。