Kubebuilderは、CustomResourceDefinition(CRD)とコントローラーを組み合わせてKubernetesを独自のAPIで拡張する、Go製のSDKです。Operatorを作るときの雛形・マニフェスト・テスト環境をまとめて生成します。この記事では、まずKubernetesのコントローラーとオペレーター(Operator)の違いを定義から整理し、そのうえで2026年9月10日公開のKubebuilder v4.16.0を使い、プロジェクト作成からReconcile、Status Conditions、Finalizer、Admission Webhook、envtestでのテストまでを実行した出力で追います。
まとめ:コントローラーとオペレーターの違いとKubebuilderの要点
- コントローラー:クラスタの状態を監視し、望ましい状態へ近づける制御ループ。Deploymentのレプリカ数を保つ処理もコントローラーです。
- オペレーター:カスタムリソースを使い、特定アプリケーションの運用手順をコード化したコントローラー。オペレーターはすべてコントローラーですが、逆は成り立ちません。
- Kubebuilderの役割:オペレーターを作る開発用SDK。kubectlはできたCRDを登録し、カスタムリソースを操作するクライアントで、両者は併用します。
- 開発の流れ:
kubebuilder init→create api→型とReconcileの実装→create webhook(必要なら)→make test→make install・make run→make deploy。 - 2026年11月時点の版:Kubebuilder v4.16.0。生成物はcontroller-runtime v0.25.0とcontroller-gen v0.22.0を使います(公開中の最新はv0.25.2とv0.23.0)。
- 古い解説に注意:controller-runtime v0.23.0(2026年1月)でWebhookの関数の型が変わりました。Kubebuilder v4.1系向けの解説のWebhookコードは、現在の雛形では書き換えが必要です。
Kubernetesのコントローラーとオペレーターの違い
コントローラーは状態を合わせ続ける制御ループ
Kubernetesの公式ドキュメントは、コントローラーを「クラスタの状態を監視し、必要な箇所で変更を行う、または変更を要求する制御ループ」と定義しています。Deploymentにreplicas: 3と書くとPodが3つに保たれるのは、kube-controller-manager内のReplicaSetコントローラーが「宣言された数」と「実際に動いている数」の差を検知し、不足分のPodを作るためです。
コントローラーの処理は、いまの状態を読み、望ましい状態との差を埋めるところで終わります。何回呼ばれても結果が変わらない(冪等である)ことが前提で、前回どのイベントで呼ばれたかには依存しません。
オペレーターはカスタムリソースで運用知識をコード化したコントローラー
オペレーターについて、公式ドキュメントは「カスタムリソースを使ってアプリケーションとその構成要素を管理する、Kubernetesのソフトウェア拡張」と定義しています。データベースのバックアップ、バージョンアップの順序、障害時のフェイルオーバーのように、人が手順書で行っていた運用をコントローラーに書き込み、kind: PostgresClusterのような独自リソースで宣言できるようにしたものです。
| 観点 | コントローラー | オペレーター |
|---|---|---|
| 範囲 | 制御ループ全般 | コントローラーの一種 |
| 監視対象 | 組み込み・カスタムどちらも | カスタムリソースが中心 |
| 持つ知識 | 汎用の調整処理 | 特定アプリの運用手順 |
| 例 | ReplicaSet・Job・Endpoints | Rook・CloudNativePG |
| 作る道具 | client-go・controller-runtime | Kubebuilder・Operator SDK |
区別の基準は、カスタムリソースを通じてアプリケーション固有の運用を実装しているかどうかです。組み込みのServiceだけを監視してラベルを付け直すコントローラーは、Operatorとは呼びません。Ceph向けのRookは典型的なオペレーターで、Rook CephがKubernetes上でCephを動かすオペレータの仕組みで構成を追えます。
オペレーターの成熟度を表す5段階の能力レベル
「どこまで自動化していればオペレーターと言えるか」を測る物差しとして、Operator FrameworkはOperator Capability Levelsを公開しています。
| レベル | 名称 | 自動化する範囲 |
|---|---|---|
| 1 | Basic Install | 導入と設定 |
| 2 | Seamless Upgrades | パッチ・マイナー版の更新 |
| 3 | Full Lifecycle | バックアップ・障害復旧 |
| 4 | Deep Insights | メトリクス・アラート・ログ |
| 5 | Auto Pilot | スケーリング・自動調整・異常検知 |
この記事のサンプルは、レベル1の基礎となる設定管理と状態通知を学ぶ簡略例です。アプリケーション本体の導入や健全性確認までは実装していません。自作する前に、目的のミドルウェアにレベル3以上の既製オペレーターがあるかを確かめてください。バックアップと復旧まで自前で書くと、コード量もテストの手間も一段増えます。
CRDだけで足りる場合とコントローラーが必要な場合
CRDを登録しただけでは、kube-apiserverがカスタムリソースを保存して返すだけで、何も動きません。設定値の置き場としてCRDを使い、別のツールが読むだけならコントローラーは不要です。カスタムリソースの作成をきっかけにPodやConfigMap、クラウド上のリソースを作る、あるいは結果をstatusに書き戻す必要が出たときに、コントローラーを書く意味が生まれます。CRDとAPIグループの関係はKubernetes APIのURL・エンドポイント構造とcurl実例で扱っています。
Kubebuilderの構成要素とkubectlとの役割分担
KubebuilderはSIG API Machineryが管理するkubernetes-sigs配下のプロジェクトで、次の部品を束ねて雛形を作ります。
| 部品 | 役割 | v4.16.0の生成物 | 最新(2026-11-05) |
|---|---|---|---|
| controller-runtime | Manager・Client・Reconcilerの基盤 | v0.25.0 | v0.25.2 |
| controller-gen | マーカーからCRD・RBACを生成 | v0.22.0 | v0.23.0 |
| setup-envtest | テスト用apiserver・etcdの取得 | Kubernetes 1.37.0 | – |
| kustomize | config配下のマニフェスト組み立て | v5.8.1 | – |
生成物の版は、go.modとMakefileのCONTROLLER_TOOLS_VERSIONで確認できます。最新版へ上げるかは、Kubebuilderの次の版が雛形を更新するのを待つのが無難です。controller-runtimeはマイナー版ごとに破壊的変更を入れることがあり、後述のWebhookの型変更もその一例です。
kubectlとの関係は「作る道具」と「操作する道具」です。kubectlは手元の端末からkube-apiserverへリクエストを送るクライアントで、Kubebuilderが生成したMakefileのinstallとdeployも、内部でkustomizeの出力をkubectl applyに渡しています。kubectlのバージョンスキューポリシーは、通信先のkube-apiserverに対して前後1マイナー版です。Kubernetes自体の構成から押さえたい場合はKubernetes(クバネティス)の仕組みとDockerとの違いを先に読むと、以降の用語がつながります。
Kubebuilderのインストールとプロジェクト作成
Kubebuilderの動作前提とインストール
公式Quick Startが挙げる前提は、Go v1.24.6以上、Docker 17.03以上、kubectl v1.11.3以上と、v1.11.3以上のクラスタへのアクセスです。ただしv4.16.0で生成したgo.modはgo 1.26.0を宣言しているため、手元のGoは1.26以上にそろえておくと迷いません。Go自体の導入はGo言語の導入からHTTP APIを動かすまでの手順を参照してください。検証用のクラスタはkindでローカルにk8sクラスタを構築する手順で用意できます。
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 version
# KubeBuilder: v4.16.0
# Kubernetes: 1.37.0
# Go OS/Arch: darwin/amd64
kubebuilder initとcreate apiで生成されるファイル
公式のGuestbookの例に沿って、プロジェクトの初期化とAPIの追加を行います。--domainはAPIグループの接尾辞になり、次の例ではwebapp.my.domainというグループが作られます。
mkdir guestbook && cd guestbook
kubebuilder init --domain my.domain --repo my.domain/guestbook
kubebuilder create api --group webapp --version v1 --kind Guestbook --resource --controller
主な生成物は次のとおりです(.githubやconfig/prometheusなどは省略)。
api/v1/guestbook_types.go # Spec・Statusの型定義
cmd/main.go # Managerの起動
internal/controller/guestbook_controller.go
internal/controller/suite_test.go # envtestの起動
config/crd/ config/rbac/ config/manager/ config/samples/
test/e2e/ # Kindを使うE2Eテスト
Dockerfile Makefile PROJECT AGENTS.md
PROJECTファイルにはcliVersion: 4.16.0とlayout: go.kubebuilder.io/v4が記録されます。kubebuilder alpha updateはこのファイルを手がかりに、3方向マージで新しいKubebuilderの雛形へ追従させるコマンドです。PROJECTを手で消すと、この追従手段を失います。
マーカーによるCRDスキーマとkubectl表示列の設定
型定義のコメントに書く+kubebuilder:マーカーが、CRDのOpenAPIスキーマとkubectlの表示に変換されます。次の例は、messageを1文字以上の必須項目にし、短縮名gbと3つの表示列を足したものです。v4.16.0の雛形は、StatusにConditions []metav1.Conditionを最初から持っています。
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:resource:shortName=gb
// +kubebuilder:printcolumn:name="Message",type=string,JSONPath=".spec.message"
// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=".status.conditions[?(@.type=='Ready')].status"
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=".metadata.creationTimestamp"
type Guestbook struct { ... }
type GuestbookSpec struct {
// +kubebuilder:validation:MinLength=1
Message string `json:"message"`
}
type GuestbookStatus struct {
// +optional
ConfigMapName string `json:"configMapName,omitempty"`
// 雛形にあるConditions(+listType=map, +listMapKey=type)はこの下に残す
}
表示列を1つでも定義すると、kubectlの既定表示からAGE列が消えるため、上の例ではcreationTimestampの列を自分で足しています。もう1点、+listTypeなどの配列向けマーカーの直後に別のフィールドを挟むと、make manifestsがmust apply listType to an array, found stringで止まります。新しいフィールドはマーカーの塊より上に置いてください。
ReconcileによるConfigMap作成と状態・削除処理の実装
ConfigMapを作る最小のReconcile
internal/controller/guestbook_controller.goのReconcileを、Guestbookごとに<名前>-messageというConfigMapを作る処理に置き換えます。importにはfmt・corev1・meta・metav1・controllerutilを足します。
// +kubebuilder:rbac:groups="",resources=configmaps,verbs=get;list;watch;create;update;patch;delete
const guestbookFinalizer = "webapp.my.domain/finalizer"
func (r *GuestbookReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
log := logf.FromContext(ctx)
var gb webappv1.Guestbook
if err := r.Get(ctx, req.NamespacedName, &gb); err != nil {
return ctrl.Result{}, client.IgnoreNotFound(err)
}
// (Finalizerの処理はこの位置に入る。次の次の節で示す)
cm := &corev1.ConfigMap{ObjectMeta: metav1.ObjectMeta{
Name: gb.Name + "-message", Namespace: gb.Namespace,
}}
op, err := controllerutil.CreateOrUpdate(ctx, r.Client, cm, func() error {
// 無関係な既存ConfigMapを乗っ取らない
if cm.ResourceVersion != "" && !metav1.IsControlledBy(cm, &gb) {
return fmt.Errorf("configmap %s already exists and is not controlled by this Guestbook", cm.Name)
}
cm.Data = map[string]string{"message": gb.Spec.Message}
return controllerutil.SetControllerReference(&gb, cm, r.Scheme)
})
if err != nil {
return ctrl.Result{}, err
}
log.Info("configmap reconciled", "name", cm.Name, "operation", op)
// (Status Conditionsの更新は次の節で示す)
return ctrl.Result{}, nil
}
func (r *GuestbookReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&webappv1.Guestbook{}).
Owns(&corev1.ConfigMap{}).
Named("guestbook").
Complete(r)
}
CreateOrUpdateで冪等にし、SetControllerReferenceで所有者参照を付けるので、Guestbookを消すとConfigMapもガベージコレクションで消えます。SetControllerReferenceが拒むのは別のコントローラーが所有している場合だけで、所有者のいない同名ConfigMapは黙って取り込まれます。冒頭のIsControlledByの確認はそれを防ぐためのもので、envtestではconfigmap other-message already exists and is not controlled by this Guestbookのエラーで止まり、既存の中身が残ることを確かめました。Ownsを書いておくと、子のConfigMapを誰かが手で消したときにも親のReconcileが呼ばれて作り直されます。ConfigMap用のRBACマーカーを書き忘れても、envtestのテストは管理者権限で動くため通ってしまい、クラスタに載せて初めて権限エラーになります。
Status ConditionsによるReady状態の通知
処理の結果はstatusに書き戻します。Kubebuilder v4.16.0のGood practicesは、Kubernetes API conventionsに沿ったStatus Conditionsで状態を表すよう勧めています。meta.SetStatusConditionは同じTypeの条件があれば更新し、無ければ追加します。
gb.Status.ConfigMapName = cm.Name
meta.SetStatusCondition(&gb.Status.Conditions, metav1.Condition{
Type: "Ready", Status: metav1.ConditionTrue,
Reason: "ConfigMapReconciled", Message: "configmap " + cm.Name + " is up to date",
ObservedGeneration: gb.Generation,
})
if err := r.Status().Update(ctx, &gb); err != nil {
return ctrl.Result{}, err
}
Conditionsに寄せる利点は、利用者側がkubectl wait --for=condition=Readyでそのまま待てることです。独自のstatus.phase文字列を作ると、待ち合わせのたびにJSONPathを書く手間が利用者に回ります。ObservedGenerationを入れておくと、specを変えた直後の古いReadyと、変更を反映したあとのReadyを見分けられます。
Finalizerによる削除前の外部リソース後処理
所有者参照で消えるのはクラスタ内の子リソースだけです。クラウド上のバケットや外部DNSのレコードなど、クラスタの外に作ったものはFinalizerで後始末します。公式ドキュメントのとおり、Finalizerが付いたオブジェクトを削除すると、APIサーバーはmetadata.deletionTimestampを設定するだけで、metadata.finalizersが空になるまで実体を消しません。
if !gb.DeletionTimestamp.IsZero() {
if controllerutil.ContainsFinalizer(&gb, guestbookFinalizer) {
log.Info("cleanup before delete", "name", gb.Name) // 外部リソースの削除をここで行う
controllerutil.RemoveFinalizer(&gb, guestbookFinalizer)
if err := r.Update(ctx, &gb); err != nil {
return ctrl.Result{}, err
}
}
return ctrl.Result{}, nil
}
if controllerutil.AddFinalizer(&gb, guestbookFinalizer) {
if err := r.Update(ctx, &gb); err != nil {
return ctrl.Result{}, err
}
}
Kubebuilder Bookのfinalizerの解説は、削除前の処理を冪等にするよう求めています。後始末の途中で失敗してReconcileがやり直されても、二重削除でエラーにならない書き方にしてください。外部リソースが無いなら、Finalizerは付けない方が安全です。コントローラーが止まっている間は削除が完了しなくなるためで、その挙動は後のkubectlの実測で示します。
Admission Webhookによるデフォルト値の設定と入力検証
create webhookで生成されるものとcert-managerの扱い
CRDのスキーマで書けない検査は、Admission Webhookに回します。v4.16.0では次のコマンドで、デフォルト値を入れるMutating Webhookと、検証するValidating Webhookの雛形ができます。変換用の--conversionもあります。
kubebuilder create webhook --group webapp --version v1 --kind Guestbook --defaulting --programmatic-validation
生成されたのはinternal/webhook/v1/の実装とテスト、config/webhook/、config/certmanager/などです。実行前後でconfig/default/kustomization.yamlを比べると、../webhookと../certmanagerの行、Webhook用のパッチ、証明書のreplacementsがコメントアウトから外れていました。このままmake deployすると、cert-managerのCertificateリソースが必要になります。Kubebuilder Bookは証明書の配布にcert-managerを使う手順を載せつつ、所定の場所に証明書を置ける仕組みなら他の方法でもよいとしています。
手元でmake runするときは、Webhookの証明書が無いのでENABLE_WEBHOOKS=falseを付けて起動します。生成されたcmd/main.goはこの環境変数がfalseのときだけWebhookの登録を飛ばします。
DefaulterとValidatorの実装
次の例は、messageが空ならhelloを入れ、ConfigMapの名前が他のリソースと衝突するなら作成を拒否するWebhookです。衝突の確認はクラスタ内の別オブジェクトを読む必要があり、CRDのスキーマやCELの式では書けません。Webhookを使う理由になるのは、こうした検査です。importにはfmt・corev1・apierrors・types・clientを足し、生成済みのValidateUpdateとValidateDeleteはそのまま残します。
// 生成されたValidatorにReaderを持たせる
type GuestbookValidator struct {
Reader client.Reader
}
func SetupGuestbookWebhookWithManager(mgr ctrl.Manager) error {
return ctrl.NewWebhookManagedBy(mgr, &webappv1.Guestbook{}).
WithValidator(&GuestbookValidator{Reader: mgr.GetAPIReader()}).
WithDefaulter(&GuestbookDefaulter{}).
Complete()
}
func (d *GuestbookDefaulter) Default(_ context.Context, obj *webappv1.Guestbook) error {
if obj.Spec.Message == "" {
obj.Spec.Message = "hello"
}
return nil
}
func (v *GuestbookValidator) ValidateCreate(ctx context.Context, obj *webappv1.Guestbook) (admission.Warnings, error) {
var cm corev1.ConfigMap
key := types.NamespacedName{Name: obj.Name + "-message", Namespace: obj.Namespace}
err := v.Reader.Get(ctx, key, &cm)
if err == nil {
return nil, fmt.Errorf("configmap %s already exists", key.Name)
}
if !apierrors.IsNotFound(err) {
return nil, err
}
return nil, nil
}
Mutating WebhookはCRDのスキーマ検証より前に動きます。message: ""のGuestbookは本来minLength: 1に反しますが、envtestで作成するとDefaulterがhelloを入れ、そのまま作成に成功しました。衝突するConfigMapを先に作っておいた場合は、次のエラーで拒否されます。
admission webhook "vguestbook-v1.kb.io" denied the request: configmap taken-message already exists
v4.1系の解説のWebhookコードがそのまま通らない理由
検索上位の日本語の解説には、Kubebuilder v4.1.1(controller-runtime v0.18.4)を対象にしたものがあります。その時期のWebhookはruntime.Objectを受け取り、関数の中で型アサーションしていました。controller-runtime v0.23.0のリリースノートは、Validator・Defaulterを型引数で受け取る形に変えた破壊的変更を告知しています。
| 項目 | v0.22以前 | v0.23以降 |
|---|---|---|
| 登録 | WebhookManagedBy(mgr).For(&T{}) |
WebhookManagedBy(mgr, &T{}) |
| 引数 | obj runtime.Object |
obj *T |
| 型アサーション | 関数内で必要 | 不要 |
古い記事のコードを貼ってビルドが通らないときは、まずこの2点を書き換えます。controller-runtime v0.20.0では旧来のDefaulter・Validatorインタフェース自体も削除されています。Kubebuilderの版に合わせた雛形をcreate webhookで作り直し、中身だけを移すのが確実です。
envtestによるテストとkubectlによる動作確認
make testの実行結果
make testはsetup-envtestでKubernetes 1.37.0のkube-apiserverとetcdをbin/k8s/へ取得し、go testを走らせます。Webhookのテストは、envtestがWebhookの設定を登録し、テスト内で起動したManagerがWebhookサーバーを務める構成で、実際にAPIサーバーを経由して呼ばれます。上の実装に、ConfigMapの中身・所有者参照・Finalizer・Ready・無関係なConfigMapを乗っ取らないことを確かめるテストと、Webhookの既定値と拒否のテストを足して実行しました。
$ make test
Setting up envtest binaries for Kubernetes version 1.37...
ok my.domain/guestbook/internal/controller 9.448s coverage: 86.2% of statements
ok my.domain/guestbook/internal/webhook/v1 12.154s coverage: 72.2% of statements
macOS(Intel)で、初回はenvtestバイナリの取得を含めて全体1分34秒、取得済みの2回目は47秒でした。envtestにはkube-controller-managerが無いので、所有者参照によるガベージコレクションは起きません。Guestbookを消したあとにConfigMapが消えることは、Kindを使うtest/e2e/に自分でテストを足して確かめます。
kubectlで見るカスタムリソースとFinalizerの挙動
envtestのkube-apiserver(v1.37.0)にCRDを登録し、同じプロセスでコントローラーを動かした状態で、kubectl v1.37.2から操作しました。
$ kubectl api-resources --api-group=webapp.my.domain
NAME SHORTNAMES APIVERSION NAMESPACED KIND
guestbooks gb webapp.my.domain/v1 true Guestbook
$ kubectl apply -f guestbook.yaml
guestbook.webapp.my.domain/guestbook-sample created
$ kubectl get gb
NAME MESSAGE READY AGE
guestbook-sample hello True 3s
$ kubectl get gb guestbook-sample -o jsonpath='{.metadata.finalizers}'
["webapp.my.domain/finalizer"]
$ kubectl wait --for=condition=Ready gb/guestbook-sample
guestbook.webapp.my.domain/guestbook-sample condition met
続いてコントローラーだけを止め、削除を試しました。kubectlは「deleted」と表示しますが、リソースは残り、deletionTimestampが付いた状態で止まります。Finalizerを外すコントローラーがいないためです。
$ kubectl delete gb guestbook-sample --wait=false
guestbook.webapp.my.domain "guestbook-sample" deleted from default namespace
$ kubectl get gb
NAME MESSAGE READY AGE
guestbook-sample hello True 15s
$ kubectl get gb guestbook-sample -o jsonpath='{.metadata.deletionTimestamp}'
2026-11-04T22:35:24Z
$ kubectl patch gb guestbook-sample --type=merge -p '{"metadata":{"finalizers":null}}'
guestbook.webapp.my.domain/guestbook-sample patched
$ kubectl get gb
No resources found in default namespace.
Operatorをアンインストールした後にカスタムリソースが消せなくなる典型がこの状態です。kubectl patchでFinalizerを外せば消えますが、本来の後始末(外部リソースの削除)は行われません。撤去は「カスタムリソースを先に消す→消え切ったのを確かめる→Operatorを消す」の順で行います。なお、生成されたconfig/samples/のサンプルはspec:の下がコメントだけなので、messageを書き足してから適用します。
イメージのビルドとクラスタへのデプロイ
クラスタ内でOperatorを動かすには、コンテナイメージを作ってDeploymentとして配置します。Webhookを足したプロジェクトは、先にcert-managerをクラスタへ入れておきます。
make docker-build docker-push IMG=<registry>/guestbook:tag
make deploy IMG=<registry>/guestbook:tag
Helmで配布したい場合は、kubebuilder edit --plugins=helm/v2-alphaでkustomizeの出力からdist/chart/にチャートが生成され、Makefileにhelm-deployなどのターゲットが加わります。プラグインはalpha段階なので、社外へ配るチャートの正本にするなら、生成後の差分をレビューする運用が前提です。チャートの基本はHelmとは?helm repo addの使い方と主要コマンドで解説しています。EKSなどクラウドのKubernetes基盤を含めて構築を任せたい場合は、一創のAWS・Google Cloud・Azureのインフラ構築でも対応しています。
Operator SDK・Metacontrollerとの選び分け
| ツール | 最新リリース | 記述言語 | 向く場面 |
|---|---|---|---|
| Kubebuilder | v4.16.0(2026-09-10) | Go | GoでOperatorを書く標準 |
| Operator SDK | v1.42.3(2026-06-26) | Go・Ansible・Helm | OLMで配布する |
| Metacontroller | v4.17.6(2026-10-15) | 任意(Webhook) | Go以外で軽く書く |
| KUDO | v0.19.0(2021-04-27) | YAML宣言 | 新規採用は避ける |
Operator SDKはKubebuilderをCLIとプラグインのライブラリとして使っており、Goで書く部分のディレクトリ構成とコードはほぼ共通です。差はOperator Lifecycle Manager(OLM)向けのバンドル生成と、Ansible・HelmでOperatorを作れる点です。OpenShiftやOperatorHubへの掲載を予定しているならOperator SDK、そうでなければ依存の少ないKubebuilderから始めるのが順当です。
Metacontrollerは、同期処理を任意の言語のWebhookとして書き、ループの管理をMetacontrollerに任せる方式です。Goを書けないチームでも作れる代わりに、Webhookサーバーの可用性がそのままOperatorの可用性になります。KUDOは最終リリースが2021年4月で、現在のKubernetesへの追従が止まっているため、新規の選択肢から外してください。
Kubebuilderを採用すべきでない場面
Kubebuilderで作るOperatorは、Goのコード・テスト基盤・証明書の運用まで抱えます。次の条件に当てはまるなら、別の手段の方が保守は軽くなります。
- 入力値の検証だけが目的:CRDのスキーマで書ける制約はマーカーで済みます。組み込みリソースへの独自ルールなら、Kubernetes v1.30でstableになったValidatingAdmissionPolicyでCELの式を書けば、Webhookサーバーも証明書も要りません。ポリシーを多数管理するならKyvernoのポリシー適用の仕組みも候補です。
- マニフェストのテンプレート化だけが目的:環境ごとの値の差し替えはHelmやKustomize、GitOpsツールの仕事です。状態を監視して直し続ける必要がないなら、コントローラーは過剰です。
- クラウドリソースの宣言的管理:S3バケットやRDSをカスタムリソースで扱いたいだけなら、既製の実装があるCrossplaneのクラウドインフラ管理の仕組みを先に検討します。
- Goのコードを保守できる人がいない:Reconcileの不具合で更新が繰り返されると、APIサーバーへの負荷や管理対象の障害につながります。Finalizerの不具合はリソースが消せない状態も生みます。書いた人しか直せない状態で本番に入れるのは避けてください。
逆に、ステートフルなミドルウェアのバックアップ・昇格・バージョンアップのように、手順書が長く順序を誤ると壊れる運用があるなら、Kubebuilderで書く価値があります。対象のKubernetesの版はKubernetesの最新バージョンと確認方法・EOL一覧で確かめ、envtestの版と合わせてください。
よくある質問
Kubebuilderとkubectlはどちらを覚えればよいですか?
日常の操作に使うのはkubectlなので、先に覚えるのはkubectlです。KubebuilderはGoでカスタムコントローラーやWebhookを開発するときにだけ使い、作ったOperatorのCRD登録や動作確認にもkubectlを使います。
Kubernetesのコントローラーとオペレーターの違いは何ですか?
コントローラーは、望ましい状態へ実際の状態を近づける制御ループの総称です。オペレーターは、カスタムリソースを使ってアプリケーション固有の運用を自動化するコントローラーを指します。ReplicaSetコントローラーのような組み込みのものはオペレーターとは呼びません。
カスタムリソースの削除が終わらないのはなぜですか?
Finalizerが残っている場合は、担当コントローラーの停止や、後始末の処理がエラーで完了していない可能性があります。kubectl get <リソース> -o jsonpath='{.metadata.finalizers}'でFinalizerを確かめ、コントローラーが止まっていれば復旧させ、動いていればログで後始末のエラーを探します。kubectl patchでFinalizerを外すと消えますが、外部リソースの後始末は行われません。
Webhookを足したらmake runで動かなくなりました。どうすればよいですか?
起動ログに証明書ファイルの読み込みエラーがある場合は、Webhookサーバー用の証明書が手元にないことが原因です。ENABLE_WEBHOOKS=false make runのようにWebhookを無効にして起動し、Webhook自体の動作はmake testのenvtestか、cert-managerを入れたクラスタへのmake deployで確かめます。
Operator SDKとKubebuilderの違いは何ですか?
Operator SDKはKubebuilderをライブラリとして使っており、Go製Operatorの構成は共通です。Operator SDKには、OLM向けのバンドル生成と、Ansible・HelmベースのOperatorへの対応が加わります。