Operator 프로덕션 업그레이드와 마이그레이션 — 무중단으로 진화시키기

1. Operator 자체 업그레이드      - 컨트롤러 Deployment 롤링, 리더 선출, graceful shutdown
2. CRD 스키마 진화               - 다중 버전 CRD, conversion webhook, storage version
3. 관리 워크로드 안전 롤아웃     - 단계적/파티션 롤아웃, observedGeneration, status conditions
4. 롤백 전략                     - 다운그레이드 함정, 비가역 변환, 필드 손실
5. 다중 버전 운영                - 여러 API 버전 동시 서빙, deprecation 정책
6. 카나리 Operator              - 일부 네임스페이스에만 신규 버전 배포
7. 버전 호환성                  - K8s 1.36 / Go 1.26, controller-runtime v0.24.x, version skew
8. 대규모 CR 마이그레이션        - 일회성 배치 잡, storage version migrator, rate limit
9. 장애 대응                    - 롤아웃 중간에 문제가 났을 때
10. 체크리스트                  - 배포 전/후 점검 항목

package main

import (
	"crypto/tls"
	"flag"
	"os"

	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/healthz"
	"sigs.k8s.io/controller-runtime/pkg/log/zap"
	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
	"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
)

func main() {
	var enableLeaderElection bool
	var probeAddr string
	flag.BoolVar(&enableLeaderElection, "leader-elect", true,
		"Enable leader election for controller manager.")
	flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081",
		"The address the probe endpoint binds to.")
	flag.Parse()

	ctrl.SetLogger(zap.New(zap.UseDevMode(false)))

	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
		Scheme: scheme,
		Metrics: metricsserver.Options{
			BindAddress:   ":8443",
			SecureServing: true,
			// 2026: kube-rbac-proxy 제거됨. 인증/인가를 매니저에 내장.
			FilterProvider: filters.WithAuthenticationAndAuthorization,
			TLSOpts: []func(*tls.Config){
				func(c *tls.Config) { c.MinVersion = tls.VersionTLS13 },
			},
		},
		HealthProbeBindAddress: probeAddr,
		LeaderElection:         enableLeaderElection,
		LeaderElectionID:       "db-operator.example.com",
		// 리더가 죽었을 때 standby가 빠르게 인계받도록 lease를 조정.
		LeaseDuration: durationPtr(15 * time.Second),
		RenewDeadline: durationPtr(10 * time.Second),
		RetryPeriod:   durationPtr(2 * time.Second),
		// 종료 시 리더십을 즉시 반납해 다운타임을 줄인다.
		LeaderElectionReleaseOnCancel: true,
	})
	if err != nil {
		os.Exit(1)
	}

	_ = mgr.AddHealthzCheck("healthz", healthz.Ping)
	_ = mgr.AddReadyzCheck("readyz", healthz.Ping)

	if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
		os.Exit(1)
	}
}

apiVersion: apps/v1
kind: Deployment
metadata:
  name: db-operator-controller-manager
  namespace: db-operator-system
spec:
  replicas: 2
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: manager
          image: registry.example.com/db-operator:v1.4.0
          args:
            - --leader-elect=true
            - --health-probe-bind-address=:8081
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8081
            initialDelaySeconds: 15
            periodSeconds: 20
          readinessProbe:
            httpGet:
              path: /readyz
              port: 8081
            initialDelaySeconds: 5
            periodSeconds: 10
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 512Mi
          lifecycle:
            preStop:
              exec:
                command: ["/bin/sh", "-c", "sleep 5"]

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

	var db examplev1.Database
	if err := r.Get(ctx, req.NamespacedName, &db); err != nil {
		return ctrl.Result{}, client.IgnoreNotFound(err)
	}

	// 외부 호출에 ctx를 전달하면 종료 시 즉시 취소되어 graceful shutdown이 보장된다.
	if err := r.provisioner.EnsureReady(ctx, &db); err != nil {
		if ctx.Err() != nil {
			// 종료 중이면 다음 리더가 다시 처리하도록 조용히 반환.
			return ctrl.Result{}, nil
		}
		log.Error(err, "failed to ensure database ready")
		return ctrl.Result{RequeueAfter: 30 * time.Second}, nil
	}

	return ctrl.Result{}, nil
}

              ┌──────────────────────────────────────────────┐
              │                 API Server                    │
  v1alpha1 ──▶│  served:true   ─┐                             │
  v1beta1  ──▶│  served:true    ├─▶ conversion webhook ─▶ etcd│ (storage: v1)
  v1       ──▶│  served:true,   │                             │
              │  storage:true ──┘                             │
              └──────────────────────────────────────────────┘

   v1alpha1 (spoke)              v1 (hub, storage)              v1beta1 (spoke)
        │                            ▲   │                            │
        │  ConvertTo(hub) ───────────┘   └──── ConvertFrom(hub) ◀─────┤
        └────────── ConvertFrom(hub) ◀──── ConvertTo(hub) ────────────┘

