Cloudflare Workers KVの旧REST API経路は、2026年10月15日に停止する。移行自体は/workers/namespaces/を/storage/kv/namespaces/へ変える直接置換で、request parametersとresponse payloadは同じと案内されている。ただし、簡単な変更であるほど依存箇所の見落としが主な障害になる。SDKの内部実装ではなくURLを直書きした箇所を、コード以外も含めて期限前に洗い出す必要がある。

何が変わったか

/accounts/{account_id}/workers/namespaces/*配下のlegacy routesが2026年7月15日に非推奨となり、10月15日に停止する。置換先は/accounts/{account_id}/storage/kv/namespaces/*で、namespace一覧・作成、namespace詳細、key一覧、metadata、valueの各操作が対象となる。

変更前後の差

旧経路と新経路は同じparametersとpayloadを扱うため、データ移行やschema変換は不要である。差はURL pathに集中する。しかし、API gatewayのallowlist、モックサーバー、監視のendpoint名、Terraform以外の独自IaC、手順書のcurl例などは自動的に更新されない。

誰に影響するか

Cloudflare公式SDKやWranglerだけを使い、内部で新経路へ追随している環境は直接影響が小さい可能性がある。一方、REST APIを直接呼ぶ社内CLI、GitHub Actions、バックアップ、namespace棚卸し、key一括投入、監査収集は確認が必要である。vendor SDKをforkしている場合も固定URLを検索する。

期限

停止日は2026年10月15日である。期限当日に置換するのではなく、少なくとも本番と同じ権限・件数で読み書きを検証し、旧経路の呼び出しがゼロになった期間を確保する。

必要な対応

文字列検索だけでなく、HTTP trace、proxy log、Cloudflare API利用メトリクスから旧pathを確認する。read系を先に移行し、namespace作成・削除、bulk writeなど変更系はdry-runと対象制限を付けて確認する。利用しているAPI tokenの権限は変わらない想定でも、実際の401・403を検証する。

実装・移行手順

  1. 全リポジトリ、CI変数、runbook、監視設定で/workers/namespaces/を検索する
  2. 呼び出し元、method、頻度、変更系か読取系かを一覧化する
  3. 共通API clientのbase pathを新経路へ変更する
  4. namespace一覧、key一覧、metadata、value GETを比較する
  5. 検証namespaceでPUT、POST、DELETEを実行する
  6. 旧経路の利用logを監視し、ゼロを確認する
  7. 期限前に旧経路をテストで拒否し、残存依存を検出する

失敗しやすい点

本体コードだけを検索し、CIのshell、サンプル、運用端末、外部ジョブを見落とすことが多い。URL置換後にmock fixtureが旧pathのままで、テストが実通信と異なる場合もある。workersという単語を広く置換せず、対象pathを限定する。

リスク

期限後は管理APIが失敗し、アプリのKV binding自体が動いていても、デプロイ時のnamespace作成、設定同期、緊急復旧が止まる可能性がある。変更系のテストで本番namespaceを誤って削除するリスクもあるため、専用検証資源とtokenを使う。

評価方法

  • 旧pathを含むコード・設定件数
  • 旧pathの実通信件数
  • 新旧GET結果の一致率
  • 変更系試験の成功率
  • 401・403・404・429の発生数
  • rollback所要時間

ロールバック

10月15日まではclientのbase pathを設定で旧経路へ戻せるが、停止後はrollback先にならない。したがって本質的なrollbackはコード変更の取消ではなく、新経路clientの安定版へ戻すことになる。移行branchを小さく保ち、API操作の前後スナップショットを保存する。

編集部分析

payload互換のdeprecationは実装難度が低い一方、優先順位を下げられやすい。停止時に問題となるのは日常リクエストより、障害時だけ使う復旧スクリプトである。実行頻度の低い管理経路ほど、通信logではなく資産台帳と演習で確認すべきである。

実務チェックリスト

  • [ ] 旧pathをコード・CI・手順書から検索した
  • [ ] 共通clientで新pathへ集約した
  • [ ] read系の新旧結果を比較した
  • [ ] 変更系を検証namespaceで試した
  • [ ] 旧path通信がゼロになった
  • [ ] 2026年10月15日より前に移行を完了する

一次情報