kubebuilder-api-design

Kubebuilder API 設計（Go）

Kubebuilder を使って Go で Kubernetes API を設計します（主に Kubernetes オペレーター向け）。CRD 型定義、スキーママーカー、ステータス／条件、および基本的なスキャフォールド／再生成ワークフローを扱います。

デフォルトの対象範囲は、API 設計と CRD の生成です。明示的に依頼されない限り、コントローラーや Webhook のビジネスロジックは実装しません。

前提とするツール（生成に必要なもの）

このスキルは、何も実行せずに API 設計（Go 型とマーカーのみ）を支援できます。ただし、スキャフォールドを作成し、CRD／マニフェストを再生成するには、通常、ユーザーの環境／プロジェクトに次のものが必要です。

• go ツールチェーン（プロジェクトの go.mod の要件に適合するもの）
• kubebuilder CLI（または Kubebuilder をラップする Operator SDK）
• make（Kubebuilder プロジェクトでは Makefile を通じて生成を実行します）

注記：

• controller-gen は通常、プロジェクトの Makefile ターゲットによって自動的にインストールされます（バージョンは固定されています）。そのため、独立した前提条件とは限りません。
• クラスターに対して実行／テストする場合にのみ、クラスター用ツール（kubectl、kind など）が必要です。明示的に依頼されない限り、対象範囲には含めません。

k8s-crd-design-review との関係

生成された CRD YAML は、コンパイル済み API コントラクトとして扱います。Go 型とマーカーを調整して生成を実行した後、../k8s-crd-design-review/SKILL.md を使って、生成された CRD YAML（または差分）の設計レビューを行います。

SSA／GitOps に関する注記：リストのセマンティクスは API コントラクトの一部です。

• リストセマンティクスマーカー（+listType=set|map、+listMapKey=...）を早い段階で使用すると、生成された CRD が SSA で適切に動作し、安定した差分を生成できます。
• 詳細なガイダンスは ../k8s-crd-design-review/references/list-semantics-gitops-ssa.md にあります。

バージョニング／複数バージョンの CRD（参照先）

ユーザーが複数バージョンの API（例：v1alpha1 → v1beta1 → v1）を設計している場合、または変換 Webhook が必要な場合：

• 手順については、Kubebuilder のマルチバージョンチュートリアルに従います：book.kubebuilder.io/multiversion-tutorial/tutorial.html。
• このスキルでは「Go 型＋マーカー＋生成」に焦点を当てます。互換性レビューや移行計画については、../k8s-crd-design-review/SKILL.md（特に ../k8s-crd-design-review/references/versioning-and-migrations.md）に引き継ぎます。

Spec／Status での関連付け（オブジェクト参照）の設計

CRD が別の Kubernetes オブジェクト（またはそのフィールド／キー）を参照する必要がある場合、「参照」は便利なインポートではなく、API 設計として扱います。

適切なスコープを持つ、API が所有する参照型を優先する（汎用的なコア型は避ける）

新しい API では、corev1.LocalObjectReference や corev1.ObjectReference のような汎用 Kubernetes 参照構造体を埋め込むことは避けてください。

Kubernetes upstream は、corev1.LocalObjectReference および corev1.ObjectReference の新たな使用を明示的に推奨していません。仕様が不十分で、用途ごとに検証やドキュメントを整備しにくいためです。

• 要点：「これらの汎用型を使うのではなく、参照の目的に適した、ローカルで提供・使用する型を作成してください。」

このガイダンスは、古い API に見られるその他の過度に汎用的な参照型にも同様に当てはまります（こうした型は、セマンティクスが不明確で、検証に一貫性がなく、デフォルト値の扱いも煩雑になりがちです）。

パターン：関係ごとに専用の<Thing>Ref型を定義する

CRDに合わせて、それぞれの関係に小さな専用の構造体を定義します。

• 必須フィールドは実際に必須にします（omitemptyと空文字列のデフォルト値を組み合わせるなど、上流の後方互換性のための工夫をそのまま模倣しないでください）
• 関係に実際にある制約（名前の形式、許可するKind、Namespaceのルール）をスキーマに反映します
• ドメインに合ったフィールドごとの説明を追加します（kubectl explainが役立つようにします）

例（同じNamespace内の名前による参照）：