package v1

// Hub은 이 타입이 변환 hub임을 표시한다. 별도 구현은 필요 없다.
func (*Database) Hub() {}

package v1beta1

import (
	"sigs.k8s.io/controller-runtime/pkg/conversion"
	dbv1 "github.com/example/db-operator/api/v1"
)

// ConvertTo는 이 spoke(v1beta1)를 hub(v1)로 변환한다.
func (src *Database) ConvertTo(dstRaw conversion.Hub) error {
	dst := dstRaw.(*dbv1.Database)

	dst.ObjectMeta = src.ObjectMeta

	// 단순 필드는 그대로 복사
	dst.Spec.Engine = src.Spec.Engine
	dst.Spec.Replicas = src.Spec.Replicas

	// v1beta1의 StorageGB(int) → v1의 Storage(구조체)로 재편
	dst.Spec.Storage = dbv1.StorageSpec{
		SizeGB:    src.Spec.StorageGB,
		ClassName: "standard", // 신규 필드의 기본값
	}

	// status도 변환
	dst.Status.Phase = src.Status.Phase
	dst.Status.ObservedGeneration = src.Status.ObservedGeneration
	return nil
}

// ConvertFrom은 hub(v1)를 이 spoke(v1beta1)로 변환한다.
func (dst *Database) ConvertFrom(srcRaw conversion.Hub) error {
	src := srcRaw.(*dbv1.Database)

	dst.ObjectMeta = src.ObjectMeta

	dst.Spec.Engine = src.Spec.Engine
	dst.Spec.Replicas = src.Spec.Replicas

	// v1의 Storage 구조체 → v1beta1의 StorageGB(int)로 축소
	// 주의: ClassName 정보는 v1beta1에 표현할 수 없어 손실된다.
	dst.Spec.StorageGB = src.Spec.Storage.SizeGB

	dst.Status.Phase = src.Status.Phase
	dst.Status.ObservedGeneration = src.Status.ObservedGeneration
	return nil
}

func (r *Database) SetupWebhookWithManager(mgr ctrl.Manager) error {
	return ctrl.NewWebhookManagedBy(mgr).
		For(r).
		Complete()
}

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  group: example.com
  names:
    kind: Database
    plural: databases
  scope: Namespaced
  conversion:
    strategy: Webhook
    webhook:
      conversionReviewVersions: ["v1"]
      clientConfig:
        service:
          namespace: db-operator-system
          name: db-operator-webhook-service
          path: /convert
  versions:
    - name: v1alpha1
      served: true
      storage: false
      deprecated: true
      deprecationWarning: "example.com/v1alpha1 Database is deprecated; use v1"
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
    - name: v1beta1
      served: true
      storage: false
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object

단계 1: v1을 served:true, storage:false로 추가 (아직 저장은 v1beta1)
        conversion webhook 배포 + 변환 함수 검증
단계 2: 컨트롤러 신규 버전 배포 (v1을 인식)
단계 3: storage version을 v1로 전환 (v1beta1 storage:false, v1 storage:true)
단계 4: storage version migrator로 기존 CR을 v1로 재저장
단계 5: v1alpha1/v1beta1을 deprecated 표기 후, 충분한 유예 기간 뒤 served:false
단계 6: 더 이상 참조가 없으면 구버전 제거

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

	// 이미 최신 generation을 처리했다면 추가 작업 없음
	if db.Status.ObservedGeneration == db.Generation &&
		meta.IsStatusConditionTrue(db.Status.Conditions, "Ready") {
		return ctrl.Result{}, nil
	}

	// ... 실제 reconcile 로직 ...

	db.Status.ObservedGeneration = db.Generation
	meta.SetStatusCondition(&db.Status.Conditions, metav1.Condition{
		Type:               "Ready",
		Status:             metav1.ConditionTrue,
		ObservedGeneration: db.Generation,
		Reason:             "Reconciled",
		Message:            "database is ready",
	})
	if err := r.Status().Update(ctx, &db); err != nil {
		return ctrl.Result{}, err
	}
	return ctrl.Result{}, nil
}

