Karpenter 升级指南:从 CRD 管理到 v1.14 全版本迁移实战手册

原创2026-09-16 16:23:591,992 阅读

Karpenter 升级指南:从 CRD 管理到 v1.14 全版本迁移实战手册

Karpenter 是一个运行在集群内的 Kubernetes 节点弹性伸缩控制器(Node Autoscaler),与 Cluster Autoscaler 不同,它并不绑定某个具体的 Kubernetes 版本,你可以沿用现有的升级机制来升级 Karpenter 本身,持续获得 bug 修复与新功能。本文以 v1.14 版本的官方升级指南为主体,系统梳理生产环境升级流程、CI/CD 流水线选型、CRD 升级的正确姿势,并逐版本列出从 v0.6.2 到 v1.14.0 的所有破坏性变更与操作要求,帮助你安全、平滑地完成 Karpenter 升级。

读完本文,你将掌握:如何设计一套可回滚的生产升级流程;如何通过独立 karpenter-crd Helm chart 管理与 Karpenter 强耦合的 CRD;以及升级到 v1.1.0(API 大版本切换)之前必须完成的迁移动作。

升级前的总体认知:Karpenter 与 Kubernetes 版本的解耦

Karpenter 是一个 controller,运行在集群内部,但它不像 Cluster Autoscaler 那样与特定 Kubernetes 版本绑定。因此升级 Karpenter 时,不需要与 Kubernetes 控制平面升级同步进行,只需使用你现有的插件(add-on)升级机制即可。

需要特别注意的是:自 Karpenter v1.0.0 发布起,官方已停止对 v0.36 及以下版本的支持。请尽快升级到最新版本,并持续保持 Karpenter 处于最新状态,以便及时获得 bug 修复与新特性。当前仓库中 charts/karpenter/Chart.yaml 与 charts/karpenter-crd/Chart.yaml 的版本均为 1.14.1,即本文写作时的最新主线版本。

生产环境升级的标准流程

Karpenter 承担着集群扩缩容与工作负载管理的关键职责,未经测试的升级可能导致节点供给失败、孤儿节点、工作负载中断,以及因失控扩缩容带来的成本问题。因此在生产环境升级 Karpenter 时,必须建立一套稳健的 CI/CD 流程,建议按照以下结构化步骤执行。

升级前验证(Pre-upgrade Validation)

  • 校验全部必需的 IAM 权限(节点角色 node role、控制器角色 controller role)
  • 检查 Webhook 配置
  • 备份现有 NodePool 与 NodeClass 配置
  • 记录当前版本与相关设置(方便回滚时对照)

预发环境准备(Staging Environment Setup)

  • 创建或确认预发(staging)环境可用
  • 更新 Helm values 或 manifests 中的版本标签
  • 配置自动化验证测试

预发部署(Staging Deployment)

  • 部署到预发环境
  • 运行全面测试,包括节点供给(node provisioning)测试
  • 验证控制器健康状态
  • 测试 NodePool 与 NodeClass 功能是否正常
  • 监控系统行为

生产审批与部署(Production Approval and Deployment)

  • 要求人工审批/评审
  • 如有必要,安排维护窗口
  • 执行生产部署
  • 监控部署进度
  • 验证所有组件功能正常

部署后(Post-Deployment)

  • 监控系统健康
  • 验证节点供给
  • 保留可用的回滚配置
  • 更新相关文档

CI/CD 流水线选型

以下是官方推荐的几类 CI/CD 流水线方案,每类都可以承载上述 Karpenter 升级工作流,最终选择应结合现有基础设施、团队技能栈以及自动化与集成的具体需求:

方案 适用场景
GitHub Actions 适合托管在 GitHub 的仓库,内置 Kubernetes 支持,配置简单
GitLab CI 容器原生的流水线,集成 Kubernetes 功能较强
ArgoCD 专为 Kubernetes GitOps 工作流设计
AWS CodePipeline 与 EKS 及 AWS 服务原生集成
Flux 开源的 Kubernetes GitOps 工具,具备自动部署能力

CRD 升级:Karpenter 升级中最容易被忽略的环节

Karpenter 随包发布若干 CustomResourceDefinitions(CRD)。这些 CRD 有两种发布方式:

方式一:独立 Helm chart karpenter-crd