// ConfigMapRef identifies a ConfigMap in the same namespace.
// The referenced ConfigMap must exist before this resource becomes Ready.
type ConfigMapRef struct {
    // Name is the name of the referenced ConfigMap.
    // +kubebuilder:validation:MinLength=1
    // Consider adding a stricter pattern if you want to enforce DNS-1123 label.
    Name string `json:"name"`
}

例（設計上、Namespaceをまたぐことが許可されている場合のNamespace＋名前による参照）：

// SecretRef identifies a Secret.
// If Namespace is omitted, it defaults to the resource namespace.
type SecretRef struct {
    // +kubebuilder:validation:MinLength=1
    Name string `json:"name"`

    // +optional
    // +kubebuilder:validation:MinLength=1
    Namespace string `json:"namespace,omitempty"`
}

参照のセマンティクスを最初に決めて文書化する

関係ごとに、次の項目を明示的に選択して文書化します。

• スコープ：同じNamespace内のみか、Namespaceをまたぐか（Namespaceをまたぐ場合は通常、追加の認可や保護策が必要です）
• 識別情報：名前のみか、名前＋Namespaceか、あるいは（まれに）UID／resourceVersionか（ほとんどのAPIでは名前／Namespaceにとどめるべきです）
• 許可する参照先：固定のKind（推奨）か、「いずれか1つ」のKindか（後者の場合は、明示的にモデル化します）
• ライフサイクルの動作：参照先が存在しない、名前が変更される、削除される、または再作成される場合にどうなるか
• Statusへの反映：解決した詳細情報（例：確認済みUID）を公開する場合は、SpecではなくStatusに格納します

ユーザーが「任意のオブジェクトへの参照」を求める場合は、そのまま受け入れず、対象を絞るよう促します。特定のKind、または明示的に定めた少数のKindを必須とし、それをAPI型に反映してください。

ワークフロー

ステップ 0 — 入力を集める（必要なことだけを確認する）

1. APIの識別情報：Group、Version、Kind、Plural、Scope（NamespacedまたはCluster）
2. 希望するSpecフィールド（必須フィールドを含む）と、変更不可に関する要件
3. Statusの要件：conditionsか、observedGenerationか、概要フィールドか
4. 制約：列挙値、範囲、パターン、最大項目数、一意性、他のオブジェクトへの参照など

ユーザーが関係／参照について言及した場合は、次の情報を確認します。

• 参照先のKindと、Namespaceをまたぐ参照が許可されるか
• 参照が必須かどうか
• オブジェクト全体を参照する必要があるか、サブフィールド（例：secretKeyRef）を参照する必要があるか
• 参照先が存在しない場合や変更された場合に想定される動作

ユーザーがすでにCRDのYAMLを用意している場合は、それを契約として扱い、Go型＋マーカーに対応付けます。

ステップ 1 — Go API型を作成する

次の型を作成します。

• type <Kind>Spec struct { ... }
• type <Kind>Status struct { ... }
• type <Kind> struct { metav1.TypeMeta; metav1.ObjectMeta; Spec; Status }
• type <Kind>List struct { metav1.TypeMeta; metav1.ListMeta; Items []<Kind> }

目安：

• オプショナルなスカラー値や構造体にはポインターを使い、「未設定」とゼロ値を区別できるようにします。
• 該当する場合は、Kubernetesのネイティブ型（metav1.Time、resource.Quantity、intstr.IntOrString）を優先します。
• StatusとSpecは分けます。有用な場合はObservedGenerationとConditionsを含めます。
• 関係には、汎用のKubernetes参照型を埋め込むより、APIが所有する<Thing>Ref構造体を優先します（「関係の設計」を参照）。

一般的なGo／Kubernetes型の選択肢については、./references/go-type-patterns.mdを参照してください。

ステップ 2 — Kubebuilderマーカーを追加する（検証、デフォルト値、表示）

希望するAPI契約に合わせてマーカーを追加します。

• ルートとサブリソース：
  • +kubebuilder:object:root=true
  • +kubebuilder:subresource:status
• フィールドの検証とデフォルト値（最小／最大値、パターン、列挙値、長さ、項目など）
• SSAと正確性のためのリストセマンティクス（listType=set|map、listMapKey=...）
• Status／Specの重要な情報をひと目で確認できるプリンター列

