Commit 29011bb
authored
docs(design): propose S3 admission control + raft blob offload (#637)
## Summary
PR #636 (`s3ChunkBatchOps = 4` で Raft entry を `MaxSizePerMsg = 4 MiB`
に整列) のフォローアップとして、design doc を 2 本提出します。コードは含まず docs だけ。
### 1. `docs/design/2026_04_25_proposed_s3_admission_control.md`
**問題**: PR #636 は per-entry の memory accounting を直すが、aggregate (= 同時 PUT
数 × 各 PUT の inflight) は client 並列度で青天井。
**提案**: ノードが受け入れて Raft に commit する前の S3 PUT body bytes を **共通セマフォで hard
cap**。
- (A) `Content-Length` で request entry に pre-charge
- (B) `flushBatch` の per-batch (4 MiB) で sub-lease —
`dispatchAdmissionTimeout` 経過で 503 SlowDown
- デフォルト 256 MiB cap (GOMEMLIMIT=1800 MiB の ~14%)、env で tunable
- `Retry-After` 付き 503 → AWS SDK が自動 retry
- M1〜M4 の段階導入、metrics/Grafana panel まで含む
### 2. `docs/design/2026_04_25_proposed_s3_raft_blob_offload.md`
**問題**: 5 GiB PUT が WAL に丸ごと書かれ、follower catch-up と snapshot transfer が
O(stored bytes) でスケールしない。
**提案**: Raft が運ぶのは `ChunkRef{SHA256, Size}` (~100 B) と manifest だけ。chunk
本体は別キー名前空間 `!s3|chunkblob|<SHA>` でローカル Pebble に直書き、follower は applyLoop
で `chunkref` を見たら **非同期 fetch RPC で peer から取りに行く**。
- 1 GiB PUT の Raft 負荷: ~100 KiB に圧縮 (10⁴× 削減)
- Snapshot size: O(manifest count) になる
- Reference count + grace period の GC
- `ELASTICKV_S3_BLOB_OFFLOAD=true` でオプトイン、legacy `BlobKey` 経路は並走
- M0 spike 〜 M4 migrator までの 5 段階ロールアウト
両方とも:
- `docs/design/README.md` のファイル名・ヘッダ規約に準拠 (Status: Proposed / Date:
2026-04-25)
- 関連 PR (#593, #600, #612, #617, #636) と既存 design (workload isolation,
raft grpc streaming) を相互参照
- リスクと open questions を明示
## Test plan
- [x] markdown lint clean (textlint なし、手動確認)
- [x] ファイル名規約 `YYYY_MM_DD_proposed_<slug>.md` 準拠
- [x] 既存 design へのリンクが docs/design/README.md と整合
レビューは設計の方向性 (admission control の cap 値、blob offload の content-addressing
単位、M0-M4 の milestone 配分) に focus してもらえると助かります。
/gemini review
@codex review
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
* Added design proposal for S3 PUT request admission control and load
management strategy
* Added design proposal for S3 object storage optimization approach
<!-- end of auto-generated comment: release notes by coderabbit.ai -->2 files changed
Lines changed: 1146 additions & 0 deletions
0 commit comments