쿠버네티스 API 및 클라이언트 라이브러리

본 포스팅은 Kubernetes Official Documents을 기반으로 한다.

쿠버네티스 API

쿠버네티스 API를 사용하면 쿠버네티스 오브젝트들의 상태를 쿼리하고 조작할 수 있다. 쿠버네티스 컨트롤 플레인의 핵심은 API 서버와 그것이 노출하는 HTTP API이다. 사용자와 클러스터의 다른

kubernetes.io

# Kubernets API

쿠버네티스의 컨트롤 플레인의 핵심은 API 서버이다. API 서버는 최종 사용자, 클러스터의 다른 부분 그리고 외부 컴포넌트가 서로 통신할 수 있도록 HTTP API를 제공한다.

쿠버네티스 API를 사용하면 쿠버네티스의 API Object(Pod, Namespace, Configmap) 그리고 Event를 Query하고 조작할 수 있다.

대부분의 작업은 kubectl CLI 또는 API를 사용하는 kubeadm과 같은 다른 CLI를 통해 수행할 수 있다. 물론, REST Request를 통해 API에 직접 접근할 수도 있다.

쿠버네티스 API를 사용하여 애플리케이션을 작성하는 경우 클라이언트 라이브러리 중 하나를 사용하는 것이 좋다.

# Open API Specification

완전한 API에 대한 세부 사항은 OpenAPI를 활용해서 문서화했다.

OpenAPI V2

쿠버네티스 API 서버는 /openapi/v2 엔드포인트를 통해 통합된 OpenAPI v2 스펙으 ㄹ제공한다. 요청 헤더에 다음과 같이 기재하여 응답 형식을 지정할 수 있다.

헤더	사용할 수 있는 값	참고
Accept-Encoding	gzip	이 헤더를 제공하지 않는 것도 가능
Accept	application/cohttp://m.github.proto-openapi.spec.v2@v1.0+protobuf	주로 클러스터 내부 용도로 사용
Accept	application/json	기본값
Accept	*	JSON으로 응답

쿠버네티스는 주로 클러스터 내부 통신을 위해 대안적인 Protobuf에 기반한 직렬화 형식을 구현한다.
이 형식에 대한 자세한 내용은 쿠버네티스 Protobuf 직렬화 디자인 제안과 API Object를 정의하는 Go Package에 들어있는 각각의 스키마에 대한 IDL(인터페이스 정의 언어)파일을 참고할 수 있다.

OpenAPI V3

쿠버네티스 v1.28 버전은 OpenAPI v3 API 발행에 대한 베타 지원을 제공한다. 이는 베타 기능이며 기본적으로 활성화되어 있다. kube-apiserver 구성 요소에 OpenAPIV3 기능 게이트를 비활성화하여 이 베타 기능을 비활성화할 수 있다.

/openapi/v3 Discovery Endpoint는 사용 가능한 모든 그룹/버전의 목록을 제공한다. 이 엔드포인트는 JSON 만을 반환한다. 이러한 그룹/버전은 다음과 같은 형식으로 제공된다.

{
    "paths": {
        ...,
        "api/v1": {
            "serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
        },
        "apis/admissionregistration.k8s.io/v1": {
            "serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
        },
        ....
    }
}

위의 상대 URL은 변경이 가능하지 않은 OpenAPI 상세를 가리키고 있으며, 이는 클라이언트에서의 캐싱을 향상시키기 위함이다. 같은 목적을 위해 API 서버는 적절한 HTTP 캐싱 헤더(Expires는 1년 뒤로, Cache-Control을 immutable)를 설정한다.

사용 중단된 URL이 사용되면, API 서버는 최신 URL로 리다이렉트를 반환한다.

Kubernetes API Server는 쿠버네티스 그룹 버전에 따른 OpenAPI v3 스펙을 /openapi/v3/apis/\<groups>/\<version>?hash=\<hash> 엔드포인트에 게시힌다.

사용 가능한 요청 헤더 목록은 아래의 표를 참고한다.

헤더	사용할 수 있는 값	참고
Accept-Encoding	gzip	이 헤더를 제공하지 않는 것도 가능
Accept	application/cohttp://m.github.proto-openapi.spec.v3@v1.0+protobuf	주로 클러스터 내부 용도로 사용
Accept	application/json	기본값
Accept	*	JSON으로 응답

# 지속성

쿠버네티스는 오브젝트의 직렬화된 상태를 etcd에 기록하여 저장한다.

# API Group & Version 규칙

필드를 쉽게 제거하거나 리소스 표현을 재구성하기 위해, 쿠버네티스는 각각 `/api/v1` 또는 `/apis/rbac.authorization.k8s.is/v1alpha1` 과 같은 서로 다른 API 경로에서 여러 API 버전을 지원한다.

버전 규칙은 리소스나 필드 수준이 아닌 API 수준에서 수행되어 API가 시스템 리소스 및 동작에 대한 명확하고 일관된 보기를 제공하고 수명 종료 및 & 또는 실험적 API에 대한 접근을 제어할 수 있도록 한다.

보다 쉽게 발전하고 API를 확장하기 위해, 쿠버네티스는 활성화 또는 비활성화가 가능한 API 그룹을 구현한다.

API Resource는 API 그룹, 리소스 유형, 네임스페이스(네임스페이스 리소스용) 및 이름으로 구분된다. API Server는 API Version 간의 변환을 투명하게 처리한다. 서로 다른 모든 버전은 실제로 동일한 지속 데이터의 표현이다. API 서버는 여러 API 버전을 통해 동일한 기본 데이터를 제공할 수 있다.

