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

Keycloak 栈——以模块形式组合的数据库支撑身份服务器

本示例将一个小型的真实栈——一个数据库支撑的身份 服务器——从一个由开发者编写的 Aggregate 编译为合成的 Kubernetes manifest。

身份服务器不是单个组件。它是一个模块:一个可复用的 子 aggregate,组合了两个单 workload 组件——

  • 一个服务器,在其 HTTP 端口上提供账户控制台和令牌端点, 不保存本地状态;以及
  • 一个后端,即 PostgreSQL,保存服务器的 realm、客户端和用户, 并将它们持久化到卷上。

模块自行连接从服务器到后端的内部边, 并将服务器导出为其公共端点 http。顶层 Aggregate 按名称导入该模块并渲染组合后的栈;运维人员在 Release 中 设定模块内部组件的规格。

文件

文件角色
aggregate.yaml开发者意图:导入身份服务器模块(core/keycloak)。
manifest-helm-synth.yaml将服务器和后端类型映射到各自的 synth helm Recipes,并将模块附加的凭据 Feature 映射到一个从模块凭据参数生成 Secret 的实现。
release-helm-synth.yamlKubernetes 目标的运维记录。按模块作用域 ID 为该模块的内部组件设定规格;留给 schema 默认值的部分以自包含方式渲染。

演示内容

  • 以模块形式组合。 一个多 workload 能力——实际上由服务器加配置数据库构成的身份 服务器——被打包为组合两个单 workload 组件的 子 aggregate,而不是一个单体 组件。该模块按名称导入,并在任何需要身份 服务器的地方复用。
  • 模块内部的内部边。 服务器声明对 后端的使用;后端 Recipe 的 provides 中的 host、port、user 和 database 被 传入服务器,并组合为其数据库连接。编译器 只路由这些字符串,而不解释它们。
  • 公共端点。 模块将其服务器导出为 http,即使用方连接的 稳定公共名称——与模块内部的 组件名称解耦。
  • 运维人员设定内部组件规格。 Release 通过模块作用域 ID(server.backend、 server.server)定位模块的 内部组件以设置计算资源,而开发者的 Aggregate 无需重复声明 物理规格。
  • 自迁移 schema。 服务器在启动时针对后端自行创建并迁移其 schema, 因此启动时 schema 已就绪,无需 单独的迁移步骤。
  • 按引用获取的共享凭据。 服务器向其 PostgreSQL 后端进行身份验证,因此两者共享同一个密码。模块将其作为 参数 db_password 接收,并用它两次附加 core/referenced-secret 凭据 Feature:一次附加到后端自身的凭据槽,一次 作为服务器到后端连接的 credential,即服务器 出示该密码的连接。每个 workload 都从 Secret 读取密码,而不是内联携带;引导管理员账户的 密码是第二个参数 admin_password。 由于模块附加了该 Feature,Manifest 需要映射它。本示例 将两个参数保留为模块的开发默认值,并将该 Feature 映射到 k8s-secret-from-parameter,它会生成携带每个 值的 Secret,因此该栈可以自包含运行。对于承载真实 流量的 Release,Aggregate 声明自己的参数,并通过 aggregates.server.parameters 向下传递,由 Release 提供这些参数,并由 Manifest 将该 Feature 映射到 k8s-existing-secret,它将每个 参数读作命名空间中已存在的 Secret 的名称。
  • 可复现的镜像。 服务器和后端都固定了明确的镜像 标签,因此渲染出的 manifest 引用稳定的镜像。

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

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

Terminal window
aggrega scaffold --example keycloak-stack

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd keycloak-stack

构建

此工作区不带 .aggrega-config.yaml,因此标准库实体从 hub 注册表 hub.aggrega.ai 解析,无需目录标志;--auto-pull 会在构建期间写入新克隆所缺少的锁文件:

Terminal window
aggrega build --release release-helm-synth.yaml --auto-pull

渲染产物输出到 dist/ 下。Kubernetes 目标离线渲染普通 manifest——无需拉取 chart。

借助 AI 助手

已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。

只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `keycloak-stack` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `keycloak-stack`,不设 `dir`:它会把示例写入一个新的 `keycloak-stack` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `keycloak-stack`、`release` 设为 `release-helm-synth.yaml`、`auto_pull` 设为 true、`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `keycloak-stack/dist/` 下。

组合后的栈是什么样子

服务器渲染为一个无状态 Deployment,外加一个监听 HTTP 端口的 ClusterIP Service。其容器携带由后端边组合而成的连接—— 后端的集群内 Service 名称、用户和数据库——以及 自包含的 HTTP 设置、已开启并在管理端口上提供的 健康端点,以及引导管理员账户,两个密码均从 Secret 读取:

env:
- name: KC_DB_PASSWORD
valueFrom:
secretKeyRef:
name: server-zdserver-db.credential
key: db-password
- name: KC_BOOTSTRAP_ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: server-zdserver-admin-password
key: admin-password
- name: KC_DB
value: postgres
- name: KC_DB_URL_HOST
value: server-zdbackend-default
- name: KC_DB_URL_PORT
value: "5432"
- name: KC_DB_URL_DATABASE
value: keycloak
- name: KC_DB_USERNAME
value: keycloak
- name: KC_HTTP_ENABLED
value: "true"
- name: KC_HOSTNAME_STRICT
value: "false"
- name: KC_HEALTH_ENABLED
value: "true"
- name: KC_HTTP_MANAGEMENT_PORT
value: "9000"
- name: KC_BOOTSTRAP_ADMIN_USERNAME
value: admin

容器在 HTTP 端口旁声明管理端口 9000, Deployment 在该端口上探测服务器:/health/started 上的启动探针在服务器启动期间 阻止其他探针执行,/health/ready 上的就绪探针 在服务器响应之前不让流量进入,/health/live 上的存活探针 在服务器停止响应时将其重启。Service 仍然只转发 HTTP 端口。

后端渲染为一个 StatefulSet,带有挂载在 /var/lib/postgresql/data 的持久卷,外加一个 ClusterIP Service 和一个 headless Service。其 POSTGRES_PASSWORD 从它自己的 Secret server-zdbackend-password 读取同一个数据库密码。这三个 Secret 与 workload 一同生成, 模块附加的每个凭据对应一个,各自携带模块的开发 默认值。