CircleCIでの "error: exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha1"" エラーの解決方法

問題の概要

AWS EKS（Elastic Kubernetes Service）クラスターへのデプロイをCircleCIで実行する際に、以下のエラーが発生することがあります：

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

このエラーは、kubectlとAWS CLI間の互換性の問題によって発生します。具体的には、古いバージョンのAWS CLIやkubectlが新しいEKSクラスターとの認証に失敗する場合にこのエラーが表示されます。

根本原因

このエラーの主な原因は以下のいずれかです：

1. AWS CLIのバージョンが古い - v1alpha1 APIが非推奨となり、v1beta1に置き換えられました
2. kubectlのバージョン不一致 - 新しいEKSクラスターと互換性のないkubectlバージョンを使用している
3. kubeconfigファイルの設定不備 - 認証設定に古いapiVersionが指定されている

解決方法

方法1: AWS CLIのアップデート（推奨）

最も確実な解決策は、AWS CLIを最新バージョンに更新することです。

Linux/Mac

# AWS CLI v2のインストール/更新
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install --update

# kubeconfigの再生成
aws eks update-kubeconfig --region ${AWS_REGION} --name ${EKS_CLUSTER_NAME}

Homebrew (Mac)

brew upgrade awscli
aws eks update-kubeconfig --region ${AWS_REGION} --name ${EKS_CLUSTER_NAME}

Python pip

pip3 install awscli --upgrade --user
aws eks update-kubeconfig --region ${AWS_REGION} --name ${EKS_CLUSTER_NAME}

方法2: kubeconfigファイルの手動修正

既存のkubeconfigファイルを手動で修正する方法です：

# 現在の設定のバックアップ
cp ~/.kube/config ~/.kube/config.backup.$(date +%Y%m%d)

# apiVersionの変更
sed -i 's/client.authentication.k8s.io\/v1alpha1/client.authentication.k8s.io\/v1beta1/g' ~/.kube/config

または、テキストエディタで ~/.kube/config ファイルを開き、すべての v1alpha1 を v1beta1 に置き換えます。

方法3: kubectlバージョンの調整

使用しているEKSクラスターのバージョンと互換性のあるkubectlバージョンを選択します：

# 特定のkubectlバージョンをインストール（例：v1.23.6）
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

TIP

EKSクラスターのバージョンと±1バージョンのkubectlを使用することを推奨します（例：EKS 1.22ならkubectl 1.21-1.23）。

方法4: AWS IAM Authenticatorの更新

AWS IAM Authenticatorも更新が必要な場合があります：

# 最新版のAWS IAM Authenticatorをインストール
curl -o aws-iam-authenticator https://amazon-eks.s3.us-west-2.amazonaws.com/1.21.2/2021-07-05/bin/linux/amd64/aws-iam-authenticator
chmod +x ./aws-iam-authenticator
sudo mv ./aws-iam-authenticator /usr/local/bin/

CircleCIでの対応

CircleCIの設定ファイル（.circleci/config.yml）では、以下のように修正します：

- deploy/update-image:
    resource-name: deployment/core-web
    template-file-path: core-web-pod.yml
    cluster-name: report
    environment: report
    template-repository: git@github.com:say-way/sw-k8s.git
    replicas: 3
    # 以下のパラメータを追加または更新
    authenticator-release-tag: v0.5.9  # 最新バージョンを指定
    kubectl-version: v1.23.6         # 互換性のあるバージョンを指定

環境変数による暫定対応

一時的な対応として環境変数を設定する方法もあります：

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

WARNING

この方法は一時的な対応であり、根本的な解決にはなりません。本番環境では他の方法を適用してください。

よくある問題と解決策

Python環境の問題

pyenvなどで複数のPython環境を使用している場合、AWS CLIが想定外のPythonバージョンで動作している可能性があります：

# 使用中のPythonバージョンを確認
aws --version

# systemのPythonを使用するように切り替え（pyenvの場合）
pyenv global system

Helmとの互換性問題

Helmを使用している場合、対応するバージョンをインストールする必要があります：

# Helmのバージョンダウングレード（例）
curl -L https://git.io/get_helm.sh | bash -s -- --version v3.8.2

予防策

1. 定期的なアップデート - AWS CLI、kubectl、AWS IAM Authenticatorを定期的に更新する
2. バージョン互換性の確認 - EKSクラスターのバージョンとツールの互換性を事前に確認する
3. 自動化された設定管理 - Infrastructure as Code（IaC）で環境構築を自動化し、一貫性を保つ

まとめ

error: exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha1" エラーは、AWS EKSとクライアントツール間のバージョン不一致によって発生します。最も効果的な解決策は、AWS CLIの更新とkubeconfigの再生成です。CircleCI環境では、Orbのパラメータを適切に設定し、定期的なメンテナンスを実施することでこの問題を予防できます。