如何在升级期间修复 Karpenter 迁移问题 (v0.25.0 v1.5.0)

Source: Dev.to

介绍

本指南涵盖了在生产环境中将 Karpenter 从 v0.25.0 升级到 v1.5.0 时遇到的真实问题、产生原因以及精准的解决方案。如果你计划进行此升级，下面的步骤可以为你节省大量调试时间。

升级概览

跳过 CRD 迁移步骤会导致控制器崩溃、资源卡住以及卸载失败。

常见错误与解决方案

1. 未找到 Helm Chart

helm upgrade karpenter karpenter/karpenter --version 1.5.0
# Error: chart "karpenter" matching 1.5.0 not found

原因： 旧的 Helm 仓库仅包含到 0.16.3 的版本。Karpenter v1.x 已迁移至 OCI 注册表。

解决办法：

helm upgrade karpenter oci://public.ecr.aws/karpenter/karpenter \
  --version 1.5.0 \
  --namespace karpenter \
  --wait

2. OCI 标签带 v 前缀

helm upgrade karpenter oci://public.ecr.aws/karpenter/karpenter --version v1.5.0
# Error: ... v1.5.0: not found

原因： 从 v0.35.0 开始，OCI 标签不再使用 v 前缀。

解决办法： 使用不带 v 前缀的版本号。

--version 1.5.0   # NOT v1.5.0

3. 缺少 v1 CRD

# ERROR: no matches for kind "NodeClaim" in version "karpenter.sh/v1"
# panic: unable to retrieve the complete list of server APIs

原因： v1.5.0 控制器需要新的 v1 CRD（NodePool、NodeClaim、EC2NodeClass），而集群中仍只有旧的 v1alpha5 CRD。

解决办法： 在升级控制器之前先安装新 CRD。

helm upgrade --install karpenter-crd \
  oci://public.ecr.aws/karpenter/karpenter-crd \
  --version 1.5.0 \
  --namespace karpenter \
  --create-namespace

随后升级控制器：

helm upgrade karpenter oci://public.ecr.aws/karpenter/karpenter \
  --version 1.5.0 \
  --namespace karpenter \
  --wait

4. IAM 权限错误

"error": "not authorized to perform: ec2:DescribeImages"

原因： Karpenter v1 引入了新的实例配置文件和 AMI 发现工作流。

解决办法： 为 Karpenter 控制器的 IAM 角色添加以下权限：

{
  "Effect": "Allow",
  "Action": [
    "ec2:DescribeImages",
    "iam:GetInstanceProfile",
    "iam:CreateInstanceProfile",
    "iam:DeleteInstanceProfile",
    "iam:AddRoleToInstanceProfile",
    "iam:RemoveRoleFromInstanceProfile"
  ],
  "Resource": "*"
}

重启部署：

kubectl rollout restart deployment karpenter -n karpenter

迁移步骤

备份现有资源

kubectl get provisioners -A -o yaml > provisioners-backup.yaml
kubectl get awsnodetemplates -A -o yaml > awsnodetemplates-backup.yaml

安装新 CRD（如果尚未完成）

helm upgrade --install karpenter-crd \
  oci://public.ecr.aws/karpenter/karpenter-crd \
  --version 1.5.0 \
  --namespace karpenter

升级控制器（在 CRD 之后）

helm upgrade karpenter oci://public.ecr.aws/karpenter/karpenter \
  --version 1.5.0 \
  --namespace karpenter \
  --wait

将 Provisioner 转换为 NodePool

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  template:
    spec:
      requirements:
        - key: karpenter.sh/capacity-type
          operator: In
          values: ["on-demand"]
      nodeClassRef:
        group: karpenter.k8s.aws
        kind: EC2NodeClass
        name: default
  disruption:
    consolidationPolicy: WhenEmptyOrUnderutilized

将 AWSNodeTemplate 转换为 EC2NodeClass

apiVersion: karpenter.k8s.aws/v1
kind: EC2NodeClass
metadata:
  name: default
spec:
  amiSelectorTerms:
    - alias: al2@latest
  subnetSelectorTerms:
    - tags:
        karpenter.sh/discovery: my-cluster
  securityGroupSelectorTerms:
    - tags:
        karpenter.sh/discovery: my-cluster
  role: "karpenter-node-role-name"

应用新资源：

kubectl apply -f ec2nodeclass.yaml
kubectl apply -f nodepool.yaml

验证：

kubectl get ec2nodeclass
kubectl get nodepools

测试节点供应

kubectl run test --image=nginx --requests=cpu=1,memory=1Gi

排空并清理旧资源

kubectl delete provisioner default
kubectl delete awsnodetemplate default

结果

• Karpenter v1.5.0 稳定运行
• 所有节点已迁移至 NodePools
• 集群已准备好 EKS 1.32
• 升级期间零停机

参考资料

• 官方升级指南
• v1 迁移指南

升级期间监控日志

kubectl logs -n karpenter -l app.kubernetes.io/name=karpenter -f