はじめに
feature flag は、アプリケーションコードを変更せずに機能のオンとオフを切り替える設定です。新しい告知バナーを準備しているとします。練習環境では試したい一方で、公開版ではオフのままにしたいでしょう。Workers KV は、key と呼ばれる名前の下に小さな値を保存します。Worker は、返すレスポンスを決める必要があるときに、banner:new のようなキーを読み取れます。これは、頻繁に読み取られ、変更頻度が低い設定に適しています。
このコースを始める前に、LabEx を Cloudflare アカウントに接続するを完了してください。この実験では、LabEx VM のターミナル、デバイス認証、アカウント確認、account_id について説明します。このコースを直接開いた場合は、先にその実験を行ってください。また、Workers beginners course の内容に沿って、小さな JavaScript Worker を作成し、Wrangler でデプロイする方法を知っている必要があります。Worker を使うと、サーバーを管理しなくても、Cloudflare 上でリクエスト処理コードを実行できます。
ここでは、namespace を作成します。namespace は、1 つのキー集合を他の集合から分離して保持する名前付きコンテナです。binding を使って namespace を Worker に接続します。binding は、コードがそのリソースにアクセスするために使う設定済みの名前です。ローカル環境とクラウド環境での操作を練習し、読み取り専用のバナーエンドポイントを公開した後、使い捨てのリソースを削除します。
自分の学習用アカウントを使用してください。この新しい VM では、Workers と KV の権限を持つ独自のログインが必要です。この実験では、KV Free allowances の範囲内で、Worker 1 個、namespace 1 個、少数の合成値を使用します。この小規模な実験に購入済みドメインや有料アップグレードは必要ありません。既存のアカウント使用量は引き続き利用枠に加算されます。公開エンドポイントに個人情報は含まれません。
セットアップでは、Node.js 22.22.0 とプロジェクトローカルの Wrangler 4.131.1 を /home/labex/project/feature-flags にインストールします。直接依存するパッケージのバージョンを固定して npm install を実行するため、ツールを再度インストールする必要はありません。クラウド側の削除とログアウトの確認が終わるまで、VM を開いたままにしてください。
専用のフラグ namespace に接続する
このステップでは、この実験専用のリソース名を作成し、クラウドの namespace をプロジェクトに接続します。namespace を分けることで、練習用のキーが既存アプリケーションのキーと混ざるのを防ぎます。
準備済みのプロジェクトに移動します。
cd /home/labex/project/feature-flags
一度だけ一意の名前を生成します。openssl rand -hex 6 はランダムなサフィックスを出力し、$(...) はその値を名前に挿入します。シェル変数に保存すると、このターミナルで続けて実行するコマンドから同じ名前を使えます。
WORKER_NAME="labex-flags-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
この VM を認証します。アカウント ID の読み取りに加えて、Workers Scripts Write はデプロイと削除を許可し、Workers KV Write はこの実験の namespace とキーの管理を許可します。
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
表示されたデバイスリンクをブラウザーで開き、現在のコードを入力します。要求された権限と学習用アカウントを確認し、Wrangler を認証してください。同意ページにはバックグラウンドアクセスが表示されることもあります。ターミナルに戻り、ログインが完了するまで待ちます。
同意ページで Developer Platform を展開し、要求された権限を次の例と比較してください。この実験には 2 つの write 権限が必要です。これらはフラグの読み取りだけでなく、リソース管理も許可します。
npx wrangler whoami --json
loggedIn: true と、学習用アカウントの name を確認します。アカウントが 1 つしか表示されない場合も確認してください。そのアカウントの id をコピーします。次の設定で YOUR_ACCOUNT_ID をその値に置き換えてから、コマンドを実行します。ここで使う cat のヒアドキュメントは、2 つの JSON 行の間にあるすべての内容をファイルへ書き込みます。> はファイルを置き換えます。引用符で囲まれていない区切り文字により、シェルは $WORKER_NAME を展開します。
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true
}
JSON
そのアカウントに namespace を作成します。namespace のタイトルには Worker の一意な名前を含めるため、後で対応するリソースを識別できます。--update-config=false を指定すると、binding の編集内容が自動的にファイルへ反映されず、自分で確認できます。
npx wrangler kv namespace create "$WORKER_NAME-flags" --update-config=false
出力には新しい namespace ID が含まれます。ID をコピーし、次の完全な設定内の YOUR_ACCOUNT_ID と YOUR_NAMESPACE_ID を置き換えます。FLAGS はコードから使う binding 名であり、ID は実際の Cloudflare リソースを識別します。
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"kv_namespaces": [
{ "binding": "FLAGS", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
この実験で作成した namespace のタイトルを探し、ID がファイル内の値と一致することを確認します。他の namespace が表示されても、そのままにしてください。この設定には、後続のコマンドが使用するアカウントとリソースが記録されています。binding は namespace への参照であり、データのコピーではありません。
ローカルとリモートのフラグを分離する
このステップでは、同じキーの下に異なる値を保存し、ローカルでの変更がクラウド側のデータに影響しないことを確認します。Local は、この LabEx VM 内のストレージを指します。Remote は、Cloudflare アカウント内の namespace を指します。Wrangler は binding を使ってストアを識別し、--local または --remote オプションで操作対象を選択します。
まず、公開機能を無効にします。
npx wrangler kv key put banner:new disabled --binding FLAGS --remote
同じ機能を VM のローカルストアで有効にします。
npx wrangler kv key put banner:new enabled --binding FLAGS --local
両方の値を読み取ります。put はキーに値を書き込み、get は値を取得します。banner:new のコロンは、関連するキーをまとめる命名規則です。ディレクトリを作成するものではありません。
--text を付けると、保存された値を UTF-8 テキストとしてデコードし、独立した行に表示します。
npx wrangler kv key get banner:new --binding FLAGS --local --text
enabled と表示されることを確認します。
npx wrangler kv key get banner:new --binding FLAGS --remote --text
disabled と表示されることを確認します。誤ってリモート側の値を変更した場合は、disabled を指定した put コマンドをもう一度実行してから、再度読み取ってください。プロジェクトフォルダーだけを見て、操作対象を判断しないでください。
次に、不要になったフラグを削除します。次のコマンドは、FLAGS に割り当てられた、この実験用の使い捨てリモート namespace だけに影響します。
npx wrangler kv key put banner:old retired --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
一覧には保存された値ではなく、banner:new や banner:old のようなキー名が表示されます。値が必要な場合は get を使用してください。
npx wrangler kv key delete banner:old --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --local
この時点で、両方の一覧には banner:new だけが含まれているはずです。2 つの値がまだ異なることを確認したい場合は、再度読み取ってください。キーを削除すると 1 件のエントリが削除されます。後で namespace を削除すると、コンテナ全体が削除されます。
KV は eventually consistent です。変更が他の場所での読み取りに反映されるまで、時間がかかる場合があります。Worker が一時的に以前の値や、以前は存在しなかったキーを認識することもあります。値を表示させるために、同じ値を何度も上書きしないでください。今回のような表示用フラグではこの遅延が問題になりませんが、即時のアクセス取り消しを判断する用途には適していません。動作については後の実験で確認します。ストレージモデルについては、how KV works を参照してください。
ローカル Worker からフラグを読み取る
このステップでは、保存した設定に応じてアプリケーションの動作を変えます。Worker は env.FLAGS を読み取ります。env には、設定済みのリソース binding が含まれています。get() は非同期処理なので、await を使って値が返るまで待ってから、返す内容を決めます。
ハンドラーを作成します。引用符で囲んだ JS 区切り文字により、シェル変数を展開せず、JavaScript をそのまま保持できます。
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
if (new URL(request.url).pathname !== "/banner") {
return new Response("Not found", { status: 404 });
}
const value = await env.FLAGS.get("banner:new");
return Response.json({
feature: "new-banner",
enabled: value === "enabled"
});
}
};
JS
存在しないキーを読み取ると null が返ります。"enabled" と厳密に比較することで、値がない場合や想定外の値の場合に、この任意のバナーをオフにできます。これは小さな 安全なデフォルト です。設定が指定されていなくても、アプリケーションは利用可能な状態を保ちます。これは接続エラーを隠すものではありません。接続エラーは、キーが存在しない場合とは別の問題です。
ローカル開発を開始します。--local により、ローカル binding を使ってこの VM 内で Worker を実行します。> local.log 2>&1 は出力とエラーをログへ送ります。& により、ターミナルで続けてコマンドを入力できます。$! はバックグラウンドプロセスの ID です。ここでは後でプロセスを停止できるように保存します。
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
ポート 8080 で準備完了を示すメッセージが表示されるまで待ちます。まだ起動中の場合は、続行する前にもう一度ログを読み取ってください。
curl -i http://127.0.0.1:8080/banner
curl -i はレスポンスヘッダーと本文を表示します。HTTP 200、JSON の Content-Type、そして次の内容が表示されることを確認します。
{"feature":"new-banner","enabled":true}
true はローカル KV ストアの値から得られたものです。開発サーバーを起動しただけでは、リモート側の disabled の値は VM にコピーされません。次の比較のため、サーバーは起動したままにしてください。
デプロイして公開レスポンスを比較する
このステップでは、同じコードを公開し、クラウドの namespace から値が読み取られることを確認します。デプロイでは Worker と binding 設定がアップロードされますが、ローカル KV エントリはアップロードされません。
npx wrangler deploy
デプロイの出力を確認します。Worker 名、FLAGS binding、公開 workers.dev アドレスを確認してください。実際のアドレスを下の設定に保存し、実行前に例の値を置き換えます。シェル変数を使うと、長い URL を何度も入力せずに済みます。
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/banner"
HTTP 200 と、次の内容が表示されることを確認します。
{"feature":"new-banner","enabled":false}
クラウド側の設定は disabled なので、公開レスポンスの値は false です。新しいホスト名にまだ接続できない場合は、少し待ってから再試行してください。レスポンスが古い値を返す場合は、リモートキーを一度確認し、値を急速に書き換えるのではなく、KV の反映を待ってください。ネットワークエラーはテストの成功を意味しません。
curl -i http://127.0.0.1:8080/banner
ローカルのレスポンスは引き続き true です。1 つのハンドラーと 2 つの分離されたデータストアがあります。ローカル開発では VM のデータを読み取り、デプロイ済みの Worker では binding が識別する namespace を読み取ります。
Cloudflare Dashboard で同じ学習用アカウントを選択し、Storage & databases → Workers KV を開きます。この実験の名前に一致する namespace を探し、そのキーを確認します。banner:new だけが残っており、リモート値が disabled であることを確認してください。次に Workers & Pages を開き、この実験の Worker を選択して Bindings ビューを確認します。FLAGS binding と、先ほど確認した namespace を比較してください。ここでは読み取りだけを行います。変更を加える場所は引き続きターミナルです。
namespace は Metrics タブで開きます。KV Pairs を選択して実際のエントリを確認してください。使用量の集計は書き込みより遅れて更新されることがあります。Workers & Pages に新しい Worker が表示されない場合は、Refresh をクリックします。Bindings では表まで下にスクロールし、binding 名と namespace を照合してください。
生成された名前、namespace ID、公開サブドメインは例とは異なります。Dashboard に namespace が表示されることは、その namespace の場所を確認するものです。HTTP レスポンスが成功することは、アプリケーションがその namespace を利用できることを確認するものです。
使い捨てのクラウドリソースを削除する
このステップでは、Wrangler の認証が有効なうちに 2 つのリソースを削除します。namespace は Worker より長く存在できるため、アプリケーションだけを削除しても、そのデータは削除されません。
このターミナルで開始したローカル開発プロセスを停止します。
kill "$DEV_PID"
削除する前に、保存されているリソース参照を確認します。
cat wrangler.jsonc
labex-flags-... という Worker 名と、FLAGS namespace ID を確認します。この設定で選択される Worker を削除します。
npx wrangler delete
確認を求められたら、表示された名前がこの実験のものと一致することを確認し、y で確定します。次に、FLAGS が参照する namespace だけを削除します。
npx wrangler kv namespace delete --binding FLAGS
確認プロンプトが表示されたら、対象 namespace を確認してから受け入れてください。独立したチェックが削除対象のリソースを特定できるように、wrangler.jsonc はそのまま残します。
npx wrangler kv namespace list
この実験で作成した namespace が表示されず、関係のない namespace は残っているはずです。Dashboard の一覧を更新し、この実験の Worker と namespace が消えていることを確認します。リクエストの失敗やログイン期限切れは、削除が成功した証拠にはなりません。ログアウトする前に、このステップのチェックを実行して、認証済みのインベントリを確認できるようにしてください。
VM の認証を終了する
このステップでは、クリーンアップのチェックが成功した後に Wrangler の接続を解除します。ログアウトすると、この VM に保存された Wrangler の認証が終了します。ただし、クラウドリソースが削除されたり、通常の Dashboard のブラウザーセッションからログアウトしたりするわけではありません。
npx wrangler logout
npx wrangler whoami --json
構造化された結果で "loggedIn": false と表示されることを確認します。この未認証のコマンドは、ここでは想定どおりゼロ以外の終了ステータスで終了する場合があります。接続エラーだけが表示され、認証状態が明示されない場合は、接続が回復してから再試行してください。
残っているローカルファイルとローカル KV の状態は、この使い捨て VM に属します。これらは、すでに削除したクラウドリソースとは別のものです。これで実験を終了できます。
まとめ
分離された KV namespace を作成し、binding を通して接続しました。また、local と remote を明示したコマンドでキーの書き込み、読み取り、一覧表示、削除を行いました。Worker は分離された 2 つのストアから同じキーを読み取り、ローカルのバナーは有効、公開バナーは無効のままになることを確認しました。さらに、フラグが存在しない場合の安全なデフォルトを使い、KV の更新を即時にグローバルへ反映されるスイッチとして扱ってはいけない理由を学びました。
最後に、公開レスポンスを確認し、認証が有効な状態で Worker と namespace を削除して、Wrangler からログアウトしました。次は、構造化された JSON 値を使って、機密性のないアカウント設定を提供します。
