kubectl invalid apiVersion "client.authentication.k8s.io/v1alpha1"

어느날 갑자기 kubectl 명령을 실행 했는데 이런 오류 메시지와 함께 실행이 안되는 현상이 발생했다.

$ kubectl version --client
error: exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha1"

명령어를 잘못 입력했나 싶어 다시 실행을 해도 결과는 마찬가지였다. 뭐가 문제인가 싶어 그제서야 오류 메시지의 내용을 확인했다. 해석하면 이런 내용이다.

오류: 플러그인 실행: 유효하지 않은 apiVersion "client.authentication.k8s.io/v1alpha1"

친절하게 클라이언트 API 버젼이 맞지 않아 오류라고 알려준다. 그럼 지금까지는 왜 잘 사용할 수 있었던걸까?

일단 버젼이 안맞는다고 하니 kubectl 자체 버젼을 업데이트 해보기로 했다. 아래 홈페이지에서 최신 버젼의 kubectl을 다운로드 받을 수 있다.
https://kubernetes.io/docs/tasks/tools/

Install Tools

현재 기준 최신 kubectl은 버젼이 1.26.0인데 이것도 같은 오류 메시지를 보여주고 있다. 뭐가 문제일까? 관련 내용을 검색했더니, 이미 이런 경험을 한 사람들의 글이 눈에 보였다.
https://enumclass.tistory.com/257

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

명령은 다르지만 증상은 invalid apiVersion: client.authentication.k8s.io/v1alpha1 으로 동일하며 kubectl 1.23.6에서 문제가 발생하지 않았다는 내용을 보고 kubectl을 down grade를 해 설치해 보았다.

$ curl -LO "https://dl.k8s.io/release/v1.23.6/bin/darwin/amd64/kubectl"

일단은 1.23.6 버젼에서는 정상적으로 동작하는 것을 확인했다.

$ kubectl version --client 
Client Version: version.Info{Major:"1", Minor:"23", GitVersion:"v1.23.6", GitCommit:"ad3338546da947756e8a88aa6822e9c11e7eac22", GitTreeState:"clean", BuildDate:"2022-04-14T08:49:13Z", GoVersion:"go1.17.9", Compiler:"gc", Platform:"darwin/amd64"}

현재 kubectl은 1.26까지 나왔는데 버젼을 낮춰야 동작하는게 정상으로 보이지는 않아서 좀 더 찾아 봤더니 kubectl 1.24 부터 client.authentication.k8s.io/v1alpha1 를 이용한 인증을 지원하지 않기 때문이라고 한다.

https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#deprecation

GitHub - kubernetes/kubernetes: Production-Grade Container Scheduling and Management

초기에 Homebrew로 설치했던 kubernetes CLI 버젼은 1.22였었다.

$ brew search kubernetes-cli   
==> Formulae
kubernetes-cli ✔                         kubernetes-cli@1.22

==> Casks
kubernetic

다만, 최근 redis 를 brew로 설치해 본다고 brew를 사용하면서 업데이트를 했는데, 이 때 kubenetes-cli도 버젼도 같이 업데이트가 되면서 이런 상황이 벌어진 것으로 보인다. 설치되어 있는 kubernetes-cli 정보를 확인하면 1.25.5 가 설치되어 있었음을 알 수 있다.

$ brew info kubernetes-cli
==> kubernetes-cli: stable 1.25.5 (bottled), HEAD
Kubernetes command-line interface
https://kubernetes.io/
/usr/local/Cellar/kubernetes-cli/1.25.5 (228 files, 54.2MB)
  Poured from bottle on 2022-12-13 at 21:38:53
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/kubernetes-cli.rb
License: Apache-2.0
==> Dependencies
Build: bash ✘, coreutils ✔, go ✔
==> Options
--HEAD
	Install HEAD version
==> Caveats
zsh completions have been installed to:
  /usr/local/share/zsh/site-functions
