CircleCI 部署中出现 "error: exec plugin: invalid apiVersion client.authentication.k8s.io/v1alpha1" 错误的解决方法

问题描述

在使用 CircleCI 部署到 Amazon EKS 集群时，遇到以下错误信息：

error: exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha1"

这个错误是由于 kubectl 与 AWS CLI 之间的版本不兼容导致的。具体来说，较新版本的 kubectl 不再支持 client.authentication.k8s.io/v1alpha1 API 版本，而需要使用更新的 v1beta1 版本。

根据问题中提供的配置，我们可以看到在 deploy-production 和 deploy-demo 任务中都使用了：

- kubernetes/install-kubectl:
    kubectl-version: v1.22.0

这个版本的 kubectl 已经不再兼容旧的认证 API。

解决方案

方案一：更新 AWS CLI 和重新生成 kubeconfig（推荐）

这是最彻底和最推荐的解决方案，适用于大多数情况：

Linux/Mac

# 更新 AWS CLI 到最新版本
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install --update

# 备份现有配置并重新生成 kubeconfig
mv ~/.kube/config ~/.kube/config.bk
aws eks update-kubeconfig --region ${AWS_REGION} --name ${EKS_CLUSTER_NAME}

Windows

# 使用 Winget 更新 AWS CLI (Windows)
winget install Amazon.AWSCLI

# 删除旧配置并重新生成
# 先删除 $HOME/.kube 文件夹中的配置文件
aws eks update-kubeconfig --name ${EKS_CLUSTER_NAME} --region ${REGION}

方案二：手动修改 kubeconfig 文件

如果您无法立即更新 AWS CLI，可以手动修改 kubeconfig 文件：

1. 打开 kubeconfig 文件：

   nano ~/.kube/config
   # 或使用其他编辑器
   # atom ~/.kube/config
   # code ~/.kube/config

2. 查找所有 client.authentication.k8s.io/v1alpha1 实例

3. 将其替换为 client.authentication.k8s.io/v1beta1

4. 保存文件并重试 kubectl 命令

方案三：设置环境变量（临时解决方案）

在某些情况下，可以通过设置环境变量来解决：

export KUBERNETES_EXEC_INFO='{"apiVersion":"client.authentication.k8s.io/v1beta1"}'

# 如果使用 sudo，也需要为 root 用户设置
sudo su
export KUBERNETES_EXEC_INFO='{"apiVersion":"client.authentication.k8s.io/v1beta1"}'
exit

方案四：使用特定版本的 kubectl

如果更新 AWS CLI 不可行，可以考虑使用特定版本的 kubectl：

# 安装特定版本的 kubectl
curl -LO https://storage.googleapis.com/kubernetes-release/release/v1.23.6/bin/linux/amd64/kubectl
chmod +x ./kubectl
sudo mv ./kubectl /usr/local/bin/kubectl

# 验证版本
kubectl version

针对 CircleCI 的具体解决方案

对于问题中提到的 CircleCI 配置，建议采取以下措施：

更新 CircleCI 配置

在您的 .circleci/config.yml 文件中，确保使用更新的组件：

orbs:
  aws-ecr: circleci/aws-ecr@7.0.0  # 使用最新版本
  aws-eks: circleci/aws-eks@2.0.0  # 使用最新版本
  kubernetes: circleci/kubernetes@2.0.0  # 使用最新版本

在部署任务中添加 AWS CLI 更新步骤

在部署任务中添加 AWS CLI 更新步骤：

- run:
    name: Update AWS CLI
    command: |
      curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
      unzip awscliv2.zip
      sudo ./aws/install --update

重新生成 kubeconfig

在部署任务中确保重新生成 kubeconfig：

- run:
    name: Update kubeconfig
    command: |
      aws eks update-kubeconfig --region ${AWS_REGION} --name ${EKS_CLUSTER_NAME}

深入理解问题原因

这个错误的发生是由于 Kubernetes 生态系统的版本演进导致的：

1. API 版本弃用：client.authentication.k8s.io/v1alpha1 已被弃用，取而代之的是 v1beta1
2. 版本不匹配：新版本的 kubectl 不再支持旧的认证 API 版本
3. AWS CLI 滞后：某些 AWS CLI 版本仍然生成使用旧 API 版本的 kubeconfig 文件

注意

如果您使用 pyenv 或其他 Python 版本管理工具，请确保使用的 Python 版本与 AWS CLI 兼容。不兼容的 Python 版本可能导致 AWS CLI 无法正常工作。

验证解决方案

实施任何解决方案后，使用以下命令验证修复是否成功：

# 检查节点状态
kubectl get nodes

# 检查 pod 状态
kubectl get pods --all-namespaces

# 检查当前上下文
kubectl config current-context

总结

"error: exec plugin: invalid apiVersion client.authentication.k8s.io/v1alpha1" 错误是由于 kubectl 和 AWS CLI 版本不兼容导致的。最可靠的解决方案是：

1. 更新 AWS CLI 到最新版本
2. 重新生成 kubeconfig 文件
3. 确保使用兼容的 kubectl 版本

对于 CircleCI 环境，建议在配置文件中显式添加 AWS CLI 更新步骤，并使用最新版本的 Orb 来避免此类兼容性问题。

最佳实践

定期更新您的 CI/CD 流水线中的工具版本，并测试与您的基础设施组件的兼容性，可以避免类似的版本不匹配问题。