Operator 베스트 프랙티스와 안티패턴

# 나쁜 예 — 내부 구현이 새어 나온 비대한 API
spec:
  statefulSetName: my-db-sts
  podAntiAffinityWeight: 100
  replicationProtocol: streaming
  walSegmentSize: 16MB
  checkpointTimeout: 300s
  # ... 수십 개의 저수준 옵션

# 좋은 예 — 의도만 선언
spec:
  replicas: 3
  version: "16.3"
  storage: { size: 50Gi }
  highAvailability: true

// 나쁜 예 — 호출마다 새 리소스를 만든다 (비멱등)
func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	job := newBackupJob()             // 매번 새 이름의 Job 생성
	r.Create(ctx, job)                // reconcile 100번 = Job 100개
	return ctrl.Result{}, nil
}

// 좋은 예 — 원하는 상태를 선언하고 없을 때만 만든다
func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	desired := desiredBackupJob(req)
	_, err := controllerutil.CreateOrUpdate(ctx, r.Client, desired, mutateFn)
	return ctrl.Result{}, err
}

관측의 세 채널
 1. status.conditions  — 현재 상태와 이유를 선언적으로
 2. Kubernetes events   — 사건의 타임라인(kubectl describe)
 3. Prometheus metrics  — reconcile 횟수/지연/에러, 도메인 지표

안전한 업그레이드의 조건
 - CRD: 새 필드는 optional + default, 기존 필드 의미 불변
 - 여러 API 버전 공존 (v1alpha1, v1beta1, v1) + conversion
 - 관리 워크로드: 헬스 게이트를 통과해야 다음 단계
 - 롤백 경로 존재 (백업, 이전 버전 이미지 보존)

// 나쁜 예 — reconcile마다 알림 폭탄
func (r *Reconciler) Reconcile(...) (ctrl.Result, error) {
	r.slackNotify("deployment started!")  // 재호출마다 슬랙 도배
	// ...
}

올바른 역할 분리
  spec   : 사용자가 쓴다 → Operator가 읽는다 (desired)
  status : Operator가 쓴다 → 사용자가 읽는다 (observed)

깨진 패턴 (피할 것)
  - 사용자가 status.replicas를 수정하게 함
  - Operator가 status.targetVersion을 입력으로 신뢰

// 나쁜 예 — 에러 시 즉시 무한 재시도
if err != nil {
	return ctrl.Result{Requeue: true}, nil  // CPU/API 폭주
}

// 좋은 예 — 에러를 반환하면 controller-runtime이 지수 백오프
if err != nil {
	return ctrl.Result{}, err  // 자동 백오프 재시도
}

// 의도적 지연도 명시적으로
return ctrl.Result{RequeueAfter: 30 * time.Second}, nil

// 나쁜 예 — 모든 것에 대한 모든 권한
// +kubebuilder:rbac:groups="*",resources="*",verbs="*"

// 좋은 예 — 필요한 리소스에 필요한 동사만
// +kubebuilder:rbac:groups=apps,resources=statefulsets,verbs=get;list;watch;create;update;patch
// +kubebuilder:rbac:groups=core,resources=services,verbs=get;list;watch;create;update;patch
// +kubebuilder:rbac:groups=batch,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete

스코프 선택 가이드
 - 단일 팀/네임스페이스 대상 → 네임스페이스 스코프 권장
 - 멀티테넌트 플랫폼 → 클러스터 스코프 + 강한 격리 필요
 - watch 대상을 특정 네임스페이스로 제한하면 메모리/부하도 절감

webhook 안전 설계
 - failurePolicy를 신중히: Fail은 안전하지만 가용성 위험,
   Ignore는 가용성 우선이지만 검증 우회 위험
 - webhook 대상 범위를 namespaceSelector/objectSelector로 좁힘
 - webhook 자신의 네임스페이스는 제외 (자기 부트스트랩 데드락 방지)
 - webhook을 여러 레플리카로 HA 구성

// 나쁜 예 — 매번 전체 파드를 API 서버에서 직접 List
pods := &corev1.PodList{}
r.APIReader.List(ctx, pods)  // 캐시 우회 + 셀렉터 없음

// 좋은 예 — 캐시에서, 셀렉터로 좁혀서
pods := &corev1.PodList{}
r.List(ctx, pods,
	client.InNamespace(req.Namespace),
	client.MatchingLabels{"app": req.Name})

// 사용자가 요청한 작업에 대한 권한을 위임 검증
sar := &authzv1.SubjectAccessReview{
	Spec: authzv1.SubjectAccessReviewSpec{
		User: requestingUser,
		ResourceAttributes: &authzv1.ResourceAttributes{
			Namespace: ns,
			Verb:      "create",
			Resource:  "databases",
			Group:     "db.example.com",
		},
	},
}
if err := r.Create(ctx, sar); err != nil {
	return err
}
if !sar.Status.Allowed {
	// 사용자에게 권한 없음 → Operator도 대신 수행 거부
	return fmt.Errorf("user %s is not allowed to create databases", requestingUser)
}