==> Analytics
install: 125,407 (30 days), 394,320 (90 days), 1,389,134 (365 days)
install-on-request: 85,925 (30 days), 268,956 (90 days), 941,102 (365 days)
build-error: 21 (30 days)

직접 설치했던 kubectl을 실행 파일 및 kubenetes-cli를 삭제 후 재설치해보니 1.26.0으로 다시 설치가 되었다.

어쨌든 kubectl 1.24.0 이후 부터는 client.authentication.k8s.io/v1alpha1 를 지원하지 않으며, 새로 설치한 kubectl 1.26.0도 여전히 당연하겠지만 invalid apiVersion "client.authentication.k8s.io/v1alpha1" 메시지를 출력한다.

이 정도 왔으면 kubectl의 문제라기 보다는 cluster 접속 설정에 대한 문제로 생각을 바꿔 볼 필요가 있다.

일반적으로 kubectl은 Kubernetes Cluster 접속을 위해 ~/.kube/config에 있는 cluster config 의 정보를 이용한다. 이 정보는 일반적으로 Kubernetes cluster 공급자가 제공을 하는데, EKS는 aws 서비스이므로 aws cli를 이용하여 EKS 접속을 위한 정보를 구성하게 된다.

실제로 ~/.kube/config에 aws cli로 갱신된 context 정보를 확인해 보면 apiVersion이 client.authentication.k8s.io/v1alpha1인 것을 볼 수 있었다.

  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1alpha1
      args:
      - --region

이 정보를 아래와 같이 v1beta1으로 변경하면 kubectrl 1.26.0 에서도 정상적으로 사용할 수 있는 것을 알 수 있다.

  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - --region

이제 kubectl이 1.26.0에서 정상 동작하는 것을 확인했으니 다음으로는 aws cli가 v1beta1으로 정보를 생성 할 수 있는 방법을 찾아 봐야 한다.

처음 참고했던 블로그에 달린 링크에 aws-cli에 대한 링크를 다시 확인해 보자. https://github.com/aws/aws-cli/issues/6920

aws-cli에 대한 issue board 였는데 kubectl을 1.23.6에서 1.24로 업그레이드하고 나서 문제가 발생한다는 내용이다. 다양한 사람들이 공감하고 우회할 수 있는 다양한 방법을 제시했는데 그중 aws CLI version을 최신 버젼으로 설치하라는 내용이 눈에 들어왔다.

설치되어 있는 aws cli 버젼을 확인했더니 2.2.33이었다.

$ aws --version
aws-cli/2.2.33 Python/3.8.8 Darwin/21.6.0 exe/x86_64 prompt/off

현재 시점 최신 버젼은 2.9.5인데 2.2.23은 좀 오래된 버젼이긴했다. 아래 홈페이지에서 aws cli 최신 버젼 설치 방법을 알 수 있다.
https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

Installing or updating the latest version of the AWS CLI - AWS Command Line Interface

업데이트 완료!

$ aws --version
aws-cli/2.9.5 Python/3.9.11 Darwin/21.6.0 exe/x86_64 prompt/off

설치된 버젼이 2.9.5인 것을 확인했고 aws-cli로 kubeconfig 정보를 업데이트 하면

$ aws eks --region $REGION update-kubeconfig --name $CLUSTER_NAME

cluster config 정보는 v1alpha1이 아닌 v1beta1으로 적용되고, kubectl도 eks에 정상 연결되는 것을 확인 할 수 있다.

$ kubectl version --client
WARNING: This version information is deprecated and will be replaced with the output from kubectl version --short.  Use --output=yaml|json to get the full version.
Client Version: version.Info{Major:"1", Minor:"26", GitVersion:"v1.26.0", GitCommit:"b46a3f887ca979b1a5d14fd39cb1af43e7e5d12d", GitTreeState:"clean", BuildDate:"2022-12-08T19:51:43Z", GoVersion:"go1.19.4", Compiler:"gc", Platform:"darwin/amd64"}
Kustomize Version: v4.5.7