Rook-Ceph 解説 2: Rook operator がやってくれること、やってくれないこと

ステータス: ドラフト（2026-10-29）、ソースと公式ドキュメント基準、実測なし。 基準のバージョンは Rook v1.21.1（タグが指すコミット 09d2f0d8d883b70b30de796c4390371be725ff3b、2026-10-26 リリース）と、Rook チャートがサブチャートとして組み込む ceph-csi-operator v1.1.0 （コミットく 98eee8980fc69e5c9c02c80958abe06c3faba5eb）です。記事内のソースリンクはすべてこのコミットに固定しています。TT Lab の検証クラスターで operator が作成したリソースを直接数える作業は、第 4 篇（元データが集まり次第執筆します）で行います。作成ルール：実測データが基本であり、測定できなかったものは「未実測」、原文から見つからなかったものは「未確認」と表示します。

目次

• 1. operator と Rook の位置づけ
• 2. CRD の一覧と reconcile が作るもの
• 3. mon の配置とフェイルオーバー
• 4. OSD prepare Job がディスクを選ぶ方式
• 5. CSI のデプロイ：v1.21 では 3 者で分担する
• 6. アップグレードの順序
• 7. クラスターのクリーンアップ：cleanupPolicy
• 8. toolbox
• 9. operator がやってくれないこと
• 参考

1. operator と Rook の位置づけ

Kubernetes の operator は、人間が行っていた運用の知識をコントローラーに移し替えたプログラムです。ユーザーが「こういう状態であってほしい」という希望をカスタムリソース（CR、Custom Resource）として記述しておくと、operator が現在の状態と比較して、足りないものを作成し、過剰なものを削除します。この比較と調整を 1 回実行することを reconcile と呼びます。

Rook の公式ドキュメント（Storage Architecture）では、Rook の役割を 3 つの層に分けています。Ceph の設定を自動化する Rook operator、ボリュームを作成してアタッチする Ceph-CSI ドライバー、そして実際にデータを保存する Ceph デーモンです。同じドキュメントに最も重要な 1 行があります。 「Rook is not in the Ceph data path.」 アプリケーションの読み書きは第 1 篇で見たとおり、アプリと OSD の間を直接往復し、operator はその経路上に立ちません。そのため、operator のポッドが一時的に停止しても、すでにアタッチされているボリュームの I/O が operator を経由することはありません。operator が停止したときに遅延するのは、新しい OSD や mon の交換といった、operator が担当する「変更作業」です。

2. CRD の一覧と reconcile が作るもの

v1.21.1 の deploy/examples/crds.yamlには、CRD（CR の種類を定義するスキーマ）が 21 種類あります。

CephBlockPool, CephBlockPoolRadosNamespace, CephBucketNotification, CephBucketTopic, CephCOSIDriver, CephClient, CephCluster, CephFilesystem, CephFilesystemMirror, CephFilesystemSubVolumeGroup, CephNFS, CephNVMeOFGateway, CephObjectRealm, CephObjectStore, CephObjectStoreAccount, CephObjectStoreUser, CephObjectZone, CephObjectZoneGroup, CephRBDMirror, ObjectBucket, ObjectBucketClaim

よく使われるものが reconcile で作成するものを、Ceph 側と Kubernetes 側に分けて整理すると以下のようになります。

残りは用途のみ簡単に記載します。CephNFS（NFS ゲートウェイ）、CephRBDMirror・CephFilesystemMirror（他クラスターへのミラーリング）、CephObjectRealm・ZoneGroup・Zone（RGW マルチサイト）、CephBucketTopic・Notification（バケットイベント通知）、CephCOSIDriver（COSI ドライバー）、CephNVMeOFGateway（NVMe over Fabrics ゲートウェイ）、CephObjectStoreAccount（RGW アカウント）です。

CephCluster の reconcile は順序が決められています。 cluster.go の reconcileCephDaemonsに沿って進めると、設定上書き用 ConfigMap を作成し、 mon を起動し（L121）、クラスターのアイデンティティが生成されたことを確認し、mgr を起動し（L149）、OSD を起動します（L164）。MDS と RGW はこの関数には含まれていません。それぞれ CephFilesystem と CephObjectStore を担当する別のコントローラーが reconcile を行います。