// RolloutPolicy는 CR spec에 정의되어 단계적 전환을 제어한다.
type RolloutPolicy struct {
	// MaxUnavailable: 동시에 교체 가능한 인스턴스 비율(%)
	MaxUnavailable int `json:"maxUnavailable"`
	// Partition: 이 인덱스 미만은 새 버전으로 바꾸지 않는다(점진 확대)
	Partition int `json:"partition"`
	// Paused: true면 롤아웃을 멈추고 현 상태를 유지한다
	Paused bool `json:"paused"`
}

func (r *DatabaseReconciler) rolloutManagedPods(
	ctx context.Context, db *examplev1.Database, desiredImage string,
) (bool, error) {
	pods, err := r.listManagedPods(ctx, db)
	if err != nil {
		return false, err
	}

	// 일시정지 상태면 아무 것도 바꾸지 않는다
	if db.Spec.Rollout.Paused {
		return false, nil
	}

	// 인덱스 내림차순으로, partition 이상인 것만 대상으로 삼는다
	updating := 0
	maxConcurrent := percentToCount(db.Spec.Rollout.MaxUnavailable, len(pods))

	for i := len(pods) - 1; i >= db.Spec.Rollout.Partition; i-- {
		p := pods[i]
		if podImage(p) == desiredImage {
			continue // 이미 새 버전
		}
		if !isHealthy(p) {
			// 직전에 바꾼 Pod가 아직 건강하지 않으면 더 진행하지 않는다
			return true, nil
		}
		if updating >= maxConcurrent {
			return true, nil // 동시 교체 한도 도달, 다음 reconcile에서 계속
		}
		if err := r.recreatePodWithImage(ctx, p, desiredImage); err != nil {
			return false, err
		}
		updating++
	}

	// 모든 대상이 새 버전이면 완료
	return updating > 0, nil
}

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

	// 운영자가 긴급 정지를 걸면 reconcile을 건너뛴다
	if db.Annotations["example.com/reconcile-paused"] == "true" {
		ctrl.LoggerFrom(ctx).Info("reconcile paused by annotation")
		return ctrl.Result{}, nil
	}
	// ...
	return ctrl.Result{}, nil
}

[올바른 롤백 순서 — 스토리지 버전을 올린 경우]

  1. conversion webhook은 그대로 유지 (절대 먼저 내리지 않는다)
  2. 컨트롤러만 이전 버전으로 롤백
  3. 구버전이 인식하는 버전으로 storage version을 되돌릴지 신중히 판단
  4. 이미 v1로 저장된 CR이 있다면 migrator로 다시 구버전으로 재저장 필요

func TestConversionRoundTrip(t *testing.T) {
	original := &v1beta1.Database{
		Spec: v1beta1.DatabaseSpec{
			Engine:    "postgres",
			Replicas:  3,
			StorageGB: 100,
		},
	}

	// v1beta1 → v1 → v1beta1
	hub := &v1.Database{}
	if err := original.ConvertTo(hub); err != nil {
		t.Fatal(err)
	}
	roundTripped := &v1beta1.Database{}
	if err := roundTripped.ConvertFrom(hub); err != nil {
		t.Fatal(err)
	}

	// v1beta1이 표현 가능한 필드는 무손실이어야 한다
	if roundTripped.Spec.StorageGB != original.Spec.StorageGB {
		t.Errorf("StorageGB lost: got %d want %d",
			roundTripped.Spec.StorageGB, original.Spec.StorageGB)
	}
}

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
	Scheme: scheme,
	Cache: cache.Options{
		// 이 컨트롤러는 canary 네임스페이스만 감시한다
		DefaultNamespaces: map[string]cache.Config{
			"team-canary": {},
		},
	},
	// 카나리는 별도의 리더 선출 ID를 써 기존 컨트롤러와 충돌하지 않게 한다
	LeaderElection:   true,
	LeaderElectionID: "db-operator-canary.example.com",
})

[호환성 점검 순서]

  1. go.mod에서 controller-runtime, client-go, apimachinery 버전 정렬
  2. 대상 클러스터의 K8s 버전이 지원 범위 안인지 확인
  3. 제거 예정(deprecated) API를 사용 중인지 점검 (예: 구 admissionregistration 버전)
  4. controller-tools를 올린 뒤 CRD를 재생성해 스키마 diff 확인
  5. envtest로 통합 테스트를 돌려 회귀 확인

package main

