쿠버네티스 API

2022. 7. 11. 11:28

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

쿠버네티스 API를 사용하면 쿠버네티스의 API 오브젝트(예: 파드(Pod), 네임스페이스(Namespace), 컨피그맵(ConfigMap) 그리고 이벤트(Event))를 질의(query)하고 조작할 수 있다.

대부분의 작업은 kubectl cli 또는 API 를 사용하는 kubeadm 과 같은 다른 커맨드 라인 도구를 통해 수행하는 편이지만 경우에 따라 REST call 을 사용하여 API 에 직접 접근하는 경우도 있다.

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

OpenAPI 명세

완전한 API 상세 내용은 OpenAPI 를 활용해서 문서화했다.

OpenAPI V2

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

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

쿠버네티스는 주로 클러스터 내부 통신을 위해 Protobuf 에 기반한 직렬화 형식을 구현한다.

OpenAPI V3

기능 상태: Kubernetes v1.24 [beta]

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

/openapi/v3 디스커버리 엔드포인트는 사용 가능한 모든 그룹/버전의 목록을 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 은 변경 불가능한(immutable) OpenAPI 상세를 가리키고 있으며, 이는 클라이언트에서의 캐싱을 향상시키기 위함이다. 같은 목적을 위해 API 서버는 적절한 HTTP 캐싱 헤더를 설정한다. 사용 중단된 URL 을 사용하면 API 서버는 최신 URL 로의 리다이렉트를 제공한다.

쿠버네티스 API 서버는 쿠버네티스 그룹 버전에 따른 OpenAPI v3 스펙을 /openapi/v3/apis/<group>/<version>?hash=<hash> 엔드포인트에 게시한다. 요청 헤더에 다음과 같이 기재하여 응답 형식을 지정할 수 있다.

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

지속성(Persistence)

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

API 그룹과 버전 규칙

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

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

API 리소스는 API 그룹, 리소스 유형, 네임스페이스 (네임스페이스 리소스용) 및 이름으로 구분된다. API 서버는 API 버전 간의 변환을 투명하게 처리한다. API 서버는 여러 API 버전을 통해 동일한 기본 데이터를 제공한다.

예를 들어, 동일한 리소스에 대해 v1 과 v1beta1 이라는 두 가지 API 버전이 있다고 가정하면 원래 API 의 v1beta1 버전을 사용하여 오브젝트를 만든 경우, 나중에 v1beta1 또는 v1 API 버전을 사용하여 해당 오브젝트를 읽거나 업데이트하거나 삭제할 수 있다.

API 변경 사항

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

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

쿠버네티스는 일반적으로 API 버전 v1 에서 안정 버전(general availability)에 도달하면, 공식 쿠버네티스 API 에 대한 호환성 유지한다. 또한, 쿠버네티스는 가능한 경우 베타 API 버전에서도 호환성을 유지한다. 베타 API 를 채택하면 기능이 안정된 후에도 해당 API 를 사용하여 클러스터와 계속 상호 작용할 수 있다.

참고: 쿠버네티스는 또한 alpha API 버전에 대한 호환성을 유지하는 것을 목표로 하지만, 일부 상황에서는 호환성이 깨질 수 있기 때문에 alpha API 버전을 사용하는 경우, API가 변경된 경우 클러스터를 업그레이드할 때 쿠버네티스에 대한 릴리스 정보를 확인해야한다.

API 버전 수준 정의에 대한 자세한 내용은 API 버전 레퍼런스를 참조한다.

API 확장

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

커스텀 리소스를 사용하면 API 서버가 선택한 리소스 API 를 제공하는 방법을 선언적으로 정의할 수 있다.
통합 계층(aggregation layer)을 구현하여 쿠버네티스 API 를 확장할 수 있다.

저작자표시 (새창열림)

'플랫폼 > kubernetes' 카테고리의 다른 글

쿠버네티스 오브젝트 이름, ID (0)	2022.07.12
쿠버네티스 오브젝트 관리 (0)	2022.07.12
쿠버네티스 오브젝트란? (0)	2022.07.12
쿠버네티스 클러스터 구성요소 (0)	2022.07.11
쿠버네티스란? (0)	2022.07.11

맥스네 블로그