CRD 設計とバージョニング — スキーマ・検証・Conversion Webhook

package v1beta1

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

// DatabaseSpec はユーザーが宣言する desired state です。
type DatabaseSpec struct {
	// Engine は使用するデータベースエンジンです。
	// 作成後は変更できません。
	// +kubebuilder:validation:Enum=postgres;mysql;mariadb
	// +kubebuilder:validation:Required
	Engine string `json:"engine"`

	// Version はエンジンのバージョンです。
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Pattern=`^[0-9]+\.[0-9]+$`
	Version string `json:"version"`

	// Replicas はレプリカ数です。デフォルトは 1 です。
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=9
	// +kubebuilder:default=1
	Replicas int32 `json:"replicas,omitempty"`

	// StorageGB はインスタンスあたりのストレージサイズ（GB）です。
	// +kubebuilder:validation:Minimum=10
	// +kubebuilder:default=20
	StorageGB int32 `json:"storageGB,omitempty"`

	// BackupPolicy は任意のバックアップ設定です。
	// +optional
	BackupPolicy *BackupPolicy `json:"backupPolicy,omitempty"`
}

type BackupPolicy struct {
	// Schedule は cron 形式のバックアップ間隔です。
	// +kubebuilder:validation:Required
	Schedule string `json:"schedule"`

	// RetentionDays はバックアップ保持日数です。
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:default=7
	RetentionDays int32 `json:"retentionDays,omitempty"`
}

// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="engine は変更できません"
Engine string `json:"engine"`

// +kubebuilder:validation:XValidation:rule="self.engine != 'mariadb' || self.replicas == 1",message="mariadb は単一レプリカのみ対応します"
// +kubebuilder:validation:XValidation:rule="!has(self.backupPolicy) || self.replicas >= 1",message="バックアップを有効化するには最低 1 レプリカが必要です"
type DatabaseSpec struct {
	// ... フィールド ...
}

openAPIV3Schema:
  type: object
  properties:
    spec:
      type: object
      required:
        - engine
        - version
      properties:
        engine:
          type: string
          enum: [postgres, mysql, mariadb]
          x-kubernetes-validations:
            - rule: "self == oldSelf"
              message: "engine は変更できません"
        replicas:
          type: integer
          minimum: 1
          maximum: 9
          default: 1
      x-kubernetes-validations:
        - rule: "self.engine != 'mariadb' || self.replicas == 1"
          message: "mariadb は単一レプリカのみ対応します"

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  group: example.com
  names:
    kind: Database
    plural: databases
  scope: Namespaced
  versions:
    - name: v1alpha1
      served: true
      storage: false
      schema:
        openAPIV3Schema: { }
    - name: v1beta1
      served: true
      storage: true
      schema:
        openAPIV3Schema: { }
    - name: v1
      served: false
      storage: false
      schema:
        openAPIV3Schema: { }

ユーザーが v1alpha1 で GET
        │
        ▼
  API サーバーが etcd から v1beta1（storage）で読む
        │
        ▼
  conversion webhook: v1beta1 → v1alpha1 変換
        │
        ▼
  ユーザーに v1alpha1 で応答


ユーザーが v1 で CREATE
        │
        ▼
  conversion webhook: v1 → v1beta1（storage）変換
        │
        ▼
  etcd に v1beta1 で保存

ステップ 1: v1beta1 を追加（served=true, storage=false）
        storage はまだ v1alpha1
        │
        ▼
ステップ 2: storage を v1beta1 に切り替え（storage=true）
        storage-version-migrator で既存オブジェクトを再保存
        │
        ▼
ステップ 3: v1alpha1 を served=false に
        新規リクエストを受け付けなくなる
        │
        ▼
ステップ 4: CRD status.storedVersions から v1alpha1 を削除
        すべてのオブジェクトが v1beta1 で再保存された後にのみ
        │
        ▼
ステップ 5: v1alpha1 のスキーマ定義を削除

   v1alpha1 (Spoke)        v1 (Spoke)
        │                     │
        │  ConvertTo/From     │  ConvertTo/From
        ▼                     ▼
        └────► v1beta1 (Hub) ◄┘

package v1beta1

import "sigs.k8s.io/controller-runtime/pkg/conversion"

// Hub はこのバージョンが変換ハブであることを示します。
func (*Database) Hub() {}

// コンパイル時にインターフェース充足を保証します。
var _ conversion.Hub = (*Database)(nil)

package v1alpha1

import (
	"sigs.k8s.io/controller-runtime/pkg/conversion"
	v1beta1 "example.com/api/v1beta1"
)