3. mon の配置とフェイルオーバー

第 1 篇で見たように、MON は過半数が生存していなければクラスターが動作しません。そのため、Rook が最も細心の注意を払って保護するのが mon です。Rook ドキュメントの Monitor Healthとソースを合わせて読むと、以下のようになります。

アイデンティティは Service の IP です。 Ceph における mon のアイデンティティは IP アドレスであり、変更してはなりません。ポッド IP は再起動のたびに変わるため、Rook は mon ごとに Kubernetes Service を 1 つずつ作成し、その ClusterIP を固定のアイデンティティとして使用します。

データはノードにバインドされます。 mon のメタデータは、CephCluster の dataDirHostPath（デフォルト /var/lib/rook）配下のホストディスクや、 volumeClaimTemplate で作成されたボリュームに保存されます。そのため、mon ポッドは再起動時に同じノードに戻る必要があり、そのおかげで既存のデータから処理を継続できます。

配置は canary で決定します。 新しい mon をどのノードに配置するか決定する際、Rook はまず名前の末尾に -canary を付与したテスト用 Deployment を起動して Kubernetes スケジューラーにノードを選ばせ、その結果を mon の配置場所として使用します （scheduleMonitor、mon.go#L731-L740). allowMultiplePerNode: false の場合、mon 同士が同じノードに配置されないようにする anti-affinity が必須ルールとして組み込まれ、 true の場合、重み 50 の優先ルールになります（第 3 篇で確認するクラスターチャート values のコメント）。

検査は 45 秒ごと、置き換えは 10 分後です。

health.goに HealthCheckInterval = 45 * time.Second つの定数があります。 MonOutTimeout = 10 * time.Minute と

1. です。流れは以下の通りです。
2. 45 秒ごとに Ceph にクォーラムの状態を問い合わせます。
3. クォーラムに存在しない mon を初めて検知した時刻を記録しておきます。その間、Kubernetes は Deployment を通じてそのポッドを再度起動しようと試みます。ドキュメントには、「新しい mon に置き換えるよりも、既存の mon を復旧させる方が常に望ましい」と記載されています。failoverMon10 分経過しても復帰しない場合は、新しい名前（これまでの最大番号の次、例えば mon-a・b・c であれば mon-d）で新しい mon を構築します。古い mon の Deployment は 0 にスケールダウンしておき（ホストネットワークを使用する mon は、新しい mon が同じホスト IP で起動しないようにするためにスケールダウンしません）、新しい mon が失敗した場合はロールバックします （).
4. 、health.go#L7421 回の検査で置き換えられる mon は 1 つだけです（).

health.go#L331例外が 3 つあります（).

• health.go#L286-L323タイムアウトが 0
• ：フェイルオーバーを行いません。ドキュメントには、計画メンテナンス時に有用であると記載されています。 mon が存在していたノードが削除された場合shouldFailoverMonImmediately).
• ：10 分間待機することなく即座に移動させます（タイムアウトが経過したにもかかわらず mon ポッドがノードにすら配置されていない状態の場合

（例：ノードのドレイン）、タイムアウト時間だけさらに待機します。ドキュメントの表現では「待機時間が 2 倍になる」となります。 healthCheck.daemonHealth.mon.interval·timeout これら 2 つの値は CephCluster の ROOK_MON_OUT_TIMEOUT·ROOK_MON_HEALTHCHECK_INTERVAL で変更できます。operator の環境変数 が存在する場合はそちらが優先されます（過去の動作との互換性、 health.go#L58-L103）。).ドキュメントでは、間隔が短すぎるとmonが頻繁に入れ替わりすぎ、長すぎると新しいmonが立ち上がる前に他のmonが死亡してクォーラムを失うリスクがあると警告しています。

monが替わるとアドレスも変わります。Rookはmonを立ち上げるたびに、CSI側にmonアドレスを再度通知します（第5節のCephConnection、 mon.go#L1261-L1269).

4. OSD prepare Jobがディスクを選定する方式

OSDは「ディスクを探し、準備し、デーモンを起動する」の2段階で作成されます。前の段階はノードごとに1つずつ実行されるJobが行い、後ろの段階はoperatorが行います。名前は osd.go#L64-L69に定義されています。Jobは rook-ceph-osd-prepare-<노드>、OSDデーモンは rook-ceph-osd-<번호> です。