효율화 기법
 - 캐시 범위 제한: 특정 네임스페이스/라벨만 watch
 - predicate로 이벤트 필터: 관심 없는 변경은 reconcile 안 함
 - MaxConcurrentReconciles로 동시성 조절 (너무 높으면 API 폭주,
   너무 낮으면 처리 지연)
 - field selector/label selector로 List 범위 축소

// spec 변경(generation 증가)만 reconcile
builder.WithPredicates(predicate.GenerationChangedPredicate{})

테스트 피라미드
 1. 단위 테스트: reconcile 로직, 헬퍼 함수 (fake client 활용)
 2. envtest: 진짜 API 서버 + etcd로 reconcile 통합 검증
    (controller-runtime이 제공, kube-apiserver 바이너리 사용)
 3. e2e: kind 클러스터에 실제 배포해 시나리오 검증
 4. 카오스/장애 주입: 파드 강제 삭제, 네트워크 분단 시 동작

Operator의 운영 지표 예시
 - reconcile 에러율 (controller_runtime_reconcile_errors_total)
 - reconcile 지연 (워크큐 대기 시간)
 - 워크큐 깊이 (밀린 작업이 쌓이는가)
 - 도메인 SLI (예: 페일오버 성공률, 백업 신선도)

알림 규칙 예시
 - reconcile 에러율이 5분간 높음 → 경고
 - 워크큐가 계속 증가 → 컨트롤러 멈춤 의심
 - 백업이 24시간 이상 없음 → 호출

 1. CR이 실제로 존재하고 spec이 맞는가
    kubectl get database orders-db -o yaml
 2. status.conditions가 무엇을 말하는가
    → Reason/Message에 단서가 있는 경우가 대부분
 3. Operator 파드가 살아 있고 reconcile하고 있는가
    kubectl logs -n operator-system deploy/db-operator
 4. RBAC가 막고 있지 않은가 (Forbidden 로그)
    kubectl auth can-i create statefulsets --as=system:serviceaccount:operator-system:db-operator
 5. 워크큐가 밀려 있는가 (메트릭 확인)
    workqueue_depth, reconcile_errors_total
 6. 이벤트 타임라인
    kubectl describe database orders-db

func (r *Reconciler) reconcileDelete(ctx context.Context, db *dbv1alpha1.Database) (ctrl.Result, error) {
	// 외부 리소스 정리 — 이미 없어도 에러로 보지 않는다
	if err := r.cleanupExternalBackupBucket(ctx, db); err != nil {
		if !isNotFound(err) {
			return ctrl.Result{}, err // 진짜 에러만 재시도
		}
	}
	// 정리 끝 → finalizer 제거 → 쿠버네티스가 실제 삭제
	controllerutil.RemoveFinalizer(db, dbFinalizer)
	return ctrl.Result{}, r.Update(ctx, db)
}

Level 1: 기본 설치
  - CR로 설치/설정. helm으로 배포 가능.

Level 2: 원활한 업그레이드
  - 관리 대상의 버전 업그레이드를 안전하게 수행.

Level 3: 풀 라이프사이클
  - 백업/복구, 스케일, 장애 복구를 자동화.

Level 4: 깊은 인사이트
  - 메트릭/알림/로그로 관측 가능. 성능 분석 제공.

Level 5: 오토 파일럿
  - 오토스케일, 자동 튜닝, 이상 감지, 자가 치유.

[API 설계]
[ ] spec이 작고 의도(what) 중심인가
[ ] 새 필드가 optional + default로 하위 호환을 지키는가
[ ] 여러 API 버전 + conversion 전략이 있는가

[reconcile]
[ ] 멱등한가 (두 번 호출 시 두 번째가 무변화)
[ ] 외부 부수효과가 전이 시점에만 한 번 발생하는가
[ ] 에러는 반환해 백오프에 맡기는가 (무한 requeue 없음)
[ ] finalizer로 정리 로직을 보장하는가

[관측]
[ ] status.conditions가 사람이 읽을 수 있는가
[ ] 중요한 사건을 event로 남기는가
[ ] 도메인 메트릭을 노출하는가

[보안]
[ ] RBAC가 최소 권한인가 (와일드카드 없음)
[ ] 시크릿을 status/event/log에 노출하지 않는가
[ ] 가능한 한 네임스페이스 스코프인가

[효율]
[ ] 캐시/watch 범위를 제한했는가
[ ] predicate로 불필요한 reconcile을 거르는가
[ ] MaxConcurrentReconciles를 적절히 설정했는가

[테스트/운영]
[ ] envtest로 통합 검증하는가
[ ] 멱등성/삭제 테스트가 있는가
[ ] 알림 규칙과 런북이 있는가