凭据模型
同一个附加族
在 Aggrega 中,凭据是一个 Feature。它与其他任何 Feature 一样,在同一个位置、使用同一个关键字、以同一种结构附加。下例中,开发者在 Aggregate 中附加数据库的凭据,并在 values 中写入其定位符:
# the Aggregate — its parameters and the components' own values left outspec: components: api: type: core/compute/server db: type: core/datastore/mariadb features: root_password: # a credential Feature type: core/secret-value:1.0.0 values: key: MARIADB_ROOT_PASSWORD origin: "{{ .parameters.db_root_pass }}"而运维人员在 Release 中为服务器附加一个指标抓取目标,因为 core/prometheus-exporter 接受的每一项输入(抓取的端口、路径和间隔)都属于运维范畴,所以写在 infra 中:
# the Release — the api's own infra and the db's entry left outspec: components: api: features: metrics: # an operational Feature type: core/prometheus-exporter:1.0.0 infra: port: http # the named port of the api's Service只有一个附加关键字(features:)、一种渲染上下文结构(.features.<name>;对于写在连接上的附加,则是连接下的同一结构 .context.uses.<alias>.features.<slot>)、一种执行顺序,以及一套输出坐标:对于组件上的附加,坐标依次是它所附加的组件和它附加时使用的名称,无论目标的布局是将这两者表示为与组件自身目录并列的 <component>--<instance>/ 目录,还是表示为 <component>--<instance>-- 文件名前缀。各个附加之间的差异在于它们产生什么(注入的值、可引用的资源、边车容器、云身份),而不在于声明它们的位置。
凭据 Feature 在其目录实体上带有标签 feature.aggrega.ai/kind: secret。该标签是描述性元数据:它告诉读者、目录站点和标签选择器这个 Feature 的用途。编译器中没有任何分支读取它,也没有任何行为取决于它。行为来自运维人员将该 Feature 类型映射到的 FeatureRecipe。
一句话概括的心智模型:附加只有一种;变化的是它产生什么。
槽位与自由附加
Component 或 Feature 可以在 featuresSchema 中声明槽位:
spec: featuresSchema: root_password: required: true inject: [] # blackbox — the Recipe delivers it selector: "feature.aggrega.ai/kind=secret" user_password: inject: [env, file] # transparent — the developer may dictate delivery实例名与某个已声明槽位相同的附加会填充该槽位。以其他任何名称进行的附加是自由附加:实体并未请求它,它与实体所请求的内容一同渲染。为已声明槽位生成的 schema 保持开放,因此声明一个槽位永远不会使该块拒绝自由附加。有一种情形会中止而非渲染:直接写在组件上的附加,其 Feature 满足某个在该处无任何绑定的槽位的 selector,这是一个写错了名称的填充,而不是自由附加。
槽位可以约束两项内容:
inject——Workload 可以为填充该槽位的内容选择的交付机制。空列表表示黑盒槽位:由 Recipe 自身的管线交付它(例如 chart 的existingSecret选项),Workload 不能在容器中引用它。selector——一个标签选择器字符串,填充该槽位的 Feature 的标签必须满足它。kind=secret标签正是在这里发挥作用:希望槽位只由凭据填充的实体作者用选择器表明这一点,而该检查是编译器在静态分析期间执行的一次标签集求值。
槽位可以做的第三件事是要求自己最终被绑定。required: true 使该槽位名称成为必需:当没有任何附加绑定它时,编译器会在静态分析期间中止,并给出指明该槽位及声明它的组件类型的诊断。该要求是针对所有作用域级联完成后组件最终拥有的附加集合来判断的,因此在组件之上的作用域中提供的附加,与直接写在组件上的填充一样能绑定该槽位。
另一个声明面表达的是另一种要求。可重复的 Component 注解 features.aggrega.ai/requiredType.<label> 声明一项存在性要求:至少有一个附加必须带有该注解所指定的 Feature 类型,名称和作用域不限;没有任何附加满足的要求会在同一静态分析期间中止,并给出其自身的诊断。两者永远不能互相替代——槽位问的是某个具名绑定点是否已绑定,存在性要求问的是是否有某个附加带有指定类型——因此需要其 Recipe 读取所附加内容的实体应声明槽位,而其契约仅要求某项能力存在的实体则应声明存在性要求。
编译器保证什么、不保证什么
本节是承重的一节。Aggrega 是一个预先(ahead-of-time)编译器,它的保证比“secret”一词诱使读者设想的范围要窄。
编译器从不解析凭据。 它不向云 API 进行身份验证,不读取 vault,也不在 aggrega build 期间获取机密材料。凭据附件的 values 和 infra 作为不透明标量穿过图并进入渲染上下文,由 FeatureRecipe 将它们渲染为目标平台所期望的任何制品。解析发生在之后,在集群或 IaC 状态管理器中,针对渲染出的制品所指向的内容进行。
编译器无法区分指针与材料值。 它与标量的含义无关(参见 05-invariants.md)。定位符携带存储坐标(path、key、ARN)的凭据附件会渲染出指向该坐标的引用;定位符携带材料本身的凭据附件会将材料原样渲染到输出文件中。两者都合法,编译器对它们一视同仁,因为它无法区分二者。
因此,对该保证的如实表述是:
Aggrega 保证编译器不执行任何解析。它不保证渲染输出中不含材料——这完全取决于附加的是哪个凭据 Feature,以及其作者在其中放入了什么:开发者放在
values中,或运维人员放在infra中。
值得牢记的两个推论:
- 渲染出的制品树的敏感程度等同于其中携带材料最多的附件。请相应地对待
dist/:只要任一附件内联携带材料,该树就包含材料。 - 目录自带的
core/secret-value和core/referenced-secret系列包含直接接受值的形式。它们之所以存在,是因为真实部署需要一条本地开发路径,而且它们对此毫不隐瞒:随附的示例使用明显的占位符(dev-root-pw-change-me),正是为了让渲染示例中的材料一看便知不是真实凭据。对于不得携带材料的部署,请附加一个由存储支持的凭据 Feature,其 FeatureRecipe 输出获取资源(ExternalSecret、vault 获取自定义资源、provider 原生的 secret 引用),而不是输出数据的那种。
标准库的约定是:凭据以附件形式请求,而不是写入 values 块,这样把本地开发填充替换为由存储支持的填充只需修改 Manifest,而无需编辑开发者意图。这是目录遵循的约定,而不是编译器强制执行的规则。
声明的敏感性
如上一节所述,编译器无法区分指针与实际值——但作者可以区分,并且可以加以声明。Aggrega 中的敏感性是声明上的一个注解:目录实体的作者说明哪些内容承载机密材料,编译器根据这一说明以及它已构建的连接关系推导出其余部分。不会根据值进行任何推断,也不会根据字段名进行任何猜测。
它只在两个位置编写,二者表达的主张确实不同。
在 schema 叶节点上——此数据是机密材料。 values、infra 或 provides 叶节点声明 sensitive: true:
spec: schema: values: origin: type: string required: true sensitive: true # the material key: type: string default: value # a data key — a locator, not material在附加槽位上——绑定到此处的任何内容都会处理机密材料。 featuresSchema 槽位声明 sensitive: true:
spec: featuresSchema: password: selector: "feature.aggrega.ai/kind=secret" sensitive: true inject: [env]这两个层级并不是为了方便而相互重复,可引用凭据的形态正是说明原因的实例。可引用凭据发布 provides.name 和 provides.key——资源的定位符及其中的数据键——而两者都不敏感:Kubernetes Secret 的名称是公开的,其中的键也是如此。两者都以明文形式作为 secretKeyRef 渲染到使用方自己的清单中。然而该凭据所填充的槽位无疑会处理机密材料。仅凭一个层级无法同时表达这两个事实:为使槽位被视为敏感而标记已发布的定位符,会对它们作出错误的陈述,并将这一错误带到读取该声明的每一处。
编译器根据这两种声明,针对每个附加项推导出它是否处理声明为敏感的材料——当所附加的 Feature 声明了敏感叶节点,或者它所绑定的槽位声明了敏感性时,结果为真,二者任一即可。推导依据的是所有编写作用域合并之后的附加项,因此被较窄填充取代的较宽作用域声明不会残留,而槽位的要求适用于实际胜出的那个填充。一个完全没有声明敏感叶节点的凭据 Feature——因为材料由目标引擎掌管、作者什么也不写——在绑定到敏感槽位时,仍然会产生敏感附加项。
上限,直白地说明
“sensitive”一词容易让读者期待一种保密机制。它并不是,其保证在以下五个具体方面比名称所暗示的更窄:
- 它不加密。 不进行任何包装、密封或转换。
- 它不改变构建的结果,仅有一个例外。 不会因为缺少声明而使构建中止,凭据实体不带任何声明的目录也能成功构建。不会因为存在声明而接受或拒绝任何值,除非 CloudFormation Recipe 或 FeatureRecipe 的
valuesMapping读取声明为敏感的值来填充来源模板的参数:此时该映射绑定的每个字面量都会被拒绝,因此添加声明可能使原本成功的构建变为中止——参见 A secret bound to a CloudFormation parameter would be written into the template(绑定到 CloudFormation 参数的机密将被写入模板)。在其他所有情况下,向现有目录添加声明,原本成功的构建仍会成功。 - 它不保证渲染输出中不含材料。 上文所述的保证不变:制品是否承载材料,取决于附加了哪个填充以及其作者在其中放入了什么。以内联方式提供的声明为敏感的值,在构建会渲染它的任何地方,都与未声明的值完全一样被渲染——上文的 CloudFormation 拒绝是阻止字面量而不是渲染它,内部函数则按给定内容原样写入,包括其文本——
dist/的敏感程度仍然等同于其中承载材料最多的附加项。 - 它不强制交付机制。 声明无法将内联值转换为存储引用,也不会缩小槽位的
inject允许列表所允许的范围。强制交付意味着生成作者从未声明的资源,而这正是无幽灵基础设施不变量所禁止的——参见 05-invariants.md。 - 在大多数目标上,它不会改变任何渲染出的字节,并且在这些目标上永远不会。 有两条随附的渲染路径会在其产出中依据该声明行事(Helm、Helm-Chart 和 Compose 的 provider 也会读取它,但仅用于让被标记的值不出现在失败信息的文本中):Terraform provider 会用 Terraform 自身的敏感性属性标记一个携带已声明敏感材料的 vendored 模块输入——参见 language-reference/providers/terraform.md “Declared-sensitive module inputs”;当输入名称由某个 Recipe 的
valuesMapping,或由附加到某个组件上的 Feature 的 FeatureRecipe 的对应映射自行编造时,没有任何输入能够携带该属性,构建会打印一条说明此情况的提示,参见 A declared-sensitive value reaches the target through a values mapping(一个已声明敏感的值通过 values 映射到达目标)——而 CloudFormation provider 会拒绝上文所述的字面量绑定,这会使构建中止,而不是改变其字节。在其他所有情况下,在现有目录中添加声明会使每个渲染出的产物保持完全相同。超出这一点的上限是结构性的,而不是取决于已构建了什么:声明只可能在其自身语言带有敏感性概念的目标平台上到达渲染出的产物——即该平台能够理解的一种声明,它决定平台如何显示一个值,而不是如何存储它。在没有这种概念的目标上,声明无从转化为任何东西,因此无论有无声明,相同的输入都会渲染出相同的结果,永久如此。
声明确实会改变的一点,是 CLI 为供人阅读而打印的内容。在逐遍跟踪和 inspect 布局中,声明为敏感的值会被替换为固定的占位符,保留键而只隐去值。这是在无人部署的界面上做出的显示决定;渲染制品则原样生成,因为它们就是可部署的产物。
当编译器能够通过键识别该值时——声明的叶节点,或承载来自声明的 provides 键之材料的交付键——替换是精确的。模板已写入另一个文档的值没有可供替换的键,因为渲染后的文档不会记录每个字符来自哪个声明,而要恢复这一信息就意味着检查内容。因此,跟踪会针对一个其中声明为敏感的数据已显示为占位符的上下文再次求值同一模板来展示此类文档,并将结果标注为重新渲染,而非实际渲染的内容:依据值的内容进行分支的模板,在占位符下的渲染结果会不同,而没有任何声明指名的数据则原样传递。这些界面、该标注及其限制,参见 language-reference/vocabulary/compact-form-authoring.md 中的“Declaring a leaf sensitive”。
因此,对这一维度所能提供的内容,如实的陈述是:
敏感性声明是随实体一起传递的作者意图陈述,使工具和策略能够推断一个部署处理了什么。它不是保护这些内容的机制。
保护材料仍然是机密存储、集群以及处理渲染树的流水线的职责——正如本章其余部分所述。
凭据如何到达容器
有两种交付形态,由附件的 FeatureRecipe 而非开发者选择:
注入值。 FeatureRecipe 声明一个 injectMapping,且不声明任何资源。其输出会在基础 Recipe 渲染之前深度合并到消费方组件的交付管道中,因此读取 .context.inject.env.<KEY> 的 Recipe 会收到该值。不会生成任何独立的内容。
在同一个键下交付两个凭据会使构建停止,并指出这两个附件:如果一个映射写入的键已由另一个已附加的 Feature 交付——无论是通过该 Feature 自己的映射还是它自己的 inject: 块——该映射会被拒绝而不是合并,因此一个凭据永远不会被当作另一个凭据呈现。这一规则对每个附件都相同,无论它附加在何处,也无论它填充的是组件上的槽位还是连接上的槽位。如果映射替换的键是由组件自己的 inject: 块或其某个连接交付的,这属于路由 Features 所依赖的拦截,仍然合法。
可引用资源。 FeatureRecipe 声明 source、workload、artifacts 和/或 valuesMapping,因此会生成一个资源——通常是平台原生的 Secret。它通过自己的 provides 发布该资源的标识,消费方以 .features.<name>.provides.name / .provides.key 读回。资源自身的名称由同一个已发布的 provides 派生,因此消费方读取的名称与资源携带的名称是同一个求值得到的字符串,而不是两个可能出现偏差的派生结果。
Recipe 的 Workload 通过容器的 attachments: 映射消费可引用的填充:
workload: | containers: main: attachments: DB_PASSWORD: from: root_password # a slot the Component declares as: env合成器根据槽位已发布的 provides 解析引用——对于 as: env 是 Kubernetes secretKeyRef,对于 as: file 是由 secret 支持的卷。Recipe 作者只需写出槽位名称和机制。
FeatureRecipe 可以两者兼做:重写交付管道,并且生成资源。它还可以声明由 Wasm 步骤组成的 pipeline,这些步骤对每个附件族都同样运行——凭据附件可以在受邀时转换宿主组件的渲染文档,与运维附件完全一样。
由谁命名凭据
凭据的定位符(secret 的名称、要获取的存储条目、要交付的值)由知道它的人编写,而这个人并不总是开发者。由 Release 连接的连接在 Aggregate 中没有条目,而 Release 在任何地方都不编写 values,因此仅从 values 获取定位符的凭据永远无法在这样的连接上命名,也无法在 Release 所做的任何附加上命名。
因此,每个携带调用方定位符的标准库凭据 Feature(core/referenced-secret、core/referenced-secret-set、core/secret-value 和 core/secret-provided)都接受来自任一作者的定位符:开发者在 Aggregate 中附加的 values 里提供,或运维人员在 Release 中附加的 infra 里提供。该叶子字段在两个支柱中具有相同的名称、相同的结构和相同的 sensitive: true 声明,每种实现都读取携带它的那个支柱。Release 的 values: 禁令保持不变:运维人员的定位符位于 infra 中。不接受定位符的 Features(core/random-password、core/generated-secret)不受影响。
**恰好一个,由 Feature 保证。**一个附加在一个支柱中携带定位符,既不能两个都有,也不能两个都没有。任何支柱的 schema 都无法表达这一点,因为每个支柱都是单独验证的;由每个 Feature 自身的 assertions 块来表达,违反它的附加会中止构建,并指出该 Feature、该附加和该组件。这是目录实体的契约,其维护方式与每个 Feature 断言相同:编译器对 Feature 作者编写的模板求值,自身不持有任何关于凭据、支柱或定位符的规则。
**保持原位的内容。**其他每个字段都保留在其原有支柱中:可引用凭据的数据键仍写在 values 中,因此仅由 Release 所做的附加会读取其默认值;core/secret-provided 仍然只通过附加自身的 inject: 块交付,该块只由 Aggregate 编写,连接上的附加从不携带它。
在多个消费者之间共享一个凭据
凭据可以由消费者持有。 槽位属于需要该凭据的实体,而这往往是调用方,而不是被调用的一方:一个在向外发起连接时出示密钥的组件,会在它自己的目录实体上、在它向外连接所经由的套接字上声明该密钥的槽位,因此密钥持有在出示它的那条连接上——uses 边并不要求目标提供密钥。core/ai-agent/crewai 就是随附的这种形态——它的 model 套接字声明了一个可选的 credential 槽位,带有 feature.aggrega.ai/kind=secret 选择器、inject: [env] 和 sensitive: true,Aggregate 在连接下的 uses.model.<alias>.features.credential 处填充它。标准库模型组件发布给消费者读取的是服务地址和模型名称,而不是凭据,因此智能体调用该端点时出示的密钥由智能体声明,并持有在它的连接上。该槽位是可选的,但如果一条连接到达的模型在其目录中标记为 component.aggrega.ai/hosting: managed,而该连接未携带凭据,则构建会中止,除非该连接自己的 values 声明该模型不需要凭据,即 unauthenticated: true——这是智能体的目录实体携带的一条断言,编译器像对待任何断言一样对其求值,并将该标签作为字符串读取。它所连接的模型组件可以为其自己的调用方持有一个自己的密钥——core/ai-model/vllm 正是为此声明了一个 api_key 槽位——两者是彼此独立的绑定点:附件按名称在声明槽位的地方绑定该槽位,即组件上或连接上,因此填充其中一个与另一个无关。
正是这种放置方式,使下面两种形式成为部署层面的选择:槽位位于消费者上时,一次构建可以为每个消费者提供各自的密钥,另一次构建可以为所有消费者提供同一个密钥,两者之间无需更改任何目录实体。
同一个目录实体同时支持这两种形态,由作者选择采用哪一种:
- 按消费者。 每个消费者用各自的凭据附件填充自己的槽位——在组件上,或者在槽位属于套接字时在其连接上。每个消费者都获得各自渲染出的资源。
- 共享。 对于组件声明的槽位,一个凭据在共享作用域中附加一次——Aggregate 中的子系统、Release 中的边界——并级联到该作用域中的每个组件。套接字声明的槽位按连接填充,而任何内容都不会级联进连接,因此在那里共享形态要在每条连接上编写:每条连接的凭据读取同一个参数。当消费者必须引用同一个物理资源时,由该参数为其命名——绑定到现有 Secret 实现的
core/referenced-secret会让每条连接按名称指向同一个 Secret,而生成的凭据则是一个请求加多个引用,如下文所述。
需要准确说明共享形式的渲染结果,因为很容易误解:共享附件会为每个消费者渲染一个资源,每个资源都携带来自同一声明的相同内容。渲染按组件进行,因此由 {{ .context.instance_id }}-{{ .attachment_name }} 派生的资源名称在每个消费者之间各不相同。被共享的是单一声明;输出的资源不会去重合并为一个。在渲染资源的实现下,每条连接上读取同一参数的渲染方式相同——每条连接一个资源,附件名称为连接的别名、一个点号和槽位。
如果某个部署恰好需要一个由多个消费者读取的物理 Secret,请使用一个其 FeatureRecipe 在边界作用域运行(executionScope: boundary)的凭据 Feature 来表达,它会为边界渲染一次,而不是每个组件渲染一次。
连接两端都持有的密钥
校验密钥的服务器和调用它的组件各自持有该密钥,各在自己一侧。服务器将其校验的密钥持有在自己 Component 的一个槽位中——core/ai-model/vllm、core/ai-model/tei 和 core/ai-model/tgi 都声明了 api_key,LiteLLM 模型和网关也为 LiteLLM 称为主密钥的那个密钥声明了它——其 Recipe 将填充该槽位的任何内容作为服务器读取的变量交付。调用方在自己一侧持有它出示的密钥:在出示密钥的连接上,位于其套接字声明的槽位中——如 core/ai-agent/crewai 的 model 套接字声明 credential——或者,当其 Component 在自身上声明该密钥时,位于该槽位中,用于它发起的每条连接。两端都看不到对方的附件:连接上的附件只落在调用方身上,而无论到达服务器的连接携带什么,服务器的渲染输出都相同。服务器从不知道调用方持有哪个密钥,调用方也只读取服务器发布的内容——地址和模型名称。两端之所以一致,是因为 Aggregate 用同一个参数为两者提供输入:
spec: parameters: model_key_secret: { type: string } components: model: type: core/ai-model/vllm values: { model: Qwen/Qwen2.5-0.5B-Instruct } features: api_key: # the key the server verifies type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key router: type: local/gateway/model-router # its `models` socket declares a `credential` slot uses: models: local: target: model features: credential: # the key the caller presents type: core/referenced-secret values: origin: "{{ .parameters.model_key_secret }}" key: api-key这是一个 secret 还是两个,取决于两端在何处解析 secret。provider 在一个 secret 作用域内按引用解析 secret:在 helm 上是 Kubernetes 命名空间,在 compose 上是 Compose 项目,在 terraform 上是边界的根配置,在 cloudformation 上是部署到某个 AWS 账户和区域中的堆栈。两端位于同一作用域时,它们引用同一个 secret 资源。位于不同作用域时,每一端各持有一个自己的 secret 资源,由同一个存储条目实现。Manifest 为每一端选择实现——按 Feature 类型,或者针对单个附件按其名称,连接附件的名称为 <alias>.<slot>(上例中为 local.credential)。由于同一个参数为两者提供输入,两个实现会把 origin 读作同一种定位符:都是 Secret 的名称,都是存储条目的键,或都是值本身。
在 helm 上,两端位于同一命名空间时,将 core/referenced-secret 绑定到 helm/k8s-existing-secret,并用该命名空间中某个 Secret 的名称 model-keys 履行该参数,即可让两端按名称引用它,且不渲染任何 Secret。服务器的容器携带:
- name: VLLM_API_KEY valueFrom: secretKeyRef: name: model-keys key: api-key而路由器的 Recipe 从其连接的 .context.uses.local.features.credential.provides 处读取相同的名称和键。两端位于不同命名空间时,将其绑定到 helm/k8s-external-secret,并用某个存储条目的键履行该参数,就会让每一端在自己的命名空间中拥有一个自己的 ExternalSecret,两者都获取同一个条目。在 compose 上,两端携带相同的 ${VAR} 引用,Docker Compose 用启动该项目时的环境对其进行替换。这种放置方式是标准库目录遵循的约定;编译器不会在两端之间进行任何比较。
一个密钥服务所有调用方。 vLLM、TEI 和 TGI 各自只校验单个密钥,因此每个调用方都出示同一个密钥,无论有多少条连接到达,服务器都无法区分不同的调用方。这是服务器自身的限制。TGI 匹配密钥时不区分大小写,因此仅大小写不同的两个密钥对它而言是同一个密钥。LiteLLM 模型和网关在附加了其记账数据库时,也接受它们自己签发的密钥。
由目标生成的凭据
当 Release 未提供凭据时,目录实体通常会退回到开发用默认值——Recipe 中的内联值、模块参数上的默认值。该值对目录的每位读者都相同,仅可用于评估,不可用于其他用途。core/random-password 消除了对它的需要:没有人编写凭据,因为由目标生成它。
密码不能在构建中生成。构建的输出是其输入的纯函数,且从不携带密钥的值,因此在构建时抽取的密码会在每次构建时变化,并留在渲染出的文件中。FeatureRecipe 转而渲染一个请求——一个指明其所填充的密钥资源的生成器资源——由目标在部署时抽取该值:
- 在
helm上,是集群中的控制器:通过ExternalSecret协调的 External Secrets Operator 密码生成器,或协调StringSecret的 kubernetes-secret-generator 控制器; - 在
terraform上,是 random provider 的random_password,在应用配置时抽取; - 在
cloudformation上,是一个 Secrets Manager 密钥,在堆栈创建它时生成自己的字符串。
在所有情况下,渲染输出都指明生成器和密钥资源,且不携带任何值。这是构建所拥有内容的一项属性,而不是它额外添加的保护:在目标生成该值之前,它根本不存在。之后目标将其保存在何处由目标决定——Terraform 将其保存在计划和状态中,集群则保存在 Secret 中。
**目标需要运行什么。**请求只有在有东西填充它的地方才会被填充。在 helm 上,填充者是控制器,而编译器无法检查集群来得知是否有控制器在运行,因此除非 Release 在附件上以 infra.control_plane_present: true 确认该前提条件,否则 helm 的 FeatureRecipes 会中止构建。在 terraform 和 cloudformation 上,由 apply 或堆栈自行生成该值,无需事先运行任何东西。
**无法使用的场合。**Compose 不运行控制器,也没有生成值的资源,因此没有 FeatureRecipe 在那里实现 core/random-password,在 compose 上绑定它的构建会因缺少实现而中止。以 compose 为目标的 Release 通过 core/secret-value 提供凭据,通常是 Docker Compose 在堆栈启动时替换的变量引用。
使用方如何读取它。core/random-password 发布与 core/referenced-secret 相同的 provides.name 和 provides.key,并带有相同的 feature.aggrega.ai/kind: secret 标签,因此选择凭据族的槽位会接纳它,使用方读取生成的凭据的方式与读取已存在的凭据完全相同。
多个使用方如何共享一个凭据。生成器为每个请求抽取新值,因此上一节的共享规则在这里更为严格:附加在共享作用域上——或附加在每个使用方上——的生成凭据会为每个使用方渲染一个请求,而每个请求抽取的密码都不同,数据库及其客户端无法使用。由多个使用方共享的一个生成凭据,表达为一个请求加多个引用:在一个组件上使用 core/random-password,以其 name 值固定它所填充的 Secret;在其他组件上使用 core/referenced-secret,绑定到 existing-Secret 实现并指向同一名称。由同一参数写出,两者不会不一致,渲染结果中恰好只有一个请求,所有使用方都引用它。
core/random-password 不是 core/generated-secret。后者这个 Feature 把凭据交给已掌管其整个生命周期的引擎——托管数据库、数据库控制器——且不渲染任何内容。core/random-password 则自行渲染请求,适用于其 Recipe 期望被交付凭据的 workload。
挂载优先级
一个挂载可以同时在多个作用域中声明。有争议字段的归属按以下三条规则依次解析:
- 来源。 显式编写的字段优先于由注解驱动展开所贡献的字段,无论二者各自来自哪个作用域。
- 组合权限。 你正在部署的 Aggregate 中的声明优先于它所组合的 Aggregate 内部的声明,即使被组合的文档是在更窄的作用域中声明的。
- 具体性。 在同一编写层级内,较窄的作用域逐字段细化较宽的作用域:组件级的填充仅针对它提及的字段覆盖同一实例名的子系统级或边界级挂载,它省略的字段保留较宽作用域的值。
开发者一侧提供 values,运维一侧提供 infra,因此二者从不争夺同一字段。从任一侧获取定位符的凭据 Feature 会将其声明为两个字段,每个支柱一个,并且其自身的断言会拒绝同时携带二者的挂载,因此在那里优先级也无需打破平局。优先级只决定字段值;它不会重新排列求值顺序,求值遵循 10-compilation-pipeline.md 中的级联顺序。
要求格式化字符串的旧版 chart
有时 chart 需要一个内嵌凭据材料的单一连接字符串——oracle://admin:PASSWORD@HOST:1521/DB。AOT 编译器无法根据存储坐标构建该字符串,因为它从不持有凭据材料。有两条受支持的途径:
集群端模板化。 凭据 FeatureRecipe 生成一个资源,利用 vault operator 自身的模板功能在集群中格式化该字符串。随后应用按名称引用由此生成的平台 Secret,而编译器在从未持有凭据材料的情况下完成了这一关联:
{ "apiVersion": "external-secrets.io/v1beta1", "kind": "ExternalSecret", "metadata": { "name": "oracle-dsn-secret" }, "spec": { "target": { "name": "oracle-formatted-dsn", "template": { "engineVersion": "v2", "data": { "ORACLE_DSN": "oracle://admin:{{ .password }}@10.0.5.55:1521/PROD_DB" } } }, "data": [ { "secretKey": "password", "remoteRef": { "key": "arn:aws:secretsmanager:prod/oracle" } } ] }}参数提升。 Aggregate 声明一个带类型的参数,由外围的 CI 流水线在构建时通过 Release 的 parameters: 提供其值——例如由流水线写入一个文件,再由 Release 通过 parameters: { $import: ./ci-parameters.yaml } 导入。这是显式的逃生舱口,它让其中的权衡清晰可见:凭据材料此时会流经构建过程,因此渲染输出中包含该材料,必须相应地加以处理。
本地开发
推荐的本地开发路径保持开发者意图不变,只替换绑定。Aggregate 继续挂接同一个凭据 Feature 类型;本地 Manifest 将该类型映射到本地 FeatureRecipe,而不是基于存储的那个。编译器仍然不获取任何内容——本地 FeatureRecipe 只是交付本地运行时能够解析的 provider 原生语法:对于 Compose,是写入服务环境中的变量引用,例如 ${SECRET_NAME},Docker Compose 会在栈启动时从 shell 环境或 .env 文件中替换它。切换环境只需编辑 Manifest。
围绕凭据的数据治理
Aggrega 不对数据模式建模——行、列、文件属于应用层面的问题。它用标签对数据的治理身份建模,标准库的约定是:
- 数据存在于其本体标签将其标记为有状态或类资源的组件中(
component.aggrega.ai/type: stateful-server、resource)。保存排队消息负载的消息代理也属于此类:当它拥有自己的磁盘时带有stateful-server,当 Release 接入托管的消息代理时带有resource;而它所归属的messaging分类则是单独的component.aggrega.ai/category维度。 compliance.aggrega.ai/data-class(public、internal、restricted)为这些数据赋予语义身份。该约定固定了键及其取值,但不规定哪些组件携带它:标准库中没有任何 Component 携带它,因为组件所保存数据的类别描述的是一个系统环境如何使用该组件,而不是产品本身的属性,所以由系统环境在自己的 Components 上声明。它是一个普通标签:标签选择器会对它求值,运维人员挂载的治理插件可以读取它并拒绝构建。编译器本身不解释它,也不将任何类别排在另一类别之上——存在哪些类别以及如何排序,取决于所挂载策略自身的设置,参见 ../language-reference/examples/policy-data-class-route/。
**data-class 和 sensitive 是两个维度,将二者合并会丢失信息。**它们紧挨在一起,容易被误认为同一个接口,因此请牢记二者的区别:
compliance.aggrega.ai/data-class | sensitive | |
|---|---|---|
| 形式 | 分级——public / internal / restricted | 布尔值 |
| 粒度 | 整个节点 | 一个模式叶子节点,或一个挂载槽位 |
| 含义 | 组件所保存的数据具有何种治理身份 | 该数据项是机密材料,或该绑定点会处理机密材料 |
| 编写方式 | metadata.labels 中的一个标签 | 声明上的一个关键字 |
二者不能相互替代:把敏感性强塞进分级标签,会给一个本无顺序的事实强加顺序;把数据类别强加到叶子节点上,会强加一种分类本身并不具备的粒度。一个实体可以同时携带二者,一个保存 restricted 数据、且其凭据槽位被声明为 sensitive 的组件,陈述的是两件各自成立的事实。叶子节点和槽位关键字分别在 ../language-reference/vocabulary/compact-form-authoring.md 的“Declaring a leaf sensitive”和 ../language-reference/entities/component.md 的“Declaring a slot sensitive”中讲解。
静态加密被有意置于开发者意图之外,也置于编译器之外。它属于有状态组件的 Ops Recipe,以及读取节点标签并生成加密存储配置的渲染插件。这种归属是关于该问题应归于何处的设计指导——编译器不会检查任何 Recipe 是否遵循它。
这里的独特之处与非独特之处
对外定位值得说得直白而克制,以便读者自行校准判断。
独特之处:插槽契约是发布的,而不是内联声明的。 凭据必须满足的契约——插槽、其交付允许列表、其标签选择器——由发布者在目录实体上编写,并存在于由第三方维护的目录中。使用方不会在自己的配置中内联描述该契约;它填充的是他人发布的契约,编译器则根据该已发布的声明检查填充内容。使用方和契约作者是不同的人,在不同的代码仓库中工作,遵循不同的发布节奏。
独特之处:填充受标签选择器约束。 插槽可以说明哪一类事物可以填充它(selector: "feature.aggrega.ai/kind=secret"),而不是指定某个具体实现。该检查是一次标签集求值,因此一个实体可以接受它从未知晓的一整类填充,而新的填充只要带有正确的标签即可成为合格项。
非独特之处:注入映射。 “这个本地环境变量名接收那个产出的值”这种映射是一种广为人知的模式;多种配置和部署工具都用各自的语法表达同样的思路。Aggrega 的版本是一个提前求值并合并到交付管道中的映射,但这一思路属于整个生态,而非我们首创。
非独特之处:提前(ahead-of-time)静态生成。 从更高层的描述静态生成部署制品、且生成时不访问运行中的集群,并非 Aggrega 的发明。其他工具也这样做,并且在 Aggrega 出现之前就已如此。Aggrega 所增加的是位于其上的已发布契约层,而不是静态生成本身。
不是安全边界。 本章中的任何内容都不是保密机制。凭据模型是一个连线模型:它决定指针或值从何而来、谁可以约束它,以及它如何到达容器。保护敏感材料是密钥存储、集群以及处理渲染树的流水线的职责。
交叉引用
- 05-invariants.md — 本章所依赖的预先编译不变量和字符串管道不变量。
- 10-compilation-pipeline.md — 附件解析和资源生成在管道中所处的位置。
- ../language-reference/entities/component.md —
featuresSchema插槽的编写,包括插槽级的sensitive声明、required关键字,以及插槽与存在性强制要求之间的逐点对比。 - ../language-reference/vocabulary/compact-form-authoring.md — 叶级
sensitive关键字、读取该声明的位置,以及parameters:的不对称性。 - ../language-reference/entities/workload.md — 容器的
attachments:映射及其校验规则。 - ../language-reference/examples/04-secrets.md — 编写检查清单,以及透明式与黑盒式的完整示例。
- ../language-reference/examples/05-credential-features.md — 凭据 Feature 系列及端到端的演练。
- ../language-reference/examples/model-api-key-sharing/ — 由一个代理的套接字声明的凭据插槽,基于同一个目录实体在每个连接上以三种方式填充:每个连接一个密钥、所有连接共同引用的一个 Secret,以及由某个连接覆盖的共享默认值,并附有每种形式的渲染输出。