예를 들어, 동일한 리소스에 대해 `v1`과 `v1beta1` 이라는 두 가지 API 버전이 있다고 가정해보면, API의 `v1beta1` 버전을 사용하여 오브젝트를 만든 경우, `v1beta1` 버전이 사용 중단(deprecated)되고 제거될 때까지는 `v1beta1` 또는 `v1` API 버전을 사용하여 해당 오브젝트를 읽거나, 업데이트하거나, 삭제할 수 있다. 그 이후로부터는 `v1` API를 사용하여 계속 오브젝트에 접근하고 수정할 수 있다.

# API 변경 사항

성공적인 시스템은 새로운 유즈케이스가 등장하거나 기존 사례가 변경됨에 따라 성장하고 변화해야 한다. 따라서, 쿠버네티스는 쿠버네티스 API가 지속적으로 변경되고 성장할 수 있도록 설계했다. 쿠버네티스 프로젝트는 기존 클라이언트와의 호환성을 깨지 않고 다른 프로젝트가 적응할 기회를 가질 수 있도록 장기간 해당 호환성을 유지하는 것을 목표로 한다.

일반적으로, 새 API 리소스와 새 리소스 필드는 자주 추가될 수 있다. 리소스 또는 필드를 제거하려면 API 지원 중단 정책을 따라야 한다.

쿠버네티스는 일반적으로 API 버전 `v1`에서 안정 버전(GA)에 도달하면, 공식 쿠버네티스 API에 대한 호환성 유지를 강력하게 이행한다. 또한 쿠버네티스는 공식 쿠버네티스 API의 베타 API 버전으로 만들어진 데이터와도 호환성을 유지하며, 해당 기능이 안정화되었을 때 해당 데이터가 안정 버전의 API 버전들에 의해 변환되고 접근될 수 있도록 보장한다.

만약 베타 API 버전을 사용했다면, 해당 API 승급했을 대 후속 베타 버전 혹은 안정된 버전의 API로 전환해야 한다. 해당 작업은 오브젝트 접근을 위해 두 API 버전 모두 사용할 수 있는 베타 API의 사용 중단 시기일 때 진행하는 것이 최선이다. 베타 API의 사용 중단 시기가 끝나고 더 이상 사용될 수 없다면 반드시 대체 API 버전을 사용해야 한다.

# API 확장

쿠버네티스 API는 다음 두 가지 방법 중 하나로 확장할 수 있다.

커스텀 리소스를 사용하면 API 서버가 선택한 리소스 API를 제공하는 방법을 선언적으로 정의할 수 있다.
Aggregation Layer를 구현하여 쿠버네티스 API를 확장할 수도 있다.

# Client Library

다양한 프로그래밍 언어에서 쿠버네티스 API를 사용하기 위한 클라이언트 라이브러리에 대한 개요이다.

쿠버네티스 REST API를 사용해 애플리케이션을 작성하기 위해 API 호출 또는 Request/Response 타입을 직접 구현할 필요는 없고, 사용하고 있는 프로그래밍 언어를 위한 클라이언트 라이브러리를 사용하면 된다.

클라이언트 라이브러리는 대체로 인증과 같은 공통의 작업을 처리한다. 대부분의 클라이언트라이브러리들은 API 클라이언트가 쿠버네티스 클러스터 내부에서 동작하는 경우 인증 또는 KubeConfig 파일 포맷을 통해 자격 증명과 API 서버 주소를 읽을 수 있게 Kubernets Service Account를 발견하고 사용할 수 있다.

공식적으로 지원되는 K8s Client Library

아래의 클라이언트 라이브러리들은 K8s SIG API Machinery에서 공식적으로 관리된다.

언어	클라이언트 라이브러리
C	github.com/kubernetes-client/c
dotnet	github.com/kubernetes-client/csharp
Go	github.com/kubernetes/client-go/
Haskell	github.com/kubernetes-client/haskell
Java	github.com/kubernetes-client/java
JavaScript	github.com/kubernetes-client/javascript
Perl	github.com/kubernetes-client/perl/
Python	github.com/kubernetes-client/python/
Ruby	github.com/kubernetes-client/ruby/

Commnunity에서 관리되는 K8s Client Library

다음의 쿠버네티스 API 클라이언트 라이브러리들은 쿠버네티스 팀이 아닌 각각의 저자들이 제공하고 관리한다.

더 많은 정보는 https://kubernetes.io/ko/docs/reference/using-api/client-libraries/

# K8s Glossary

Control Plane: 컨테이너의 라이프사이클을 정의, 배포, 관리하기 위한 API와 인터페이스들을 노출하는 컨테이너 오케스트레이션 레이어
API-Server: 쿠버네티스 API를 제공하는 컨트롤 플레인 컴포넌트

728x90

'Infra > Kubernetes' 카테고리의 다른 글

Kubernetes Object Management - 쿠버네티스 객체 관리 (2)	2023.10.21
쿠버네티스 객체 이해하기 - Kubernetes Object (2)	2023.10.19
쿠버네티스 구성 요소 - Kubernetes Components (0)	2023.10.13
쿠버네티스란 무엇인가? - Kubernetes (0)	2023.10.11
K8s Cluster에 kubectl 안될 때 - The connection to the server <host>:6443 was refused - did you specify the right host or port? (0)	2023.08.10

쿠버네티스 API 및 클라이언트 라이브러리 - Kubernetes API & Client Library