./references/kubebuilder-markers.mdを参照してください。

ルートマーカー、フィールドの検証／デフォルト値、リストセマンティクス、プリンター列について、「必要なマーカーはどれ？」を簡潔に確認できるチートシートは、./references/api_reference.mdを参照してください。

ステップ 3 — ステータスと条件の設計

独自の条件型を作る強い理由がない限り、[]metav1.Condition を使用してください。UX に役立つ場合にのみ、補助的なサマリーフィールドを含めてください。

長時間実行される調整対象リソースでは、kstatus 互換のレディネスを設計してください。集約シグナルとしての Ready、進行中の状態を示す Reconciling、ブロックまたは失敗した状態を示す Stalled を使用し、ステータスの鮮度が重要な箇所ではすべて observedGeneration を使用してください。

Kubebuilder/Go 実装の付録として、./references/status-and-conditions.md を参照してください。標準的な概念上のセマンティクスとレビューのヒューリスティクスについては、k8s-crd-design-review/references/conditions-and-status.md を参照してください。特に、Flux/Argo/kstatus と相性のよい CRD については、../k8s-crd-design-review/references/kstatus-readiness.md を参照してください。

ステップ 3.5 — Kubebuilder ワークフローの要点（スキャフォールディングと生成）

Kubebuilder のスキャフォールディングや再生成の手順が必要な場合（ただし、コントローラーや Webhook のビジネスロジックは対象外）、./references/kubebuilder-workflow-essentials.md の短いチェックリストに従ってください。

ステップ 4 — 「生成＋検証」チェックリストを提示する（実装しない）

コントローラーロジックは記述せず、CRD を再生成してスキーマを検証するための標準的な Kubebuilder の手順をユーザーに提示してください。

• make generate / make manifests を実行する
• 生成された CRD YAML を確認し、次の点を確かめる：
  • 必須フィールドが想定どおりである
  • 意図した箇所にデフォルト値が設定されている
  • リストのセマンティクスとマップキーが正しい
  • プリンター列が表示される

次に（推奨）：生成された CRD YAML（または差分）を対象に、../k8s-crd-design-review/SKILL.md を使用してコントラクトレビューを行い、互換性と移行への影響、ライフサイクル／ステータスのセマンティクス、SSA/GitOps の使いやすさに重点を置いてください。

API の形状についてさらに詳しいガイダンスが必要な場合は、Kubernetes API 規約の公式詳細ドキュメント を案内してください。特に、Spec and Status と Typical status properties を参照してください。

出力形式

コードを提示する場合は、ファイルごとに Go のコードスニペットを 1 つ出力してください。

1. package と imports
2. マーカー
3. Spec、Status
4. ルートオブジェクトとリスト
5. 型エイリアスとネストされた構造体（該当する場合）

コメントは簡潔にしてください。ポインターを使う理由や listType map を使う理由などの根拠は、コードの後に短い箇条書きで記載してください。

リソース

Kubebuilder の書籍（このリポジトリ内の上流ドキュメントミラー）

このスキルのチートシートを超える標準的な Kubebuilder の解説が必要な場合は、次のページを優先してください。

• マーカーの概要と構文：book.kubebuilder.io/reference/markers.html
• CRD 生成、サブリソース、storageversion：book.kubebuilder.io/reference/generating-crd.html
• オペレーター API の例では、マップ形式のリストセマンティクスで Conditions を使用：book.kubebuilder.io/getting-started.html
• 「API の設計」（resource.Quantity、metav1.Time などの型）：book.kubebuilder.io/cronjob-tutorial/api-design.html

references/

これらは必要な場合にのみ読み込みます（コンテキストを小さく保つため）。

• ./references/go-type-patterns.md
• ./references/kubebuilder-markers.md
• ./references/api_reference.md
• ./references/status-and-conditions.md（Kubebuilder/Go の実装に関する付録。概念的な意味については ../k8s-crd-design-review/references/conditions-and-status.md を参照してください）
• ./references/kubebuilder-workflow-essentials.md

---

このスキルに現在含まれているのは references/ のみです。自動化ヘルパーやボイラープレートテンプレートが必要な場合は、後から scripts/ や assets/ を追加してください。