Kubernetes Operator 개발 가이드: Kubebuilder로 Custom Resource 정의하기

 

Kubernetes Operator 개발 가이드: Kubebuilder로 Custom Resource 정의하기

---

1. Kubernetes Operator란 무엇인가?

Kubernetes Operator는 쿠버네티스에서 복잡한 애플리케이션의 생명주기 관리(배포, 업그레이드, 복구 등)를 자동화하는 패턴입니다. 기존 쿠버네티스는 Deployment, Service 같은 기본 리소스를 통해 애플리케이션을 관리하지만, 복잡한 비즈니스 로직이나 상태(state)를 갖는 애플리케이션 관리에는 한계가 존재했습니다.

Operator는 다음을 목표로 합니다.

• 사용자 정의 리소스(Custom Resource, CR)를 통해 고유한 객체 모델 제공
• 사용자 정의 컨트롤러(Custom Controller)를 통해 상태 변화를 감지하고 원하는 상태로 시스템을 조정

1.1 Operator의 핵심 구성 요소

• Custom Resource (CR): 새로운 API 객체
• Custom Controller: CR을 감시하고 필요한 작업 수행

---

2. Kubebuilder란 무엇인가?

Kubebuilder는 Go 언어 기반으로 Kubernetes Operator를 쉽게 개발할 수 있도록 돕는 프레임워크입니다.
Kubebuilder는 다음과 같은 기능을 제공합니다.

• 프로젝트 스캐폴딩(구조 생성)
• API 그룹과 버전 생성
• CRD(CustomResourceDefinition) 생성 및 관리
• Controller, Webhook 등을 자동화된 패턴으로 생성

Kubebuilder는 Kubernetes 공식 프로젝트인 controller-runtime과 controller-tools 라이브러리를 기반으로 하여 강력하고 일관성 있는 Operator 개발을 지원합니다.

---

3. Kubebuilder 설치 및 준비

3.1 필수 사전 조건

• Go 언어 설치 (버전 1.20 이상 권장)
• Kubernetes 클러스터 접근 가능(Minikube, Kind, EKS 등)
• Kubectl 설치
• Kustomize 설치(Kubebuilder가 내부적으로 사용)

3.2 Kubebuilder 설치

curl -L -o kubebuilder https://github.com/kubernetes-sigs/kubebuilder/releases/download/v3.10.0/kubebuilder_3.10.0_$(uname -s)_$(uname -m).tar.gz
tar -xzvf kubebuilder
sudo mv kubebuilder /usr/local/bin/
kubebuilder version

---

4. Kubebuilder 프로젝트 생성

4.1 프로젝트 초기화

kubebuilder init --domain example.com --repo github.com/example/memcached-operator

옵션 설명:

• --domain: API 그룹 기본 도메인 (ex: cache.example.com)
• --repo: 프로젝트 모듈 이름

4.2 API(Group/Version/Kind) 생성

kubebuilder create api --group cache --version v1 --kind Memcached

옵션 설명:

• Group: API 그룹 이름
• Version: API 버전
• Kind: 리소스 종류

질문에 따라 다음처럼 답변:

• Create Resource? (yes)
• Create Controller? (yes)

---

5. Custom Resource 정의하기

Kubebuilder는 생성한 API에 맞춰 api/v1/memcached_types.go 파일을 만들어 줍니다. 여기서 스펙을 수정할 수 있습니다.

5.1 스펙 정의

type MemcachedSpec struct {
    Size int32 `json:"size"`
}

Size는 Memcached 인스턴스의 복제 개수를 의미합니다.

5.2 상태(Status) 정의

type MemcachedStatus struct {
    Nodes []string `json:"nodes"`
}

Status는 현재 Memcached Pod들의 이름을 기록합니다.

5.3 CRD 생성 어노테이션

Kubebuilder는 어노테이션을 통해 CRD 스펙을 추가 정의할 수 있습니다.

// +kubebuilder:subresource:status
// +kubebuilder:resource:path=memcacheds,scope=Namespaced

• subresource:status: 별도의 Status 업데이트 API 생성
• resource:path=memcacheds: 리소스 이름(memcacheds) 정의

