Terraform更新kubectl_manifest时metadata.annotations超长报错解决

问题原因 #

Kubernetes对CustomResourceDefinition（CRD）的metadata.annotations总大小有严格限制，最多允许262144字节（256KB）。你通过HTTP拉取的CRD YAML文件中，注解内容超出了这个阈值，导致更新失败。

解决方案 #

1. 清理CRD中的冗余注解

直接移除CRD YAML中不必要的注解（比如自动生成的构建信息、冗余注释、非必需的版本标记等），可以通过Terraform的yamldecode和yamlencode配合修改：

data "http" "yaml_file" {
  url = var.crd_url
}

locals {
  crd_data = yamldecode(data.http.yaml_file.response_body)
  # 清空所有注解，如需保留特定注解，可改为指定键值对，例如：annotations = { "cert-manager.io/inject-ca-from" = local.crd_data.metadata.annotations["cert-manager.io/inject-ca-from"] }
  cleaned_crd = merge(local.crd_data, {
    metadata = merge(local.crd_data.metadata, {
      annotations = {}
    })
  })
}

resource "kubectl_manifest" "crd" {
  yaml_body         = yamlencode(local.cleaned_crd)
  wait              = true
  wait_for_rollout  = true
}

如果使用的是Prometheus Operator的CRD，也可以直接使用官方提供的精简版CRD，这类版本通常已经剔除了冗余注解。

2. 升级Terraform及kubectl provider版本

你当前使用的Terraform 0.14.2版本较老旧，对应的kubectl provider可能存在YAML处理逻辑冗余，导致额外添加不必要的注解。升级到Terraform 1.x系列稳定版本，并同步更新kubectl provider至最新兼容版本，可能会优化资源处理流程，避免注解膨胀。

3. 极端情况：拆分CRD（极少用到）

若清理注解后仍超出大小限制，可考虑拆分CRD的定义，但这种情况在Prometheus Operator的CRD场景中几乎不会出现，优先尝试前两种方案即可。

验证方法 #

修改代码后执行terraform plan，查看CRD的metadata.annotations字段内容及大小，确认未超过256KB限制后，再执行terraform apply完成更新。

内容的提问来源于stack exchange，提问作者Abdullah Khawer