5장: 커스텀 컨트롤러와 오퍼레이터 개발

func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 1. 관찰: 리소스 가져오기
    var myApp v1alpha1.MyApp
    if err := r.Get(ctx, req.NamespacedName, &myApp); err != nil {
        return ctrl.Result{}, client.IgnoreNotFound(err)
    }
 
    // 2. 분석: 원하는 상태와 현재 상태 비교
    currentReplicas := getCurrentReplicas(ctx, myApp)
    desiredReplicas := myApp.Spec.Replicas
 
    // 3. 조치: 차이가 있으면 수정
    if currentReplicas != desiredReplicas {
        if err := scaleDeployment(ctx, myApp, desiredReplicas); err != nil {
            return ctrl.Result{}, err
        }
    }
 
    // 4. 보고: 상태 업데이트
    myApp.Status.ReadyReplicas = desiredReplicas
    myApp.Status.Phase = "Running"
    if err := r.Status().Update(ctx, &myApp); err != nil {
        return ctrl.Result{}, err
    }
 
    return ctrl.Result{RequeueAfter: 5 * time.Minute}, nil
}

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myapps.app.example.com
spec:
  group: app.example.com
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              required: [image, replicas]
              properties:
                image:
                  type: string
                  pattern: '^[a-z0-9.-]+/[a-z0-9.-]+:[a-z0-9.-]+$'
                replicas:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 1
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                  default: 8080
                env:
                  type: object
                  additionalProperties:
                    type: string
            status:
              type: object
              properties:
                phase:
                  type: string
                  enum: [Pending, Running, Failed, Terminating]
                readyReplicas:
                  type: integer
                conditions:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                      status:
                        type: string
                      lastTransitionTime:
                        type: string
                        format: date-time
                      reason:
                        type: string
                      message:
                        type: string
      subresources:
        status: {}
      additionalPrinterColumns:
        - name: Phase
          type: string
          jsonPath: .status.phase
        - name: Replicas
          type: integer
          jsonPath: .spec.replicas
        - name: Ready
          type: integer
          jsonPath: .status.readyReplicas
        - name: Age
          type: date
          jsonPath: .metadata.creationTimestamp
  scope: Namespaced
  names:
    plural: myapps
    singular: myapp
    kind: MyApp
    shortNames: [ma]

// 권장: Conditions 패턴
type MyAppStatus struct {
    Phase           string             `json:"phase,omitempty"`
    ReadyReplicas   int32              `json:"readyReplicas,omitempty"`
    Conditions      []metav1.Condition `json:"conditions,omitempty"`
    ObservedGeneration int64           `json:"observedGeneration,omitempty"`
}

# Kubebuilder 설치
curl -L -o kubebuilder https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)
chmod +x kubebuilder && mv kubebuilder /usr/local/bin/
 
# 프로젝트 초기화
mkdir myapp-operator && cd myapp-operator
kubebuilder init --domain example.com --repo github.com/org/myapp-operator
 
# API와 컨트롤러 생성
kubebuilder create api --group app --version v1alpha1 --kind MyApp \
  --resource --controller

package v1alpha1
 
import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
 
// MyAppSpec defines the desired state of MyApp
type MyAppSpec struct {
    // Image is the container image to deploy
    // +kubebuilder:validation:Required
    // +kubebuilder:validation:Pattern=`^[a-z0-9.-]+/[a-z0-9.-]+:[a-z0-9.-]+$`
    Image string `json:"image"`
 
    // Replicas is the desired number of pods
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=100
    // +kubebuilder:default=1
    Replicas int32 `json:"replicas"`
 
    // Port is the container port to expose
    // +kubebuilder:validation:Minimum=1
    // +kubebuilder:validation:Maximum=65535
    // +kubebuilder:default=8080
    Port int32 `json:"port,omitempty"`
}
 
// MyAppStatus defines the observed state of MyApp
type MyAppStatus struct {
    Phase              string             `json:"phase,omitempty"`
    ReadyReplicas      int32              `json:"readyReplicas,omitempty"`
    Conditions         []metav1.Condition `json:"conditions,omitempty"`
    ObservedGeneration int64              `json:"observedGeneration,omitempty"`
}
 
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Phase",type="string",JSONPath=".status.phase"
// +kubebuilder:printcolumn:name="Replicas",type="integer",JSONPath=".spec.replicas"
// +kubebuilder:printcolumn:name="Ready",type="integer",JSONPath=".status.readyReplicas"
// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 
// MyApp is the Schema for the myapps API
type MyApp struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
 
    Spec   MyAppSpec   `json:"spec,omitempty"`
    Status MyAppStatus `json:"status,omitempty"`
}

package controller
 
import (
    "context"
    "fmt"
 
    appsv1 "k8s.io/api/apps/v1"
    corev1 "k8s.io/api/core/v1"
    "k8s.io/apimachinery/pkg/api/errors"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/apimachinery/pkg/runtime"
    ctrl "sigs.k8s.io/controller-runtime"
    "sigs.k8s.io/controller-runtime/pkg/client"
    "sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
    "sigs.k8s.io/controller-runtime/pkg/log"
 
    appv1alpha1 "github.com/org/myapp-operator/api/v1alpha1"
)
 
