問(wèn)題現(xiàn)象

在開(kāi)發(fā)一個(gè)名為的 Operator 過(guò)程中，當(dāng)我執(zhí)行 （其底層是 ）來(lái)安裝CustomResourceDefinition (CRD) 時(shí)，終端拋出了一個(gè)錯(cuò)誤：

The CustomResourceDefinition "nova.batch.suknna" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes
make: *** [install] Error 1

這個(gè)錯(cuò)誤信息非常明確：CRD 的 metadata.annotations 字段總大小超過(guò)了 262144 字節(jié)的硬性限制。

概念厘清：注解、CSA 與三路合并的來(lái)龍去脈

要理解這個(gè)問(wèn)題，需要先弄清楚幾個(gè)關(guān)鍵概念。

1. annotations 是什么？

在 Kubernetes 中，注解是與對(duì)象關(guān)聯(lián)的鍵值對(duì)，用于存儲(chǔ)非標(biāo)識(shí)性的元數(shù)據(jù)。這些信息可以被工具、庫(kù)或控制器讀取，但 Kubernetes 自身不依賴它們來(lái)核心邏輯。

2. last-applied-configuration

當(dāng)使用 kubectl apply 命令時(shí)，默認(rèn)采用的是 客戶端應(yīng)用（Client-Side Apply, CSA） 模式。為了智能地計(jì)算用戶下一次 apply 時(shí)究竟需要修改哪些字段（而不是盲目覆蓋），kubectl 需要一個(gè)參照物。

它的解決方案是：將你上次通過(guò) apply 提交的整個(gè) YAML/JSON 文件內(nèi)容，完整地保存在一個(gè)名為的注解里。

這個(gè)過(guò)程依賴于三路合并：

• 舊狀態(tài)： last-applied-configuration 注解中的內(nèi)容。
• 當(dāng)前狀態(tài)：從 Kubernetes API 服務(wù)器獲取的資源當(dāng)前狀態(tài)。
• 新?tīng)顟B(tài)：用戶本次想要應(yīng)用的 YAML 文件。
  kubectl 會(huì)對(duì)比這三者，精確計(jì)算出需要修改、添加或刪除的字段。

3. 問(wèn)題原因

Kubebuilder 生成的 CRD 包含了非常詳盡的 OpenAPI 驗(yàn)證規(guī)則（即 spec.versions[*].schema）。這些規(guī)則本身就是一個(gè)極其龐大的 JSON 結(jié)構(gòu)。當(dāng)這個(gè)龐大的結(jié)構(gòu)被整個(gè)塞進(jìn) last-applied-configuration 注解時(shí)，注解的大小就很容易觸達(dá) 256KB 的天花板。

解決辦法

既然問(wèn)題的根源是 CSA 模式依賴于一個(gè)本地的、可能很大的注解，那么解決方案就是換用一種不依賴這個(gè)注解的模式。

服務(wù)端應(yīng)用（Server-Side Apply, SSA） 正是為此而生。

SSA 的核心思想：

• 所有權(quán)轉(zhuǎn)移：SSA 將字段管理的職責(zé)從客戶端轉(zhuǎn)移到了 API 服務(wù)器。
• 字段管理器：服務(wù)器會(huì)為每個(gè)字段記錄一個(gè)“管理者”。當(dāng)你聲明一個(gè)字段時(shí)，你就成為了它的管理者。
• 沖突解決：如果另一個(gè)管理者（比如另一個(gè)工程師或控制器）試圖修改你管理的字段，默認(rèn)情況下會(huì)產(chǎn)生沖突，需要明確指定 --force-conflicts 來(lái)覆蓋。

實(shí)施與效果：
切換到 SSA 非常簡(jiǎn)單，只需在 kubectl apply 命令后加上 --server-side 標(biāo)志。例如，修改你的 Makefile：

install: manifests kustomize ## Install CRDs into the K8s cluster specified in ~/.kube/config.
	$(KUSTOMIZE) build config/crd | $(KUBECTL) apply --server-side=true  -f -

執(zhí)行此命令后：

1. API 服務(wù)器接管了字段合并的職責(zé)。
2. 不再需要生成和存儲(chǔ)那個(gè)龐大的 last-applied-configuration 注解。
3. CRD 的元數(shù)據(jù)大小顯著減小，256KB 的限制自然就不再是問(wèn)題了。