[ DEVOCEAN OpenLab ] Kubernetes API 와 kubebuilder

[ 최종 목표 ] kubebuilder 를 사용하여 Custom Controller 생성하기

[ 학습 단계 ]

1) Kubernetes API, Custom Resource와 Controller 란?

2) kubebuilder 란? kubebuilder 아키텍처 학습

3) Controller-runtime 주요 기능

 

 

1.1  Kubernetes API 란? Custom Resource & Controller 란?

 쿠버네티스 컨트롤 플레인(control plane)의 핵심이라고 할 수 있다. API 서버는 최종 사용자, 클러스터의 다른 부분 그리고 외부 컴포넌트가 서로 통신할 수 있도록 HTTP API 를 제공한다. 쿠버네티스 API를 사용하면 쿠버네티스의 API 오브젝트(예: 파드(Pod), 네임스페이스(Namespace), 컨피그맵(ConfigMap) 그리고 이벤트(Event))를 질의(query)하고 조작할 수 있다.

 대부분의 작업은 kubectl 커맨드 라인 인터페이스 또는 API를 사용하는 kubeadm과 같은 다른 커맨드 라인 도구를 통해 수행할 수 있다. 그러나, REST 호출을 사용하여 API에 직접 접근할 수도 있다.

 

 쿠버네티스에는 기본 제공되는 리소스가 있다. 현재 내 쿠버네티스 환경에서 제공되고 있는 리소스의 종류를 알기 위해서는 아래의 명령어로 확인가능하다.

kubectl api-resources -o wide

명결과로는 익숙한 리소스인 deployment, pod, replicaset 등등이 있는 것을 볼 수 있다.

 

1.2  Custom Resource & Controller 란?

 위의 사진에서 보이는 쿠버네티스 기본 리소스를 넘어 사용자가 정의한 새로운 리소스 유형을 Kubernetes API에 추가할 수 있다. 여기서 사용자가 정의한 새로운 리소스 유형을 바로 Custom Resource 이라고 한다. 자신만의 리소스를 클러스터에 추가하려면 CRD(Custom Resource Definition) 작업을 거쳐야한다. 이렇게 CRD를 통해 kubernetes API를 확장하여 새로운 엔드포인트와 리소스를 추가할 수 있다. 쿠버네티스 클러스터가 실행 중일 때 새로운 커스텀 리소스를 추가하거나 제거할 수 있는 동적 등록이 가능하다. 즉, 클러스터 중지 또는 재시작 없이 새로운 리소스 등록 및 삭제가 가능하다는 것이다. 또한 커스텀 리소스가 등록되면 사용자는 kubectl 명령어를 통해 해당 리소스를 관리할 수 있다.

 

 커스텀 리소스에 컨트롤러를 결합하면 Kubernetes API에 진정한 선언적 API를 제공할 수 있다. 선언적 API는 사용자가 리소스의 의도한 상태를 선언하면, Controller가 실제 리소스의 상태를 선언한 상태와 동기화시킨다. 이는 사용자가 서버에게 무엇을 해야 할지 명령하는 명령적 API와는 달리, 원하는 상태를 선언하고 Kubernetes가 이를 유지하는 방식이다. 커스텀 컨드롤러도 클러스터를 재시작하지 않고도 새로운 컨트롤러를 배포하거나 기존 컨트롤러를 업데이트할 수 있다.

 

이후에는 Custom Resource 와 Custom Controller를 통해 클러스터에서 더욱 복잡하고 특정한 요구사항을 처리할 수 있게 된다.

 

2. kubebuilder 란 ?  kubebuilder 아키텍처 학습

 kubebuilder는 자체 kubernetes API를 개발하여 쿠버네티스를 확장하여 사용할 수 있도록 도와주는 CLI 도구이다. kubebuilder 를 사용하면 CRD과 Custom Controller를 쉽게 생성하고 관리할 수 있다.

 

< 주요 기능 >

