凭据交付——`secretKeyRef` 端到端示例
一个 PostgreSQL 数据库,其密码由凭据子系统提供,按 provider 分别展示。core/datastore/postgres 上的同一个 password 槽位接受任一凭据族;开发者附加的凭据族决定密码的交付方式,而数据库 Recipe 以其 provider 支持的方式读取该槽位。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example credential-secretkeyref然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd credential-secretkeyref构建
本示例包含三个 release。每次运行构建一个:
aggrega build --release release-helm.yaml --auto-pullaggrega build --release release-compose.yaml --auto-pullaggrega build --release release-negative.yaml --auto-pull # expected to fail (see below)每个 release 都通过此工作区的 .aggrega-config.yaml,从它指定为默认的 hub 注册表解析其目录实体,因此无需 --catalog 标志,--auto-pull 会在构建期间写入新克隆所缺少的锁文件。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `credential-secretkeyref` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `credential-secretkeyref`,且不设置 `dir`:它会把示例写入新的 `credential-secretkeyref` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具 — `release-helm.yaml`、`release-compose.yaml` — 每次都将 `workspace_root` 设为 `credential-secretkeyref`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。然后以同样的方式调用 `build` 工具,将 `release` 设为 `release-negative.yaml`:这次构建本应被拒绝,所以把拒绝信息读给我。告诉我每次构建写入了哪些文件;它们位于 `credential-secretkeyref/dist/` 下。Helm——可引用的 Secret + secretKeyRef
aggregate-helm.yaml 将 core/referenced-secret 附加到 password 槽位。Manifest 将其映射到 k8s-secret-from-parameter,后者生成一个 Kubernetes Secret,并以 provides {name, key} 的形式发布该 Secret 的标识。postgres 的 helm Recipe 通过 containers.attachments 引用该槽位,合成器将其渲染为 env secretKeyRef。
aggrega build --release release-helm.yaml --auto-pull生成的 Secret(dist/helm/helm/db--password--db-secret-db-password.yaml)与数据库的 secretKeyRef(dist/helm/helm/db-statefulset.yaml)指向同一个资源,因为两者都读取 .features.password.provides.name——不存在重新推导,也不需要两端共同遵守的约定:
[… omitted: the apiVersion and the Secret kind]metadata: name: db-password [… omitted: the labels and annotations every rendered document carries]stringData: POSTGRES_PASSWORD: "dev-pw-change-me"
# db-statefulset.yaml (container env)- name: POSTGRES_PASSWORD valueFrom: secretKeyRef: name: db-password # == the Secret's metadata.name key: POSTGRES_PASSWORD # == the Secret's data keyCompose——注入值凭据
aggregate-compose.yaml 附加 core/secret-value。Compose 没有 Secret 资源 / secretKeyRef 原语,因此 Manifest 将该凭据映射到 dotenv-secret,后者通过注入管道,以该附加项在 values.key 中指定的键(这里是 POSTGRES_PASSWORD)交付该值,postgres 的 compose Recipe 则以该键读取它。
aggrega build --release release-compose.yaml --auto-pull# dist/compose/compose/docker-compose.yaml → POSTGRES_PASSWORD: dev-pw-change-me反例——不可引用的填充值被引用拒绝
aggregate-negative.yaml 将注入值凭据 core/secret-value 附加到 password 槽位,然后在 helm 上构建,而其中 postgres Recipe 通过 containers.attachments(一个 secretKeyRef)引用该槽位。secretKeyRef 需要一个可指向的 Secret 资源,但注入值凭据不发布任何此类资源——因此构建会明确地中止:
aggrega build --release release-negative.yaml --auto-pull# [… omitted: the pull's lines, which carry the same halt, and two lint notices]# [CATALOG_ERROR E0212] instance db# rendering node "db"# [… omitted: the cause, "workload attachment slot is not referenceable", naming the Recipe and its path in your catalog, then one line each for the "name" and the "key" the slot's provides does not expose]此 release 预期会失败——中止本身就是要说明的内容。构建以 1 退出,而不是报告成功,因此读者和任何运行它的脚本都能看到这道防护。
有两种修复方法。附加一个可引用的凭据(core/referenced-secret),如 aggregate-helm.yaml 中所示;或者保留 core/secret-value 附加项,并在 Manifest 中将其映射到 k8s-secret-from-value,即 core/secret-value 的 Helm 实现,它将值写入其生成的一个 Secret,并发布该 Secret 的名称和键,使引用有可指向的资源。若绑定到 env-secret,注入值凭据则通过注入管道到达容器,绝不通过 containers.attachments 引用。