ArtifactLibrary
ArtifactLibrary 是一种目录实体,用于保存可复用的制品包——即一组彼此关联、带有名称的辅助输出文件集合。生成相同支撑资源的 Recipes 和 FeatureRecipes(例如一个 CRD 及其 RBAC 和一个 ConfigMap,或一个 NetworkPolicy 搭配一个 HPA)只需在库中声明一次该集合,并在使用时通过一个值为 $import: 指令的 artifacts: 条目引用它。该库实体属于第 3 层:供需要跨 Recipe 复用制品的目录选择性启用。如果目录中的每个 Recipe 都各自携带辅助文件,则无需任何 ArtifactLibrary。
ArtifactLibrary 的作用
平台架构师编写 ArtifactLibraries,用于集中管理在目录的 Recipes 和 FeatureRecipes 中反复出现的辅助清单。库不是可部署的构建指令,而是一个定义命名空间。Recipe 和 FeatureRecipe 的作者通过 $import: 指令引用某个 bundle,只需编写一次,即可在该导入解析到的任何位置使用。
这种库类型与其他三种的区别在于条目的粒度。SchemaLibrary 的一个条目是一个 schema,MappingLibrary 的一个条目是一个模板片段,WorkloadLibrary 的一个条目是一个 Workload 文档——每个都是在单一位置使用的单一主体。ArtifactLibrary 的条目则是一组文件,因为它所归组的资源只有放在一起才有用:导入一个 CRD 而不带上它的 RBAC,会生成一组无法工作的清单。正因如此,bundle 是复用的单位,而单一使用位置会展开为多个输出。
实体信封
ArtifactLibrary 实体带有标准的目录信封。apiVersion: aggrega.ai/v1beta1 和 kind: ArtifactLibrary 标明实体种类;metadata.name 是 PascalCase 标识符;metadata.version 遵循严格的语义化版本。两者均为必填。metadata.description、metadata.labels 和 metadata.annotations 为可选——labels 和 annotations 是作者声明的不透明元数据,供读取该库的任何程序据以匹配,编译器不解释它们的值。库的内容位于 spec.artifacts 之下,这是一个必填的映射,必须至少声明一个 bundle。
信封在全部三个层级上都是封闭的——文档根、metadata 和 spec 都会拒绝 schema 未声明的键。
apiVersion: aggrega.ai/v1beta1kind: ArtifactLibrarymetadata: name: PlatformArtifacts version: 1.0.0spec: artifacts: OperatorSupport: crd.yaml: | apiVersion: apiextensions.k8s.io/v1 kind: CustomResourceDefinition metadata: name: widgets.platform.example.com spec: group: platform.example.com scope: Namespaced rbac.yaml: | apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: "{{ .context.instance_id }}-operator" rules: - apiGroups: ["platform.example.com"] resources: ["widgets"] verbs: ["get", "list", "watch"]编写 Artifact Bundle
spec.artifacts 有两层,每层各有不同的职责。外层键是bundle 名称,即使用方引用的标识符。内层键是文件名,每个内层值是输出到该文件的 Go 模板正文。一个 bundle 必须至少声明一个文件。
spec: artifacts: NetworkBaseline: deny-all.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-deny-all" spec: podSelector: {} policyTypes: ["Ingress"] allow-dns.yaml: | apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: "{{ .context.instance_id }}-allow-dns"文件正文是以 YAML 字符串形式编写的 Go 模板片段。由于 manifest 是多行的,文件正文使用 YAML 的字面量风格标量(|),使换行和缩进在往返过程中得以保留。bundle 条目的值必须是文件名到字符串正文的映射;在 bundle 的位置写一个裸字符串或一个序列会被拒绝——使用方导入的层级是 bundle,而不是单个文件。
正文对实体信封而言是不透明的。编译器在加载 ArtifactLibrary 时原样存储每个字符串,不在此时解析模板;模板解析器在使用时运行,即当 Recipe 或 FeatureRecipe 导入该 bundle 时。原样存储正文可在重新输出时保持编写的保真度,同时也意味着模板错误会在 bundle 被使用、其支柱上下文已知的位置暴露,而不是在库中暴露。
bundle 内的文件顺序即作者编写的顺序,在加载和使用过程中均保持不变,因此输出的文件集在多次构建之间保持稳定。
文件正文中可以使用 Go 模板完整的组合词汇:{{ define "name" }}...{{ end }} 声明可复用的块,{{ template "name" . }} 调用这些块,管道和函数遵循标准 Go text/template 包。文件正文可读取的支柱上下文——.values、.infra、.locals、.context、.features,以及在使用方 Recipe 声明时可用的 .workload 和 .source——与使用方 Recipe 自身的 artifacts: 条目所读取的上下文相同,详见 Recipe 页面中 artifacts: 字段的说明。如果正文在使用方 Recipe 未声明 workload: 时读取 .workload,或在未声明 source: 时读取 .source,编译将中止,并给出指明无法满足的引用的诊断信息——每个支柱都单独检查,因此声明其中一个并不允许读取另一个。
单一编写模式
ArtifactLibrary 只提供一种编写模式:Go 模板。spec 不接受并行的编写方式,在库级别也不提供提升表达能力的逃生舱口。
原因在于消费端的一致性。Recipes 和 FeatureRecipes 全程使用 Go 模板,它们自身的内容通过解析导入 bundle 的同一个 Go 模板引擎求值。并行的编写方式会迫使作者在单个 Recipe 的渲染过程中切换求值模型:Recipe 自身内容用一种模型,导入的 bundle 用另一种。保持编写方式一致,意味着作者只需学习一种求值模型,并在各处使用。
需要超出 Go 模板组合能力的表达力时,作者应在更高层级进行组合,即使用以自身实质性变化包装库 bundle 的 Components 或 Features,而不是在库内部升级为第二种编写语言。
命名约定
库名称和包名称遵循 PascalCase。实体信封的 JSON Schema 通过模式约束在两个位置强制执行该约定:
metadata.name匹配^[A-Z][A-Za-z0-9]*$。spec.artifacts的映射键通过propertyNames匹配同一模式。
包名称不符合 PascalCase 的 ArtifactLibrary 会在工作区加载时无法通过信封校验。这一强制执行至关重要:包名称出现在 #/artifacts/<name> 引用片段中,因此不符合 PascalCase 的名称会传播到每个导入该包的使用方。
命名的统一性使 #/artifacts/<name> 片段清晰易读:#/artifacts/OperatorSupport 一目了然。
包内的文件名形式自由,只要每个文件名都指向一个文件。 它们不采用 PascalCase,也不受任何 schema 模式约束,因为它们命名的是构建输出最终携带的文件——crd.yaml、deny-all.yaml、values-override.json 都是有效的。文件名必须是一个以普通方式书写的常规相对文件名;对于不指向其自身文件的文件名,构建会拒绝,详见引用库条目。这两个层级受到不同约束,是因为它们服务于不同的读者:包名称是其他实体引用的标识符,而文件名是使用方在导入该包的目录中看到的名称。
引用库条目
Recipe 和 FeatureRecipe 的作者在一个 artifacts: 条目中引用 bundle,该条目的值是一个 $import: 映射,通过 bundle 的裸名称标识进行引用:
# Inside a Recipe's spec:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport"#/artifacts/<name> 片段用于选择 bundle,并将 artifacts 引用与 MappingLibrary 的 #/mappings/<name>、SchemaLibrary 的 #/schemas/<name> 以及 WorkloadLibrary 的 #/workloads/<name> 区分开来。引用不携带注册表主机;带主机的 oci://… 形式会同时被信封 schema 和使用位置拒绝,因此物理注册表位置永远不会进入编写的源码。作者可以用 <Library>:<version>#/artifacts/<name> 声明一个可选的最低版本下限——版本分隔符是 :,与其他库类型及锁文件固定版本一致,改写为 @ 会被拒绝,并给出指明修正后引用的诊断信息。解析出的版本由每个 Release 的锁文件提供,锁文件按名称、版本和内容摘要固定每个被使用的库;物理位置在解析时绑定。
**bundle 拥有其文件名,使用方的键拥有这些文件所在的目录。**一个导入 bundle 的 artifacts: 条目会展开为该 bundle 中每个文件对应的一个输出,每个输出都以 <key>/<filename> 的形式嵌套在使用键之下。使用位置的键——上例中的 operator-support——命名的是整个使用,而非任何单个文件;该示例输出 operator-support/crd.yaml 和 operator-support/rbac.yaml。因此,bundle 名称是为了在引用处易读而选择的,文件名是为输出目录的读者而选择的,两者无需彼此一致。使用键本身被限定为单个文件名——以字母或数字开头,后接字母、数字、点、连字符和下划线,超出该字符集的键会导致信封校验失败——因此它恰好命名一个目录段,该段之下的一切都来自 bundle。正因如此,bundle 的文件名可以保持自由格式,而键保持严格:文件名在其 bundle 内唯一,键在其文档内唯一,且键是该条目输出的每条路径的第一段,所以不会有两个 artifacts: 条目命名同一个输出。自由格式指的是在该段之内自由:文件名可以带有自己的嵌套布局——crds/widget.yaml 会落在 <key>/crds/widget.yaml——但它必须是键之下一个以平实方式书写的普通相对文件名,不符合的文件名会使构建中止,而不是把文件放到使用它的 Recipe 从未指定的位置。这会拒绝以下名称:向上越出键或指向绝对位置的名称;. 或 ./,以及像 x/.. 这样折叠回键本身的名称,它们指向的是键自身的目录而非其中的文件;以及带有末尾或重复 /,或含有 . 或 .. 部分的名称——x/、a//b、./a、a/../b——这些是另一个名称也能表示的同一文件的第二种写法,因此 a//b 与 a/b 并存会把两个文件放到同一路径。诊断信息会指明该 bundle 文件及其被导入时所用的键。确实具有相同文件名的两个输出会在节点渲染时使构建中止,这种情况发生在两种不同的输入类型提供同一个文件名时。关于 artifacts: 如何与 Recipe 的其他输入类型组合,以及两种非库编写模式,请参阅 Recipe;关于更广义的 $ref: / $import: 区别,请参阅 vocabulary/cross-document-ref。
跨库组合
bundle 文件的主体是终端内容。 与 MappingLibrary 或 WorkloadLibrary 条目不同,bundle 文件不能是字段根级的 $import: 重定向:单个文件槽位容纳不下另一个 bundle 会带来的多个文件,因此编译器拒绝这种形式,而不是把它解析成作者并未编写的内容。首个标记为 $import: 的主体会中止构建,并给出指明该 bundle 和该文件的诊断。
组合改为在消费位置进行,那里有容纳它的空间。需要两个 bundle 的 Recipe 声明两个 artifacts: 条目,每个条目各自独立展开:
# Inside a Recipe's spec — compose bundles where the outputs land:spec: artifacts: operator-support: $import: "PlatformArtifacts#/artifacts/OperatorSupport" network-baseline: $import: "PlatformArtifacts#/artifacts/NetworkBaseline"未知的库名,以及在能够解析的库中不存在的 bundle 名,会作为不同的诊断分别报告,因此作者可以区分缺失的依赖和拼写错误的 bundle 名。
层级定位
在实体层级文档模型中,ArtifactLibrary 属于第 3 层——供需要跨 Recipe 复用制品的目录按需选用。Recipes 自带辅助文件的目录无需任何 ArtifactLibrary 实体即可发布;层级标记表示的是“进阶内容;不需要时可跳过”,用于文档导航,而非表示能力。编译器对 ArtifactLibrary 与其他目录实体类型一视同仁:在加载工作区时进行相同的信封校验,在发布时使用相同的 OCI 发布流水线,并以相同方式在锁文件中按名称、版本和内容摘要进行固定。
这一库类型在目录层面补全了一个集合——SchemaLibrary 存放可复用的 schema 定义,MappingLibrary 存放可复用的映射片段,WorkloadLibrary 存放可复用的工作负载内容,ArtifactLibrary 存放可复用的制品包。每一种都可独立按需选用;目录只发布自己需要的那些,其余一概不带。
ArtifactLibrary 不是什么
以下是几个值得提前澄清的常见误解:
-
不能替代内联的
artifacts:。 大多数 Recipes 携带的辅助文件足够专用,适合内联编写,作者可以将其与 Recipe 的其余部分一起阅读。当同一组文件伴随许多 Recipes 时,ArtifactLibrary 才有帮助;对于一次性内容,内联编写才是正确的选择。 -
不能用来重命名 bundle 内的文件。 文件名属于 bundle。使用方可以选择文件所在的目录(这正是消费键的作用),但不能决定其中任何一个文件的名称:需要不同文件名的使用方,要么使用声明了该文件名的 bundle,要么内联编写该文件。
-
不是存放 workload、mapping 或 schema 内容的地方。 Workload 文档属于 WorkloadLibrary,Recipe 的 values 文档属于 MappingLibrary,schema 定义属于 SchemaLibrary。各库类型按内容类型划分,而不是按复用模式划分。
-
不是处理横切资源的机制。 适用于许多 component、且与由哪个 Recipe 实现无关的辅助资源(例如附加到每个数据存储的备份 sidecar),应通过 FeatureRecipe 的资源生成来处理,它按 Feature 而不是按 Recipe 附加。参见 entities/featurerecipe.md。ArtifactLibrary 提取的是多个 Recipes 各自代表自身生成的文件。
-
不是可独立部署的实体。 bundle 是 artifact 内容,而 artifact 内容永远不能单独寻址:它作为 Recipe 或 FeatureRecipe 消费的输入而存在。发布 ArtifactLibrary 会使其 bundle 可被导入,但不会使其可被部署。