Cloudflare Worker のリリースとロールバックを管理する

はじめに

サポート可用性エンドポイントは、新しいリリースが 503 を返し始めるまで正常に動作していました。この実験では、使い捨ての Worker を 2 つのバージョンで公開し、アクティブなバージョンを特定して、正常なリリースを復元します。アップロード成功のメッセージだけを信用せず、実際の HTTP の動作と Cloudflare のデプロイメントメタデータを比較します。

ローカルでの Wrangler 開発、アカウント認証、デプロイメントについて、すでに理解していることを前提とします。この新しい VM では、自分の学習用アカウントを使って開始してください。以前の VM や Worker は再利用しません。セットアップでは Node.js 22.22.0 とプロジェクトローカルの Wrangler 4.131.1 をインストールし、2 つの小さな合成ハンドラー用フィクスチャを用意します。ドメイン、ストレージサービス、シークレットは必要ありません。すべてのデプロイメントとクリーンアップ操作を自分で実行します。

バージョンは、変更できないコードと設定のスナップショットです。デプロイメントによって、どのバージョンにトラフィックを送るかを選択します。ロールバックでは、既存のバージョンを使って新しいデプロイメントを作成します。ローカルのソースを書き換えたり、バインドされたリソースのデータを復元したりする操作ではありません。詳しくは、公式のバージョン概要を参照してください。

正常なリリースを準備する

このステップでは、正常なエントリーポイントを準備し、ローカルでの動作を確認します。用意されたフィクスチャにより、リリース操作に集中できます。正常なハンドラーは available=true を返します。不具合のあるハンドラーはヘルスチェックを正常に保ちながら、ビジネス用のルートでは 503 を返します。

cd /home/labex/project/release-recovery

cat versions/good.js

diff -u versions/good.js versions/faulty.js

ファイルの内容が異なるため、diff は終了コード 1 で終了します。これは想定どおりです。変わるのは可用性の値と HTTP ステータスだけです。正常なフィクスチャをコピーすると、設定で指定されたソースファイルが選択されます。

cp versions/good.js src/index.js

Node の標準 crypto API を使って、一意な名前を生成します。下記の引用符で囲まれていない EOF 区切り文字では、シェル変数が JSON に展開されます。このファイルにはコメントがないため、標準の JSON リーダーでも読み取れます。

WORKER_NAME="labex-release-$(node -p "require('node:crypto').randomBytes(6).toString('hex')")"

cat > wrangler.jsonc <<EOF
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-07-30",
  "workers_dev": true,
  "preview_urls": false,
  "version_metadata": {"binding": "RELEASE"}
}
EOF

バージョンメタデータのバインディングによって、ランタイムのバージョン ID とタグが提供されます。ローカル開発ではローカルメタデータが使われます。クラウド上のバージョンを識別できるのは、デプロイ済みのメタデータだけです。このバインディングの詳細はこちらで確認できます。

& を使ってローカルサーバーをバックグラウンドで起動し、出力を dev.log にリダイレクトします。リクエストを送る前に、Ready と表示されるまで待ちます。

npx wrangler dev --ip 0.0.0.0 --port 8080 > dev.log 2>&1 &

cat dev.log

curl -i http://127.0.0.1:8080/health

curl -i http://127.0.0.1:8080/api/availability

両方のルートは 200 を返し、availability は true になるはずです。ローカルのバージョンやタグの値は、開発用のプレースホルダーになる場合があります。次のステップで開発ジョブを停止する前に、検証を実行してください。

正常なバージョンをデプロイして記録する

このステップでは、正常なソースを学習用アカウントにデプロイし、実際のバージョンを記録します。ローカルジョブを停止します。必要に応じて、現在のジョブ番号に置き換えてください。

jobs

kill %1

npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read

表示されたデバイスリンクをブラウザーで開き、コードを入力して、使用する学習用アカウントを認証します。認証情報はログインフロー内で入力してください。標準のアカウント出力を読み、アカウントが 1 つしか表示されない場合でも、その名前を確認します。

npx wrangler whoami --json

下記の YOUR_ACCOUNT_ID を、そのアカウントの実際の ID に置き換えます。この標準的な Node コマンドは、プロジェクト設定を明示的に更新します。一時的な環境変数でアカウントを選択するわけではありません。

