实体参考概述
Aggrega 的编写词汇包括 Aggregate、Component、Feature、Recipe、FeatureRecipe、Plugin、Manifest、Release、SchemaLibrary、MappingLibrary、WorkloadLibrary 和 ArtifactLibrary,以及嵌入在 Recipe 合成输入中、由平台拥有的 Workload 类型。每个实体都是符合 JSON Schema 的 YAML 文档;本参考描述的每个字段、关键字和跨实体引用都是该编写契约的一部分。
本组章节涵盖编写层面:每个实体接受哪些字段,每个字段对作者意味着什么,字段如何跨实体交互(Recipe 的 implements: 指明它所实现的 Component,Release 的 manifest: 指向一个 Manifest,Workload 的 containers.<name>.attachments 引用在 Component 的 featuresSchema 中声明的槽位)。每个实体的概念角色——分类体系为何呈现这种形态、哪个领域拥有哪个实体、四个领域如何分离编写关注点——见 ../architecture/04-entity-taxonomy.md。Workload 类型作为三种 Recipe 输入类型之一的架构角色见 ../architecture/16-recipe-input-composition.md。
本参考的组织方式
编写词汇由两类页面记录,它们回答不同的问题。
上面列出的每种类型都有一份生成的 schema 参考。 这些页面根据编译器自身发布的 schema 生成,schema/README.md 为完整集合建立了索引——包括实体类型、插件传输结构和工作区文件。要回答“这个文档可以包含什么”,请查阅 schema 参考:每个字段、其类型、是否必需,以及信封强制执行的约束。
下面的页面是编写指南。 它们由人工编写,讲解 schema 无法表达的内容:某种类型的用途、其字段如何与其他类型交互、哪种编写形态适合哪种情况,以及标准库目录遵循的约定。要回答“我该如何编写,它为何是这种形态”,请查阅编写指南。
各实体参考
- Aggregate——开发者的声明式意图工件。声明组件、通过
uses表达的组件拓扑、用于按环境变化的参数契约,以及 Feature 挂载。 - Component——由平台架构师编写的目录实体,定义一种可复用的组件类型。声明其
values和infraschema(各自为紧凑或完整形式的 JSON Schema 2020-12 声明)、provides输出契约、usesSchema入边契约,以及通过featuresSchema声明的凭据槽位。 - Feature——由平台架构师编写的目录实体,用于横切关注点(监控 sidecar、数据脱敏、路由策略)。声明其
values和infraschema(各自为 JSON Schema 2020-12 声明)、appliesTo挂载选择器以及互操作性约束。 - Recipe——由运维编写的从 Component 到特定 provider 的转换。组合三种输入类型(
source:+valuesMapping:、workload:、artifacts:——每种都按统一的文件导入词汇接受内联内容或$import:),外加一个构成调用方注入契约的provides块。 - FeatureRecipe——由运维编写的从 Feature 到特定 provider 的转换。使用与 Recipe 相同的三种输入类型契约,外加一个
injectMapping,用于拦截注入管道以在调用方一侧重写变量。 - Plugin——内容寻址的 WebAssembly 插件。声明它实现的唯一插槽类型——
provider、linter、pipeline-step、governance、cli、parser或importer——及其 ABI 版本,以及该插槽类型提供的能力。渲染 provider 的 Plugin(pluginType: provider)在spec.provider.capabilities中声明它服务的 provider 名称,并在同一个spec.provider块中携带其 provider 插槽元数据——workloadSchema和wellKnownAnnotations。 - Manifest——按项目的映射表。在
components和features下将抽象的 Component 和 Feature 类型绑定到具体的 Recipe 和 FeatureRecipe URI,查找顺序为name> 带版本的type> 不带版本的type。 - Release——按环境的部署路由器。将一个 Aggregate 绑定到一个 Manifest,将组件映射到物理边界,提供按环境的参数值,并挂载由运维管理的 Features。
库实体
四种库类型属于第 3 层——可选启用的复用实体。当同一内容在目录的多个实体中重复出现时,目录才声明库,否则不包含它们。每种库只容纳一种内容类型,引用中的片段(#/schemas/、#/mappings/、#/workloads/、#/artifacts/)指明该引用指向哪个库。
- SchemaLibrary——可复用的 JSON Schema 2020-12 定义以及可选的参数化辅助项,在 Component 或 Feature 的 schema 中通过
$ref: <Library>#/schemas/<name>引用。 - MappingLibrary——可复用的 Go 模板片段,通过
$import: <Library>#/mappings/<name>导入 Recipe 或 FeatureRecipe 的valuesMapping:。 - WorkloadLibrary——可复用的 Workload 内容,通过
$import: <Library>#/workloads/<name>导入 Recipe 或 FeatureRecipe 的workload:。 - ArtifactLibrary——可复用的辅助输出文件包,通过
$import: <Library>#/artifacts/<name>导入 Recipe 或 FeatureRecipe 的artifacts:。文件包是复用单位:一次导入会为包中的每个文件展开一个输出。
平台拥有的类型
- Workload——平台拥有的编译器类型(不是用户编写的目录实体)。嵌入在 Recipe 的
workload:字段中(内联或通过$import:);描述 provider 合成为 provider 原生清单的部署形态。