kubectl apply 大型 CRD 报 annotations Too long：处理客户端配置注解

安装或更新 Prometheus Operator 的 CRD 时，其他对象已经创建，某个 CustomResourceDefinition 却报 metadata.annotations: Too long: must have at most 262144 bytes。若操作使用普通 kubectl apply，先检查客户端是否把整份 CRD 配置写进了 kubectl.kubernetes.io/last-applied-configuration 注解。

大型 schema 即使没有手写长注解，也可能在客户端 apply 生成这份副本后超过限制。可以评估改用 Server-Side Apply，但它引入字段所有权管理，已有对象不能只加一个开关就忽略冲突。以下采用 Kubernetes 1.22 及以后稳定的 Server-Side Apply 行为，具体 Operator 版本仍须与集群兼容。

限制的是所有注解的总字节数

262144 字节是对象注解键和值合计的上限，约为 256 KiB，并非 CRD 清单文件的固定大小限制。schema 本体、客户端附加的配置副本和其他注解，应分开检查。

确认本次提交的准确文件、命令和工具链。直接用 kubectl、经 Helm 渲染后再 apply、由 GitOps 控制器同步，实际管理方式可能不同。查看清单中的 metadata.annotations，判断是否含完整 JSON 配置或过长的业务数据。不要为了缩小文件，直接删除 schema 的字段和校验规则。

已有对象可用下面的只读检查示例查看注解与字段管理记录，CRD 名称需替换：

kubectl get crd prometheuses.monitoring.coreos.com \
  -o yaml --show-managed-fields

CRD 是集群级对象，不用命名空间区分。若对象从未创建成功，服务器上查不到它是正常结果，应检查准备提交的清单。输出可能很大，按内部配置资料保存，不要把完整内容贴进公开日志。

先预检，再用确定的管理身份提交

Server-Side Apply 将字段管理交给 API 服务器。下面是受控管理 CRD 的操作结构示例，文件名和 field-manager 名称需按实际管理流程确定，并在后续操作中保持一致：

kubectl apply --server-side --field-manager=debug-crds \
  --dry-run=server -f crd.yaml

kubectl apply --server-side --field-manager=debug-crds \
  -f crd.yaml

先运行预检并审阅结果，通过后才提交第二条。服务端 dry-run 不持久保存对象，但仍会向目标集群发送校验请求；确认当前上下文、权限与准入策略。示例只处理一份已核对的 CRD，不要把包含工作负载的大目录一起套上新管理方式。

这里显式采用非默认管理身份，避免依赖默认 kubectl 管理器为客户端 apply 兼容维护配置注解的行为。它也不会自动接管已有字段，迁移时可能出现冲突。若 CRD 已由 Helm 或 GitOps 管理，应优先在对应工具中启用支持的管理方式，不能另加一个管理器与它争夺字段。

提交清单本身若已经包含超长的 last-applied 注解，切换模式不会自动删掉那段文字。需要核对新清单和现有对象，按管理迁移方案处理旧注解；其他业务注解真的超限时，也要由其管理方调整存储方式。不能把 Server-Side Apply 当作放宽注解上限的开关。

冲突意味着有人正在管理这些字段

出现 field manager 冲突时，对照报错字段、现有 managedFields 和目标清单，判断是否提交了旧 schema，或正在覆盖另一个工具的改动。应先统一字段管理责任，而不是反复换管理器名字。

--force-conflicts 会覆盖冲突值并转移字段所有权。只有确认本次应接管这些字段、保存原配置、评估 Operator 兼容性后，才可作为审定迁移的一步。它不修复 schema 错误，也不能消除下一次控制器同步产生的争夺。

不要用“删除 CRD，再 create”处理生产更新。删除 CRD 会删除它保存的所有自定义对象，随后重建的定义不会自动恢复这些对象。监控工作负载可能因此受影响；仅为绕开配置注解上限，没有必要把已有资源置于这种风险中。

验收不只看 serverside-applied

变更前保存 CRD 清单、字段管理记录、相关自定义资源及部署配置。提交后确认目标 CRD 的版本与 schema 正确，Established 条件成立，相关自定义资源仍存在，Operator 能继续协调预期工作负载。只看到 apply 成功，不足以证明监控采集已经恢复。

后续同步也须继续使用审定的管理方式。若又退回客户端 apply，大型配置副本可能再次触发同一限制。回退前核对旧 schema 是否能容纳当前资源和版本，按对应产品的升级恢复流程操作；不能把重新启用旧客户端 apply 或直接删除定义当作无损回退。