シークレット

シークレットは、暗号化されたテキスト値を Worker に付けるバインディングの一種です。API キーや認証トークンなどの機密情報の保存に使います。

Worker のコードからは、次の方法でシークレットにアクセスできます。

• Worker の fetch イベントハンドラー に渡される env パラメーター。
• cloudflare:workers から env をインポートし、コードの任意の場所からシークレットにアクセスする。
• Node.js 互換 を有効にした Worker では process.env。

シークレットは、ほかの 環境変数 と同じように Workers からアクセスできます。たとえば DB_CONNECTION_STRING シークレットがある場合、env パラメーター経由で Worker コードから使えます。

import postgres from "postgres";

export default {
	async fetch(request, env, ctx) {
		const sql = postgres(env.DB_CONNECTION_STRING);

		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

cloudflare:workers から env をインポートすれば、リクエストハンドラーの外を含む、コードの任意の場所からシークレットにアクセスできます。

import { env } from "cloudflare:workers";
import postgres from "postgres";

// Initialize the database client at the top level using a secret
const sql = postgres(env.DB_CONNECTION_STRING);

export default {
	async fetch(request) {
		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

import { env } from "cloudflare:workers";
import postgres from "postgres";

// Initialize the database client at the top level using a secret
const sql = postgres(env.DB_CONNECTION_STRING);

export default {
	async fetch(request: Request): Promise<Response> {
		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

env をグローバルに使う詳細は グローバルとして env をインポートする を参照してください。

ローカル開発で使うシークレットは、Wrangler 設定ファイルと同じディレクトリの .dev.vars または .env に置きます。

これらのファイルは dotenv ↗ の構文で記述します。例:

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

Cloudflare 環境ごとに異なるシークレットを設定するには、.dev.vars.<environment-name> または .env.<environment-name> という名前のファイルを作成します。

ローカル開発で Cloudflare 環境を選ぶと、対応する環境固有のファイルが、汎用の .dev.vars（または .env）より先に読み込まれます。

• .dev.vars.<environment-name> を使う場合、すべてのシークレットを環境ごとに定義する必要があります。.dev.vars.<environment-name> が存在すると、そのファイルだけが読み込まれ、.dev.vars は読み込まれません。
• 一方、一致する .env ファイルはすべて読み込まれ、値がマージされます。各変数には、もっとも具体的なファイルの値が使われます。優先順位は次のとおりです。
  • .env.<environment-name>.local（もっとも具体的）
  • .env.local
  • .env.<environment-name>
  • .env（もっとも汎用）

Worker が必要とするシークレット名は、Wrangler 設定の secrets 設定プロパティ で宣言できます。定義すると、必須シークレットが Worker に設定されていない場合、wrangler deploy と wrangler versions upload は分かりやすいエラーで失敗します。

シークレットは wrangler secret put または wrangler versions secret put コマンドで追加できます。

wrangler secret put は Worker の新しいバージョンを作成し、すぐにデプロイします。

npx wrangler secret put <KEY>

段階的デプロイ を使う場合は、代わりに wrangler versions secret put コマンドを使います。Worker の新しいバージョンだけが作成され、その後 wrangler versions deploy でデプロイできます。

npx wrangler versions secret put <KEY>

ダッシュボードからシークレットを追加するには、次の手順を実行します。

1. Cloudflare ダッシュボードで Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Overview で Worker を選び、Settings を開きます。

3. Variables and Secrets で Add を選びます。

4. 種類で Secret を選び、Variable name と Value を入力します。このシークレットは Worker から利用できますが、値は Wrangler とダッシュボードでは非表示になります。

5. （任意）シークレットを追加する場合は Add variable を選びます。

6. Deploy を選び、変更を反映します。

wrangler deploy または wrangler versions upload の --secrets-file フラグで、Worker コードと同時にシークレットをアップロードできます。JSON または .env ファイルのパスを受け取ります。形式は wrangler secret bulk と同じです。1 バージョンあたり、一括リクエストで最大 100 個のシークレットをアップロードできます。

npx wrangler deploy --secrets-file .env.production

npx wrangler versions upload --secrets-file secrets.json

ファイルに含まれないシークレットは、前のバージョンから保持されます。CI/CD パイプラインで、コードのデプロイとシークレットの更新を 1 回の操作で行いたい場合に便利です。

シークレットは wrangler secret delete または wrangler versions secret delete コマンドで削除できます。

wrangler secret delete は Worker の新しいバージョンを作成し、すぐにデプロイします。

npx wrangler secret delete <KEY>

段階的デプロイ を使う場合は、代わりに wrangler versions secret delete コマンドを使います。Worker の新しいバージョンだけが作成され、その後 wrangler versions deploy でデプロイできます。

npx wrangler versions secret delete <KEY>

ダッシュボードから Worker プロジェクトのシークレットを削除するには、次の手順を実行します。

1. Cloudflare ダッシュボードで Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Overview で Worker を選び、Settings を開きます。

3. Variables and Secrets で Edit を選びます。

4. Edit ドロワーで、削除するシークレットの横の X を選びます。

5. Deploy を選び、変更を反映します。

6. （任意）編集ドロワーの代わりに、シークレット横の削除アイコンをクリックすることもできます。

シークレット は 環境変数 です。違いは、定義したあと Wrangler や Cloudflare ダッシュボードではシークレットの値が表示されないことです。そのため、パスワードや API トークンなどの機密データは、漏洩を防ぐために常に暗号化する必要があります。Worker から見ると、環境変数とシークレットに違いはありません。シークレットの値は、定義したとおりに渡されます。

• Wrangler の secret コマンド — シークレットの作成、削除、一覧の Wrangler コマンドを確認します。
• secrets 設定プロパティ — Wrangler 設定で必須のシークレット名を宣言します。ローカル開発とデプロイ時の検証、および型生成の情報源になります。
• Cloudflare Secrets Store — 機密情報をシークレットとして暗号化して保存し、アカウント全体で安全に再利用します。