Kubernetes API Version / Groups

Kubernetes 클러스터는 Control plane 구성요소로 Kube Controller, Kube Scheduler 등이 있지만 가장 핵심이 되는 구성 요소는 Kube API Server 이다. 사용자는 이 API 서버에서 제공하는 API를 통하여 Kubernetes 의 모든 오브젝트를 관리할 수 있다. 또한 대부분의 API 는 kubectl 명령어 / kubeadm 명령어로도 동일한 기능을 제공한다.

다음은 파드 정보를 조회하는 명령어의 예시이다.

---

#1. curl 명령을 통한 default 네임스페이스의 파드 조회

<명령어>
curl -k http://localhost:8001/api/v1/namespaces/default/pods

<결과>
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "resourceVersion": "61651419"
  },
  "items": []
}

#2. kubectl 명령을 통한 default 네임스페이스의 파드 조회

<명령어>
kubectl get po

<결과>
No resources found in default namespace.

 

1. API Version

버전 수준	상세 설명
알파(Alpha)	▶ 시험적으로 테스트 되는 기능으로, 기본적으로 비활성화 되어 있다.    ▶ 기능에 대한 기술지원이 공지 없이 중단 될 수 있으며, API 의 호환성도 보장하지 않는다.     ▶ 명명규칙 : 안정화 버전의 버전명에 alpha 를 포함 (예: v1alpha1)
베타(Beta)	▶ 알파 단계에서 테스트가 더 많이 진행되었으며, 기본적으로 활성화 되어 있다.    ▶ 세부 기능이 변경될 수 있지만, 전반적인 기능에 대한 지원은 유지된다.    ▶ API 의 호환성이 보장되지 않지만, 이 경우 이관을 위한 가이드가 제공된다.    ▶ 명명규칙 : 안정화 버전의 버전명에 beta 가 포함 (예: v2beta3)
안정화(Stable)	▶ 가장 안정화된 버전으로 이후 여러 버전에 걸쳐서 소프트웨어 릴리스에 포함된다.      ▶ 명명규칙 : v1, v2 와 같이 정수로 사용되는 vX 형식이다.

---

2. API Group

API group 을 확인하기 전에 먼저 kube-api server로 curl 명령을 전송하여 kubernetes cluster 의 버전을 확인한다.  이 항목(API Group)에서의 'version' 은 위 'API Version' 과는 별개인 kubernetes cluster 의 버전임을 유념하자.

# Kubernetes API version check (인증서 오류 출력시 '-k' 플래그 추가)
curl https://kube-apiserver:6443/version
{
  "major": "1",
  "minor": "22+",
  "gitVersion": "v1.21.3",
  "gitCommit": "f9c549dac9ca9ca665305e12ac2f8f0795e7be",
  "gitTreeState": "clean",
  "buildDate": "2021-01-05T07:28:26Z",
  "goVersion": "go1.15.1",
  "compiler": "gc",
  "platform": "linux/amd64"
}

위 api 의 경우 kube-api server 의 경로 하위에 '/version' 으로 된 부경로(이하 subpath)를 사용한다. kubernetes 에는 많은 API 들이 존재하는데 이 API들은 상위 API Group 으로 그룹화하여 관리하게 된다.

API Group은 다음과 같으며 버전이 증가될 때마다 변경될 수 있다. 

버전 수준	상세 설명
/metrics	cluster 의 상태 확인을 위해 필요.
/healthz	cluster 의 상태 확인을 위해 필요.
/version	kubernetes cluster 의 버전을 확인
/logs	3rd-party logging application 과의 통합 연계를 위해 사용
/api	core group. 모든 핵심 기능이 존재하며 하위 v1/core를 단순하게 v1이라고 표현
/apis	named group.   /api 보다 더 조직화 되어 있으며 신규 출시될 기능들이 named group 에서 사용

 

표로 분류하면 아래와 같으며 API Group 의 주요 내용은 kubernetes API References Page 에서도 확인 가능하다.

Kubernetes API Group

2-1) 명령어를 통한 API Group 의 확인

전체 API Resource 의 내용은 kube-api server로 curl 명령을 전송하여 확인 가능하다.

curl -k https://kube-apiserver:6443 

결과>
{
  "paths": [
    "/.well-known/openid-configuration",
    "/api",
    "/api/v1",
    "/apis",
    "/apis/",
    "/apis/admissionregistration.k8s.io",
    "/apis/admissionregistration.k8s.io/v1",
    ...
    "/readyz/poststarthook/start-kube-apiserver-admission-initializer",
    "/readyz/shutdown",
    "/version"
  ]
}

 

2-2) 명령어를 통한 API Group 의 확인 : 권한 오류 시

만약 아래와 같이 권한이 없다고 나올 경우, TLS통신에 대한 인증 정보(ca.crt, crt파일, key 파일)를 포함해준다.

ca.crt, admin.crt, admin.key 파일을 확인하기 위해 kubeconfig 를 이용하는 방법은 해당 포스트(KubeConfig 파일 확인하기)를 참고한다.

# curl -k https://kube-apiserver:6443 
{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    
  },
  "status": "Failure",
  "message": "forbidden: User \"system:anonymous\" cannot get path \"/\"",
  "reason": "Forbidden",
  "details": {
    
  },
  "code": 403
}

# 하단과 같이 인증 정보 포함
curl -k https://kube-apiserver:6443 --key admin.key  --cert admin.crt  --cacert ca.crt

결과>
{
  "paths": [
    "/.well-known/openid-configuration",
    "/api",
    "/api/v1",
    ...
    "/version"
  ]
}

 

2-3) 명령어를 통한 API Group 의 확인 : 인증 대체 proxy 구동

다른 방법으로는 kubectl proxy 명령어로 proxy 모드를 구동하는 방법도 있다(kube-proxy 와는 다르므로 주의하자). 이 방법을 사용할 경우 foreground 에서 api server 에 인증 작업을 대신해주는 proxy 모드가 구동된다.

# 인증을 대신 수행해주는 kubectl proxy 모드 발동
kubectl proxy

결과
Starting to serve on 127.0.0.1:8001

# 별도의 터미널에서 8001번 포트 호출

이후 추가로 별도의 터미널을 이용하여 8001번 포트로 curl 명령을 전송할 경우 api server로부터 resource 목록을 확인할 수 있다.

---