Operator 고급 — Finalizer, Admission Webhook, Status·Conditions 설계

                     +-------------------------------+
   kubectl apply --> | Admission (mutating)          |  defaulting
                     |   - 기본값 채우기              |
                     +---------------+---------------+
                                     |
                                     v
                     +-------------------------------+
                     | Admission (validating)        |  validation
                     |   - 스펙 검증, 거부            |
                     +---------------+---------------+
                                     |
                                     v
                     +-------------------------------+
                     | etcd 저장 (spec)              |
                     +---------------+---------------+
                                     |
                                     v
                     +-------------------------------+
                     | Reconcile 루프                |  desired-state 수렴
                     |   - 외부 리소스 생성/갱신     |
                     |   - finalizer 추가            |
                     |   - status/conditions 갱신    |
                     +-------------------------------+

사용자: kubectl delete myresource foo
        |
        v
+-------------------------------------------+
| API 서버                                  |
|   finalizers가 비어있나?                   |
+--------------------+----------------------+
        | 비어있음                | 비어있지 않음
        v                        v
+----------------+    +-------------------------------+
| 즉시 GC 삭제   |    | deletionTimestamp 설정        |
+----------------+    | (객체는 남아있음, 삭제 예정)  |
                      +---------------+---------------+
                                      |
                                      v
                      +-------------------------------+
                      | Reconcile 재호출               |
                      |   deletionTimestamp != 0 감지 |
                      |   -> 외부 리소스 정리          |
                      |   -> finalizer 제거            |
                      +---------------+---------------+
                                      |
                                      v
                      +-------------------------------+
                      | finalizers 비었음 -> GC 삭제  |
                      +-------------------------------+

package controller

import (
	"context"

	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"

	cloudv1 "example.com/operator/api/v1"
)

const bucketFinalizer = "cloud.example.com/bucket-cleanup"

func (r *BucketReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	log := ctrl.LoggerFrom(ctx)

	var bucket cloudv1.Bucket
	if err := r.Get(ctx, req.NamespacedName, &bucket); err != nil {
		// NotFound는 이미 삭제된 것이므로 무시한다.
		return ctrl.Result{}, client.IgnoreNotFound(err)
	}

	// 1) 삭제 요청 여부 판단
	if !bucket.ObjectMeta.DeletionTimestamp.IsZero() {
		// 삭제 진행 중. finalizer가 아직 우리 것이라면 정리한다.
		if controllerutil.ContainsFinalizer(&bucket, bucketFinalizer) {
			if err := r.cleanupExternalBucket(ctx, &bucket); err != nil {
				// 정리 실패 시 finalizer를 남겨 두고 재시도하게 한다.
				log.Error(err, "외부 버킷 정리 실패")
				return ctrl.Result{}, err
			}

			// 정리 성공. finalizer 제거 -> GC가 객체를 지운다.
			controllerutil.RemoveFinalizer(&bucket, bucketFinalizer)
			if err := r.Update(ctx, &bucket); err != nil {
				return ctrl.Result{}, err
			}
		}
		// finalizer가 없으면 더 할 일이 없다.
		return ctrl.Result{}, nil
	}

	// 2) 정상 생성/갱신 경로: finalizer가 없으면 먼저 추가
	if !controllerutil.ContainsFinalizer(&bucket, bucketFinalizer) {
		controllerutil.AddFinalizer(&bucket, bucketFinalizer)
		if err := r.Update(ctx, &bucket); err != nil {
			return ctrl.Result{}, err
		}
		// Update가 새 리소스 버전을 만들었으므로 즉시 반환하고
		// 다음 Reconcile에서 본 작업을 이어간다.
		return ctrl.Result{}, nil
	}

	// 3) 실제 외부 리소스 수렴 로직
	if err := r.reconcileExternalBucket(ctx, &bucket); err != nil {
		return ctrl.Result{}, err
	}

	return ctrl.Result{}, nil
}

func (r *BucketReconciler) cleanupExternalBucket(ctx context.Context, bucket *cloudv1.Bucket) error {
	name := bucket.Status.ExternalName
	if name == "" {
		// 아직 외부 리소스를 만든 적이 없다 -> 정리할 것이 없다.
		return nil
	}

	err := r.CloudAPI.DeleteBucket(ctx, name)
	if isNotFound(err) {
		// 이미 없음 -> 성공으로 간주 (멱등성)
		return nil
	}
	return err
}

kubebuilder create webhook \
  --group cloud \
  --version v1 \
  --kind Bucket \
  --defaulting \
  --programmatic-validation

package webhookv1

import (
	"context"
	"fmt"

	"k8s.io/apimachinery/pkg/runtime"
	ctrl "sigs.k8s.io/controller-runtime"
	logf "sigs.k8s.io/controller-runtime/pkg/log"
	"sigs.k8s.io/controller-runtime/pkg/webhook"
	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"

	cloudv1 "example.com/operator/api/v1"
)

