バージョンの上書き

バージョンの上書き（version overrides）を使うと、現在のデプロイに含まれる Worker の特定バージョンへリクエストを送れます。トラフィックが 0% のバージョンも対象です。

リクエストでバージョンの上書きを指定するには、Worker へのリクエストに Cloudflare-Workers-Version-Overrides ヘッダーを付けます。Cloudflare-Workers-Version-Overrides は Dictionary Structured Header ↗ で、複数のキーと値のペアを含められます。各 キー は、上書きを適用する Worker の名前です。値 は使うバージョン ID で、String ↗ である必要があります。例:

curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker-name="dc8dcd28-271b-4367-9840-6c244f84cb40"'

リクエストのバージョン上書きが適用されない理由はいくつかあります。例:

• デプロイに、指定したバージョンが含まれていない場合があります。直近の変更後、グローバルに利用できるようになるまで数秒かかることがあります。
• ヘッダーの値が、有効な Dictionary ↗ ではない場合があります。

バージョンの上書きが適用されない場合、リクエストは段階的デプロイの設定どおり、割合に従ってルーティングされます。

呼び出された Worker のバージョンは、Observability ↗ で確認できます。Logpush などでも確認できます。クライアントへ実行バージョンを伝えたい場合（デバッグを速く、分かりやすくするためなど）は、version metadata バインディング を使い、Worker の応答にバージョン ID を返せます。

外部トラフィックの割合を段階的に上げる前に、本番で新しいバージョンを試したいことがあります。これは一般に「スモークテスト（smoke test）」と呼ばれます。

この例では、最初はすべてのトラフィックを 1 つのバージョンへ向けるデプロイです。

wrangler versions deploy で新しいデプロイを作成し、前のバージョンを 100% のまま、新しいバージョンを 0% にします。

新しいバージョンを 100% まで段階的に上げる前に、バージョンの上書きでテストします。

curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker-name="dc8dcd28-271b-4367-9840-6c244f84cb40"'

サービスバインディング を使い、ある Worker から別の Worker へサブリクエストを送るときも、Cloudflare-Workers-Version-Overrides ヘッダーを設定できます。上流の Worker から、下流の Worker の特定バージョンをテストできます。

元のリクエストオブジェクトを転送すると、上書きヘッダーは自動で引き継がれます。

// The override header from the inbound request is forwarded to the downstream Worker.
export default {
	async fetch(request, env) {
		return env.MY_SERVICE.fetch(request);
	},
};

// The override header from the inbound request is forwarded to the downstream Worker.
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		return env.MY_SERVICE.fetch(request);
	},
};

上書きヘッダーを明示的に設定することもできます。

// Replace the version ID with the target version from `wrangler versions list`.
export default {
	async fetch(request, env) {
		const response = await env.MY_SERVICE.fetch("https://example.com/", {
			headers: {
				"Cloudflare-Workers-Version-Overrides":
					'my-downstream-worker="dc8dcd28-271b-4367-9840-6c244f84cb40"',
			},
		});
		return response;
	},
};

// Replace the version ID with the target version from `wrangler versions list`.
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const response = await env.MY_SERVICE.fetch("https://example.com/", {
			headers: {
				"Cloudflare-Workers-Version-Overrides":
					'my-downstream-worker="dc8dcd28-271b-4367-9840-6c244f84cb40"',
			},
		});
		return response;
	},
};

• Version affinity — Cookie とヘッダーを使い、段階的デプロイ中にユーザーを特定バージョンへ固定します。
• 段階的デプロイ — 割合によるトラフィック分割の仕組みを説明します。
• サービスバインディング — Worker 同士の通信方法です。
• version metadata バインディング — Worker 内からバージョン ID とタグにアクセスします。