node -e 'const fs=require("node:fs");const p="wrangler.jsonc";const c=JSON.parse(fs.readFileSync(p));c.account_id="YOUR_ACCOUNT_ID";fs.writeFileSync(p,JSON.stringify(c,null,2)+"\n");'

cat wrangler.jsonc

タグは読みやすいラベルであり、バージョン UUID が正確な識別子です。デプロイによってバージョンがアップロードされ、そのバージョンにトラフィックが送られます。メッセージには、そのバージョンの目的を記録します。

npx wrangler deploy --tag good --message "Known-good availability"

表示された workers.dev URL と Current Version ID をコピーし、次のコマンドに入力します。これらは例示用のプレースホルダーであり、固定された共有リソースではありません。このアカウントに workers.dev サブドメインがない場合は、Deploy Your First Cloudflare Worker の初回セットアップに従ってから、デプロイをもう一度実行します。

APP_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"

printf '%s\n' "YOUR_GOOD_VERSION_ID" > good-version.txt

curl -i "$APP_URL/api/availability"

npx wrangler deployments status

npx wrangler versions list

レスポンスでは、200、available=true、tag=good、および記録したバージョン UUID が表示されるはずです。アクティブなデプロイメントでは、そのバージョンに 100% のトラフィックが割り当てられている必要があります。Dashboard でこの Worker を正確に開き、Deployments を確認して、CLI に表示されたバージョンとアクティブなデプロイメントを画面上のリソースと対応付けます。デプロイ直後でレスポンスが以前の状態を示している場合は、5 秒待って読み取りを繰り返します。ただし、繰り返しは最大 1 分間に限定し、伝播の遅延を隠すためにコードを変更しないでください。観察結果が一致したら、検証を実行します。

不具合のあるリリースを確認する

このステップでは、使い捨ての Worker で制御されたリリース回帰を再現します。ヘルスチェック用のエンドポイントが正常でも、ビジネス用のルートが正常に動作するとは限りません。エントリーポイントを不具合のあるフィクスチャに置き換え、別のタグ付きバージョンを公開します。

cp versions/faulty.js src/index.js

npx wrangler deploy --tag faulty --message "Demonstrate availability regression"

このデプロイメントの新しい Current Version ID を保存します。正常なバージョンの ID ではありません。両方のルートと現在のデプロイメントを確認します。

printf '%s\n' "YOUR_FAULTY_VERSION_ID" > faulty-version.txt

curl -i "$APP_URL/health"

curl -i "$APP_URL/api/availability"

npx wrangler deployments status

npx wrangler versions list

ヘルスチェックは 200 のままです。可用性は 503、available=false、tag=faulty を返すようになります。ランタイム UUID は、100% のトラフィックを受け取る新しいアクティブバージョンと一致する必要があります。このステップでは 503 が意図した不具合であり、検証を省略する理由ではありません。伝播が進行中の場合は、同じく時間を限定したレスポンスの再確認を行います。独立したチェックでは、復旧前にこの不具合が観測できることが必要です。

Compute → Workers & Pages で、使用している正確な Worker を開き、Deployments を選択します。Active deployment の下にある ID と、Version History で faulty タグが付いた行を比較します。スクリーンショットでは UUID を短縮した例を使っています。コマンドでは保存した完全な UUID を使用してください。faulty バージョンがアクティブな間も、正常なバージョンは履歴に残ります。上記の wrangler deployments status を使って、設定された 100% のトラフィック割り当てを確認します。この静かなスクリーンショットに表示される活動量の 0 は、ビジネス用のルートが正常であることを証明しません。

不具合のあるバージョンがアクティブで、正常なバージョンが履歴に残っている状態

ロールバックしてローカルソースを整合させる

このステップでは、正確な正常バージョンを復元します。保存した ID を読み取り、トラフィックを変更する前に、選択する正常なバージョンを確認します。シェルのコマンド置換によってファイルから UUID を読み取ります。新しいバージョンをアップロードする操作ではありません。

cat good-version.txt faulty-version.txt

npx wrangler versions view "$(cat good-version.txt)"