// +kubebuilder:webhook:path=/mutate-cloud-example-com-v1-bucket,mutating=true,failurePolicy=fail,sideEffects=None,groups=cloud.example.com,resources=buckets,verbs=create;update,versions=v1,name=mbucket-v1.kb.io,admissionReviewVersions=v1

type BucketCustomDefaulter struct {
	DefaultRegion string
}

var _ admission.CustomDefaulter = &BucketCustomDefaulter{}

func (d *BucketCustomDefaulter) Default(ctx context.Context, obj runtime.Object) error {
	bucket, ok := obj.(*cloudv1.Bucket)
	if !ok {
		return fmt.Errorf("expected a Bucket object but got %T", obj)
	}
	log := logf.FromContext(ctx)

	// region이 비어 있으면 기본값을 채운다.
	if bucket.Spec.Region == "" {
		bucket.Spec.Region = d.DefaultRegion
		log.Info("defaulting region", "region", d.DefaultRegion)
	}

	// versioning이 명시되지 않으면 안전하게 켠다.
	if bucket.Spec.Versioning == nil {
		enabled := true
		bucket.Spec.Versioning = &enabled
	}

	return nil
}

// +kubebuilder:webhook:path=/validate-cloud-example-com-v1-bucket,mutating=false,failurePolicy=fail,sideEffects=None,groups=cloud.example.com,resources=buckets,verbs=create;update,versions=v1,name=vbucket-v1.kb.io,admissionReviewVersions=v1

type BucketCustomValidator struct{}

var _ admission.CustomValidator = &BucketCustomValidator{}

func (v *BucketCustomValidator) ValidateCreate(ctx context.Context, obj runtime.Object) (admission.Warnings, error) {
	bucket, ok := obj.(*cloudv1.Bucket)
	if !ok {
		return nil, fmt.Errorf("expected a Bucket object but got %T", obj)
	}
	return v.validate(bucket)
}

func (v *BucketCustomValidator) ValidateUpdate(ctx context.Context, oldObj, newObj runtime.Object) (admission.Warnings, error) {
	oldBucket := oldObj.(*cloudv1.Bucket)
	newBucket := newObj.(*cloudv1.Bucket)

	// region은 불변 필드로 강제한다.
	if oldBucket.Spec.Region != newBucket.Spec.Region {
		return nil, fmt.Errorf("spec.region is immutable")
	}
	return v.validate(newBucket)
}

func (v *BucketCustomValidator) ValidateDelete(ctx context.Context, obj runtime.Object) (admission.Warnings, error) {
	return nil, nil
}

func (v *BucketCustomValidator) validate(bucket *cloudv1.Bucket) (admission.Warnings, error) {
	var warnings admission.Warnings

	if bucket.Spec.Region == "" {
		return nil, fmt.Errorf("spec.region must not be empty")
	}

	allowed := map[string]bool{"ap-northeast-2": true, "us-east-1": true}
	if !allowed[bucket.Spec.Region] {
		return nil, fmt.Errorf("spec.region %q is not allowed", bucket.Spec.Region)
	}

	if bucket.Spec.RetentionDays > 365 {
		warnings = append(warnings, "retentionDays가 365를 초과합니다. 비용에 유의하세요.")
	}

	return warnings, nil
}

func SetupBucketWebhookWithManager(mgr ctrl.Manager) error {
	return ctrl.NewWebhookManagedBy(mgr).
		For(&cloudv1.Bucket{}).
		WithDefaulter(&BucketCustomDefaulter{DefaultRegion: "ap-northeast-2"}).
		WithValidator(&BucketCustomValidator{}).
		Complete()
}

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigned-issuer
  namespace: system
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: serving-cert
  namespace: system
spec:
  dnsNames:
    - webhook-service.system.svc
    - webhook-service.system.svc.cluster.local
  issuerRef:
    kind: Issuer
    name: selfsigned-issuer
  secretName: webhook-server-cert

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: bucket-validating-webhook
  annotations:
    cert-manager.io/inject-ca-from: system/serving-cert
webhooks:
  - name: vbucket-v1.kb.io
    failurePolicy: Fail
    sideEffects: None
    admissionReviewVersions: ["v1"]
    clientConfig:
      service:
        name: webhook-service
        namespace: system
        path: /validate-cloud-example-com-v1-bucket
    rules:
      - apiGroups: ["cloud.example.com"]
        apiVersions: ["v1"]
        operations: ["CREATE", "UPDATE"]
        resources: ["buckets"]

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status

type Bucket struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   BucketSpec   `json:"spec,omitempty"`
	Status BucketStatus `json:"status,omitempty"`
}

