コンテンツにスキップ
個人開発者のための Cloudflare CLI 完全攻略ガイド

第20章: Gradual Rollouts（段階的カナリアリリース）（実践チュートリアル）

コードを本番へデプロイした瞬間、全ユーザーへ100%反映される運用は、未知のバグや高負荷エラーが発生した際のリスクが極めて高くなります。 Cloudflare Workersの Gradual Rollouts（段階的ロールアウト） を使えば、「10%のリクエストだけ新バージョンに流してエラー率を監視し、安全を確認してから100%に昇格させる」 という安全なリリース戦略をCLIから実現できます。

本チュートリアルのゴール

  1. wrangler versions upload: 即時公開せずに新バージョンをクラウドへステージング
  2. wrangler versions deploy: トラフィックのパーセンテージ配分（例: 90% / 10%）
  3. wrangler tail: カナリアバージョンでエラーが発生していないかリアルタイム監視
  4. 100%昇格 または 1秒での安全な切り戻し（ロールバック）
【カナリアリリースの流れ】
[ 全世界のリクエスト (100%) ]
      ├── 90% ──> [ バージョン 1 (安定版) ]
      └── 10% ──> [ バージョン 2 (新機能テスト版) ]
           │
           ├── エラーなし ──> 100%へ昇格！
           └── 異常検知   ──> 1秒でバージョン1へ100%巻き戻し！

Step 1: 初期バージョン（v1）のデプロイ

まずは現在稼働中の安定バージョンを作成・デプロイします。

// src/index.ts (バージョン1)
export default {
  async fetch(req: Request): Promise<Response> {
    return new Response(JSON.stringify({ version: 'v1.0.0', status: 'stable' }), {
      headers: { 'Content-Type': 'application/json' },
    });
  }
};
Terminal window
# 通常デプロイでv1を稼働
npx wrangler deploy

Step 2: 新機能バージョン（v2）のアップロード（非公開）

コードに新機能を追加します。

// src/index.ts (バージョン2)
export default {
  async fetch(req: Request): Promise<Response> {
    return new Response(JSON.stringify({
      version: 'v2.0.0-canary',
      status: 'testing',
      newFeature: '高速レスポンスエンジン'
    }), {
      headers: { 'Content-Type': 'application/json' },
    });
  }
};

ここで wrangler deploy ではなく、wrangler versions upload を実行します。

Terminal window
npx wrangler versions upload --message "v2.0.0 カナリア検証版"

出力例:

Uploaded version 4a8b7c6d-1111-2222-3333-444455556666
Message: v2.0.0 カナリア検証版
Version is not currently receiving traffic.

新バージョンのIDが発行されましたが、まだトラフィックは1滴も流れていません。

Step 3: トラフィックの割合配分（カナリアリリース開始）

現在稼働中のバージョン一覧を確認します。

Terminal window
npx wrangler versions list

出力された2つのバージョンIDを使って、トラフィックを「旧版90% / 新版10%」に分割します。

Terminal window
npx wrangler versions deploy \
  <OLD_VERSION_ID>@90% \
  <NEW_VERSION_ID>@10%

出力例:

Deploying versions:
  - <OLD_VERSION_ID> (90%)
  - <NEW_VERSION_ID> (10%)
✨ Successfully deployed!

Step 4: 動作検証（curlでリクエストを連打）

ループで10回リクエストを投げてみます。

Terminal window
for i in {1..10}; do curl -s https://my-worker.xxxx.workers.dev; echo ""; done

結果:

{"version":"v1.0.0","status":"stable"}
{"version":"v1.0.0","status":"stable"}
{"version":"v2.0.0-canary","status":"testing","newFeature":"高速レスポンスエンジン"}
{"version":"v1.0.0","status":"stable"}
...

約10回に1回の割合で新バージョンが応答し、大半のユーザーは旧安定版にアクセスしていることが確認できます。

Step 5: 昇格またはロールバックの実行

パターンA: 動作良好のため100%へ完全移行

Terminal window
npx wrangler versions deploy <NEW_VERSION_ID>@100%

パターンB: エラーを検知したため直ちにロールバック

Terminal window
npx wrangler versions deploy <OLD_VERSION_ID>@100%

Gitのrevertコミットや再ビルドを待つことなく、コマンド1発・約1秒で安全に旧バージョンへ戻すことができます。

まとめ

  • wrangler versions upload: リリース前の事前検証用アップロード。
  • パーセンテージ指定: 1%〜99%の任意の割合でリスクを抑えて本番検証。
  • エンタープライズ品質: 個人開発でもダウンタイム・事故リスクゼロの運用が実現。

💡 用語解説コラム

[!NOTE] カナリアリリース (Canary Release)
炭鉱のカナリアに由来するデプロイ手法。全体に公開する前に一部のユーザー（例: 5%〜10%）にだけ新機能を先行配信し、重大なバグがないか安全確認します。