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

MappingLibrary

MappingLibrary 是一种目录实体,用于存放可复用的 Go 模板片段。共享整份 valuesMapping: 文档的 Recipes 和 FeatureRecipes(例如以同一 chart 为源的多个 Recipes 各自交给该 chart 的 values)只需在库中声明一次该文档,并在使用时通过 valuesMapping: { $import: ... } 指令引用它。该库实体属于第 3 层:供需要跨 Recipe 复用映射的目录选择启用。没有重复模板内容的目录无需包含任何 MappingLibrary。

MappingLibrary 的作用

平台架构师编写 MappingLibraries,用于集中管理在目录的 Recipes 和 FeatureRecipes 中反复出现的 Go 模板片段。库不是可部署的构建指令,而是一个定义命名空间。Recipe 和 FeatureRecipe 的作者通过 $import: 指令引用库条目:只需编写一次,凡是该导入能够解析之处都可使用。

“库”与“使用方”的划分是有意为之。Recipes 编码构建指令(source、valuesMapping、artifacts)。FeatureRecipes 编码行为附加。MappingLibraries 只编码模板片段,即其他实体在渲染时使用的 Go 模板内容。保持这三种角色相互独立,使每种实体类型都能按各自的节奏演进;不需要共享模板内容的作者永远不会接触到这种库实体。

实体信封

MappingLibrary 实体带有标准的目录信封。apiVersion: aggrega.ai/v1beta1 和 kind: MappingLibrary 标明实体种类;metadata.name 是一个 PascalCase 标识符;metadata.version 遵循严格的语义化版本。库的内容位于 spec.mappings 之下,这是一个必需的映射,必须至少声明一个条目。

apiVersion: aggrega.ai/v1beta1
kind: MappingLibrary
metadata:
name: BaseMappings
version: 1.0.0
spec:
mappings:
SimpleValues: 'image: {{ .values.image }}'
Replicas: 'replicas: {{ optional .infra "replicas" 1 }}'

条目由使用它的 Recipe 自身的模板引擎、依据该 Recipe 的渲染上下文求值,因此它读取的是 Recipe 自身的 valuesMapping: 所读取的小写支柱——.values、.infra、.context 等——并使用相同的函数,例如针对缺失键、能感知是否存在的 optional 辅助函数。.Values(Helm 对 chart values 的写法)不是该上下文所定义的根:读取它的条目会中止构建,并指出该引用。

编写映射条目

每个映射条目都是以 YAML 字符串形式编写的 Go 模板片段。该片段对实体信封而言是不透明的——编译器在加载 MappingLibrary 时原样存储该字符串,并在 Recipe 或 FeatureRecipe 通过 valuesMapping: { $import: ... } 导入该条目时,于使用阶段对其进行解析。导入会替换 Recipe 的整个 valuesMapping:——$import: 映射不携带其他任何键——因此一个条目是一份完整的 values 文档,而不是拼接进某份文档的一个片段。

较短的片段可以写在一行内:

spec:
mappings:
AppName: 'fullnameOverride: "{{ .context.rendered_name }}"'

多行片段使用 YAML 的字面量风格标量(|),以便换行和缩进在往返过程中得以保留:

spec:
mappings:
ProbeBlock: |
readinessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}
livenessProbe:
httpGet:
path: /healthz
port: {{ .values.port }}

片段内可以使用 Go 模板的全部组合词汇:{{ define "name" }}...{{ end }} 在单个库内声明可复用的块;{{ template "name" . }} 调用这些块;管道和函数按照标准 Go text/template 包的规定提供支持。

单一编写模式

MappingLibrary 只提供一种编写模式:Go 模板。spec 不接受任何并行的编写界面,也没有库级别的表达能力逃生舱口。

原因在于使用界面的一致性。Recipes 和 FeatureRecipes 全部使用 Go 模板,它们自身的内容通过解析导入条目的同一个 Go 模板引擎求值,因此条目的读法与 Recipe 自身文本完全相同,作者只需学习一种求值模型。Go 模板的组合词汇——库内的 {{ define }} 和 {{ template }},以及使用时的 $import: 指令——提供了库所需的可复用块和参数化调用。

需要超出 Go 模板组合词汇所提供的表达能力的作者,应在更高层级进行组合——用 Components 或 Features 包装库条目,并加入它们自身的实质性变化——而不是在 MappingLibrary 内部升级到一种并行的编写语言。

