同一个开发者意图,两种凭据交付形态
凭据如何到达运行中的容器,是部署位置的属性,而不是应用程序的属性。一个集群没有密钥存储,因此部署本身通过 Kubernetes Secret 携带凭据内容。另一个集群运行着密钥存储 operator,因此部署只携带一个指针,由集群在协调时获取凭据内容。
此工作区包含一个 Aggregate,并为两个目标构建它。两者之间 Aggregate 不变,数据库对其密码的引用也不变。变化的只是 Manifest 中的一行。
哪些会变,哪些保持不变
| 文件 | local 目标 | store 目标 |
|---|---|---|
aggregate.yaml | 同一个文件 | 同一个文件 |
| Manifest | manifest-local.yaml | manifest-store.yaml |
| Release | release-local.yaml | release-store.yaml |
两个 Manifests 的区别只在于各自的名称和一个映射条目:
$ diff manifest-local.yaml manifest-store.yaml7c7< name: credential-shape-local-manifest---> name: credential-shape-store-manifest16c16< core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0---> core/referenced-secret:1.0.0: helm/k8s-external-secret:1.0.0两个 Releases 的区别只在于各自的名称和所指向的 Manifest:
$ diff release-local.yaml release-store.yaml7c7< name: credential-shape-local---> name: credential-shape-store12c12< manifest: credential-shape-local-manifest---> manifest: credential-shape-store-manifest两个 Releases 声明了相同的 environment。这是有意为之:环境名称会作为标签写入每个渲染出的文档,因此保持它不变,就只留下一处可以变化的地方——Manifest 所绑定的 FeatureRecipe。当然,真实的一对 Releases 会各自命名自己的环境,而凭据形态的差异与此完全相同。
开发者一侧,只写一次
aggregate.yaml 用同一个可引用的凭据 Feature 填充 PostgreSQL Component 的两个凭据槽:
features: password: type: core/referenced-secret values: key: POSTGRES_PASSWORD origin: postgres-superuser-password app_user_password: type: core/referenced-secret values: key: APP_USER_PASSWORD origin: postgres-app-passwordcore/referenced-secret 指定一个密钥资源(由其 FeatureRecipe 的输出创建,或者已经存在),并通过其 provides 契约发布该资源的定位信息——其 name 以及其中的数据 key。消费方 Recipe 读取该定位信息。它从不自行推导资源名称,也从不询问是哪个 FeatureRecipe 生成了它。
每个目标输出什么
每次构建写出六个文件。其中四个——StatefulSet、两个 Service 和初始化 ConfigMap——在两个目标中逐字节相同。另外两个是凭据资源,每个已填充的槽一个,目标之间的差异就在这里。
local 目标,来自 k8s-secret-from-parameter,位于
dist/helm/helm/db--password--db-secret-db-password.yaml:
apiVersion: v1kind: Secretmetadata: name: db-password [… omitted: the labels and annotations naming the aggregate, component, environment, compiler and provider versions, boundary and Recipe — the same set every rendered document carries]stringData: POSTGRES_PASSWORD: "postgres-superuser-password"store 目标,来自 k8s-external-secret,位于
dist/helm/helm/db--password--db-externalsecret-db-password.yaml:
apiVersion: external-secrets.io/v1kind: ExternalSecretmetadata: name: db-password [… omitted: the same label and annotation set as above]spec: refreshInterval: "1h" secretStoreRef: name: platform-secret-store kind: ClusterSecretStore target: name: db-password creationPolicy: Owner data: - secretKey: POSTGRES_PASSWORD remoteRef: key: "postgres-superuser-password"API 组不同,kind 不同,内容也不同。在 local 目标上,凭据内容就在渲染出的文档中,任何能读取该部署的人都能读到——因此这种形态适合本地和开发集群,而不适合生产集群。在 store 目标上,渲染出的文档只携带条目名称;凭据内容保留在存储中,由 operator 将其协调为名为 db-password 的 Secret。
比较两个输出目录树,可以看到差异所在以及差异止于何处(下方“构建”一节给出了生成 local/ 和 store/ 的命令):
$ diff -r local storeOnly in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yamlOnly in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yamlOnly in store/helm/helm: db--password--db-externalsecret-db-password.yamlOnly in local/helm/helm: db--password--db-secret-db-password.yaml四行,全部位于同一目录,因为在此目标上,附件的文件与 component 自身的文件并列存放,而不是放在子目录中。文件名承载了两个坐标:db--password-- 是 db 上的 password 附件,db--app-zuuser-zupassword-- 是 app_user_password 附件——下划线被编码为 -zu,因为这里坐标和文件自身的名称共用一个字符串。
四行,别无其他:两个凭据资源只存在于 local 目标的目录树中,两个只存在于 store 目标的目录树中。diff -r 报告两个目录树共有的文件内容没有任何差异,因此这四个共同文档是完全相同的,而不仅仅是相似。
不会变化的引用
数据库容器将两个凭据读取为由 secretKeyRef 支持的环境变量。该代码块在两个目标中逐字节相同:
- name: POSTGRES_PASSWORD valueFrom: secretKeyRef: name: db-password key: POSTGRES_PASSWORD- name: APP_USER_PASSWORD valueFrom: secretKeyRef: name: db-app-user-password key: APP_USER_PASSWORD它之所以相同,是因为消费方 Recipe 不做分支。它向槽请求已发布的 name 和 key,并将其写出。两个 FeatureRecipes 发布相同的两个键,因为 Feature 声明了它们,所以任意一个都能满足消费方——在 store 目标上,一旦 operator 将 ExternalSecret 协调为该名称下的 Secret,引用即可解析。
正是这种不变性使两种形态可以互换。 如果消费方自行推导 Secret 名称,替换绑定后它就会指向一个在该名称下已不存在的资源。
origin 的含义由 FeatureRecipe 决定
core/referenced-secret 将 origin 声明为凭据内容的来源,并把其解释交给 FeatureRecipe:
k8s-secret-from-parameter将其作为凭据内容写入 Secret。k8s-external-secret将其读取为要从存储中获取的键。
编译器原样传递该字符串;它与给定字符串属于哪一种含义无关。正因如此,一个附件无需开发者一侧做任何修改即可服务两种形态——这也是替换绑定之前需要检查的地方,因为同一个编写的字符串必须对读取它的那个 FeatureRecipe 有意义。
发布的名称,以及槽名称中的下划线
该 Component 将其第二个凭据槽命名为 app_user_password。Kubernetes 对象名称不能包含下划线,因此发布的 provides.name 会将下划线规范化为连字符,资源最终名为 db-app-user-password:
- name: APP_USER_PASSWORD valueFrom: secretKeyRef: name: db-app-user-password两个 FeatureRecipes 的规范化方式完全相同,因此替换绑定不会改变消费方的引用。名称只在生产方发布一次,输出的资源和消费方的引用都从这一个发布值解析。
store 目标对集群的要求
ExternalSecret 是一种自定义资源。将 store 目标的输出应用到集群,需要集群中运行着密钥存储 operator,并且存在一个名为 platform-secret-store 的 ClusterSecretStore。此工作区不安装其中任何一个:本示例渲染的是此类集群所使用的内容,并说明如何选择形态。
集群运行哪种存储、使用什么名称,是目标的属性而非应用程序的属性,因此 k8s-external-secret 没有为此提供编写键。存储名称不同的集群,由指定该存储名称的 FeatureRecipe 来服务。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example credential-shape-per-target然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd credential-shape-per-target构建
aggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pull--auto-pull 在首次构建时将目录解析为 Release 旁边的 lockfile;之后构建同一 Release 无需该标志。
两个目标都写入 dist/,而 aggrega build 不会清空它,因此请将每次运行的输出另存,以便比较两者:
out=$(mktemp -d)rm -rf dist && aggrega build --release release-local.yaml --auto-pull && cp -r dist "$out/local"rm -rf dist && aggrega build --release release-store.yaml --auto-pull && cp -r dist "$out/store"( cd "$out" && diff -r local store )要确认每个目标的渲染是确定性的,请添加 --verify-determinism:每个节点会渲染两次,若任一节点的两次渲染结果不同,构建即中止。
aggrega build --release release-local.yaml --verify-determinismaggrega build --release release-store.yaml --verify-determinism借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `credential-shape-per-target` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `credential-shape-per-target`,且不设置 `dir`:它会把示例写入新的 `credential-shape-per-target` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具 — `release-local.yaml`、`release-store.yaml` — 每次都将 `workspace_root` 设为 `credential-shape-per-target`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `credential-shape-per-target/dist/` 下。文件
aggregate.yaml—— 开发者意图:一个类型为core/datastore/postgres的dbcomponent,其两个凭据槽都由core/referenced-secret填充。两个 Releases 都原样使用它。manifest-local.yaml—— 将core/referenced-secret绑定到k8s-secret-from-parameter,后者根据编写的凭据内容渲染一个 Kubernetes Secret。manifest-store.yaml—— 将同一个 Feature 绑定到k8s-external-secret,后者 渲染一个指定存储条目的 ExternalSecret。除自身名称和那一行外,与manifest-local.yaml完全相同。release-local.yaml、release-store.yaml—— 两个 Releases。除各自名称 和各自指向的 Manifest 外完全相同。.aggrega-config.yaml— 指定目录实体从中解析的 hub 注册表。
这里的 origin 值是占位符。它们不是任何真实服务的凭据,并且在 local 目标上两者都会以明文渲染到输出中。