Crossplane Composition 通俗理解
Composition = 高层抽象 API 的实现模板Crossplane
- XRD（CompositeResourceDefinition）：定义对外 API 长什么样（schema、字段），相当于接口定义。
- Composition：接口的实现，描述创建这个高层资源时，到底要生成哪些底层 Managed Resource（MR，云资源 CRD），字段怎么映射、怎么打补丁 (patch)Crossplane。
类比：
- XRD：定义
kind: XPostgres，对外只暴露storageGB、instanceClass两个简单参数，只定义契约，不写怎么创建。 - Composition：写模板：创建 1 个 RDS 实例 + 1 个安全组 + 1 个 DB 子网组；把 XR 的
storageGB赋值给 RDS 的存储字段；给资源打统一标签；处理字段拷贝、状态回写。
用户只需要提交一个简单的XPostgres（XR/ Claim），Crossplane 控制器读取绑定的 Composition，自动批量生成一堆底层云资源，统一生命周期：创建、更新、删除全部联动Crossplane。
核心三对象关系
- XRD：定义新的 K8s API（CRD），对外暴露参数、校验规则；集群范围 / 命名空间，定义 Claim 是否可用Crossplane。
- Composition：
apiextensions.crossplane.io/v1，绑定一个 XRD（compositeTypeRef），描述要生成哪些资源、字段如何转换。一个 XRD 可以绑定多个 Composition，实现多后端：比如同样XPostgres，prod 走 AWS RDS，dev 走 GCP CloudSQL，对使用者完全透明。 - XR / Claim(XRC)：使用者提交实例。
- XR：集群级别；
- Claim：命名空间级别，给业务开发者使用，代理生成 XR。
数据流：
plaintext
User → Claim(命名空间) → XR(集群) → Composition模板 → 生成多个ManagedResource(云资源CR) → Provider Controller调用云API创建真实资源
修改 Claim → XR 更新 → Composition reconcile → 底层 MR 自动更新；删除 Claim → 所有底层资源一起删除（受 deletionPolicy 控制）GitHub。
Composition 两种模式
1. Resources 模式（传统 YAML+patch，v1 老模式）
spec.resources[]，每个 resource 写base（资源模板），再写patches做字段映射：从 XR 的 spec 拷贝到底层 MR 的 spec，也可以把 MR 的 status 回写到 XR 的 statusCrossplane。极简骨架示例：
yaml
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: aws-postgres
spec:
compositeTypeRef: #绑定XRD定义的API
apiVersion: db.platform.io/v1alpha1
kind: XPostgres
resources:
- name: rds
base:
apiVersion: database.aws.upbound.io/v1beta1
kind: Instance
spec:
forProvider:
engine: postgres
allocatedStorage: 10
patches:
#把XR.spec.parameters.storageGB覆盖到底层RDS
- fromFieldPath: spec.parameters.storageGB
toFieldPath: spec.forProvider.allocatedStorage
- name: sg
base:
apiVersion: ec2.aws.upbound.io/v1beta1
kind: SecurityGroup
缺点：只有声明式 patch，没有 if‑else、循环，复杂逻辑很难写，YAML 补丁爆炸。
2. Pipeline 模式（Composition Functions，现代推荐）
spec.mode: Pipeline，执行函数流水线，不再写spec.resources，用 gRPC 函数做资源渲染、条件判断、循环、复杂转换、校验。
最常用官方函数：function‑patch‑and‑transform，在函数内部写 resources+patch。还可以用 python/kcl/go 自定义 Function。
yaml
spec:
compositeTypeRef:
apiVersion: db.platform.io/v1alpha1
kind: XPostgres
mode: Pipeline
pipeline:
- step: render
functionRef:
name: function-patch-and-transform
input:
apiVersion: pt.fn.crossplane.io/v1beta1
kind: Resources
resources:
#这里写resources与patches，和老模式几乎一样
production‑grade 的 Crossplane 平台，全部用 Pipeline+Function 模式，方便做复杂业务逻辑、多环境差异化、循环生成多个同类型资源。
Patch 是什么？
Patch 是 Composition 里的核心机制：
fromFieldPath：来源路径，来自 XR（用户输入）或者已生成的子资源 status；toFieldPath：目标路径，底层 ManagedResource 字段；支持字符串拼接、条件、默认值，实现参数透传、元数据复制、状态回填（把 RDS 的 endpoint 回填到 XR 的 status 对外暴露）Crossplane。
关键能力与坑点
✅能力
- 封装复杂度：业务开发者只需要高层 API，不用懂云厂商几十个参数。平台团队维护 Composition，统一管控合规标签、安全策略。
- 多实现同一 API：同一个 XRD，多个 Composition，实现多云、环境差异化。
- 统一生命周期：删一个 Claim，所有子资源联动删除。可以用
Usage资源控制删除顺序（先删依赖，再删主资源）Crossplane。 - 状态聚合：把多个底层资源 status 聚合到 XR 的 status，使用者只看一个对象状态。
⚠️常见坑
- Composition 只做模板，不存储状态；所有实际状态保存在 XR、子 ManagedResource 对象。控制器循环 reconcile，任何偏离模板都会被修复（漂移自愈）。
- Resources 模式无法循环生成不定数量资源（比如动态 N 个子网），这种场景必须上 Composition Function。
- 多 Composition 匹配策略：可以给 XR 打 label 选择匹配哪一个 Composition，实现同一个 XR 根据标签选择不同后端。
deletionPolicy: Orphan：删除 XR/Claim 时，保留云上真实资源，生产务必谨慎。- Patch 路径写错不会报错，只会字段不生效，排障看 crossplane pod 日志。
和 Helm 对比（很容易混淆）
- Helm：渲染出一堆 K8s 资源，交给 k8s api；不知道云资源，没有 reconcile 循环。
- Composition：模板生成 ManagedResource CRD 对象；Crossplane Provider 持续 reconcile 云上真实资源，持续状态对齐；可以抽象出全新的自定义 API（XRD）给外部调用，适合做企业内部 IaaS/PaaS 控制平面GitHub。
Helm 面向 K8s 应用；Crossplane Composition 面向基础设施控制平面抽象。
一句话总结
XRD 定义 “对外长什么样”，Composition 定义 “内部怎么实现”。用户提交高层 Claim，Composition 负责展开成一堆底层云资源，并且持续维护它们生命周期。
如果你需要，我可以给一个极简完整示例：XRD + Composition + Claim 完整可运行 yaml。