Karpenter 升级指南:从 CRD 管理到 v1.14 全版本迁移实战手册
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起不再支持v1beta1API。在升级到1.1.0及以上版本前,必须先完成 v1 迁移指南 中要求的迁移动作。
- Capacity Buffers API 毕业到
v1beta1:该版本将 CapacityBuffers API 升级到v1beta1,并随包发布新的autoscaling.x-k8s.io_capacitybuffersCRD(见 charts/karpenter/crds/autoscaling.x-k8s.io_capacitybuffers.yaml)。如果使用独立karpenter-crdchart,请随控制器一起升级以安装新 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 考虑尚无公开定价数据的实例类型。该能力由现有
NodeOverlayfeature 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:GetManagedResourceIAM 权限(见 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:启用ReservedCapacityfeature 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移除对v1beta1API 的支持,不要在完成迁移前升级。详见 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引入v1API,并使用 conversion webhooks 支持现有v1beta1API。不要在未完成迁移的情况下升级,请先阅读 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-settingsConfigMap 传参:改为通过 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 配置全部移入
logConfigvalues 块(已废弃,v1 将移除)。Karpenter 现在仅通过logLevelHelm 值暴露日志级别;如需更精细的日志解析配置,建议让日志解析器直接处理 Karpenter 的 Zap JSON 日志。 - 默认日志编码从
console改为json:若之前未显式设置日志编码,默认值会随 Helm chart 变化。logEncoding值在0.33.x前仍可用,但已废弃,建议改用logConfig.logEncoding。 - 节点 disruption taint 变化:Karpenter 现在使用
karpenter.sh/disruption:NoSchedule=disruptingtaint,取代上游的node.kubernetes.io/unschedulabletaint,防止 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/unschedulabletaint。
升级到 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+ 修复。
- 移除
extraObjectsHelm 值:该值在多数安装场景中无效,且容易形成反模式。官方建议如需随 chart 安装 Karpenter 相关 manifests,请单独创建 chart 并依赖控制器 chart。 - 移除
aws.nodeNameConvention设置:Karpenter 通过 Machine 编排容量后不再需要节点名称。Karpenter 会忽略karpenter-global-settingsConfigMap 中不认识的配置,保留该键只会被忽略。 - 新增"受限标签"(restricted tags):以下标签不允许通过 AWSNodeTemplate 或
karpenter-global-settings自定义覆盖,否则 webhook 校验失败:karpenter.sh/managed-bykarpenter.sh/provisioner-namekubernetes.io/cluster/${CLUSTER_NAME}
- 指标语义变化(基于 Machine 资源的引入):
karpenter_nodes_terminated:如需按原因查看 Machine 删除,请使用karpenter_machines_terminated;前者现在只统计节点终止数量,无附加标签karpenter_nodes_created:同理,改用karpenter_machines_createdkarpenter_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.shmutating 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-settingsConfigMap 后,需要重启 deployment 使配置生效:kubectl rollout restart -n karpenter deploy/karpenter。 - 移除内部实例类型过滤:此前
g2(NVIDIA device plugin 不支持)与 FPGA 实例类型会被过滤,现在只能通过 provisioner 或 Pod 上的 well-known 节点标签设置 requirements 过滤。参见选择节点。 aws.tags成为顶层字段:karpenter-global-settingsConfigMap 中该键的值需要是 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-settingsConfigMap 动态读取):CLUSTER_NAME->settings.aws.clusterNameCLUSTER_ENDPOINT->settings.aws.clusterEndpointAWS_DEFAULT_INSTANCE_PROFILE->settings.aws.defaultInstanceProfileAWS_ENABLE_POD_ENI->settings.aws.enablePodENIAWS_ENI_LIMITED_POD_DENSITY->settings.aws.enableENILimitedPodDensityAWS_ISOLATED_VPC->settings.aws.isolatedVPCAWS_NODE_NAME_CONVENTION->settings.aws.nodeNameConventionVM_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 不再更新(仅保留旧版本)。脚本化安装/升级需调整:- 无需再执行
helm repo add添加仓库 - 使用
helmCLI 时必须提供 chart 的完整 URL - 如果此前版本号不带
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 会过滤掉裸金属与部分非当前世代实例类型。显式指定实例类型/家族列表时按列表执行,也可通过添加Existsrequirement 完全取消过滤:
- 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升级,注意awsnodetemplateCRD 曾在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→awsnodetemplatesCRD 更名步骤同上。
升级到 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 升级的几条核心经验:
- CRD 先行:CRD 与 Karpenter 版本强耦合,而 Helm 主 chart 不会管理 CRD 生命周期。优先使用独立的
karpenter-crdchart 统一管理,升级顺序永远是"先 CRD、后控制器"。 - API 迁移是最大的分水岭:
0.32.x(v1beta1 双支持)、1.0.0(v1 API + conversion webhook)、1.1.0(移除 v1beta1)构成了一条明确的迁移路径,跨过这些版本前务必完成对应的迁移指南。 - IAM 权限随版本演进:从
ec2:DescribeSpotPriceHistory、eks:DescribeCluster到ec2:DescribeInstanceStatus、arc-zonal-shift:GetManagedResource、iam:ListInstanceProfiles,每次升级都要对照 Getting Started 的 cloudformation.yaml 审计控制器角色与节点角色。 - 用 CI/CD 兜底生产安全:预发验证 → 自动测试 → 人工审批 → 生产部署 → 部署后监控,配合 ArgoCD / GitHub Actions / AWS CodePipeline 等流水线,把升级变成可重复、可回滚的工程流程。
只有把 CRD、API 迁移、IAM 权限与流程规范这四件事都做到位,Karpenter 的升级才能既快又稳。