// ConvertTo は v1alpha1 を Hub（v1beta1）に変換します。
func (src *Database) ConvertTo(dstRaw conversion.Hub) error {
	dst := dstRaw.(*v1beta1.Database)

	// メタデータはそのままコピーします。
	dst.ObjectMeta = src.ObjectMeta

	// 同一のまま保たれるフィールド。
	dst.Spec.Engine = src.Spec.Engine
	dst.Spec.Version = src.Spec.Version
	dst.Spec.Replicas = src.Spec.Replicas

	// v1alpha1 の storageGB(int) が v1beta1 でも同一と仮定。
	dst.Spec.StorageGB = src.Spec.StorageGB

	// v1alpha1 になかったフィールド: 妥当なデフォルトで埋める。
	if src.Spec.Backup != "" {
		dst.Spec.BackupPolicy = &v1beta1.BackupPolicy{
			Schedule:      src.Spec.Backup,
			RetentionDays: 7,
		}
	}

	dst.Status.Phase = src.Status.Phase
	return nil
}

// ConvertFrom は Hub（v1beta1）を v1alpha1 に変換します。
func (dst *Database) ConvertFrom(srcRaw conversion.Hub) error {
	src := srcRaw.(*v1beta1.Database)

	dst.ObjectMeta = src.ObjectMeta
	dst.Spec.Engine = src.Spec.Engine
	dst.Spec.Version = src.Spec.Version
	dst.Spec.Replicas = src.Spec.Replicas
	dst.Spec.StorageGB = src.Spec.StorageGB

	// v1beta1 の構造化バックアップを v1alpha1 の単純な文字列に縮約。
	if src.Spec.BackupPolicy != nil {
		dst.Spec.Backup = src.Spec.BackupPolicy.Schedule
	}

	dst.Status.Phase = src.Status.Phase
	return nil
}

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: databases.example.com
spec:
  conversion:
    strategy: Webhook
    webhook:
      conversionReviewVersions:
        - v1
      clientConfig:
        service:
          namespace: db-operator-system
          name: db-operator-webhook
          path: /convert
          port: 443
        caBundle: <cert-manager が注入>

func (r *Database) SetupWebhookWithManager(mgr ctrl.Manager) error {
	return ctrl.NewWebhookManagedBy(mgr).
		For(r).
		Complete()
}

versions:
  - name: v1alpha1
    served: true
    storage: false
    deprecated: true
    deprecationWarning: "example.com/v1alpha1 Database は deprecated です。v1beta1 を使用してください。"

// +kubebuilder:printcolumn:name="Engine",type=string,JSONPath=`.spec.engine`
// +kubebuilder:printcolumn:name="Replicas",type=integer,JSONPath=`.spec.replicas`
// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
type Database struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`
	Spec   DatabaseSpec   `json:"spec,omitempty"`
	Status DatabaseStatus `json:"status,omitempty"`
}

// +kubebuilder:subresource:status
type Database struct { /* ... */ }

type DatabaseStatus struct {
	// Phase は人間が読むための要約状態です。
	Phase string `json:"phase,omitempty"`

	// Conditions は標準の状態条件リストです。
	// +optional
	// +patchMergeKey=type
	// +patchStrategy=merge
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ObservedGeneration は最後に処理した spec 世代です。
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

// +kubebuilder:subresource:scale:specpath=.spec.replicas,statuspath=.status.replicas,selectorpath=.status.labelSelector
type Database struct { /* ... */ }

悪い:  spec.restartNow: true        (命令、一回限り)
良い:  spec.version: "16.2"         (意図、コントローラが reconcile)
良い:  spec.paused: true            (状態、持続的な意味)

# 1. 現在保存されているバージョンを確認。
kubectl get crd databases.example.com -o jsonpath='{.status.storedVersions}'

# 2. 新バージョンを served=true でデプロイ（storage はまだ旧バージョン）。
kubectl apply -f crd-with-new-version.yaml

# 3. storage を新バージョンに切り替え。
kubectl patch crd databases.example.com --type=merge \
  -p '{"spec":{"versions":[{"name":"v1beta1","storage":true}]}}'

# 4. すべてのオブジェクトを新 storage バージョンで再保存（no-op パッチでトリガー）。
kubectl get databases.example.com --all-namespaces -o name | \
  xargs -I{} kubectl patch {} --type=merge -p '{}'

# 5. status.storedVersions から旧バージョンが消えたか確認。
kubectl get crd databases.example.com -o jsonpath='{.status.storedVersions}'

# 6. 旧バージョンを served=false に、その後スキーマを削除。