凭据 Features
本页说明一个概念,即标准库中的凭据 Features 以及 Manifest 如何选择由什么来实现每一个,它并不是一个可运行的工作区。一个开发者意图,两种凭据交付形态针对同一凭据的两种实现构建同一个 Aggregate;可通过以下命令将其写入你自己的文件夹:
aggrega scaffold --example credential-shape-per-target然后它会打印接下来要运行的命令:
cd credential-shape-per-targetaggrega build --release release-local.yaml --auto-pullaggrega build --release release-store.yaml --auto-pull凭据填充 Component 在其 featuresSchema 中声明的槽位(参见 entities/component.md);槽位、填充它的 Feature 以及 Manifest 绑定的 FeatureRecipe 构成了从作者的附加项到运行中工作负载的完整路径。
凭据 Feature 家族
凭据 Feature 带有 feature.aggrega.ai/kind: secret 标签。该标签是描述附加项产出内容的目录元数据;没有任何编译器分支读取它,凭据 Feature 与其他 Feature 一样在 features: 下附加,由开发者在 Aggregate 中附加,或由运维人员在 Release 中附加。
标准库按实现对密钥所做的处理来划分凭据 Features:
core/secret-value将一个值交付到组件的注入管道,由该组件的 Recipe 在那里读取——一个 chart 值、一个环境变量。core/secret-provided同样产生一个值,但改为将其作为provides键发布,因此由附加项在透明槽位上自己的inject:块说明它的去向。core/referenced-secret指定一个密钥资源——一个 Kubernetes Secret、一个 AWS Secrets Manager 密钥、一个 Vault 条目——该资源由其实现创建或已经存在,并发布该资源的name和key,消费方以.features.<slot>.provides.name和.features.<slot>.provides.key读取它们。core/referenced-secret-set实体化一个这样的资源,其中包含作者提供的一组数据键,并且只发布其定位符,适用于目标已固定其读取的键名的消费方。Docker Compose 没有这样的资源,因此在那里它的实现改为以值的形式交付这些键,如下文所述。MariaDB(Bitnami chart)——一个多键凭据 Secret使用了它。core/generated-secret不产出任何内容:目标引擎自行生成并管理凭据,就像托管数据库对其管理员密码所做的那样。运维人员在 Release 中附加它,因为引擎是否拥有该凭据取决于 Manifest 选择的 Recipe;Terraform RDS(内联 HCL 制品) 就以这种方式绑定一个必需槽位。core/random-password渲染一个请求,让目标将密码生成到一个密钥资源中,并按照core/referenced-secret的方式发布该资源的定位符。没有人编写该凭据,渲染输出中也不包含它。
它们是对等的——相同的标签、相同的附加面、相同的槽位——因此槽位总是被填充,而在不同 Releases 之间变化的是由什么来填充它。声明了 provides 契约的凭据 Feature 要求实现它的每个 FeatureRecipe 都发布这些键,如果某个 FeatureRecipe 没有这样做,构建就会终止;正是这一点使消费方的读取是安全的。
core/random-password 需要目标上有某种机制来生成该值,因为构建从不这样做:在 Kubernetes 上是一个控制器(External Secrets Operator 或 kubernetes-secret-generator),由 Release 通过 infra.control_plane_present: true 确认其存在;在 Terraform 上是一个 random_password 资源;在 CloudFormation 上是一个自行生成字符串的 Secrets Manager 密钥。Docker Compose 没有提供任何实现,因此在其上绑定它的构建会终止。每个请求都会生成各自的值,因此两个组件要共享同一个生成的密码,需将其附加一次并固定 name,再在其他地方通过绑定到 helm/k8s-existing-secret 的 core/referenced-secret 读取它。
由谁指定凭据:values 或 infra,恰好其一
core/secret-value、core/secret-provided、core/referenced-secret 和 core/referenced-secret-set 接受来自任一作者的凭据定位符:开发者在 Aggregate 中将其写在附加项的 values 中,运维人员在 Release 中将其写在附加项的 infra 中。两者中的叶子相同——origin,对于集合则为 entries——每种实现都会读取携带它的那个支柱。
运维人员的写法使凭据能够用在开发者无法编写的地方:用在 Release 连接的连接上,以及用在仅由 Release 创建的附加项上,因为 Release 在任何地方都不写 values。
# Release: the operator wires the connection and names the secret.spec: components: router: uses: models: gpt: target: gpt features: credential: type: core/referenced-secret infra: origin: openai-team-a两者恰好其一。 每个支柱都是单独校验的,因此两个 schema 都无法要求定位符;这条规则改由每个 Feature 自身的 assertions 承担,定位符同时位于两个支柱中或都不在其中的附加项会使构建中止(E0033),并指出该 Feature、该附加项和组件。这是目录实体的契约:编译器像评估任何 Feature 的断言一样评估它们的断言。
其余一切都保留在各自的支柱中。 key 仍然是 values 的叶子,因此仅由 Release 创建的附加项读取默认数据键 value。在两个支柱中都声明 origin 正是支柱重叠提示所检查的内容,因此加载这些 Features 时会报告该提示——LINT: Feature "core/referenced-secret" ... declares property "origin" in both values: and infra: pillars。在这里,重叠就是契约;该提示不改变任何结论,也不改变渲染出的任何字节。
Manifest 选择实现
多个 FeatureRecipes 可以针对同一目标实现同一个 Feature,由 Manifest 进行选择。core/referenced-secret 在 Kubernetes 上有三个实现,凭据所在的位置决定选择哪一个:
helm/k8s-secret-from-parameter将作者提供的值写入它输出的 Secret,因此该材料位于渲染输出中:适用于评估和本地工作。helm/k8s-external-secret渲染一个ExternalSecret,指向密钥存储中的某个条目,由集群中的 External Secrets Operator 将其协调为 Secret。helm/k8s-existing-secret不输出任何内容:它将origin读取为一个已存在的 Secret 的名称,并按原样发布。
前两者以相同方式派生 Secret 的名称,即根据宿主的渲染名称和槽位的名称,因此消费方从任一者读取到相同的定位符,其渲染出的引用保持不变;这正是示例所展示的。第三者发布现有 Secret 自身的名称,因此绑定它会有意改变消费方的引用。
core/secret-value 在 Docker Compose 上由 compose/dotenv-secret 实现,它将值按编写的原样写入服务的环境:写成 ${DB_PASSWORD} 的 origin 会以该引用写入,Docker Compose 在栈启动时从你的 shell 或 .env 文件中填充它。在 Kubernetes 上,helm/env-secret 将值交付到注入管道,helm/k8s-secret-from-value 还会将其写入一个 Secret 并发布其定位符,供按引用读取凭据的消费方使用。两种 Kubernetes 实现都不接受 Compose 变量引用,因为那里没有任何东西会填充它。
core/referenced-secret 在 Docker Compose 上由 compose/dotenv-referenced-secret 实现。Compose 没有可供引用的 secret 资源,因此 origin 就是凭据本身,而不是某个 Secret 的名称:它以附加项的 key 为名交付到 inject 管道中,读取该槽位的 Compose Recipe 将其按编写的原样写入输出文件,因此写成 ${DB_PASSWORD} 的 origin 会以该引用写入。它不创建任何资源,因此它发布的名称为空,发布的键为 values.key。
core/referenced-secret-set 在 Docker Compose 上由 compose/dotenv-secret-set 实现,它将每个条目作为以其键命名的变量交付到 inject 管道中,并按编写的原样写入服务的环境,因此值为 ${GITHUB_TOKEN} 的条目会以该引用写入。它不创建任何资源,因此它发布的定位符为空:Compose 上的消费方从自己的 inject 管道读取这些条目,而不是按名称引用某个 Secret,正如 compose/mcp 和 compose/mcp-stdio-bridge 自 1.1.0 起对 Model Context Protocol 服务器的 server_env 所做的那样。
为多个目标提供的 FeatureRecipe 名称(如 provided-secret)在 Manifest 中需连同其目标一起书写,即 compose/provided-secret:1.0.0,因为不带前缀的名称会同时匹配两者。
一个名称,只发布一次
消费方的 Recipe 从不推导凭据所产生的 Secret 的名称:它读取凭据发布的定位符,existingSecret: "{{ .features.root_password.provides.name }}"。该名称只在 FeatureRecipe 的 provides 上编写一次,因此更改其组成方式只需在那一处编辑。凭据交付——secretKeyRef 端到端在 Kubernetes 上构建可引用的路径,在 Docker Compose 上构建注入的路径,共享凭据——按消费方、共享以及两者兼具展示了多个消费方各自持有自己的密钥或共享同一个密钥。