import (
	"context"
	"time"

	"golang.org/x/time/rate"
	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

// migrateStorageVersion은 모든 Database CR을 한 번씩 no-op 업데이트해
// 현재 storage version으로 재저장한다.
func migrateStorageVersion(ctx context.Context, c client.Client) error {
	// 초당 10건으로 제한 (API 서버/webhook 보호)
	limiter := rate.NewLimiter(rate.Limit(10), 1)

	var continueToken string
	for {
		var list examplev1.DatabaseList
		opts := []client.ListOption{client.Limit(100)}
		if continueToken != "" {
			opts = append(opts, client.Continue(continueToken))
		}
		if err := c.List(ctx, &list, opts...); err != nil {
			return err
		}

		for i := range list.Items {
			if err := limiter.Wait(ctx); err != nil {
				return err
			}
			db := &list.Items[i]

			// no-op annotation 토글로 update를 유발해 재저장
			if db.Annotations == nil {
				db.Annotations = map[string]string{}
			}
			db.Annotations["example.com/storage-migrated-at"] =
				time.Now().UTC().Format(time.RFC3339)

			if err := c.Update(ctx, db); err != nil {
				// 충돌은 다음 라운드에서 재시도되도록 로그만 남긴다
				continue
			}
		}

		if list.Continue == "" {
			break
		}
		continueToken = list.Continue
	}
	return nil
}

var _ = metav1.ObjectMeta{} // import 사용 표시

1. rate limit 필수            - API 서버/webhook 과부하 방지 (초당 N건)
2. 페이지네이션              - List에 Limit + Continue 사용, 메모리 폭발 방지
3. 멱등성                    - 중간에 죽어도 다시 돌리면 되도록 설계
4. 충돌 허용                 - 동시 업데이트 충돌은 다음 라운드에서 재시도
5. 진행 가시성              - 처리 건수/실패 건수를 메트릭으로 노출
6. webhook 헬스 확인        - 변환이 실패하면 즉시 중단

[장애 대응 플레이북]

증상 감지
   │
   ▼
1) 롤아웃 즉시 정지
   - CR에 reconcile-paused=true annotation (확산 차단)
   - 또는 Rollout.Paused=true로 단계적 전환 중단
   │
   ▼
2) 영향 범위 파악
   - status conditions / observedGeneration으로 어디까지 진행됐는지 확인
   - 새 버전으로 바뀐 워크로드 수 집계
   │
   ▼
3) 가역성 판단
   - 스토리지 버전을 아직 안 올렸나? → 컨트롤러 이미지 롤백으로 충분
   - 이미 올렸나? → conversion webhook 유지하며 신중히 롤백
   │
   ▼
4) 컨트롤러 롤백
   - Deployment 이미지를 직전 정상 태그로
   - 단, CRD/webhook은 함부로 같이 내리지 않는다
   │
   ▼
5) 데이터 정합성 확인
   - 손실 가능 필드(ClassName 등)가 영향받았는지 점검
   - 필요 시 백업에서 복구
   │
   ▼
6) 사후 분석
   - round-trip 테스트 누락, webhook 헬스 미점검 등 원인 기록

[업그레이드 전]
□ go.mod의 controller-runtime/client-go/apimachinery 버전 정렬 확인
□ 대상 K8s 버전이 지원 범위(1.36) 안인지 확인
□ CRD 재생성 후 기존과 schema diff 확인
□ conversion 함수 round-trip 테스트 통과
□ envtest 통합 테스트 통과
□ 리더 선출 + LeaderElectionReleaseOnCancel 설정 확인
□ Deployment maxUnavailable=0 / maxSurge=1 확인
□ 롤백 절차 문서화 + 백업 확인
□ 신규 스키마가 구버전 컨트롤러와 호환되는지(카나리 가능 여부) 판단

[업그레이드 중]
□ 새 버전 served:true, storage:false로 먼저 추가
□ conversion webhook 헬스 확인
□ 컨트롤러 롤링 후 리더 인계 정상 동작 확인
□ 관리 워크로드는 partition으로 점진 확대
□ status conditions / observedGeneration으로 진행 추적

[업그레이드 후]
□ storage version 전환은 컨트롤러 안정화 이후 별도로
□ storage version migrator로 기존 CR 재저장 (rate limit)
□ 구버전 deprecated 표기 후 유예 기간 부여
□ 메트릭(reconcile 에러율, webhook 지연) 정상 범위 확인
□ 더 이상 참조 없는 구버전을 served:false → 제거