CRD 以独立的 Helm chart karpenter-crd 发布(OCI 仓库地址为 oci://public.ecr.aws/karpenter/karpenter-crd),可由 Helm 管理 CRD 的完整生命周期。安装或升级 karpenter-crd 的命令如下:

KARPENTER_NAMESPACE=kube-system
helm upgrade --install karpenter-crd oci://public.ecr.aws/karpenter/karpenter-crd --version x.y.z --namespace "${KARPENTER_NAMESPACE}" --create-namespace

方式二:随 karpenter 主 chart 内置

CRD 也内置于 karpenter 主 chart 的 crds 目录 中。但注意:Helm 不会通过这种方式管理 CRD 的生命周期——它只会在 chart 首次安装时安装 CRD,后续的 chart 升级不会新增或删除 CRD,即使 CRD 已经发生变化。

官方推荐做法

由于 CRD 与 Karpenter 版本强耦合,应随 Karpenter 一起更新,官方建议使用独立的 karpenter-crd chart 来管理 CRD。以 v1.14.0 为例,该版本新增了 autoscaling.x-k8s.io_capacitybuffers CRD,其定义文件位于仓库 charts/karpenter/crds/autoscaling.x-k8s.io_capacitybuffers.yaml;如果你使用独立 karpenter-crd chart,务必与控制器一起升级,否则新 CRD 不会被安装。

常见故障:invalid ownership metadata

如果从旧版本 Karpenter 安装 karpenter-crd chart 时遇到 invalid ownership metadata; label validation error: 错误,说明集群中已存在的 CRD 缺少 Helm 所需的属主标签/注解(例如此前通过 kubectl replace 或主 chart 安装过 CRD)。处理方式参见 troubleshooting 文档:

# 缺少 managed-by 标签时
kubectl label crd ec2nodeclasses.karpenter.k8s.aws nodepools.karpenter.sh nodeclaims.karpenter.sh nodeoverlays.karpenter.sh app.kubernetes.io/managed-by=Helm --overwrite

# 缺少 release 注解时
KARPENTER_NAMESPACE=kube-system
kubectl annotate crd ec2nodeclasses.karpenter.k8s.aws nodepools.karpenter.sh nodeclaims.karpenter.sh nodeoverlays.karpenter.sh meta.helm.sh/release-name=karpenter-crd --overwrite
kubectl annotate crd ec2nodeclasses.karpenter.k8s.aws nodepools.karpenter.sh nodeclaims.karpenter.sh nodeoverlays.karpenter.sh meta.helm.sh/release-namespace="${KARPENTER_NAMESPACE}" --overwrite

分版本升级指南

升级前请先阅读 兼容性文档,确认目标 Karpenter 版本与你的 Kubernetes 版本兼容(例如 Karpenter 1.13+ 才支持 Kubernetes 1.36)。以下按版本从新到旧列出所有注意事项。

升级到 1.14.0+

警告:Karpenter 1.1.0 起不再支持 v1beta1 API。在升级到 1.1.0 及以上版本前,必须先完成 v1 迁移指南 中要求的迁移动作。

  • Capacity Buffers API 毕业到 v1beta1:该版本将 CapacityBuffers API 升级到 v1beta1,并随包发布新的 autoscaling.x-k8s.io_capacitybuffers CRD(见 charts/karpenter/crds/autoscaling.x-k8s.io_capacitybuffers.yaml)。如果使用独立 karpenter-crd chart,请随控制器一起升级以安装新 CRD(参见上文 CRD 升级章节)。在 charts/karpenter/values.yaml 中,该功能由 settings.featureGates.capacityBuffer(ALPHA,默认关闭)控制。
  • 新增 Dynamic Resource Allocation(DRA)支持:包括可消费容量(consumable capacity)与可分区设备(partitionable devices)。该能力是增量式的,现有 NodePool 无需任何配置变更。
  • 新增 Balanced 合并(consolidation)策略:现有使用 WhenEmptyOrUnderutilized 的 NodePool 不受影响,除非主动选用新策略。
  • 新增 preview 实例类型支持:允许 Karpenter 考虑尚无公开定价数据的实例类型。该能力由现有 NodeOverlay feature gate 控制,属于 opt-in 特性。
  • 无破坏性变更 🎉

完整变更日志可分别查看 karpenter-provider-aws 与 kubernetes-sigs/karpenter 的 v1.14.0 发布说明。

升级到 1.13.0+

  • 无破坏性变更 🎉(同样需先完成 v1beta1 → v1 API 迁移)

升级到 1.12.0+

  • CA bundle 漂移检测:新增对 CA bundle 的 drift 检测,更新后的哈希逻辑会将现有节点标记为 drifted。
  • AWS Application Recovery Controller Zonal Shift 支持:该特性为 opt-in,默认关闭,需要新增 arc-zonal-shift:GetManagedResource IAM 权限(见 cloudformation.yaml)。启用方式参考 Getting Started 的 Zonal Shift Onboarding 章节。当前 charts/karpenter/values.yaml 中对应配置为 settings.enableZonalShift: false。
  • 新增必需的 ec2:DescribeInstanceStatus 权限:用于 interruption controller 中的 EC2 实例状态健康检查(见 cloudformation.yaml)。升级前需要更新 Karpenter 控制器角色的 IAM 策略。

升级到 1.11.0+

  • placement group 相关 IAM 权限新增(用于支持放置组,见 cloudformation.yaml):
    • 在 AllowRegionalReadActions 中新增 ec2:DescribePlacementGroups 动作
    • 在 AllowScopedEC2InstanceAccessActions 中新增 arn:${AWS::Partition}:ec2:${AWS::Region}:*:placement-group/* 资源
  • 如果你使用了放置组(placement groups),需要更新 Karpenter 控制器角色。

升级到 1.10.0+

  • EventBridge 规则新增 detail-type:用于捕获 Capacity Reservation Instance Interruption 警告。如果你使用可中断的 ODCR(On-Demand Capacity Reservations),需要更新 EventBridge 规则以加入该 detail-type。

升级到 1.9.0+

  • IAM 策略拆分为 5 个独立策略:如果你依赖 Getting Started 指南 CloudFormation 模板创建的 IAM 策略,需要更新 IAM 角色以挂载全部 5 个策略。自 1.8 以来策略授予的权限本身没有变化。

升级到 1.8.0+

警告:v1.8.4 存在回归问题,可能导致 Karpenter 无法调度带有特定 TopologySpreadConstraint 配置的 Pod,请勿升级到该版本。

  • 新增 Static Capacity 支持:使用该特性前必须同步升级 Karpenter 的 CRD。

升级到 1.7.0+

  • Instance profile 路径变化:Karpenter 现在以特定路径结构 /karpenter/{region}/{cluster-name}/{nodeclass-uid}/ 创建 instance profiles,取代原先的根路径 /。该变化有助于更好地组织和管理 instance profiles。已有 instance profiles 无需处理,新创建的将使用新路径。
  • 新增 IAM 权限:控制器角色需要新增 iam:ListInstanceProfiles 权限。
  • 指标重命名:karpenter_pods_pods_drained_total 更名为 karpenter_pods_drained_total;karpenter_nodeclaims_disrupted_total 的 reason 标签 liveness 更名为 registration_timeout。
  • 显式忽略带 ResourceClaim 请求的 Pod:旧版本 Karpenter 不了解该字段也会忽略这类请求。当前版本 Karpenter 尚不支持 DRA。

升级到 1.6.0+

  • 原生 ODCR 支持毕业到 beta 并默认启用。

    警告(使用 open ODCR 用户的破坏性变更):如果你使用 open 实例资格的 ODCR,但未在 EC2NodeClass 上设置 spec.capacityReservationSelectorTerms,升级后 Karpenter 将不再使用这些预留容量,回退到 on-demand——预留容量会被闲置但仍产生计费。请在升级前配置好,参见 原生 ODCR 支持指南。

  • 新增 MinValuesPolicy 配置:控制 Karpenter 调度器如何处理 min values。取值 Strict(min values 无法满足时调度失败)或 BestEffort(无法满足时放宽 min values)。默认为 Strict,以保持既有行为(见 charts/karpenter/values.yaml)。
  • 新增 DisableDryRun 配置(1.6.2+):禁用 EC2NodeClass 校验期间执行的 dry run 调用(见 charts/karpenter/values.yaml)。

升级到 1.5.0+ 与 1.4.0+

  • 均为无破坏性变更 🎉

升级到 1.3.0+

  • 指标重命名:alpha 指标 karpenter_ignored_pod_count 更名为 karpenter_scheduler_ignored_pod_count。
  • 新增 capacity-type 取值 reserved:启用 ReservedCapacity feature gate 后,Karpenter 引入新的 karpenter.sh/capacity-type 取值(reserved)。任何通过 nodeSelector 显式选择 on-demand 并希望利用 ODCR 容量的应用,可能需要改用 nodeAffinity 以同时选择 reserved 与 on-demand 容量。

升级到 1.2.0+

  • 指标 reason 标签由 camelCase 改为 snake_case:karpenter_voluntary_disruption_queue_failures_total 与 karpenter_nodeclaims_disrupted_total 的 reason 标签值相应更新:Drifted -> drifted、Empty -> empty、Expired -> expired、Underutilized -> underutilized。
  • NodeClass 控制器合并:nodeclass.status 与 nodeclass.termination 控制器合并为单一 nodeclass 控制器。如果你依赖这两个控制器的日志或指标,请更新为引用新的 nodeclass 控制器。

升级到 1.1.0+

警告:Karpenter 1.1.0 移除对 v1beta1 API 的支持,不要在完成迁移前升级。详见 v1 迁移指南。

  • 移除 v1beta1 兼容注解的支持:升级前必须完成迁移,详见 kubelet 配置迁移章节。
  • nodeClassRef.group 与 nodeClassRef.kind 成为必填项:升级前确保所有 NodePool / NodeClaim 都设置了这两个值(参见 v1 迁移指南 中的相关说明)。
  • Bottlerocket AMIFamily 支持 instanceStorePolicy: RAID0:指定该值时 Karpenter 会自动生成 userData 对实例存储卷做 RAID0(与 AL2、AL2023 行为一致)。

    注意:该 userData 配置仅在 Bottlerocket v1.22.0+ 上有效。若使用更早版本的 Bottlerocket 镜像(< v1.22.0)并配置 amiFamily: Bottlerocket 与 instanceStorePolicy: RAID0,节点将无法加入集群。

  • Neuron 加速器标签值修正:karpenter.k8s.aws/instance-accelerator-name 标签值现在反映正确的名称:trainium、inferentia、inferentia2。此前所有 Neuron 加速器都使用 inferentia。
  • 移除内部标签 karpenter.k8s.aws/cluster:该标签曾用于 launch template 管理,现改用 eks:eks-cluster-name,与其他 Karpenter 供给的资源保持一致。
  • 通用 operator 指标被废弃,由资源专属指标替代。

升级到 1.0.0+

警告:Karpenter 1.0.0 引入 v1 API,并使用 conversion webhooks 支持现有 v1beta1 API。不要在未完成迁移的情况下升级,请先阅读 v1 迁移指南。

完整变更日志请参见 v1 迁移指南的 Changelog 章节。

升级到 0.37.0+

警告:0.33.0 及以上版本只支持 Karpenter v1beta1 API,无法与现有的 Provisioner、AWSNodeTemplate 或 Machine alpha API 一起工作。不要直接升级到 0.37.0+,应先升级到 0.32.x,该版本同时支持 alpha 与 beta API,可以在无停机的情况下完成全部 API 迁移。

注意:自 0.37.3 起 Webhooks 默认重新启用,以方便迁移到 v1.0。如果集群的网络策略阻止 Ingress,需要放行端口 8000、8001、8081、8443。你也可以继续通过 Helm chart 选择禁用 webhooks。

  • EC2NodeClass 新增 readiness 状态条件:升级前务必先升级 CRD,否则 Karpenter 将无法供给新节点。
  • 日志记录器命名变化:Karpenter 不再在创建 controller logger 时更新 logger 名称,改为遵循 controller-runtime 标准——logger 名称固定为 "logger": "controller",控制器名称存入结构化字段 "controller"。
  • NodeClass 控制器命名拆分:nodeclass -> nodeclass.status、nodeclass.hash、nodeclass.termination。
  • NodeClaim 状态条件不再包含 severity 字段。

升级到 0.36.0+

警告(回滚限制):v0.36.x 引入了限制回滚的 drift 更新。从 >=v0.36.0 回滚时,只有 v0.32.9+、v0.33.4+、v0.34.5+、v0.35.4+ 这些补丁版本支持回滚。如果回滚到更早的补丁版本,Karpenter 可能 drift 集群中的所有节点。

注意:自 0.36.5 起 Webhooks 默认重新启用(端口与上节相同)。

  • 指标重命名:karpenter_cloudprovider_instance_type_price_estimate 更名为 karpenter_cloudprovider_instance_type_offering_price_estimate,与新增的 karpenter_cloudprovider_instance_type_offering_available 指标对齐;同时移除了 region 标签(可从 Karpenter 运行环境推断)。

升级到 0.35.0+

注意:自 0.35.8 起 Webhooks 默认重新启用(端口与上节相同)。

  • OCI 标签与 Helm chart 版本改为合法语义化版本:git tag 中的 v 前缀被移除,格式统一为 x.y.z。

升级到 0.34.0+

警告:Ubuntu EKS 优化 AMI 已针对 Kubernetes 1.29+ 从 20.04 迁移到 22.04。依赖 Ubuntu AMI family 的 AMI 自动发现用户暂不支持该新 AMI 版本。如果使用 Ubuntu AMI family,请在升级到 Kubernetes 1.29 前仔细评估;不做任何 EC2NodeClass 修改直接升级到 1.29 会导致 Karpenter 无法创建新节点。

注意:自 0.34.9 起 Webhooks 默认重新启用(端口与上节相同)。

  • 新增 nodepool.spec.disruption.budgets:允许控制集群中的 disruption 速度。由于需要更新 CRD,升级前应重新应用新 CRD。参见 Disruption Budgets。
  • Disruption 并行度变化:使用 Disruption Budgets 后,Karpenter 会同时处理多个批次节点的 disruption,集群整体缩容更快。0.34.0 之前每种 disruption 类型都有硬编码的并行度上限;0.34.0+ 对给定 NodePool 最多同时 disruption 10% 的节点。没有设置能与 0.34.0 之前行为完全等价。参考旧版本限制:
    • Empty Expiration / Empty Drift / Empty Consolidation:无限并行
    • Non-Empty Expiration / Non-Empty Drift / Single-Node Consolidation:一次一个节点
    • Multi-Node Consolidation:最多 100 个节点
  • 核心控制器重大变更:为支持 Disruption Budgets,Karpenter 核心控制器发生变化,可同时考虑多个 disruption 批次,性能提升的同时 Karpenter Pod 的 CPU 与内存占用可能上升。升级到 0.34.0+ 后,可能需要增加 Karpenter 控制器 Pod 的资源配额。
  • 新增默认 podSecurityContext:配置卷的 fsgroup: 65536。如果使用 sidecar 容器,请检查该配置是否兼容。可通过 --set podSecurityContext=null 禁用。
  • dnsPolicy 改回 ClusterFirst:此前的 Default(注意:这并非 Kubernetes 集群默认值)给 IPv6 双栈集群或依赖集群服务的用户(如 service mesh)带来困惑。该变更可能影响 Fargate 或 MNG 上由 Karpenter 管理集群内 DNS 服务(多数集群为 core-dns)的用户。如需旧行为,可通过 --set dnsPolicy=Default 恢复。
  • 禁止设置 nodepool.spec.template.spec.resources:webhook 校验此前就不允许该字段,现在 CEL 校验也明确禁止。若之前设置了该字段,升级前务必移除,否则资源更新会失败。

升级到 0.33.0+

注意:自 0.33.8 起 Webhooks 默认重新启用(端口与上节相同)。

  • 移除 karpenter.sh/provisioner-name 标签支持:NodePool labels/requirements 或应用侧的 nodeSelector、affinity、topologySpreadConstraints 中如仍使用该标签,请先改用 karpenter.sh/nodepool 标签,否则升级后可能出现 Pod 调度失败。
  • spot-instances-request 增加打标签:现在与实例、卷、主 ENI 使用相同的标签。需要为控制器策略新增 ec2:CreateTags 对 spot-instances-request 的权限,并可进一步通过 ec2:RunInstances 动作的 scoping 要求携带这些标签。
  • 建议将安装命名空间设为 kube-system:将 Karpenter 标识为关键集群组件,使其请求获得更高优先级(不同的 PriorityLevelConfiguration)。注意:更改命名空间会导致 service account 命名空间变化;如果使用 IRSA 认证,需要把控制器 trust policy 的 scope 从 karpenter:karpenter 改为 kube-system:karpenter。
  • 弃用 webhook,改用 CEL 校验:Kubernetes >= 1.25(EKS 1.25 默认启用 CEL 校验)无需额外操作;低于 1.25 时需设置 DISABLE_WEBHOOK=false 环境变量或 --set webhook.enabled=true。
  • 移除 karpenter-global-settings ConfigMap 传参:改为通过 Karpenter deployment manifest 中的容器环境变量传参。
  • Drift=true 默认启用(FEATURE_GATES):如果此前未启用该 feature gate,升级后 Karpenter 将检查 NodePool 声明的期望状态与节点实际状态的差异。参见 Drift 概念文档。
  • 不再通过 ConfigMap 查找 zap-logger-config:如使用 Zap 日志配置,需挂载到文件系统。可通过 --set logConfig.enabled=true 启用(默认关闭)。若在 0.32.x 设置了 logConfig 相关值(如 logConfig.logEncoding),升级后需显式设置 logConfig.enabled=true。Zap 日志配置为 beta 期废弃功能,计划在 v1 移除。
  • 默认 LOG_LEVEL 从 debug 改为 info。
  • 移除 SubnetSelectorTerm、SecurityGroupsSelectorTerm、AMISelectorTerm 的逗号分隔列表支持:现在每个 selector 支持多个 term,可用独立 term 表达更明确的 OR 约束。

升级到 0.32.0+

警告:0.32.0 引入 v1beta1 API,对 API 与安装流程有重大变更。不要直接升级,请参照 v1beta1 迁移升级流程。该版本同时支持 alpha 与 beta API,可将现有 Provisioner、AWSNodeTemplate、Machine alpha API 平滑迁移到 NodePool、EC2NodeClass、NodeClaim beta API。注意:升级到 0.32.0 后如需回滚,只有 0.31.4 支持在集群中已部署 v1beta1 API 的情况下回滚。

  • 设置项更名:settings.InterruptionQueue 取代 settings.aws.InterruptionQueueName,CLI 参数也改为 --interruption-queue。
  • Webhook metrics 端口改为 8001:如果该端口已被占用或运行在 hostNetworking 模式,可通过 WEBHOOK_METRICS_PORT 环境变量或 Helm 值 webhook.metrics.port 修改。
  • 支持通过 webhook.enabled=false 禁用 webhooks:会同时禁用 webhook server 并阻止向集群部署任何权限、mutating/validating webhook 配置。
  • Zap logger 配置全部移入 logConfig values 块(已废弃,v1 将移除)。Karpenter 现在仅通过 logLevel Helm 值暴露日志级别;如需更精细的日志解析配置,建议让日志解析器直接处理 Karpenter 的 Zap JSON 日志。
  • 默认日志编码从 console 改为 json:若之前未显式设置日志编码,默认值会随 Helm chart 变化。logEncoding 值在 0.33.x 前仍可用,但已废弃,建议改用 logConfig.logEncoding。
  • 节点 disruption taint 变化:Karpenter 现在使用 karpenter.sh/disruption:NoSchedule=disrupting taint,取代上游的 node.kubernetes.io/unschedulable taint,防止 Pod 调度到正在 disruption 的节点。之前容忍 node.kubernetes.io/unschedulable 的 Pod(最典型的是默认带该 toleration 的 DaemonSet)现在会在终止时被驱逐。如需 Pod 在缩容时不被驱逐,请为其添加 toleration:
tolerations:
  - key: karpenter.sh/disruption
    effect: NoSchedule
    operator: Equals
    value: disrupting

注意:对于使用 Provisioner 供给的节点,Karpenter 仍会使用旧的 node.kubernetes.io/unschedulable taint。

升级到 0.31.0+

  • securityContext 约束范围变化:从 pod 级改为仅应用于 Karpenter 容器。如果之前依赖 pod 级 securityContext 配置 sidecar 容器,现在需要在 sidecar 容器配置中显式设置这些值。

升级到 0.30.0+

  • 静态 drift 支持扩展:Karpenter 现在会对 Provisioner 与 AWSNodeTemplate 字段做静态 drift。Provisioner 静态 drift 要求 Provisioner 与 Machine 上都有 karpenter.sh/provisioner-hash 注解;AWSNodeTemplate drift 要求 AWSNodeTemplate 与 Machine 上有 karpenter.k8s.aws/nodetemplate-hash 注解。Karpenter 不会为存量节点自动添加这些注解,因此每个节点需要被回收一次才能补上注解。
  • selector 组合校验:AWSNodeTemplate 与 Provisioner spec.provider 中,amiSelectors、subnetSelectors、securityGroupSelectors 不能再同时设置 id 选择器(aws-ids、aws::ids)与其他选择器,否则校验失败。
  • 静态设置 securityContext:在 pod 级与容器级同时静态设置,不允许通过 Helm chart 传值覆盖,以符合 Restricted Pod Security Standard 加固最佳实践。

    注意:如果 sidecar 容器无法容忍 pod 级 securityContext 约束,需要在 deployment 中为 sidecar 显式指定 securityContext 覆盖。

升级到 0.29.0+

警告:Karpenter 0.29.1 存在文件描述符与内存泄漏 bug,达到限制后会导致 Karpenter 被 OOMKilled 并重启。0.29.2+ 修复了该泄漏。

  • 默认端口调整:默认 metrics 服务端口从 8080 改为 8000,默认 webhook 服务端口从 443 改为 8443。端口由 Helm 值 controller.metrics.port 与 webhook.port 控制,如果之前设置了非默认值,需要同步更新 Prometheus scraper。
  • 新增 Security Group 与 Subnet drift 检测:如果 AWSNodeTemplate 的安全组与实例实际使用的安全组不一致,或实例使用的子网不在 AWSNodeTemplate 允许列表中,Karpenter 都会视为 drift。由于 Karpenter 通过标签发现 Subnet 与 SecurityGroup,请查看 Threat Model 了解如何管理相关 IAM 权限。

升级到 0.28.0+

警告:0.28.0 与 Kubernetes 1.26+ 不兼容(默认 --cloudprovider=external 时可能导致额外扩缩容),0.28.1+ 修复。

  • 移除 extraObjects Helm 值:该值在多数安装场景中无效,且容易形成反模式。官方建议如需随 chart 安装 Karpenter 相关 manifests,请单独创建 chart 并依赖控制器 chart。
  • 移除 aws.nodeNameConvention 设置:Karpenter 通过 Machine 编排容量后不再需要节点名称。Karpenter 会忽略 karpenter-global-settings ConfigMap 中不认识的配置,保留该键只会被忽略。
  • 新增"受限标签"(restricted tags):以下标签不允许通过 AWSNodeTemplate 或 karpenter-global-settings 自定义覆盖,否则 webhook 校验失败:
    • karpenter.sh/managed-by
    • karpenter.sh/provisioner-name
    • kubernetes.io/cluster/${CLUSTER_NAME}
  • 指标语义变化(基于 Machine 资源的引入):
    • karpenter_nodes_terminated:如需按原因查看 Machine 删除,请使用 karpenter_machines_terminated;前者现在只统计节点终止数量,无附加标签
    • karpenter_nodes_created:同理,改用 karpenter_machines_created
    • karpenter_deprovisioning_replacement_node_initialized_seconds 被 karpenter_deprovisioning_replacement_machine_initialized_seconds 取代
  • 引入 Machine CustomResource:Karpenter 通过集群内的 Machine 自定义资源编排 CloudProvider 容量。执行调度决策时创建 Machine,进而启动 CloudProvider 容量,kubelet 随后将节点注册到集群。
    • 注意 Helm 不会自动升级/安装新 CRD,请按上文 CRD 升级章节操作
    • Karpenter 启动时会为存量容量"水合"(hydrate)Machine:通过 CloudProvider 容量上的 karpenter.sh/provisioner-name 标签或节点上的同名标签发现旧版本供给的容量
  • metrics 端口 8080 → 8000:直接抓取 Pod 指标(而非通过 service)的用户需要改用端口 8000。

    警告:Karpenter 使用以下标签键维护 CloudProvider 机器与集群内 CR 的映射:karpenter.sh/managed-by、karpenter.sh/provisioner-name、kubernetes.io/cluster/${CLUSTER_NAME}。拥有这些标签创建/删除权限的用户可借此编排 Karpenter 创建/删除机器,请对照 Threat Model 评估影响。 回滚提示:升级到 0.28.0+ 后回滚到旧版本仍可正常运行,但集群中会残留 Machine CR,需手动删除 Machines 并移除 finalizers。Karpenter 使用 karpenter-sh/managed-by 标签标记"由某 Machine 管理"的容量;如果执行"升级→回滚→再次升级"的流程,务必先移除存量容量上的 karpenter.sh/managed-by 标签,否则 Karpenter 会因缺少对应 Machine CR 而回收这些容量。

升级到 0.27.3+

  • 移除 defaulting.webhook.karpenter.sh mutating webhook:如果该 webhook 不是由 Helm 管理,可能需要手动删除残留的 webhook:
kubectl delete mutatingwebhookconfigurations defaulting.webhook.karpenter.sh

升级到 0.27.0+

  • 控制器 Pod 默认启用 kubernetes.io/hostname 自反亲和:HA 模式下如果节点数不足以匹配副本数,需要先扩容节点。
  • 指标命名空间迁移:karpenter_metricscraper_...、karpenter_deprovisioning_...、karpenter_provisioner_...、karpenter_interruption_... 移入 controller_runtime 指标命名空间。
  • controller 标签值更名:podmetrics -> pod_metrics、provisionermetrics -> provisioner_metrics、metricscraper -> metric_scraper、provisioning -> provisioner_trigger、node-state -> node_state、pod-state -> pod_state、provisioner-state -> provisioner_state。
  • 指标重命名:karpenter_allocation_controller_scheduling_duration_seconds 更名为 karpenter_provisioner_scheduling_duration_seconds。

升级到 0.26.0+

  • karpenter.sh/do-not-evict 注解语义变化:不再阻止 kubectl delete node 触发的节点终止,只阻止 Karpenter 判定为"自愿"(可避免)的 disruption,如 spot 中断与手动删除节点这类"非自愿" disruption 会忽略该注解。参见 禁用 Deprovisioning。
  • 移除控制器默认资源 requests/limits:如果未在 Helm values 中自定义资源配额且依赖默认值,升级后需要自行设置。
  • controller.image 值改为 map:拆分为 controller.image.repository、controller.image.tag、controller.image.digest,手动覆盖需更新配置。

升级到 0.25.0+

  • Cluster Endpoint 支持自动发现:使用 EKS 时可省略配置中的 clusterEndpoint 字段,但需要在 Karpenter 控制器 IAM 角色上添加 eks:DescribeCluster 权限。

升级到 0.24.0+

  • 设置不再动态更新:手动修改 karpenter-global-settings ConfigMap 后,需要重启 deployment 使配置生效:kubectl rollout restart -n karpenter deploy/karpenter。
  • 移除内部实例类型过滤:此前 g2(NVIDIA device plugin 不支持)与 FPGA 实例类型会被过滤,现在只能通过 provisioner 或 Pod 上的 well-known 节点标签设置 requirements 过滤。参见选择节点。
  • aws.tags 成为顶层字段:karpenter-global-settings ConfigMap 中该键的值需要是 string-to-string 的 JSON 对象,取代旧版通过 aws.tags.<key>: value 隐式提供键值对的方式。

升级到 0.22.0+

  • 要求 Kubernetes >= v1.21:不再支持 K8s v1.20,改为支持 v1.25。原因在于 v1 PDB API 于 K8s v1.20 引入,v1beta1 API 在 K8s v1.25 被移除。

升级到 0.20.0+

  • 移除实例类型类别优先逻辑:0.20.0 前,Karpenter 在无 requirements 时会优先选择某些实例类别("m"、"c"、"r"、"a"、"t"、"i"),0.20.0+ 移除了该逻辑。裸金属与 GPU 实例类型仍会被降级优先,仅在无其他兼容实例类型时使用。由于 Karpenter 不再优先任何实例类型,若不想使用冷门实例类型且未使用运行时默认值,需要在 Provisioner 中显式指定。

升级到 0.19.0+

  • webhook 与 controller 容器合并为单一二进制:Helm chart 需要相应调整;若当前安装方式自定义了 karpenter webhook,部署工具可能需要小幅修改。
  • 原生中断处理支持:如果此前使用 Node Termination Handler 处理 spot 中断与健康事件,需要在启用 aws.interruptionQueueName 前移除该组件。参见 Interruption 文档。
  • 实例类别默认值显式持久化:默认情况下 Provisioner 限制实例类别为 c、m、r;任何实例类型约束都会覆盖该默认。旧 Provisioner 若未约束实例类型/家族/类别,现在会更灵活地使用实例类型。
  • CRD 原始 YAML URL 迁移:静态引用 CRD 或依赖 kubectl replace -f 从远端应用 CRD 的用户,需要迁移到新路径(对应版本的 charts/karpenter/crds/... 目录)。
  • 无 ownerRef 的 Pod 默认会被驱逐:终止与 consolidation 期间,"controllerless"/"naked" Pod 默认会被驱逐,可通过添加 karpenter.sh/do-not-evict: "true" 注解阻止自愿 disruption。
  • CLI/环境变量迁移为 ConfigMap 设置(以下选项已移除,改用 karpenter-global-settings ConfigMap 动态读取):
    • CLUSTER_NAME -> settings.aws.clusterName
    • CLUSTER_ENDPOINT -> settings.aws.clusterEndpoint
    • AWS_DEFAULT_INSTANCE_PROFILE -> settings.aws.defaultInstanceProfile
    • AWS_ENABLE_POD_ENI -> settings.aws.enablePodENI
    • AWS_ENI_LIMITED_POD_DENSITY -> settings.aws.enableENILimitedPodDensity
    • AWS_ISOLATED_VPC -> settings.aws.isolatedVPC
    • AWS_NODE_NAME_CONVENTION -> settings.aws.nodeNameConvention
    • VM_MEMORY_OVERHEAD -> settings.aws.vmMemoryOverheadPercent

升级到 0.18.0+

  • consolidation 指标合并:移除 karpenter_consolidation_nodes_created 与 karpenter_consolidation_nodes_terminated,改用更通用的 karpenter_nodes_created 与 karpenter_nodes_terminated,可通过指标上的 reason 标签区分 consolidation 行为。全部指标参见 Metrics 参考文档。

升级到 0.17.0+

  • Helm chart 迁移到 OCI registry:chart 现存放于 oci://public.ecr.aws/karpenter/karpenter,需要 Helm CLI v3.8.0+。旧的 charts.karpenter.sh 不再更新(仅保留旧版本)。脚本化安装/升级需调整:
    1. 无需再执行 helm repo add 添加仓库
    2. 使用 helm CLI 时必须提供 chart 的完整 URL
    3. 如果此前版本号不带 v 前缀(如 0.17.0),OCI chart 需要加上 v(如 v0.17.0)

升级到 0.16.2+ / 0.16.0+ / 0.15.0+ / 0.14.0+

以下版本均为 provisioners.karpenter.sh v1alpha5 CRD 或 AWSNodeTemplate CRD 新增字段,需要手动更新 CRD(Helm 不管理 CRD 生命周期),使用 kubectl replace -f <对应版本 charts/karpenter/crds 目录下的 CRD 文件> 应用即可:

  • 0.16.2:新增 kubeletConfiguration 字段
  • 0.16.0:新增 weight 字段
  • 0.15.0:新增 consolidation 字段
  • 0.14.0:Provisioner 与 AWSNodeTemplate CRD 均新增字段

此外 0.14.0 还有以下变化:

  • launch template 发现方式改为标签:旧命名方案 Karpenter-${CLUSTER_NAME}-* 可能与用户自建 launch template 冲突,新方案使用标签 karpenter.k8s.aws/cluster: ${CLUSTER_NAME}。Karpenter 不会清理旧命名方案的动态 launch template,可手动清理:
## 查找符合命名模式且不需要保留的 launch templates
aws ec2 describe-launch-templates --filters="Name=launch-template-name,Values=Karpenter-${CLUSTER_NAME}-*"

## 删除符合名称但没有 "karpenter.k8s.aws/cluster" 标签的 launch template
aws ec2 delete-launch-template --launch-template-id <LAUNCH_TEMPLATE_ID>
  • 新增实例类型过滤:当 provisioner 上没有 node.kubernetes.io/instance-type、karpenter.k8s.aws/instance-family、karpenter.k8s.aws/instance-category 约束时,Karpenter 会过滤掉裸金属与部分非当前世代实例类型。显式指定实例类型/家族列表时按列表执行,也可通过添加 Exists requirement 完全取消过滤:
  - key: node.kubernetes.io/instance-type
    operator: Exists
  • 支持免 launch template 的自定义 AMI:需要为控制器角色添加 ec2:DescribeImages 权限。参见 Custom AMI 文档。
  • 新增默认 toleration CriticalAddonOnly=Exists:可能导致 Karpenter 调度到此前不可调度的带该 taint 的节点,可通过 --set tolerations[0]=null 覆盖。
  • 废弃 AWS_ENI_LIMITED_POD_DENSITY 环境变量:改用 Provisioner 上的 spec.kubeletConfiguration.maxPods;未设置 maxPods 时旧变量仍生效,设置了则覆盖。

升级到 0.13.0+

  • 新增 AWSNodeTemplate CRD:原本写在 Provisioner spec.provider 下的 AWS 云提供商参数,现在都可以写在 AWSNodeTemplate 的 spec 中。spec.provider 已废弃但会继续工作以保持 v1alpha5 API 向后兼容。同时支持无需自定义 launch template 的自定义 user data,可直接写在 AWSNodeTemplate 资源中。
    • 若从 0.10.1 - 0.11.1 升级,注意 awsnodetemplate CRD 曾在 0.12.0 更名为 awsnodetemplates,需手动完成 CRD 升级:保存 manifests → kubectl delete crd awsnodetemplate → 应用新版 CRD YAML → 升级 Karpenter → 重新应用保存的 manifests。
  • 新增 EC2/spot 价格获取:升级后需为控制器策略添加 pricing:GetProducts 与 ec2:DescribeSpotPriceHistory 权限(可见于 cloudformation.yaml 中的权限清单)。

升级到 0.12.0+

  • 为每个节点添加 OwnerReference:此前删除 provisioner 会遗留孤儿节点;现在删除 provisioner 会触发 Kubernetes 级联删除逻辑,通过 Karpenter 节点 finalizer 优雅终止节点(移除 owner reference 仍可能导致孤儿节点)。
  • 从 0.10.1 - 0.11.1 升级时的 awsnodetemplate → awsnodetemplates CRD 更名步骤同上。

升级到 0.11.0+

  • vpc.amazonaws.com/pod-eni 资源报告方式变化:不再为所有支持该资源的节点报告(无论集群是否启用),改为由命令行 flag 或环境变量控制,默认关闭。若集群使用安全组用于 Pod(security groups for pods),需通过 Helm 值 controller.env 设置环境变量 AWS_ENABLE_POD_ENI=true。
  • 扩展资源由设备插件注册:其他扩展资源(如 nvidia.com/gpu)由各自设备插件(通常以 DaemonSet 安装)注册,Karpenter 不再在节点创建时注册这些资源,Pod 不会在设备插件初始化完成前绑定到节点。
  • 新增 providerRef 字段:使用该字段需手动替换 Provisioner CRD(kubectl replace -f <对应版本 CRD 文件>)。

升级到 0.10.0+

  • 新增 startupTaints 字段:标准 Helm 升级不会升级 CRD,需要先手动应用新 CRD(kubectl replace -f <对应版本 CRD 文件>)。

    如果不手动更新 CRD,Karpenter 仍能正常工作,只是会拒绝创建/更新使用 startupTaints 的 provisioner。

升级到 0.6.2+

  • Helm 变量名变化:controller.clusterName 改为 clusterName,controller.clusterEndpoint 改为 clusterEndpoint。任何设置旧变量名的配置都需要更新。

总结与最佳实践

回顾整份升级指南,可以提炼出 Karpenter 升级的几条核心经验:

  1. CRD 先行:CRD 与 Karpenter 版本强耦合,而 Helm 主 chart 不会管理 CRD 生命周期。优先使用独立的 karpenter-crd chart 统一管理,升级顺序永远是"先 CRD、后控制器"。
  2. API 迁移是最大的分水岭:0.32.x(v1beta1 双支持)、1.0.0(v1 API + conversion webhook)、1.1.0(移除 v1beta1)构成了一条明确的迁移路径,跨过这些版本前务必完成对应的迁移指南。
  3. IAM 权限随版本演进:从 ec2:DescribeSpotPriceHistory、eks:DescribeCluster 到 ec2:DescribeInstanceStatus、arc-zonal-shift:GetManagedResource、iam:ListInstanceProfiles,每次升级都要对照 Getting Started 的 cloudformation.yaml 审计控制器角色与节点角色。
  4. 用 CI/CD 兜底生产安全:预发验证 → 自动测试 → 人工审批 → 生产部署 → 部署后监控,配合 ArgoCD / GitHub Actions / AWS CodePipeline 等流水线,把升级变成可重复、可回滚的工程流程。

只有把 CRD、API 迁移、IAM 权限与流程规范这四件事都做到位,Karpenter 的升级才能既快又稳。

登录后查看全文
karpenter-provider-aws