Kubebuilder로 첫 Operator 만들기 — 프로젝트 생성부터 배포까지

go version
kubebuilder version
kubectl version --client

mkdir guestbook-operator && cd guestbook-operator
kubebuilder init --domain example.com --repo example.com/guestbook-operator

kubebuilder create api --group webapp --version v1 --kind Guestbook

guestbook-operator/
  api/v1/                 # API 타입 정의 (Spec/Status, 마커)
  internal/controller/    # reconcile 로직
  config/
    crd/                  # 생성된 CRD 매니페스트
    rbac/                 # 생성된 RBAC (role.yaml 등)
    manager/              # 컨트롤러 매니저 Deployment
    samples/              # 예시 CR
  cmd/main.go             # 매니저 진입점 (스킴 등록, 매니저 기동)
  Makefile                # build/run/deploy 등 표준 타깃
  Dockerfile              # 컨트롤러 이미지 빌드

package v1

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

// GuestbookSpec은 사용자가 원하는 상태를 정의합니다.
type GuestbookSpec struct {
	// 원하는 replica 수입니다.
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=10
	Replicas int32 `json:"replicas"`

	// 사용할 컨테이너 이미지입니다.
	// +kubebuilder:validation:MinLength=1
	Image string `json:"image"`

	// 서비스가 노출할 포트입니다.
	// +kubebuilder:default=80
	Port int32 `json:"port,omitempty"`
}

// GuestbookStatus는 관찰된 상태를 담습니다.
type GuestbookStatus struct {
	// 준비된 replica 수입니다.
	ReadyReplicas int32 `json:"readyReplicas"`

	// 상태 조건 목록입니다.
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Replicas",type=integer,JSONPath=`.spec.replicas`
// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`

// Guestbook은 우리의 커스텀 리소스입니다.
type Guestbook struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   GuestbookSpec   `json:"spec,omitempty"`
	Status GuestbookStatus `json:"status,omitempty"`
}

// +kubebuilder:object:root=true

// GuestbookList는 Guestbook의 목록입니다.
type GuestbookList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Guestbook `json:"items"`
}

func init() {
	SchemeBuilder.Register(&Guestbook{}, &GuestbookList{})
}

package controller

import (
	"context"

	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/intstr"
	"k8s.io/apimachinery/pkg/runtime"
	ctrl "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
	"sigs.k8s.io/controller-runtime/pkg/log"

	webappv1 "example.com/guestbook-operator/api/v1"
)

type GuestbookReconciler struct {
	client.Client
	Scheme *runtime.Scheme
}

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

	// 1. 대상 Guestbook을 읽는다.
	var gb webappv1.Guestbook
	if err := r.Get(ctx, req.NamespacedName, &gb); err != nil {
		if errors.IsNotFound(err) {
			// 이미 삭제됨. owner reference 덕에 하위 리소스는 GC가 정리한다.
			return ctrl.Result{}, nil
		}
		return ctrl.Result{}, err
	}

	// 2. 원하는 Deployment를 만들고 멱등하게 조정한다.
	desiredDeploy := r.buildDeployment(&gb)
	if err := ctrl.SetControllerReference(&gb, desiredDeploy, r.Scheme); err != nil {
		return ctrl.Result{}, err
	}

	var existingDeploy appsv1.Deployment
	err := r.Get(ctx, client.ObjectKeyFromObject(desiredDeploy), &existingDeploy)
	if errors.IsNotFound(err) {
		logger.Info("Deployment 생성", "name", desiredDeploy.Name)
		if err := r.Create(ctx, desiredDeploy); err != nil {
			return ctrl.Result{}, err
		}
	} else if err != nil {
		return ctrl.Result{}, err
	} else {
		// 이미 존재하면 원하는 모습으로 맞춘다.
		existingDeploy.Spec = desiredDeploy.Spec
		if err := r.Update(ctx, &existingDeploy); err != nil {
			return ctrl.Result{}, err
		}
	}

	// 3. 원하는 Service를 조정한다.
	desiredSvc := r.buildService(&gb)
	if err := ctrl.SetControllerReference(&gb, desiredSvc, r.Scheme); err != nil {
		return ctrl.Result{}, err
	}
	var existingSvc corev1.Service
	err = r.Get(ctx, client.ObjectKeyFromObject(desiredSvc), &existingSvc)
	if errors.IsNotFound(err) {
		if err := r.Create(ctx, desiredSvc); err != nil {
			return ctrl.Result{}, err
		}
	} else if err != nil {
		return ctrl.Result{}, err
	}

	// 4. status를 갱신한다.
	gb.Status.ReadyReplicas = existingDeploy.Status.ReadyReplicas
	if err := r.Status().Update(ctx, &gb); err != nil {
		return ctrl.Result{}, err
	}

	return ctrl.Result{}, nil
}

func (r *GuestbookReconciler) buildDeployment(gb *webappv1.Guestbook) *appsv1.Deployment {
	labels := map[string]string{"app": gb.Name}
	replicas := gb.Spec.Replicas
	return &appsv1.Deployment{
		ObjectMeta: metav1.ObjectMeta{
			Name:      gb.Name,
			Namespace: gb.Namespace,
		},
		Spec: appsv1.DeploymentSpec{
			Replicas: &replicas,
			Selector: &metav1.LabelSelector{MatchLabels: labels},
			Template: corev1.PodTemplateSpec{
				ObjectMeta: metav1.ObjectMeta{Labels: labels},
				Spec: corev1.PodSpec{
					Containers: []corev1.Container{{
						Name:  "app",
						Image: gb.Spec.Image,
						Ports: []corev1.ContainerPort{{ContainerPort: gb.Spec.Port}},
					}},
				},
			},
		},
	}
}

func (r *GuestbookReconciler) buildService(gb *webappv1.Guestbook) *corev1.Service {
	labels := map[string]string{"app": gb.Name}
	return &corev1.Service{
		ObjectMeta: metav1.ObjectMeta{
			Name:      gb.Name,
			Namespace: gb.Namespace,
		},
		Spec: corev1.ServiceSpec{
			Selector: labels,
			Ports: []corev1.ServicePort{{
				Port:       gb.Spec.Port,
				TargetPort: intstr.FromInt32(gb.Spec.Port),
			}},
		},
	}
}

func (r *GuestbookReconciler) SetupWithManager(mgr ctrl.Manager) error {
	return ctrl.NewControllerManagedBy(mgr).
		For(&webappv1.Guestbook{}).
		Owns(&appsv1.Deployment{}).
		Owns(&corev1.Service{}).
		Complete(r)
}

// +kubebuilder:rbac:groups=webapp.example.com,resources=guestbooks,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=webapp.example.com,resources=guestbooks/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups="",resources=services,verbs=get;list;watch;create;update;patch;delete

make manifests
make generate

make install
kubectl get crd guestbooks.webapp.example.com

make run

kubectl apply -f config/samples/webapp_v1_guestbook.yaml
kubectl get guestbook
kubectl get deployment,service

make docker-build docker-push IMG=registry.example.com/guestbook-operator:v0.1.0
make deploy IMG=registry.example.com/guestbook-operator:v0.1.0

kubectl -n guestbook-operator-system get pods
kubectl -n guestbook-operator-system logs deploy/guestbook-operator-controller-manager

make test