prepare Job内で起きることをソースコードの順序に沿って追っていくと、以下のようになります。

1. デバイスリスト。 lsblk でノードのブロックデバイスを探します。このとき rbd·nbd·drbd·zram デバイスはリストから完全に除外します。前者の3つはネットワークストレージのため読み取りが停止する可能性があり、zramは揮発性メモリであるためです (disk.go#L37-L39、v1.21.1の変更点)。
2. 使用中のデバイスの除外(getAvailableDevices, daemon.go#L347-L410)。 マウントされたデバイス、ファイルシステムシグネチャのあるデバイス、すでにBlueStore OSDが含まれているデバイスをスキップします。
3. ceph-volumeへの問い合わせ。 残ったデバイスごとに ceph-volume inventory --format json <장치> を実行し、「使用可能」と答えたものだけを残します。 拒否された理由はそのままログに記録されます（device.go#L399-L428).
4. ユーザー設定との一致確認。 useAllDevices: true であれば残りのデバイスをすべて使用しますが、LVM論理ボリュームとloopデバイスは選択しません。 deviceFilter （デバイス名の正規表現）、 devicePathFilter、ノードごとの devices リストがある場合は、それに一致するものだけを使用します。
5. 準備。 基本は ceph-volume raw prepare です。暗号化を有効にしたり、1つのデバイスに複数のOSDを配置したり（osdsPerDevice が2以上）、メタデータデバイスを分離する場合はrawモードを使用できないため、 ceph-volume lvm batch に移行します (allowRawMode, volume.go#L497-L525).
6. 結果の報告。 作成したOSDのリストをConfigMap rook-ceph-osd-<노드>-status に書き込みます (status.go#L47)。 operatorがこれを読み取り、OSDごとにDeploymentを作成します。

公式ドキュメントの要件（Prerequisites）でも同様のことが述べられています。OSDとして使用できるのは、パーティションもファイルシステムもないrawデバイス、ファイルシステムのないrawパーティション、ファイルシステムのないLVM論理ボリューム、そして block モードのPVです。そのため、「ディスクを新たに追加したのにOSDが作成されない」場合は、まず lsblk -f でファイルシステムシグネチャが残っていないか確認します。逆に、何のシグネチャもない空のディスクは useAllDevices: true で確認されることもなくOSDになります。これが第3篇でこのデフォルト値を警告する理由です。

prepare Jobはデバイスのサイズに応じてメモリを一度多く消費します。ドキュメントでは、大容量ディスクの場合は1〜2Gi程度になるとして、このJobにはメモリの上限を設定しないよう推奨しています。一度準備されたOSDは次回のprepareで「すでに存在する」としてスキップされるため、大量のメモリ消費は初回のみです。

5. CSIのデプロイ：v1.21では3つのコンポーネントが分担する

CSI（Container Storage Interface）は、Kubernetesがストレージベンダーのドライバを呼び出すための標準規格です。PVCが作成されると、CSIドライバの provisioner（コントローラー側）がストレージにボリュームを作成し、ポッドがノードに起動すると、そのノードの nodeplugin がボリュームをアタッチ・マウント（map・mount）してくれます。

以前のRookはCSIドライバを直接デプロイしていました。v1.21では、この作業を3つの主体が分担します。初めてインストールする人が最もつまずきやすいポイントであるため、順番に記載します。

1. ceph-csi-operator。 rook-ceph チャートがサブチャート（ceph-csi-operator 1.1.0）として一緒にインストールします (Chart.yaml、条件 csi.installCsiOperator)。このoperatorが実際のドライバポッドを作成します。
2. ceph-csi-driversチャート。 どのドライバを有効にするかを記述した Driver CR、 OperatorConfig、ドライバポッドが使用するRBACを作成します。このチャートはRookのリポジトリからではなく、ceph-csi-operatorのHelmリポジトリから取得し、Rookが調整したvaluesファイル（deploy/charts/ceph-csi-drivers/values.yaml）を指定してインストールします。デフォルトではRBDとCephFSが有効になり、NFSとNVMe-oFは無効になります。ドライバ名は rook-ceph.rbd.csi.ceph.com のようにoperatorのネームスペースをプレフィックスとして付与します。アップグレードドキュメントには、 このチャートをインストールしないとサービスアカウントが存在しないためCSIドライバが失敗状態になると記載されています（v1.20からの要件、 Rook Upgrades).
3. Rook operator。 monが起動した後、operatorのネームスペースに CephConnection CR（monアドレスリスト、read affinity、RBDミラー数）とデフォルトの ClientProfile（RBD・CephFSが使用するSecret名）を作成・修正します (ceph_connection.go#L37-L103, config.go#L149-L190)。 どちらも名前はCephClusterのネームスペースとなります。サブボリュームグループとRADOSネームスペースごとにClientProfileを個別に作成する点は、第2節で見た通りです。

ceph-csi-operatorは Driver CRを1つ受け取ると、CSIDriverオブジェクト、名前が -ctrlplugin で終わるDeployment（provisionerとサイドカー）、 -nodeplugin で終わるDaemonSet（すべてのノード）、liveness Service、NetworkPolicy、設定用ConfigMapを作成します (driver_controller.go#L254-L264)。 そのため、Rookクイックスタートのポッドリストに rook-ceph.rbd.csi.ceph.com-ctrlplugin-… と rook-ceph.rbd.csi.ceph.com-nodeplugin-… が表示されます。

StorageClass の provisioner は、このドライバ名と完全に一致していなければなりません。名前のプレフィックスを変更したい場合は（CSI_DRIVER_NAME_PREFIX）、初回インストール時のみ行うようドキュメントで警告されています。すでに応用・運用中のクラスターで変更すると予期せぬ動作が発生すると記載されています (Ceph CSI Drivers).

6. アップグレードの順序

Rookはアップグレードを2つに分けています。 Rook自体（管理層） と Ceph（データ層） です。

Rookのアップグレード。 チャートは rook-ceph → ceph-csi-drivers → rook-ceph-cluster の順序でアップデートします。ドキュメントで明らかにされているv1.21での破壊的変更は3つです。

• Helm OCI 차트 태그에 v を付与しません（1.21.0).
• Ceph msgr2プロトコルがデフォルトで必須になりました。msgr2にはカーネル5.11以上が必要であり、古いカーネルの場合は requireMsgr2: false で無効化します。 すでにアタッチされているボリュームは再度アタッチされるまでmsgr1を継続して使用し、monはフェイルオーバーにより新規構築されるタイミングからmsgr2のみを受け付けます。
• サポートされるKubernetesの最小バージョンがv1.32になりました。

また、v1.21ではブロックStorageClassにCSI Secretパラメータが新しく追加されましたが、StorageClassの parameters は変更できないため、チャートをアップデートする前に ceph-block StorageClassを削除するよう案内されています。同じ名前のStorageClassが再作成されるため、既存のPVには影響がないと記載されています。

Cephのアップグレード。 CephClusterのイメージを変更すると開始されます (Ceph Upgrades). Rookは、デーモンを1つずつ停止しても問題ないかを確認し、変更し、状態が安定するのを（monはクォーラム、OSDはPGがclean、MDSはup）待ってから次のデーモンに移行します。第2節で見たreconcileの順序通り、CephCluster内ではmon、mgr、OSDの順であり、MDSとRGWはそれぞれのコントローラーが担当します。OSDが1つ停止しても問題ない状態になるのを待つ時間は waitTimeoutForHealthyOSDInMinutes（デフォルト10分）です。サポートされているCephはSquid v19.2.0以上およびTentacle v20.2.1以上であり、v20.2.0はread affinityを有効にした際にデータ破損の問題が確認されているため推奨されません。Rookはv20.2.0でread affinityを自動的に無効化します (ceph_connection.go#L105-L116).

7. クラスターのクリーンアップ：cleanupPolicy

CephClusterを削除してもデータは削除されません。これがデフォルトであり、誤って削除されたCRによってデータが消失するのを防ぐための仕組みです。 チャートのドキュメントでも、 rook-ceph-cluster を削除しても /var/lib/rook とOSDディスク上のデータは残るため、ディスクを再利用するには手動で消去する必要があると記載されています。

完全に削除するには、まずCephClusterを確認用フレーズを記述します (Cleanup, CephCluster CRD: Cleanup policy).

確認用フレーズが設定された状態でCephClusterを削除すると、operatorはCephデーモンポッドが存在していたノードを記憶し、それらのポッドがすべて消えるまで5秒間隔で待機した後、ノードごとにJob（cluster-cleanup-job-<노드>、ラベル rook-ceph-cleanup）を立ち上げて dataDirHostPath を削除し、OSDディスクを消去します (cleanup.go#L62-L100)。 ドキュメントでは、アプリケーションのボリュームとPVCを事前にクリーンアップすることを強く求めています。そうしないと、ボリュームがマウントされたままになりノードの再起動が必要になる場合があります。CSI operatorのCR（operatorconfigs·drivers·clientprofiles·clientprofilemappings·cephconnections）も個別に削除する必要があります。

確認用フレーズなしで削除してしまった場合は、ノードごとに dataDirHostPath を手動で削除し、ディスクを消去する必要があります（ドキュメントの sgdisk --zap-all, dd, blkdiscard、LVM・デバイスマッパーのクリーンアップ手順）。特に dataDirHostPath を残したまま再インストールすると、新しいクラスターでmonが起動しなくなるとチャートのvaluesのコメントで警告されています。

8. toolbox

Cephを調査するための基本ツールは ceph コマンドです。Rookは、このコマンドが含まれるコンテナを toolbox というDeployment（rook-ceph-tools）として提供します (Toolbox)。 クラスターチャートでは toolbox.enabled がデフォルトの false であり、有効にするとCephイメージと同じイメージで起動します。コマンドを一度だけ実行して結果をログに残すJob方式もあり、toolboxを使用せずにkubectlプラグインを利用する方法もあります。

kubectl -n rook-ceph exec -it deploy/rook-ceph-tools -- ceph status
kubectl -n rook-ceph exec -it deploy/rook-ceph-tools -- ceph osd tree
kubectl -n rook-ceph exec -it deploy/rook-ceph-tools -- ceph df

第4篇でTT Labの実習クラスターにおけるこれら3つの出力を、第1篇の概念と照らし合わせて確認する予定です。

9. operatorが実行しないこと

operatorを導入すると「これで全て自動でやってくれるだろう」と期待しがちです。原文で確認した、Rookが実行しない、またはデフォルトでは実行しない作業です。

もう一つ指摘しておくことがあります。 useAllNodes: true のときノードの taint や affinity を変更してノードが Rook の対象から外れた場合、そのノードの OSD は operator ポッドを削除して再起動することで「確認」して初めて削除されます。誤ってデータを失わないための仕組みであり、ドキュメントでは本番環境では useAllNodes: false でノードを明示するよう推奨しています。

一言メモ。 Rook はきめ細やかな管理者です。mon に異常があれば 10 分間待ち、空きディスクを見つければ OSD を作成し、削除しろと言われれば「本当に？」と必ず確認します。しかし、データを直接運ぶことはしません。それは Ceph デーモンの役割だからです。そのため、operator が少し休止しても、すでにアタッチされているボリュームは無事です！

参考

ソースとドキュメントはいずれも 2026-10-29 に上記のコミットで閲覧しました。

• Rook v1.21.1 リリース: https://github.com/rook/rook/releases/tag/v1.21.1
• Storage Architecture: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Getting-Started/storage-architecture.md
• Monitor Health: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Storage-Configuration/Advanced/ceph-mon-health.md
• CephCluster CRD: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/CRDs/Cluster/ceph-cluster-crd.md
• Prerequisites: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Getting-Started/Prerequisites/prerequisites.md
• Ceph CSI Drivers: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-drivers.md
• Ceph-CSI Driver Helm Chart: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Helm-Charts/csi-drivers-chart.md
• Rook Upgrades: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Upgrade/rook-upgrade.md
• Ceph Upgrades: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Upgrade/ceph-upgrade.md
• Cleanup: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Storage-Configuration/ceph-teardown.md
• Toolbox: https://github.com/rook/rook/blob/09d2f0d8d883b70b30de796c4390371be725ff3b/Documentation/Troubleshooting/ceph-toolbox.md
• ceph-csi-operator v1.1.0 Driver コントローラー: https://github.com/ceph/ceph-csi-operator/blob/98eee8980fc69e5c9c02c80958abe06c3faba5eb/internal/controller/driver_controller.go