type MyAppReconciler struct {
    client.Client
    Scheme *runtime.Scheme
}
 
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    logger := log.FromContext(ctx)
 
    // 1. MyApp 리소스 가져오기
    var myApp appv1alpha1.MyApp
    if err := r.Get(ctx, req.NamespacedName, &myApp); err != nil {
        if errors.IsNotFound(err) {
            return ctrl.Result{}, nil
        }
        return ctrl.Result{}, err
    }
 
    // 2. Finalizer 처리
    finalizerName := "app.example.com/finalizer"
    if myApp.ObjectMeta.DeletionTimestamp.IsZero() {
        if !controllerutil.ContainsFinalizer(&myApp, finalizerName) {
            controllerutil.AddFinalizer(&myApp, finalizerName)
            if err := r.Update(ctx, &myApp); err != nil {
                return ctrl.Result{}, err
            }
        }
    } else {
        if controllerutil.ContainsFinalizer(&myApp, finalizerName) {
            // 정리 로직 수행
            logger.Info("Cleaning up resources", "myapp", req.NamespacedName)
            controllerutil.RemoveFinalizer(&myApp, finalizerName)
            if err := r.Update(ctx, &myApp); err != nil {
                return ctrl.Result{}, err
            }
        }
        return ctrl.Result{}, nil
    }
 
    // 3. Deployment 조정
    deployment := r.buildDeployment(&myApp)
    if err := controllerutil.SetControllerReference(&myApp, deployment, r.Scheme); err != nil {
        return ctrl.Result{}, err
    }
 
    result, err := controllerutil.CreateOrUpdate(ctx, r.Client, deployment, func() error {
        deployment.Spec.Replicas = &myApp.Spec.Replicas
        deployment.Spec.Template.Spec.Containers[0].Image = myApp.Spec.Image
        return nil
    })
    if err != nil {
        return ctrl.Result{}, err
    }
    logger.Info("Deployment reconciled", "result", result)
 
    // 4. Status 업데이트
    myApp.Status.Phase = "Running"
    myApp.Status.ObservedGeneration = myApp.Generation
    if err := r.Status().Update(ctx, &myApp); err != nil {
        return ctrl.Result{}, err
    }
 
    return ctrl.Result{}, nil
}
 
func (r *MyAppReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&appv1alpha1.MyApp{}).
        Owns(&appsv1.Deployment{}).  // Deployment 변경도 감시
        Owns(&corev1.Service{}).     // Service 변경도 감시
        Complete(r)
}

// 좋은 예: 레벨 트리거 - 현재 상태 기반
func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    desired := getDesiredState(req)
    current := getCurrentState(ctx, req)
    if !reflect.DeepEqual(desired, current) {
        applyChanges(ctx, desired)
    }
    return ctrl.Result{}, nil
}
 
// 나쁜 예: 엣지 트리거 - 이벤트 기반
// "replicas가 3에서 5로 변경됨" 같은 이벤트에 의존하면 안 됨

func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 일시적 에러: Result와 error를 모두 반환하여 재시도
    if isTransientError(err) {
        return ctrl.Result{RequeueAfter: 30 * time.Second}, err
    }
 
    // 영구적 에러: 상태에 기록하고 재시도하지 않음
    if isPermanentError(err) {
        setCondition(&myApp, "Ready", metav1.ConditionFalse, "ConfigError", err.Error())
        r.Status().Update(ctx, &myApp)
        return ctrl.Result{}, nil  // error를 반환하지 않아 재시도 안 함
    }
 
    return ctrl.Result{}, nil
}

apiVersion: operators.coreos.com/v1alpha1
kind: ClusterServiceVersion
metadata:
  name: myapp-operator.v0.1.0
spec:
  displayName: MyApp Operator
  description: Manages MyApp custom resources
  version: 0.1.0
  maturity: alpha
  installModes:
    - type: OwnNamespace
      supported: true
    - type: SingleNamespace
      supported: true
    - type: MultiNamespace
      supported: false
    - type: AllNamespaces
      supported: true
  install:
    strategy: deployment
    spec:
      deployments:
        - name: myapp-operator
          spec:
            replicas: 1
            selector:
              matchLabels:
                app: myapp-operator
            template:
              spec:
                containers:
                  - name: manager
                    image: ghcr.io/org/myapp-operator:v0.1.0
  customresourcedefinitions:
    owned:
      - name: myapps.app.example.com
        version: v1alpha1
        kind: MyApp
        displayName: MyApp
        description: A custom application resource

var _ = Describe("MyApp Controller", func() {
    Context("When creating a MyApp", func() {
        It("Should create a Deployment", func() {
            ctx := context.Background()
 
            myApp := &appv1alpha1.MyApp{
                ObjectMeta: metav1.ObjectMeta{
                    Name:      "test-app",
                    Namespace: "default",
                },
                Spec: appv1alpha1.MyAppSpec{
                    Image:    "nginx:latest",
                    Replicas: 3,
                    Port:     8080,
                },
            }
            Expect(k8sClient.Create(ctx, myApp)).Should(Succeed())
 
            // Deployment가 생성될 때까지 대기
            deployment := &appsv1.Deployment{}
            Eventually(func() error {
                return k8sClient.Get(ctx, client.ObjectKeyFromObject(myApp), deployment)
            }, timeout, interval).Should(Succeed())
 
            Expect(*deployment.Spec.Replicas).Should(Equal(int32(3)))
        })
    })
})