跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

导入 Compose 项目

本演练导入一个小型 Compose 项目——一个 API、它用来保存笔记的 PostgreSQL 数据库以及一个 Redis 缓存——并为 Docker Compose 构建结果。导入会为构建所读取的每个文件生成草稿,并沿用 Compose 文件所陈述的内容:API 到数据库和缓存的连接、数据库的用户和名称、作为变量引用的密码,以及每个镜像的标签。下面的每个文件和每段输出都来自一次真实运行;该项目和演练的每个阶段都位于 import-compose 示例中,其中的检查脚本会再次运行导入,将它写入的内容、打印的内容以及本页引用的各段内容与保存在那里的文件进行比较,并验证和构建导入所写的内容。

生成示例

你可以使用本页的命令运行此导入,也可以让你的 AI 助手替你运行。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example import-compose

然后它会打印接下来要运行的命令。第一条命令进入新文件夹;其后的那条命令见下文,它进入新文件夹的 source 文件夹,该文件夹包含本页导入的内容,也是运行导入的位置:

Terminal window
cd import-compose

在 Visual Studio Code 中打开的已生成示例的 source 文件夹,显示其 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 会根据目录中的 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:

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 运行的镜像;它们各自以 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/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 所接受的引擎版本。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/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 接受来自 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.,并在其位置写入一个空值。

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 设置健康检查。

测试

在 published_port 所发布的地址 http://127.0.0.1:8080 上访问该 API:

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 上

同一个项目可以用 --target helm 导入为 Kubernetes 版本,导入会从上面的回答文件中读取 Secret 的名称 notes-db-password。面向 Docker Compose 的草稿已经位于 source 中,因此把这些草稿生成到单独的文件夹中,像 Docker Compose 那样在其 release.yaml 中写明 API 的镜像,然后从该文件夹构建:

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

构建会在工作区根目录 source 下的 dist/helm/ 中写入普通的 Kubernetes 清单,从 helm 来看即 ../dist/helm/。在你要应用到的命名空间中创建 Secret notes-db-password,在数据键 value 下保存密码,然后按 导入如何运行 中运行步骤的说明应用该文件夹。API 的 Service 是 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 只送达数据库,因此 api 容器中没有设置 DATABASE_PASSWORD。

当 Compose 文件发生变化时

将 .aggrega-import.json 保留在草稿旁边,并在 Compose 文件变化后运行:

Terminal window
aggrega import compose.yaml --sync

它只修改导入写入的内容,并读取同一个应答文件。源文件未改动的部分会保持磁盘上的现状,无论是否被编辑过;如果源文件修改了你编辑过的部分,它会停止、指明该部分且不写入任何内容,由你手动协调。aggrega import 完整描述了这些规则和每个标志。