쿠버네티스 API
쿠버네티스 컨트롤 플레인의 핵심은 API 서버이다. API 서버는 최종 사용자, 클러스터의 다른 부분 그리고 외부 컴포넌트가 서로 통신할 수 있도록 HTTP API를 제공한다.
쿠버네티스 API를 사용하면 쿠버네티스의 API 오브젝트(예: 파드(Pod), 네임스페이스(Namespace), 컨피그맵(ConfigMap) 그리고 이벤트(Event))를 질의(query)하고 조작할 수 있다.
대부분의 작업은 kubectl 커맨드 라인 인터페이스 또는 API를 사용하는 kubeadm과 같은 다른 커맨드 라인 도구를 통해 수행할 수 있다. 그러나, REST 호출을 사용하여 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에 기반한 직렬화 형식을 구현한다. 이 형식에 대한 자세한 내용은 쿠버네티스 Protobuf 직렬화 디자인 제안과 API 오브젝트를 정의하는 Go 패키지에 들어있는 각각의 스키마에 대한 IDL(인터페이스 정의 언어) 파일을 참고한다.
OpenAPI V3
Kubernetes v1.24 [beta]쿠버네티스 v1.32 버전은 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 캐싱 헤더를
설정한다(Expires를 1년 뒤로, Cache-Control을 immutable).
사용 중단된 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으로 응답 |
지속성
쿠버네티스는 오브젝트의 직렬화된 상태를 etcd에 기록하여 저장한다.
API 그룹과 버전 규칙
필드를 쉽게 제거하거나 리소스 표현을 재구성하기 위해,
쿠버네티스는 각각 /api/v1 또는 /apis/rbac.authorization.k8s.io/v1alpha1 과
같은 서로 다른 API 경로에서 여러 API 버전을 지원한다.
버전 규칙은 리소스나 필드 수준이 아닌 API 수준에서 수행되어 API가 시스템 리소스 및 동작에 대한 명확하고 일관된 보기를 제공하고 수명 종료 및/또는 실험적 API에 대한 접근을 제어할 수 있도록 한다.
보다 쉽게 발전하고 API를 확장하기 위해, 쿠버네티스는 활성화 또는 비활성화가 가능한 API 그룹을 구현한다.
API 리소스는 API 그룹, 리소스 유형, 네임스페이스 (네임스페이스 리소스용) 및 이름으로 구분된다. API 서버는 API 버전 간의 변환을 투명하게 처리한다. 서로 다른 모든 버전은 실제로 동일한 지속 데이터의 표현이다. API 서버는 여러 API 버전을 통해 동일한 기본 데이터를 제공할 수 있다.
예를 들어, 동일한 리소스에 대해 v1 과 v1beta1 이라는 두 가지 API 버전이
있다고 가정하자. API의 v1beta1 버전을 사용하여 오브젝트를 만든 경우,
v1beta1 버전이 사용 중단(deprecated)되고 제거될 때까지는
v1beta1 또는 v1 API 버전을 사용하여 해당 오브젝트를 읽거나, 업데이트하거나, 삭제할 수 있다.
그 이후부터는 v1 API를 사용하여 계속 오브젝트에 접근하고 수정할 수 있다.
API 변경 사항
성공적인 시스템은 새로운 유스케이스가 등장하거나 기존 사례가 변경됨에 따라 성장하고 변화해야 한다. 따라서, 쿠버네티스는 쿠버네티스 API가 지속적으로 변경되고 성장할 수 있도록 설계했다. 쿠버네티스 프로젝트는 기존 클라이언트와의 호환성을 깨지 않고 다른 프로젝트가 적응할 기회를 가질 수 있도록 장기간 해당 호환성을 유지하는 것을 목표로 한다.
일반적으로, 새 API 리소스와 새 리소스 필드는 자주 추가될 수 있다. 리소스 또는 필드를 제거하려면 API 지원 중단 정책을 따라야 한다.
쿠버네티스는 일반적으로 API 버전 v1 에서 안정 버전(GA)에 도달하면, 공식 쿠버네티스 API에
대한 호환성 유지를 강력하게 이행한다. 또한,
쿠버네티스는 공식 쿠버네티스 API의 베타 API 버전으로 만들어진 데이터와도 호환성을 유지하며,
해당 기능이 안정화되었을 때 해당 데이터가 안정 버전(GA)의 API 버전들에 의해 변환되고 접근될 수 있도록 보장한다.
만약 베타 API 버전을 사용했다면, 해당 API가 승급했을 때 후속 베타 버전 혹은 안정된 버전의 API로 전환해야 한다. 해당 작업은 오브젝트 접근을 위해 두 API 버전 모두 사용할 수 있는 베타 API의 사용 중단(deprecation) 시기일 때 진행하는 것이 최선이다. 베타 API의 사용 중단(deprecation) 시기가 끝나고 더 이상 사용될 수 없다면 반드시 대체 API 버전을 사용해야 한다.
참고:
비록 쿠버네티스는 알파 API 버전에 대한 호환성을 유지하는 것을 목표로 하지만, 일부 상황에서 이는 불가능하다. 알파 API 버전을 사용하는 경우, 클러스터를 업그레이드해야 할 때에는 API 변경으로 인해 호환성이 깨지고 업그레이드 전에 기존 오브젝트를 전부 제거해야 하는 상황에 대비하기 위해 쿠버네티스의 릴리스 정보를 확인하자.API 버전 수준 정의에 대한 자세한 내용은 API 버전 레퍼런스를 참조한다.
API 확장
쿠버네티스 API는 다음 두 가지 방법 중 하나로 확장할 수 있다.
- 커스텀 리소스를 사용하면 API 서버가 선택한 리소스 API를 제공하는 방법을 선언적으로 정의할 수 있다.
- 애그리게이션 레이어(aggregation layer)를 구현하여 쿠버네티스 API를 확장할 수도 있다.
다음 내용
- 자체 CustomResourceDefinition을 추가하여 쿠버네티스 API를 확장하는 방법에 대해 배우기.
- 쿠버네티스 API 접근 제어하기는 클러스터가 API 접근을 위한 인증 및 권한을 관리하는 방법을 설명한다.
- API 레퍼런스를 읽고 API 엔드포인트, 리소스 유형 및 샘플에 대해 배우기.
- API 변경 사항에서 호환 가능한 변경 사항을 구성하고, API를 변경하는 방법에 대해 알아본다.