쿠버네티스 API

쿠버네티스 API (The Kubernetes API)

쿠버네티스 제어 플레인의 핵심은 API 서버(API server)예요. API 서버는 최종 사용자, 클러스터의 여러 부분, 외부 구성 요소가 서로 통신할 수 있게 해주는 HTTP API를 노출해요.

쿠버네티스 API는 쿠버네티스의 API 객체 상태를 쿼리하고 조작할 수 있게 해줘요(예: Pod, Namespace, ConfigMap, Event).

대부분의 작업은 kubectl 명령줄 인터페이스나 kubeadm 같은 다른 명령줄 도구를 통해 수행할 수 있으며, 이들은 API를 사용해요. 하지만 REST 호출로 API에 직접 접근할 수도 있어요. 쿠버네티스는 쿠버네티스 API를 사용해 애플리케이션을 작성하려는 사람들을 위한 클라이언트 라이브러리 집합을 제공해요.

각 쿠버네티스 클러스터는 클러스터가 서비스하는 API의 사양을 게시해요. 쿠버네티스가 이러한 API 사양을 게시하는 데 사용하는 메커니즘은 두 가지이며, 둘 다 자동 상호운용성을 가능하게 하는 데 유용해요. 예를 들어 kubectl 도구는 명령줄 완성 및 기타 기능을 활성화하기 위해 API 사양을 가져와 캐시해요. 지원되는 두 메커니즘은 다음과 같아요.

  • Discovery API는 쿠버네티스 API에 대한 정보(API 이름, 리소스, 버전, 지원되는 작업)를 제공해요. 이것은 쿠버네티스 OpenAPI와는 별개의 API이므로 쿠버네티스 특정 용어예요. 이는 사용 가능한 리소스의 간략한 요약을 의도하며 리소스의 특정 스키마를 상세히 다루지는 않아요. 리소스 스키마에 대한 참조는 OpenAPI 문서를 참조하세요.
  • 쿠버네티스 OpenAPI 문서는 모든 쿠버네티스 API 엔드포인트에 대한 (전체) OpenAPI v2.0 및 3.0 스키마를 제공해요. OpenAPI v3은 API에 대한 더 포괄적이고 정확한 보기를 제공하므로 OpenAPI에 접근하는 선호 방법이에요. 모든 사용 가능한 API 경로와, 모든 엔드포인트의 모든 작업에 대해 소비되고 생성되는 모든 리소스를 포함해요. 또한 클러스터가 지원하는 확장성 구성 요소도 포함해요. 이 데이터는 완전한 사양이며 Discovery API의 데이터보다 훨씬 커요.

출처: 문서

본문

Discovery API

쿠버네티스는 Discovery API를 통해 지원되는 모든 그룹 버전과 리소스 목록을 게시해요. 이는 각 리소스에 대해 다음을 포함해요.

  • 이름
  • 클러스터 또는 네임스페이스 범위
  • 엔드포인트 URL과 지원되는 동사(verbs)
  • 대체 이름
  • 그룹, 버전, 종류

API는 집계(aggregated) 및 비집계(unaggregated) 형태로 모두 사용할 수 있어요. 집계된 discovery는 두 개의 엔드포인트를 서비스하고, 비집계된 discovery는 각 그룹 버전에 대해 별도의 엔드포인트를 서비스해요.

집계된 discovery (Aggregated discovery)

이 기능은 쿠버네티스에서 안정(stable) 기능이에요. 1.30 릴리스부터 그랬어요. 이 기능을 더 이상 전환할 수 없어요(관련 기능 게이트가 제거됨).

쿠버네티스는 집계된 discovery에 대한 안정적인 지원을 제공하며, 클러스터가 지원하는 모든 리소스를 두 엔드포인트(/api와 /apis)를 통해 게시해요. 이 엔드포인트를 요청하면 클러스터에서 discovery 데이터를 가져오기 위해 보내는 요청 수를 크게 줄여요. 집계된 discovery 리소스를 나타내는 Accept 헤더와 함께 각각의 엔드포인트를 요청해 데이터에 접근할 수 있어요: Accept: application/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList.

Accept 헤더로 리소스 유형을 나타내지 않으면 /api와 /apis 엔드포인트의 기본 응답은 비집계 discovery 문서예요.

내장 리소스에 대한 discovery 문서는 쿠버네티스 GitHub 저장소에서 찾을 수 있어요. 이 Github 문서는 쿼리할 쿠버네티스 클러스터가 없을 때 사용 가능한 리소스의 기본 집합에 대한 참조로 사용할 수 있어요.

엔드포인트는 ETag와 protobuf 인코딩도 지원해요.

비집계 discovery (Unaggregated discovery)

discovery 집계가 없으면 discovery는 수준별로 게시되며, 루트 엔드포인트는 하위 문서에 대한 discovery 정보를 게시해요.

클러스터가 지원하는 모든 그룹 버전 목록이 /api와 /apis 엔드포인트에 게시돼요. 예시:

