Workers KV

解決する課題

グローバルに展開した Workers から、どのリージョンのユーザーがアクセスしても同じように速く設定値やコンテンツを読みたい、という要求に応えます。

• 自前でデータベースやキャッシュ層を構築せずに、キーバリュー形式のデータをエッジで即座に読み取れる
• リクエストごとに中央のデータベースへ問い合わせる必要がなく、ユーザーに最も近いロケーションから応答
• 設定情報・機能フラグ・認証トークンの検証・静的コンテンツのメタデータなど、読み取りが圧倒的に多いワークロードに最適化
• Workers からバインディング経由で扱えるため、追加のクライアントライブラリや接続管理が不要

主要概念と用語

• Namespace（ネームスペース）: キーと値の集合を束ねる論理的な入れ物。用途ごとに分けて作成し、Worker からバインディングで参照する
• Key（キー）: 値を一意に識別する文字列。ネームスペース内で一意
• Value（値）: キーに対応するデータ本体。文字列・JSON・バイナリなど任意の内容を保存可能
• Metadata（メタデータ）: キーに付随する小さな構造化データ。値を取得せずにメタ情報だけを一覧・参照できる
• Binding（バインディング）: Worker のコードからネームスペースにアクセスするための設定。wrangler の設定ファイルで Worker に紐づける
• 結果整合性 (Eventual Consistency): 書き込み直後は一部のロケーションで旧い値が読める場合がある整合性モデル。KV の基本特性
• TTL (Time To Live): キーごとに設定できる有効期限。期限が来ると自動的に読み取れなくなり、内部的にも削除される

仕様・制限・クォータ

• 値のサイズやキーの長さには上限があり、大きなファイルの保存には向かない（大容量データは R2 など他のストレージを使う）
• 書き込みはネームスペース内の同一キーに対する高頻度な更新を想定しておらず、頻繁に変わるデータには不向き
• 読み取りはエッジのキャッシュから返るため低レイテンシだが、直後の書き込み内容が全ロケームに反映されるまでには時間差がある
• TTL を設定したキーは期限到来後にアクセス不可となり、内部でも遅れて削除される
• 一覧取得（list）はキー数が多い場合ページングが必要

内部の仕組み

Workers KV は、書き込まれた値を中央のストレージに保持しつつ、アクセスのあったキーをエッジのキャッシュ層にも複製していく設計です。読み取りは基本的に最寄りのエッジキャッシュから返るため低レイテンシになりますが、書き込みが全世界のキャッシュへ伝播するまでには遅延があり、これが結果整合性の性質を生みます。

つまり「頻繁に読まれるが、めったに書き換わらない」データほど KV の恩恵を最大限に受けられます。逆に、強い整合性（書き込み直後に必ず最新値が読める）が必須なカウンターやロック処理には別の仕組み（Durable Objects など）が適しています。

設計パターン / ベストプラクティス

• 設定・機能フラグ配信: アプリ全体の設定値や A/B テストのフラグを KV に置き、Worker が起動時に読み取って動作を切り替える
• 認証トークンのキャッシュ: 検証済みトークンやセッション情報を短い TTL 付きで保存し、認証基盤への問い合わせ回数を削減
• 静的コンテンツのルーティング: URL パスとコンテンツ本体・メタデータの対応を KV に保持し、Worker がエッジで直接応答
• 書き込み頻度を抑える設計: 更新が多いデータはバッチ化・集約してから書き込み、同一キーへの連続更新を避ける
• 大きなデータは分離: 値そのものが大きい場合は R2 などに実体を置き、KV にはメタデータや参照キーだけを保存する

運用・監視

• Cloudflare ダッシュボードや Workers のログ・メトリクスから、KV へのリクエスト数やエラー状況を確認できる
• ネームスペース単位でキー数や利用状況を把握し、不要になったネームスペース・キーは整理する
• TTL を活用して不要データを自動的に失効させ、手動でのクリーンアップ作業を減らす
• 書き込みが反映されるまでの遅延を前提に、アプリ側で「古い値を読む可能性がある」ことを踏まえた設計・監視をする

コスト

読み取り回数・書き込み回数・保存量に応じた従量課金が基本モデルです。読み取りが中心のワークロードほど KV は費用対効果が高くなります。

セキュリティ

• KV 自体には直接のパブリックエンドポイントはなく、Worker のコードを経由してのみアクセスされるため、アクセス制御は Worker 側のロジックと Cloudflare のアカウント権限管理に依存する
• ネームスペースへのアクセスは Worker のバインディング設定で明示的に許可されたものだけが可能
• 機密情報（パスワードや秘密鍵そのもの）を保存する用途には向かず、そうした値は専用のシークレット管理の仕組みを使う
• アカウントレベルの権限管理で、誰がネームスペースを作成・削除・編集できるかを最小権限の原則で制御する

関連サービス・比較

強い整合性やトランザクション的な処理が必要な場合は Durable Objects、大容量ファイルの保存には R2 が適しています。用途に応じて使い分けます。

ハンズオン / CLI例

# KV ネームスペースを作成
wrangler kv namespace create "MY_CONFIG"

# キーに値を書き込む
wrangler kv key put --namespace-id=<namespace-id> "feature-flag" "enabled"

# キーの値を読み取る
wrangler kv key get --namespace-id=<namespace-id> "feature-flag"

# ネームスペース内のキー一覧を取得
wrangler kv key list --namespace-id=<namespace-id>

# キーを削除
wrangler kv key delete --namespace-id=<namespace-id> "feature-flag"