正常なタグ、対象の Worker とアカウント、および UUID を確認します。ロールバックによって、この使い捨て Worker のトラフィックの 100% がそのバージョンに送られます。メッセージには復旧の理由を記録します。対象を確認してから、コマンドを実行してください。

npx wrangler rollback "$(cat good-version.txt)" --message "Restore known-good availability"

Wrangler がオプションのメッセージを尋ねたら、Enter キーを押して Restore known-good availability を受け入れます。表示された正常な UUID と、トラフィックの 100% の送信先を読みます。一致する確認画面で、キー y を 1 回だけ押します。ロールバック成功のメッセージが表示されるまで待ってから、次に進みます。

npx wrangler deployments status

curl -i "$APP_URL/api/availability"

新しいデプロイメントでは、元の正常なバージョン UUID が使われるはずです。ただし、元のデプロイメント ID である必要はありません。可用性は再び 200 と true を返します。Dashboard の Deployments タブを更新し、アクティブな UUID を比較します。必要に応じて、同じく 1 分間に限定したレスポンスの再確認を行ってください。

この例では、Active deployment が 7afe5d31 に戻っています。これは元の good バージョンと同じ短縮 ID です。Version History のアクティブマーカーもその行に移動し、不具合のあるバージョンは引き続き一覧に残っています。自分の ID を使って、これらの対応関係を確認してください。例の値をコピーしないでください。この画面では選択されたバージョンを確認し、可用性レスポンスでは動作が修復されたことを確認します。

ロールバック後に元の正常なバージョンが再びアクティブになり、不具合のあるバージョンが履歴に残っている状態

ロールバックしても、ローカルソースは変更されません。後で通常のデプロイを実行したときに既知の不具合を誤って再導入しないよう、ローカルでも正常なフィクスチャを復元します。dry-run では、ローカルソースをバンドルしますが、アップロードは行いません。

cp versions/good.js src/index.js

npx wrangler deploy --dry-run

検証を実行します。実際のランタイム UUID とタグを現在の 100% のデプロイメントと比較し、以前の不具合のあるデプロイメントが履歴に残っていることを確認します。ローカルで作成した成功ファイルだけでは不十分です。

ロールバックでは、データベース、キュー、外部 API への書き込みは取り消されません。また、バインドされたリソースの変更によって、古いバージョンとの互換性が失われる場合があります。この実験にはそのようなリソースはありません。実際のインシデントでは、復旧前にこれらの境界を確認してください。ロールバックのドキュメントでは、制限事項と保持されるバージョンの期間について説明しています。

リリース検証用 Worker を削除する

このステップでは、認証が有効なうちに使い捨ての Worker を削除します。削除する前に、正確な名前とアカウントを確認してください。

cat wrangler.jsonc

npx wrangler delete

名前が一致するプロンプトで、キー y を 1 回だけ押します。固定された Wrangler では、Worker の削除後に従来の KV クリーンアップに関する認証エラーが報告される場合があります。より広いスコープを付与したり、エラーが表示されたからといって削除に失敗したと判断したりしないでください。Dashboard を更新して検証を実行し、認証済みのインベントリにこの Worker が存在しないことを確認します。学習用アカウント、サブドメイン、関係のないリソースは残してください。

VM の接続を解除する

このステップでは、削除が完了した後に VM の接続を解除します。ログアウトするだけでは、デプロイ済みの Worker は削除されません。

npx wrangler logout

npx wrangler whoami --json

loggedIn=false になるはずです。現在は未認証のため、構造化コマンドはゼロ以外の終了コードで終了する場合があります。最後の検証を実行します。ブラウザーのログイン状態と学習用アカウントは、今後の独立した実験でも利用できます。

まとめ

Worker のバージョンとアクティブなデプロイメントを比較し、ヘルスチェックが正常であるにもかかわらずビジネス用のルートで回帰が発生することを確認し、選択した正常なバージョンを復元しました。ランタイムメタデータによって、実際のレスポンスと 100% のデプロイメントを対応付けました。また、ローカルソースを復元し、クラウド上のクリーンアップを検証して、VM の接続を解除しました。

リリースを管理し、変更をロールバックする