{
  "kind": "APIGroupList",
  "apiVersion": "v1",
  "groups": [
    {
      "name": "apiregistration.k8s.io",
      "versions": [
        {
          "groupVersion": "apiregistration.k8s.io/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apiregistration.k8s.io/v1",
        "version": "v1"
      }
    },
    {
      "name": "apps",
      "versions": [
        {
          "groupVersion": "apps/v1",
          "version": "v1"
        }
      ],
      "preferredVersion": {
        "groupVersion": "apps/v1",
        "version": "v1"
      }
    },
    ...
}

각 그룹 버전에 대한 discovery 문서를 얻으려면 /apis/<group>/<version>(예: /apis/rbac.authorization.k8s.io/v1alpha1)에서 추가 요청이 필요하며, 특정 그룹 버전 아래에서 서비스되는 리소스 목록을 광고해요. kubectl은 클러스터가 지원하는 리소스 목록을 가져오기 위해 이 엔드포인트를 사용해요.

OpenAPI 인터페이스 정의

OpenAPI 사양에 대한 자세한 내용은 OpenAPI 문서를 참고하세요.

쿠버네티스는 OpenAPI v2.0과 v3.0을 모두 서비스해요. OpenAPI v3은 쿠버네티스 리소스의 더 포괄적인(무손실) 표현을 제공하므로 OpenAPI에 접근하는 선호 방법이에요. OpenAPI 버전 2의 제한으로 인해 default, nullable, oneOf를 포함하되 이에 국한되지 않는 특정 필드가 게시된 OpenAPI에서 제외돼요.

OpenAPI V2

쿠버네티스 API 서버는 /openapi/v2 엔드포인트를 통해 집계된 OpenAPI v2 사양을 서비스해요. 요청 헤더로 응답 형식을 요청할 수 있어요.

헤더 가능한 값 참고
Accept-Encoding gzip 이 헤더를 제공하지 않아도 허용됨
Accept application/[email protected]+protobuf 주로 클러스터 내부 사용용
application/json 기본
* application/json 서비스

경고:

OpenAPI V3

이 기능은 쿠버네티스에서 안정(stable) 기능이에요. 1.27 릴리스부터 그랬어요. 이 기능을 더 이상 전환할 수 없어요(관련 기능 게이트가 제거됨).

쿠버네티스는 API에 대한 설명을 OpenAPI v3로 게시하는 것을 지원해요.

사용 가능한 모든 그룹/버전 목록을 보려면 /openapi/v3 discovery 엔드포인트가 제공돼요. 이 엔드포인트는 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/apis/<group>/<version>?hash=<hash> 엔드포인트에서 그룹 버전별 OpenAPI v3 사양을 게시해요.

허용되는 요청 헤더는 아래 표를 참고하세요.

헤더 가능한 값 참고
Accept-Encoding gzip 이 헤더를 제공하지 않아도 허용됨
Accept application/[email protected]+protobuf 주로 클러스터 내부 사용용
application/json 기본
* application/json 서비스

OpenAPI V3를 가져오는 Golang 구현이 k8s.io/client-go/openapi3 패키지에 제공돼요.

쿠버네티스 1.37은 OpenAPI v2.0과 v3.0을 게시해요. 가까운 시일 내에 3.1을 지원할 계획은 없어요.

Protobuf 직렬화

쿠버네티스는 주로 클러스터 내부 통신을 위해 설계된 대체 Protobuf 기반 직렬화 형식을 구현해요. 이 형식에 대한 자세한 내용은 쿠버네티스 Protobuf 직렬화 설계 제안과, API 객체를 정의하는 Go 패키지에 있는 각 스키마의 인터페이스 정의 언어(IDL) 파일을 참고하세요.

영속성 (Persistence)

쿠버네티스는 객체의 직렬화된 상태를 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 버전이 있다고 해 보죠. 원래 v1beta1 버전의 API로 객체를 만들었다면, v1beta1 버전이 폐기되고 제거될 때까지 v1beta1 또는 v1 API 버전으로 그 객체를 읽고, 업데이트하고, 삭제할 수 있어요. 그 시점에는 v1 API로 객체에 계속 접근하고 수정할 수 있어요.

API 변경 (API changes)

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

일반적으로 새 API 리소스와 새 리소스 필드는 자주, 빈번하게 추가될 수 있어요. 리소스나 필드의 제거는 API 폐기 정책을 따라야 해요.

쿠버네티스는 공식 쿠버네티스 API가 일반 사용 가능(GA)에 도달하면(보통 API 버전 v1) 그 호환성을 유지하겠다는 강력한 약속을 해요. 또한 쿠버네티스는 공식 쿠버네티스 API의 베타 API 버전을 통해 유지된 데이터와의 호환성을 유지하고, 기능이 안정화되면 GA API 버전을 통해 데이터가 변환되고 접근될 수 있도록 보장해요.

베타 API 버전을 채택했다면, API가 졸업한 후 후속 베타 또는 안정 API 버전으로 전환해야 해요. 이 작업을 하기 가장 좋은 시기는 베타 API의 폐기 기간 동안인데, 객체가 두 API 버전 모두로 동시에 접근 가능하기 때문이에요. 베타 API가 폐기 기간을 완료하고 더 이상 서비스되지 않으면, 교체 API 버전을 사용해야 해요.

참고:

API 버전 수준 정의에 대한 자세한 내용은 API 버전 참조를 참고하세요.

API 확장 (API Extension)

쿠버네티스 API는 두 가지 방법 중 하나로 확장될 수 있어요.

  • 커스텀 리소스(custom resources)는 API 서버가 선택한 리소스 API를 제공하는 방법을 선언적으로 정의할 수 있게 해줘요.
  • 집계 계층(aggregation layer)을 구현해 쿠버네티스 API를 확장할 수도 있어요.

더 알아보기 (Learn more)

  • 자신의 CustomResourceDefinition을 추가해 쿠버네티스 API를 확장하는 방법을 배워 보세요.
  • 쿠버네티스 API 접근 제어는 클러스터가 API 접근에 대한 인증과 권한 부여를 어떻게 관리하는지 설명해요.
  • API 참조를 읽어 API 엔드포인트, 리소스 유형, 예시에 대해 배워 보세요.
  • API 변경에서 호환되는 변경이 무엇을 구성하고, API를 어떻게 변경하는지 배워 보세요.