10Giを要求したらPVCは11381663335バイトに：CDIファイルシステムの余剰分をドキュメント化するまで

結果：マージ（2026-10-23 04:09、 kubevirt/containerized-data-importer#4318). 実はGitHubのPR・コメント・タイムライン・検査記録、CDIソース（PRのベースコミット 9cd4fbdb）、寄与台帳のドラフト、およびクラスター一覧の生データから取得しました。時刻は韓国時間です。

一言まとめ
1. 何が問題だったのか：6%はどちら側から削られるのか
2. 原因：ドキュメントとコードのどの行か
- ドキュメント側
- 計算を行う2つの関数
3. 何を変更したか：diffの要点
4. 反応：無言の承認と1つのe2eのoverride
5. 学んだこと：オープンソース貢献のコツ
リンク

一言まとめ


PR	kubevirt/containerized-data-importer#4318 `doc: explain how filesystem overhead changes PVC and image size`
変更内容	`doc/datavolumes.md` に2段落、 `doc/cdi-config.md` に1段落。22行追加、削除なし
反応	レビューコメントなし。メンテナー1名が `/lgtm`·`/approve`、のちにe2eの1つを `/override`
結果	PR公開 10-17 00:50 → 承認 10-22 21:53 → マージ 10-23 04:09、約6日3時間18分

図：10Giの要求がPVCとディスクイメージになる計算

1. 何が問題だったのか：6%はどちら側から削られるのか

CDIはFilesystemモードのボリュームにディスクイメージを書き込む際、ファイルシステムメタデータ分の余剰（filesystem overhead）を残します。デフォルト値は 0.06 です。ドキュメントには2つの文がありました。

doc/datavolumes.md：Filesystemモードの場合、CDIは「イメージとファイルシステムメタデータの両方が入る大きさのPVCを要求する」。このロジックは spec.storage にのみ適用される。
doc/cdi-config.md: filesystemOverhead はFilesystemボリュームにおいて「残しておく量」である。

どちらの文も、結果としてPVCとディスクイメージがそれぞれ何バイトになるのかについては言及していません。「6%を残す」を読むと、PVCを要求したサイズにしてその中で6%を差し引くというイメージを抱きやすくなります。PRの本文に書いたとおり、私たちはこのドキュメントを見てVMのルートディスクサイズを決めながら、10Giを要求すればゲストが約9.4GiBを参照することになると推測していました。実際にはその逆でした。 spec.storage を使用すると、ゲストディスクがぴったり10GiBになり、大きくなるのはPVCの方です。

PR本文での実測は、TT LabクラスターのCDI v1.66.0、余剰のデフォルト値 0.06、NFSストレージクラス（Filesystemモード）で測定したものです。

DataVolume `spec.storage` 要求	PVC要求（バイト）	同じ値
10Gi	11381663335	ceil(10737418240 × 1.06)
60Gi	68289980007	ceil(64424509440 × 1.06)
80Gi	91053306676	ceil(85899345920 × 1.06)

10Giのボリュームはvirt-launcherポッド内で qemu-img info により disk.img の virtual size: 10 GiB (10737418240 bytes) を確認しました。生データは不揃いに残っています。10GiボリュームのPVCサイズ 11381663335 は2026-10-17に取得しておいた台帳のクラスター一覧（measure/kv/02-workloads.txt、59日前のPVC）にもそのまま表示されています。60Gi・80Giの値と qemu-img の出力はPRの本文とドラフトにのみ存在し、出力のオリジナルファイルはありません。

2. 原因：ドキュメントとコードのどの行か

行番号はPRのベースコミット 9cd4fbdb を基準としています。

ドキュメント側

計算を行う2つの関数

計算式は #3779（「overheadサイズ計算の数式を修正」、2025-07-03マージ）以降、以下のようになっています。

PVC要求 = align(size, 1MiB) × (1 + overhead) 切り上げ。 pkg/util/util.go 234–243行の GetRequiredSpace です。コメントにも余剰を「整列されたイメージを含む全体の新サイズの割合」として算出すると記載されています。
イメージサイズ = min(여유 공간, PVC 요청) ÷ (1 + overhead) を1MiB単位で切り捨て。 util.go 225–232行の GetUsableSpace と pkg/importer/data-processor.go 360–389行の calculateTargetSize です。切り捨てを行う理由は、qemu-imgが切り上げを行うため、利用可能な領域を超えてしまうからだとコメントに記載されています。

10Giを直接たどってみると以下のようになります。10Giは10737418240バイトであり、すでに1MiBの倍数であるため整列してもそのままです。1.06を掛けると11381663334.4になり、切り上げると11381663335になります（1節の表の1行目）。このPVCに十分な空き容量があれば、11381663335 ÷ 1.06は10737418240をわずかに超え、1MiB単位で切り捨てると再び10737418240、すなわち10GiBになります。そのため、ゲストディスクが要求した通りのサイズになります（計算）。

逆に、プロビジョニングされたファイルシステムの実際の空き容量がPVCの要求よりも小さい場合、イメージはその分小さくなります。小さなイメージにおいてこの計算が狂うという問題のissue #4024 が2026-10-29時点ですでにオープンされています。

3. 何を変更したか：diffの要点

