[Go] Kubebuilder 사용해보기 - 1

GVM 설치

golang으로 개발하기 앞서 golang version controll를 할수있는 GVM을 설치한다.

 

macOS기준으로 아래 명령어를 실행하면 설치가 된다.

bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)

source /Users/jaeyunglee/.gvm/scripts/gvm

gvm version
# Go Version Manager v1.0.22 installed at /Users/jaeyunglee/.gvm

 

특정 go version을 설치하려면 아래와같이 실행한다.

# 제공되는 버전 목록
gvm listall

# 작성일 기준 최신 golang version은 1.24.4
gvm install go1.24.4 -B

# default로 사용할 go version명시
gvm use go1.24.4 --default

 

Kubebuilder 설치

https://book.kubebuilder.io/quick-start.html

Quick Start - The Kubebuilder Book

curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/

Kubebuilder 프로젝트 생성

시작하기 앞서 용어정리...

• 컨트롤러 (Controller) - 쿠버네티스의 상태 관리자: 사용자가 선언한(desired) 상태와 실제 상태(actual)를 비교하고 자동으로 조정(reconcile) 합니다.
  • e.g. Replicaset, StatefulSet, DaemonSet ...
• 오퍼레이터 (Operator) - 특정 애플리케이션을 쿠버네티스에서 운영/관리 자동화하기 위한 Custom Controller입니다.
  
  • e.g. CRD(Custom Resource Definition). 즉, Operator는 Controller를 포함한다
  • "모든 Operator는 CR을 관리하기 위해 쓰이는 Controller이다" (https://blog.marcnuri.com/kubernetes-operator-vs-controller)

mkdir -p ~/projects/example
cd ~/projects/example
kubebuilder init --domain my.domain --repo my.domain/example

 

위 명령어를 실행하고 파일 구조를 보면 다음과같이 되어있다. 중요한 파일들은 다음과같다.

• config/default - 표준 설정으로 컨트롤러를 실행할 kustomize base가 포함
• config/manager - 클러스터내에서 컨트롤러가 Pod으로 실행되는 필요한 것들이 포함
• config/rbac - serviceaccount 와 연계된 권한 파일들이 포함
• main.go - EntryPoint

.
├── Dockerfile
├── Makefile
├── PROJECT
├── README.md
├── cmd
│   └── main.go
├── config
│   ├── default
│   │   ├── cert_metrics_manager_patch.yaml
│   │   ├── kustomization.yaml
│   │   ├── manager_metrics_patch.yaml
│   │   └── metrics_service.yaml
│   ├── manager
│   │   ├── kustomization.yaml
│   │   └── manager.yaml
│   ├── network-policy
│   │   ├── allow-metrics-traffic.yaml
│   │   └── kustomization.yaml
│   ├── prometheus
│   │   ├── kustomization.yaml
│   │   ├── monitor.yaml
│   │   └── monitor_tls_patch.yaml
│   └── rbac
│       ├── kustomization.yaml
│       ├── leader_election_role.yaml
│       ├── leader_election_role_binding.yaml
│       ├── metrics_auth_role.yaml
│       ├── metrics_auth_role_binding.yaml
│       ├── metrics_reader_role.yaml
│       ├── role.yaml
│       ├── role_binding.yaml
│       └── service_account.yaml
├── go.mod
├── go.sum
├── hack
│   └── boilerplate.go.txt
└── test
    ├── e2e
    │   ├── e2e_suite_test.go
    │   └── e2e_test.go
    └── utils
        └── utils.go

Kubebuilder API 서버 생성

kubebuilder로 새로운 group, version, kind를 생성

• api/v1alpha/Jaeyung.types.go - Jaeyung이라는 CRD에 필드 설정
• controller/Jaeyung_controller.go - Jaeyung이라는 CR의 Controller설정

kubebuilder create api --group example --version v1alpha --kind Jaeyung
'
INFO Create Resource [y/n]                        
y
INFO Create Controller [y/n]                      
y 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO api/v1alpha/jaeyung_types.go                 
INFO api/v1alpha/groupversion_info.go             
INFO internal/controller/suite_test.go            
INFO internal/controller/jaeyung_controller.go    
INFO internal/controller/jaeyung_controller_test.go 
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
mkdir -p /Users/jaeyunglee/Desktop/jaeyung1001_github/projects/example/bin
Downloading sigs.k8s.io/controller-tools/cmd/controller-gen@v0.18.0
go: downloading sigs.k8s.io/controller-tools v0.18.0
go: downloading golang.org/x/tools v0.32.0
go: downloading github.com/spf13/cobra v1.9.1
go: downloading gopkg.in/yaml.v2 v2.4.0
go: downloading github.com/fatih/color v1.18.0
go: downloading k8s.io/code-generator v0.33.0
go: downloading k8s.io/gengo/v2 v2.0.0-20250207200755-1244d31929d7
go: downloading github.com/gobuffalo/flect v1.0.3
go: downloading github.com/spf13/pflag v1.0.6
go: downloading golang.org/x/net v0.39.0
go: downloading github.com/mattn/go-colorable v0.1.13
go: downloading github.com/mattn/go-isatty v0.0.20
go: downloading golang.org/x/sys v0.32.0
go: downloading golang.org/x/text v0.24.0
go: downloading golang.org/x/sync v0.13.0
go: downloading golang.org/x/mod v0.24.0
/Users/jaeyunglee/Desktop/jaeyung1001_github/projects/example/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests
'