构建的文件
本页讲解一个概念,即构建中的哪个文件说明什么,它不是一个可运行的工作区。带 PostgreSQL 的 Web 应用,逐步搭建在一个由你构建的工作区中展示了这一点;用以下命令将其写入你自己的文件夹:
aggrega scaffold --example quickstart-web然后它会打印接下来要运行的命令:
cd quickstart-webcd 1aggrega build --release release.yaml --auto-pullexport QUICKSTART_DB_PASSWORD=choose-a-passworddocker compose -p quickstart-web -f dist/compose/docker-compose.yaml up -d --wait# then open http://127.0.0.1:8080/ in your browser五种文件,各有一位作者
一次构建读取五种文件。每种文件只说明一件事,在典型的团队中,每种文件都有自己的作者:
- 一个 Component 说明一种组件是什么:开发者可以设置的值、运维人员可以设置的基础设施设置、它向连接到它的组件发布的内容,以及它用来连接的插槽。标准库目录提供了大多数应用所需的 Components,例如
core/datastore/postgres和core/compute/server,因此工作区通常一个也不用编写; - 一个 Aggregate 属于开发者:应用有哪些组件,以及每个组件连接到什么;
- 一个 Recipe 将一种组件转换为某个工具的文件——一个 Compose 服务、一个 Helm chart、一个 Terraform 模块;
- 一个 Manifest 为某个目标选择由哪个 Recipe 实现每种组件;
- 一个 Release 指定一个 Aggregate 和一个 Manifest,并给出某个环境的设置。它就是你构建的对象:
aggrega build --release release.yaml。
这种划分只是指导:一个人可以编写全部五种文件,只要每个文件都有效,构建就会接受其中任何一个。
Aggregate:组件及其连接
示例的第一步是一个 Web 应用及其数据库。它的 Aggregate,取自 1/aggregate.yaml,省略了注释:
spec: components: web: type: core/compute/server features: db_password: type: core/secret-value values: key: PGPASSWORD origin: "${QUICKSTART_DB_PASSWORD}" uses: database: db: target: db inject: env: - in: PGHOST from: host - in: PGPORT from: port - in: PGUSER from: user - in: PGDATABASE from: database
db: type: core/datastore/postgres features: password: type: core/secret-value values: key: POSTGRES_PASSWORD origin: "${QUICKSTART_DB_PASSWORD}"这里没有指定任何端口、主机、命名空间或工具。web 通过它的 database 插槽连接到 db,inject 列表说明应用的哪个变量接收数据库发布的每个条目:from: 指定条目,in: 指定变量。
连接是一个经管道传递的字符串
数据库的 Recipe 发布 host、port、user 和 database,供连接读取。host 持有哪个地址取决于 Manifest 选择的 Recipe:数据库与应用一起运行时是一个服务名称,对于托管数据库是一个由预配工具解析的指针字符串,或者是一个已存在的服务器的地址。构建将每个发布的字符串复制到 Aggregate 指定的变量中,并且不解释它:它从不解析地址,也从不检查地址是否可达。
Manifest 与 Release
Manifest 取自 1/manifest.yaml,它将每种组件以及密码附件绑定到在 Docker Compose 上实现它的 Recipe:
spec: mappings: components: type: core/compute/server:1.1.0: compose/server:2.0.0 core/datastore/postgres:1.0.0: compose/postgres:1.0.0 features: type: core/secret-value:1.0.0: compose/dotenv-secret:1.0.0Release 取自 1/release.yaml,它指定 Aggregate 和 Manifest,并给出只有环境才知道的内容,这里是应用运行的镜像、它监听的端口,以及 Docker Compose 在你机器的回环地址上发布它所用的端口(镜像摘要已缩短):
spec: aggregate: quickstart-web manifest: quickstart-web-compose components: web: infra: image: hub.aggrega.ai/tools/quickstart-web:1.1.0@sha256:… port: 8080 published_port: 8080 db: {}示例的后续步骤会扩展它:在数据库旁加入一个 Redis 缓存,然后通过 Terraform 将相同的组件部署到 AWS 上,再加入数据库的备份。
参数:一个 Aggregate,多个环境
在不同环境之间有差异的值,在 Aggregate 中声明为带类型的参数,在使用处引用,并由每个 Release 给出。在按需运行的任务中,Aggregate 声明了其报告的调度计划:
spec: parameters: report_schedule: type: string default: "" components: report: type: core/compute/task values: schedule: "{{ .parameters.report_schedule }}"而一个 Release 满足它:
spec: parameters: report_schedule: "30 2 * * 1-5"构建在填充模板之前,会根据参数的类型检查 Release 给出的每个值。Release 从不自行编写组件的 values:它满足 Aggregate 暴露的参数,因此 Aggregate 始终是说明哪些值随环境变化的唯一位置。Release 也可以从参数专用的文件中读取参数:parameters: { $import: ./env/prod-values.yaml }。