命名约定

库名称和映射条目键遵循 PascalCase。实体信封的 JSON Schema 通过模式约束在两个位置强制执行该约定:

  • metadata.name 匹配 ^[A-Z][A-Za-z0-9]*$。
  • spec.mappings 的映射键通过 propertyNames 匹配同一模式。

如果一个 MappingLibrary 在 spec.mappings 中含有非 PascalCase 的键,它会在工作区加载时无法通过信封校验。这一强制执行承担着实际作用:映射条目键出现在 #/mappings/<name> 引用片段中;非 PascalCase 的键会传播到每个导入该条目的使用方。

命名的统一使 #/mappings/<name> 片段易于阅读:#/mappings/ProbeBlock 一目了然。

引用库条目

Recipe 和 FeatureRecipe 的作者在 valuesMapping: { $import: ... } 块中通过映射条目的裸名称标识来引用它:

# Inside a Recipe's valuesMapping block:
spec:
valuesMapping:
$import: "BaseMappings#/mappings/ProbeBlock"

#/mappings/<name> 片段用于选择条目,并将映射引用与 SchemaLibrary 的 #/schemas/<name> 区分开来。该引用使用与 SchemaLibrary $ref: 相同的裸名称标识模型——<Library>#/mappings/<name>,不携带注册表主机。版本由每个 Release 的锁文件(名称 + 版本 + 内容摘要)提供;作者可以用 <Library>:<version>#/mappings/<name> 声明一个可选的最低版本下限(版本分隔符为 :,与 recipe/feature 映射及锁文件固定版本一致),物理位置则在解析时绑定。

跨库组合

MappingLibrary 条目可以是一个字段根 $import: 重定向:其主体的第一个标记是 $import: <Library>#/mappings/<entry>,它会用被引用条目的内容替换整个条目——这是按标识复用,而不是就地模板化。该重定向在使用时(Recipe 渲染时)解析,而不是在加载 MappingLibrary 时解析,并且是递归解析的——被导入的条目本身也可以是一个字段根 $import:。$import: 只作用于整个条目;它不是片段内部的模板函数。要在单个片段内部组合模板文本,请使用 Go 模板的 define / template。

# In library A — alias an entry to a shared entry in another library:
spec:
mappings:
StandardProbe: |
$import: MonitoringLibrary#/mappings/PrometheusAnnotations

库之间可以自由地相互引用。回绕到自身的引用链会在使用它的 Recipe 渲染时中止,并给出指明循环中每一步的诊断。

层级定位

在实体层级文档模型中,MappingLibrary 属于第 3 层——供需要跨 Recipe 复用映射的目录按需选用。没有重复模板内容的目录无需包含任何 MappingLibrary 实体;层级标记表示“进阶内容;不需要时可跳过”,用于文档导航,而非表示能力。编译器对 MappingLibrary 的处理与其他目录实体类型一致:在加载工作区时执行相同的封装校验,在发布时使用相同的 OCI 发布流水线。

在目录层面,这一库类型与 SchemaLibrary 自然搭配——SchemaLibrary 存放可复用的 schema 定义;MappingLibrary 存放可复用的模板片段。两者都需要的目录就同时包含两者;两者都不需要的目录则都不包含。

MappingLibrary 不是什么

以下是几个值得提前澄清的常见误解:

  • 不是内联 valuesMapping: 的替代品。 大多数 Recipes 携带的是简单的 valuesMapping: 内容,适合以内联方式编写——这样 Recipe 保持自包含,作者可以在阅读 Recipe 其余部分的同时阅读映射内容。当同一个片段出现在许多 Recipes 中时,MappingLibrary 才有帮助;对于一次性的映射,内联编写才是正确的选择。

  • 不是存放 schema 内容的地方。 Schema 定义(JSON Schema 2020-12)属于 SchemaLibrary;模板片段属于这里。各库类型按内容类型划分,而不是按复用模式划分。

  • 不提供超出 Go 模板机制的参数化复用。 需要参数化变化的作者可以在库条目中使用 Go 模板的 {{ define }} + {{ template arg }} 机制,或者组合 Components / Features,用它们自身的变化来包装库条目。该库实体本身不提供任何参数化辅助机制(没有类似于 SchemaLibrary 的 spec.templates 参数化辅助功能的 templates 块);Go 模板的组合词汇已覆盖相同的用例。