import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

type BucketStatus struct {
	// ObservedGeneration은 컨트롤러가 마지막으로 처리한 spec 세대.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// ExternalName은 실제로 생성된 외부 버킷 이름.
	ExternalName string `json:"externalName,omitempty"`

	// +patchMergeKey=type
	// +patchStrategy=merge
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

import (
	"k8s.io/apimachinery/pkg/api/meta"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

func (r *BucketReconciler) markReady(ctx context.Context, bucket *cloudv1.Bucket, ready bool, reason, msg string) error {
	status := metav1.ConditionFalse
	if ready {
		status = metav1.ConditionTrue
	}

	meta.SetStatusCondition(&bucket.Status.Conditions, metav1.Condition{
		Type:               "Ready",
		Status:             status,
		Reason:             reason,
		Message:            msg,
		ObservedGeneration: bucket.Generation,
	})

	// observedGeneration도 함께 갱신해 "이 세대를 처리했음"을 기록한다.
	bucket.Status.ObservedGeneration = bucket.Generation

	// 반드시 Status().Update()를 써서 status 서브리소스만 갱신한다.
	return r.Status().Update(ctx, bucket)
}

func (r *BucketReconciler) reconcileExternalBucket(ctx context.Context, bucket *cloudv1.Bucket) error {
	// 진행 중 상태 기록
	if err := r.markCondition(ctx, bucket, "Progressing", metav1.ConditionTrue,
		"Creating", "외부 버킷 생성 중"); err != nil {
		return err
	}

	name, err := r.CloudAPI.EnsureBucket(ctx, bucket.Spec.Region)
	if err != nil {
		_ = r.markCondition(ctx, bucket, "Ready", metav1.ConditionFalse,
			"CreateFailed", err.Error())
		return err
	}

	bucket.Status.ExternalName = name
	return r.markCondition(ctx, bucket, "Ready", metav1.ConditionTrue,
		"Created", "외부 버킷 준비 완료")
}

// +kubebuilder:printcolumn:name="Region",type=string,JSONPath=`.spec.region`
// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
// +kubebuilder:printcolumn:name="External",type=string,JSONPath=`.status.externalName`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`

type Bucket struct {
	// ...
}

additionalPrinterColumns:
  - name: Region
    type: string
    jsonPath: .spec.region
  - name: Ready
    type: string
    jsonPath: .status.conditions[?(@.type=="Ready")].status
  - name: External
    type: string
    jsonPath: .status.externalName
  - name: Age
    type: date
    jsonPath: .metadata.creationTimestamp

NAME      REGION           READY   EXTERNAL          AGE
my-data   ap-northeast-2   True    my-data-9af31     12m

import (
	. "github.com/onsi/ginkgo/v2"
	. "github.com/onsi/gomega"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

var _ = Describe("Bucket finalizer", func() {
	It("삭제 시 외부 리소스를 정리한다", func() {
		bucket := &cloudv1.Bucket{
			ObjectMeta: metav1.ObjectMeta{Name: "test", Namespace: "default"},
			Spec:       cloudv1.BucketSpec{Region: "ap-northeast-2"},
		}
		Expect(k8sClient.Create(ctx, bucket)).To(Succeed())

		// finalizer가 추가될 때까지 대기
		Eventually(func() bool {
			_ = k8sClient.Get(ctx, client.ObjectKeyFromObject(bucket), bucket)
			return len(bucket.Finalizers) > 0
		}).Should(BeTrue())

		// 삭제 요청
		Expect(k8sClient.Delete(ctx, bucket)).To(Succeed())

		// 최종적으로 객체가 사라져야 한다
		Eventually(func() bool {
			err := k8sClient.Get(ctx, client.ObjectKeyFromObject(bucket), bucket)
			return client.IgnoreNotFound(err) == nil && err != nil
		}).Should(BeTrue())

		// 모의 클라우드 API에서 삭제가 호출됐는지 확인
		Expect(fakeCloud.DeletedBuckets()).To(ContainElement("test"))
	})
})

var _ = Describe("Bucket validator", func() {
	It("허용되지 않은 region을 거부한다", func() {
		v := &BucketCustomValidator{}
		bucket := &cloudv1.Bucket{Spec: cloudv1.BucketSpec{Region: "mars-1"}}
		_, err := v.ValidateCreate(ctx, bucket)
		Expect(err).To(HaveOccurred())
	})

	It("기본 region을 채운다", func() {
		d := &BucketCustomDefaulter{DefaultRegion: "ap-northeast-2"}
		bucket := &cloudv1.Bucket{}
		Expect(d.Default(ctx, bucket)).To(Succeed())
		Expect(bucket.Spec.Region).To(Equal("ap-northeast-2"))
	})
})