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

同一个开发者意图,两种凭据交付形态

凭据如何到达运行中的容器,是部署位置的属性,而不是应用程序的属性。一个集群没有密钥存储,因此部署本身通过 Kubernetes Secret 携带凭据内容。另一个集群运行着密钥存储 operator,因此部署只携带一个指针,由集群在协调时获取凭据内容。

此工作区包含一个 Aggregate,并为两个目标构建它。两者之间 Aggregate 不变,数据库对其密码的引用也不变。变化的只是 Manifest 中的一行。

哪些会变,哪些保持不变

文件local 目标store 目标
aggregate.yaml同一个文件同一个文件
Manifestmanifest-local.yamlmanifest-store.yaml
Releaserelease-local.yamlrelease-store.yaml

两个 Manifests 的区别只在于各自的名称和一个映射条目:

Terminal window
$ diff manifest-local.yaml manifest-store.yaml
7c7
< name: credential-shape-local-manifest
---
> name: credential-shape-store-manifest
16c16
< 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:

Terminal window
$ diff release-local.yaml release-store.yaml
7c7
< name: credential-shape-local
---
> name: credential-shape-store
12c12
< 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-password

core/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: v1
kind: Secret
metadata:
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/v1
kind: ExternalSecret
metadata:
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/ 的命令):

Terminal window
$ diff -r local store
Only in store/helm/helm: db--app-zuuser-zupassword--db-externalsecret-db-app-user-password.yaml
Only in local/helm/helm: db--app-zuuser-zupassword--db-secret-db-app-user-password.yaml
Only in store/helm/helm: db--password--db-externalsecret-db-password.yaml
Only 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 助手替你构建。

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

Terminal window
aggrega scaffold --example credential-shape-per-target

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

Terminal window
cd credential-shape-per-target

构建

Terminal window
aggrega build --release release-local.yaml --auto-pull
aggrega build --release release-store.yaml --auto-pull

--auto-pull 在首次构建时将目录解析为 Release 旁边的 lockfile;之后构建同一 Release 无需该标志。

两个目标都写入 dist/,而 aggrega build 不会清空它,因此请将每次运行的输出另存,以便比较两者:

Terminal window
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:每个节点会渲染两次,若任一节点的两次渲染结果不同,构建即中止。

Terminal window
aggrega build --release release-local.yaml --verify-determinism
aggrega 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 的 db component,其两个凭据槽都由 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 目标上两者都会以明文渲染到输出中。