---
title: "Kubebuilderとは？Kubernetesのコントローラーとオペレーターの違いと、Webhook・Finalizerまでの開発手順【v4.16】"
url: "https://www.issoh.co.jp/tech/details/6972/"
published: 2025-05-27
updated: 2026-11-05
categories: ["Kubernetes・コンテナ"]
publisher: "株式会社一創"
---

# Kubebuilderとは？Kubernetesのコントローラーとオペレーターの違いと、Webhook・Finalizerまでの開発手順【v4.16】

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の公式ドキュメント](https://kubernetes.io/docs/concepts/architecture/controller/)は、コントローラーを「クラスタの状態を監視し、必要な箇所で変更を行う、または変更を要求する制御ループ」と定義しています。Deploymentに`replicas: 3`と書くとPodが3つに保たれるのは、kube-controller-manager内のReplicaSetコントローラーが「宣言された数」と「実際に動いている数」の差を検知し、不足分のPodを作るためです。

コントローラーの処理は、いまの状態を読み、望ましい状態との差を埋めるところで終わります。何回呼ばれても結果が変わらない（冪等である）ことが前提で、前回どのイベントで呼ばれたかには依存しません。

### オペレーターはカスタムリソースで運用知識をコード化したコントローラー

オペレーターについて、[公式ドキュメント](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)は「カスタムリソースを使ってアプリケーションとその構成要素を管理する、Kubernetesのソフトウェア拡張」と定義しています。データベースのバックアップ、バージョンアップの順序、障害時のフェイルオーバーのように、人が手順書で行っていた運用をコントローラーに書き込み、`kind: PostgresCluster`のような独自リソースで宣言できるようにしたものです。

| 観点   | コントローラー                      | オペレーター                   |
| ---- | ---------------------------- | ------------------------ |
| 範囲   | 制御ループ全般                      | コントローラーの一種               |
| 監視対象 | 組み込み・カスタムどちらも                | カスタムリソースが中心              |
| 持つ知識 | 汎用の調整処理                      | 特定アプリの運用手順               |
| 例    | ReplicaSet・Job・Endpoints     | Rook・CloudNativePG       |
| 作る道具 | client-go・controller-runtime | Kubebuilder・Operator SDK |

区別の基準は、カスタムリソースを通じてアプリケーション固有の運用を実装しているかどうかです。組み込みのServiceだけを監視してラベルを付け直すコントローラーは、Operatorとは呼びません。Ceph向けのRookは典型的なオペレーターで、[Rook CephがKubernetes上でCephを動かすオペレータの仕組み](/tech/details/17287/)で構成を追えます。

### オペレーターの成熟度を表す5段階の能力レベル

「どこまで自動化していればオペレーターと言えるか」を測る物差しとして、Operator Frameworkは[Operator Capability Levels](https://operatorframework.io/operator-capabilities/)を公開しています。

| レベル | 名称                | 自動化する範囲          |
| --- | ----------------- | ---------------- |
| 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実例](/tech/details/9733/)で扱っています。

## 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との違い](/tech/details/2928/)を先に読むと、以降の用語がつながります。

## Kubebuilderのインストールとプロジェクト作成

### Kubebuilderの動作前提とインストール

[公式Quick Start](https://book.kubebuilder.io/quick-start.html)が挙げる前提は、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を動かすまでの手順](/tech/details/17483/)を参照してください。検証用のクラスタは[kindでローカルにk8sクラスタを構築する手順](/tech/details/17438/)で用意できます。

```
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](https://github.com/kubernetes-sigs/kubebuilder/blob/v4.16.0/docs/book/src/reference/good-practices.md)は、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で後始末します。[公式ドキュメント](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/)のとおり、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の解説](https://book.kubebuilder.io/reference/using-finalizers)は、削除前の処理を冪等にするよう求めています。後始末の途中で失敗して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のリリースノート](https://github.com/kubernetes-sigs/controller-runtime/releases/tag/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の使い方と主要コマンド](/tech/details/7694/)で解説しています。EKSなどクラウドのKubernetes基盤を含めて構築を任せたい場合は、一創の[AWS・Google Cloud・Azureのインフラ構築](/service/system/aws/)でも対応しています。

## 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のポリシー適用の仕組み](/tech/details/17271/)も候補です。
- **マニフェストのテンプレート化だけが目的**：環境ごとの値の差し替えはHelmやKustomize、GitOpsツールの仕事です。状態を監視して直し続ける必要がないなら、コントローラーは過剰です。
- **クラウドリソースの宣言的管理**：S3バケットやRDSをカスタムリソースで扱いたいだけなら、既製の実装がある[Crossplaneのクラウドインフラ管理の仕組み](/tech/details/15576/)を先に検討します。
- **Goのコードを保守できる人がいない**：Reconcileの不具合で更新が繰り返されると、APIサーバーへの負荷や管理対象の障害につながります。Finalizerの不具合はリソースが消せない状態も生みます。書いた人しか直せない状態で本番に入れるのは避けてください。

逆に、ステートフルなミドルウェアのバックアップ・昇格・バージョンアップのように、手順書が長く順序を誤ると壊れる運用があるなら、Kubebuilderで書く価値があります。対象のKubernetesの版は[Kubernetesの最新バージョンと確認方法・EOL一覧](/tech/details/17151/)で確かめ、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への対応が加わります。

## 関連記事

- [Kubernetes APIとは？URLの確認方法・エンドポイント構造とcurl実例【1.37で実測】](/tech/details/9733/)
- [Kubernetes（クバネティス）とは？仕組み・メリット・デメリットとDockerとの違いをわかりやすく解説](/tech/details/2928/)
- [k8sをローカルで動かす手順｜kindでクラスタ構築からDeployment公開・撤収まで](/tech/details/17438/)
- [Rook Cephとは？Kubernetes上でCephを動かすオペレータの仕組みと採用判断を実装者目線で解説](/tech/details/17287/)
- [Helmとは？helm repo addの使い方と主要コマンド【Helm 4.3対応】](/tech/details/7694/)

---

出典: [Kubebuilderとは？Kubernetesのコントローラーとオペレーターの違いと、Webhook・Finalizerまでの開発手順【v4.16】](<https://www.issoh.co.jp/tech/details/6972/>)（株式会社一創）