---

6. Controller 작성 및 동작 정의

Kubebuilder는 controllers/memcached_controller.go 파일을 생성합니다. 여기서 CR 감시 및 조정 로직을 작성할 수 있습니다.

6.1 Reconcile 메소드 기본 구조

func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    var memcached cachev1.Memcached
    if err := r.Get(ctx, req.NamespacedName, &memcached); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }

    // 비즈니스 로직 추가
    return ctrl.Result{}, nil
}

6.2 상태를 읽고 원하는 상태로 조정

• 현재 배포된 ReplicaSet 상태 조회
• 필요 시 생성하거나 업데이트
• CR Status 필드 업데이트

deployment := &appsv1.Deployment{
    ObjectMeta: metav1.ObjectMeta{
        Name:      memcached.Name,
        Namespace: memcached.Namespace,
    },
    Spec: appsv1.DeploymentSpec{
        Replicas: &memcached.Spec.Size,
        ...
    },
}
if err := r.Create(ctx, deployment); err != nil {
    return ctrl.Result{}, err
}

---

7. CustomResourceDefinition(CRD) 배포

7.1 CRD 생성 및 Controller 배포

make install
make run

• make install: CRD 생성
• make run: 로컬에서 Controller 실행

7.2 커스텀 리소스(CR) 생성

config/samples/cache_v1_memcached.yaml 파일을 수정 후 배포

apiVersion: cache.example.com/v1
kind: Memcached
metadata:
  name: example-memcached
spec:
  size: 3

kubectl apply -f config/samples/cache_v1_memcached.yaml

---

8. Kubebuilder 주요 기능 정리

기능	설명
init	프로젝트 스캐폴딩 생성
create api	API(Group/Version/Kind) 생성
CRD 자동 관리	어노테이션 기반 CRD YAML 생성
Controller 템플릿 생성	기본 Reconcile 로직 스캐폴딩
make install	CRD 등록
make run	컨트롤러 로컬 실행

---

9. 고급 기능: Webhook, Validation, Defaulting

Kubebuilder는 Admission Webhook 생성을 지원하여 Custom Resource에 대해 다음을 할 수 있습니다.

• Create/Update 시 유효성 검증(Validation)
• Default 값 자동 설정(Defaulting)
• Mutating Admission

9.1 예시: Validation 추가

// +kubebuilder:validation:Minimum=1
// +kubebuilder:validation:Maximum=10
Size int32 `json:"size"`

• Memcached 복제 개수를 1~10 사이로 제한

9.2 Webhook 생성 명령어

kubebuilder create webhook --group cache --version v1 --kind Memcached --defaulting --programmatic-validation

---

10. 실전에서 Operator 개발시 고려사항

• Idempotency(멱등성): Reconcile 메소드는 몇 번 호출되더라도 같은 결과를 유지해야 함
• OwnerReferences 설정: 생성한 리소스(Pod, Service 등)가 CR과 함께 삭제되도록 설정
• Status 업데이트 주의: 상태 업데이트는 별도 API 호출이므로 빈번한 업데이트는 피해야 함
• 성능 최적화: Watch 대상 리소스를 최소화
• 테스트 작성: controller-runtime의 envtest 패키지를 활용하여 로컬 테스트 수행

---

11. 결론

Kubebuilder를 이용한 Kubernetes Operator 개발은 복잡한 클라우드 네이티브 애플리케이션을 관리하는 데 있어 필수적인 스킬로 자리 잡고 있습니다.
Kubebuilder는 프로젝트 구조화, CRD 정의, Controller 스캐폴딩을 표준화하여 Operator 개발을 빠르고 일관성 있게 진행할 수 있도록 도와줍니다.

Custom Resource 정의와 Reconcile 구현을 제대로 설계하면, 쿠버네티스 클러스터 내 모든 애플리케이션을 사람의 개입 없이 안정적으로 운용할 수 있는 기반을 마련할 수 있습니다.

Kubebuilder로 작은 Operator를 만드는 것부터 시작하여, 점진적으로 복잡한 상태 관리 및 자동화를 구현해 나가시길 추천드립니다.