- 프로젝트 구조 생성 (Scaffolding) : kubebuilder는 프로젝트를 시작할 때 필요한 디렉토리 구조와 설정 파일을 자동으로 생성해준다. 이를 통해 개발자는 반복적인 초기 설정 작업을 생략하고 바로 코드 작성에 집중할 수 있다. kubebuilder 초기화 명령으로 시작할 때 도메인과 레포지토리 설정을 한다. 초기화 이후에는 기본 디렉토리 및 파일 구조가 자동으로 생성된 것을 볼 수 있다. 이것을 바로 스케폴딩(Scaffolding) 기능이라고 할 수 있다.

 

- API 및 CRD 생성 : kubebuilder는 새로운 API 그룹과 버전을 생성하고, 이에 맞는 CRD를 정의하는 기능을 제공한다. 이 과정에서 필요한 모든 파일과 디렉토리가 자동으로 생성된다.

 

- Controller 생성 : kubebuilder는 CRD와 연동되는 Custom Controller를 생성하여 리소스의 상태를 자동으로 관리한다. 컨트롤러는 CRD의 인스턴스를 모니터링하고, 정의된 상태와 실제 상태를 동기화하는 로직을 포함한다.

 

< kubebuilder 아키텍처 >

자료 출처: https://devocean.sk.com/blog/techBoardDetail.do?ID=165032&boardType=techBlog

 

Kubebuilder는 기본적으로 컨트롤러를 개발하기 위해 controller-runtime 라이브러리를 사용한다. 이 라이브러리는 Kubernetes의 컨트롤러 패턴을 구현하는 데 필수적이며, 아래의 주요 기능들을 제공한다.

 

3. Controller-runtime 주요 기능

- Process : 클러스터당 하나씩 존재하거나 HA 를 사용하는 경우 여러 개를 만들 수 있다.

- Manager : Kubernetes 클러스터와의 상호작용을 담당하는 핵심 인터페이스이다. 컨트롤러의 실행을 관리하고, 리소스의 상태 변화를 감지하며 관련된 리소스들을 Kubernetes API 서버에 반영한다. 프로세스당 하나씩 만들 수 있다.

- Client : Kubernetes API 서버와의 통신을 담당하는 인터페이스이다. 컨트롤러는 Client를 사용하여 Kubernetes 리소스를 생성, 조회, 업데이트, 삭제할 수 있다.

- Cache : Controller는 Client Cache를 활용하여 실시간으로 변경된 리소스 상태를 반영하고, 필요한 동작을 수행한다.

- Controller : 특정한 리소스 타입에 대한 동작을 정의한다. 각 컨트롤러는 특정 리소스와 연결되어 해당 리소스의 상태를 모니터링하고 필요한 작업을 수행한다. Reconscile 되는 리소스 유형들마다 하나씩 존재한다. 또한 filter를 통해 이벤트를 가져오고, 이벤트를 받을 때마다 reconciler 를 호출한다. back-off 처리 및 이벤트의 queue와 re-queue를 처리한다.

- Predicate : 이벤트 스트림을 필터링하여, reconciler에 처리가 필요한 이벤트만 넘겨준다.

- Reconciler : 컨트롤러의 핵심 로직을 구현하는 인터페이스로, 리소스의 현재 상태와 원하는 상태를 동기화하는 역할을 한다.

- Webhook : 리소스의 생성, 업데이트, 삭제 시점에 추가적인 검증이나 변환을 수행하는 웹훅 서버를 제공한다.

- Defulter : spec에서 설정되지 않은 필드는 여기서 설정된다.

- Validator : 잘못 설정된 object를 거부한다.

 

다음 게시물에서는 kubebuilder 를 사용하여 Custom Controller 를 생성해보겠다.

 

 

 

자료 출처:

https://kubernetes.io/ko/docs/concepts/extend-kubernetes/api-extension/custom-resources/
https://kubernetes.io/ko/docs/concepts/overview/kubernetes-api/