2つのドキュメントに計算式と例を追加しました。既存の文は1つも削除していません。

 # doc/datavolumes.md, spec.storage 의 여분 설명 바로 뒤
+In that case the requested size is the size of the disk image, and CDI requests a PVC of
+`size * (1 + overhead)`, where `size` is rounded up to a multiple of 1MiB ...
+For example, with the default overhead, a DataVolume that requests `storage: 10Gi`
+creates a PVC that requests `11381663335` bytes (`10Gi * 1.06`), and the resulting
+`disk.img` has a virtual size of `10Gi`. If the filesystem on the provisioned volume has
+less free space than the PVC request, the image is sized down ... (see #4024).
+
+With `DataVolume.spec.pvc` the PVC is created with the requested size as is, but the
+overhead is still reserved inside it when CDI writes the image (import, upload or blank),
+so the disk image ends up smaller than the requested size (about `size / (1 + overhead)`).

 # doc/cdi-config.md, filesystemOverhead 설명 뒤
+The overhead is a fraction of the disk image size, added on top of it. ...

spec.pvc 側の文は測定したものではありません。インポート・アップロード・空のディスクの3つの経路がすべて GetUsableSpace でイメージサイズを決定するというコードパスを読み解いて書いたものであるとPR本文で明かしました（未測定）。図の②はそのケースです。

AIの使用は、コミットのフッター Co-Authored-By: Claude Opus 5.5 と Signed-off-by、および本文の終わりの「この変更はAIの支援を受けてドラフトを作成し、私がレビューした」という一文で明らかにしました。KubeVirtの AI貢献ポリシーでは、ツールが自動的に挿入する Co-authored-by も受け入れると記載されています。コミットにはSSH署名が付いています（GitHubで確認済み）。

4. 反応：無言の承認と1つのe2eのoverride

時刻	日
10-17 00:50	PR公開。prowが `release-note-none`·`size/S` ラベルを付与、「信頼されていない作成者はテストを自分で開始できない」という案内、レビューアー2名を指定
10-22 21:53	メンテナー1名が `/lgtm` と `/approve` を1つのコメントで実行
10-22 22:06	coverallsのカバレッジ報告
10-23 04:07	同じメンテナーが `/override pull-containerized-data-importer-e2e-ceph`
10-23 04:09	tideがマージ

レビューコメントは一切ありませんでした。台帳には「ドキュメントPRでもe2eを18個実行する、協力者が /test all を打つ必要がある」、そして「10-20あたりで静かであれば#4024の分析を書いたレビューアーを /cc しよう」という計画が記載されていました。タイムラインを見るとその /cc は行わず、6日目に別のメンテナーが先に承認しました。

マージの2分前に行われた /override は、cephを使用する1つのe2eの結果をメンテナー権限で合格に変更したものです。なぜoverrideしたのかはPRに記載されていません。ドキュメントのみを変更したPRであるため、e2eの結果は変更に関係ないと判断されたものとみられます。マージ後のGitHubのチェックは21個すべてが合格に見えます。

同じ問題について「KubeVirtソースコードを読む」第6回でも取り上げました。この記事を書いている時点では、このPRはレビュー中でした。

5. 学んだこと：オープンソース貢献のコツ

「割合を記載するドキュメントには、何を基準にしているのかを明記する。」や「6%を残す」という同じ言葉は、「PVCから6%を差し引く」とも「イメージに6%を追加する」とも読み取れます。具体的な数字（10Gi → 11381663335バイト）を示すことで、2つの解釈のどちらであるかがすぐに判明します。
「ドキュメント内の数値は、コードから再計算できるように記述する。」PRの表に ceil(10737418240 × 1.06) を併記し、レビューアーがクラスターなしで電卓だけで確認できるようにしました。レビューコメントが一切なかった理由の1つと考えられるでしょう。
「測定したものと読み解いたものを文単位で分ける。」 spec.storage 側は実測、 spec.pvc 側はコードパスから読み解いたものであると本文に分けて記載しました。「すべて確認した」と一括りにしないことで、レビューアーはどこを重点的に確認すべきかを把握できます。
「生データはPRの本文だけでなく台帳にも残す。」 60Gi・80Giの値は現在PRの本文にのみ存在します。後日同じ計算を再度行う際、元の出力があればこの記事のように「本文にのみ存在する」と書かずに済みます。

ティティの一言 「箱に10キロ詰めてください」と言ったら、箱の料金が6%多く請求されました。箱の壁の厚さの分だそうです。だから私は10キロ用の箱には9.4キロしか入らないのだと思っていました。ところが量ってみたら中身はぴったり10キロで、箱の方剤が大きくなっていたのです！案内文に「10キロ詰めると箱は10.6キロ用のものになります」と一言書き添えたら、何も言わずに「いいね」のスタンプが押されました。

リンク

すべての資料は2026-10-29に閲覧しました。

PR: kubevirt/containerized-data-importer#4318 （マージコミット 0bafeaa7)
修正したドキュメント（ベースコミット）： doc/datavolumes.md, doc/cdi-config.md
計算コード（ベースコミット）： GetUsableSpace·GetRequiredSpace, calculateTargetSize
関連: #3779 計算修正、issue #4024
同関数付近のログ修正：第9回、containerized-data-importer#4320