CRD에 대해 Webhook을 통한 유효성 검증

CRD에 대한 Webhook은 보통 다음 두 가지 용도로 사용됩니다:

1. Validation Webhook – 리소스의 생성/수정 요청이 유효한지 검사
2. Mutation Webhook – 리소스를 자동으로 수정(default 값 설정 등)

 

왜 Webhook Validation을 사용할까?

기본적으로 CRD의 유효성 검증은 OpenAPI v3 Schema로 처리할 수 있지만,
복잡한 조건 (예: 필드 간 종속성, 외부 리소스 검사 등)은 Webhook을 통해 동적으로 처리할 수 있습니다.

예를 들어:

• spec.replicas는 1 이상이어야 한다
• spec.env 값이 prod일 때는 spec.logging이 필수다
• 특정 필드가 UUID 형식인지 검사

이런 복잡한 로직은 오직 Validation Webhook으로만 가능합니다.

 

Webhook 구조

Webhook은 일반적인 HTTP 서버입니다.
Kubernetes는 리소스의 생성/변경 시 Webhook으로 AdmissionReview 요청을 보내고,
Webhook은 AdmissionResponse로 승인 여부를 응답합니다.

 

구현 예시 (controller-runtime 기반)

여기서는 Kubebuilder + controller-runtime 기반 예제를 보여드릴게요.

1. CRD 구조 예: MyApp

// api/v1/myapp_types.go
type MyAppSpec struct {
    Replicas int    `json:"replicas"`
    Env      string `json:"env"`
    Logging  bool   `json:"logging,omitempty"`
}

type MyApp struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec              MyAppSpec `json:"spec,omitempty"`
}

 

 

2. Validation Webhook 구현

// api/v1/myapp_webhook.go

func (r *MyApp) ValidateCreate() error {
    if r.Spec.Replicas < 1 {
        return fmt.Errorf("replicas must be >= 1")
    }

    if r.Spec.Env == "prod" && !r.Spec.Logging {
        return fmt.Errorf("logging must be enabled in prod environment")
    }

    return nil
}

func (r *MyApp) ValidateUpdate(old runtime.Object) error {
    return r.ValidateCreate() // 동일 로직 재사용
}

func (r *MyApp) ValidateDelete() error {
    return nil
}

 

이 구조는 controller-runtime에서 자동으로 webhook 서버를 만들어줍니다.

 

3. Webhook 활성화 

Webhook을 사용하려면 main.go에서 등록해야 합니다.

// main.go
func main() {
    ...
    if err = (&myv1.MyApp{}).SetupWebhookWithManager(mgr); err != nil {
        log.Fatal(err)
    }
    ...
}

 

4. Webhook을 위한 인증서와 설정 (kubebuilder 사용 시 자동 생성됨)

 

• config/webhook/kustomization.yaml
• config/webhook/manifests.yaml
• ValidatingWebhookConfiguration 객체도 자동 생성됩니다.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: myapp-webhook
webhooks:
  - name: vmyapp.kb.io
    rules:
      - apiGroups: ["myorg.io"]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["myapps"]
    clientConfig:
      service:
        name: myapp-webhook-service
        namespace: default
        path: /validate-myorg-v1-myapp
      caBundle: ...

 

 

 

정리 

항목	설명
목적	CRD 생성/변경 시 정교한 유효성 검증을 수행
방법	controller-runtime에서 ValidateCreate(), ValidateUpdate() 구현
배포	Webhook 서버와 ValidatingWebhookConfiguration 설정
인증	TLS 인증서 필요 (kubebuilder 사용 시 자동 생성 가능)
주의사항	Webhook이 응답하지 않으면 리소스 생성/수정도 실패함 (높은 가용성 필요)