環境変数とシークレット

環境変数は、Container クラスの envVars フィールドで渡すか、Container の起動時に手動で設定できます。

シークレットは Worker Secrets または Secret Store を使い、環境変数として Container に渡せます。

KV の値は Workers KV を使い、値を読み取って環境変数として Container に渡せます。

次の例では、シークレット、KV の値、環境変数を渡す各方法を示します。いずれも次を渡します。

ハードコードした環境変数としての変数 "ENV_VAR"
Worker Secrets からのシークレット "WORKER_SECRET"
Secret Store からのシークレット "SECRET_STORE_SECRET"
Workers KV からの値 "KV_VALUE"

実務ではシークレットとデータの保存方法は 1 つに絞ることが多いですが、ここでは一通り示します。

シークレットと KV データを作成する

まず、Worker Secrets に "WORKER_SECRET" シークレットを作成します。

npx wrangler secret put WORKER_SECRET

yarn wrangler secret put WORKER_SECRET

pnpm wrangler secret put WORKER_SECRET

次に、Secret Store に "demo" というストアを作成し、"SECRET_STORE_SECRET" シークレットを追加します。

npx wrangler secrets-store store create demo --remote

yarn wrangler secrets-store store create demo --remote

pnpm wrangler secrets-store store create demo --remote

npx wrangler secrets-store secret create demo --name SECRET_STORE_SECRET --scopes workers --remote

yarn wrangler secrets-store secret create demo --name SECRET_STORE_SECRET --scopes workers --remote

pnpm wrangler secrets-store secret create demo --name SECRET_STORE_SECRET --scopes workers --remote

続いて、DEMO_KV という KV 名前空間を作成し、キーと値のペアを追加します。

npx wrangler kv namespace create DEMO_KV

yarn wrangler kv namespace create DEMO_KV

pnpm wrangler kv namespace create DEMO_KV

npx wrangler kv key put --binding DEMO_KV KV_VALUE 'Hello from KV!'

yarn wrangler kv key put --binding DEMO_KV KV_VALUE 'Hello from KV!'

pnpm wrangler kv key put --binding DEMO_KV KV_VALUE 'Hello from KV!'

シークレット作成の詳細は、Workers Secrets のドキュメントと Secret Store のドキュメントを参照してください。KV のセットアップは Workers KV のドキュメントを参照してください。

バインディングを追加する

次に、シークレット、KV の値、環境変数にアクセスするためのバインディングを Wrangler 設定に追加します。

{
	"name": "my-container-worker",
	"vars": {
		"ENV_VAR": "my-env-var"
	},
	"secrets_store_secrets": [
		{
			"binding": "SECRET_STORE",
			"store_id": "demo",
			"secret_name": "SECRET_STORE_SECRET"
		}
	],
	"kv_namespaces": [
		{
			"binding": "DEMO_KV",
			"id": "<your-kv-namespace-id>"
		}
	]
	// rest of the configuration...
}

name = "my-container-worker"

[vars]
ENV_VAR = "my-env-var"

[[secrets_store_secrets]]
binding = "SECRET_STORE"
store_id = "demo"
secret_name = "SECRET_STORE_SECRET"

[[kv_namespaces]]
binding = "DEMO_KV"
id = "<your-kv-namespace-id>"

"WORKER_SECRET" は env に自動で追加されるため、Wrangler 設定ファイルへの記載は不要です。

また、Wrangler 設定ファイルの コンテナ関連 の部分では、環境変数、シークレット、KV 値向けの特別な設定はしていません。

Container クラスの `envVars` を使う

次に、Container クラスの envVars フィールドで、環境変数とシークレットをコンテナに渡します。

// https://developers.cloudflare.com/workers/runtime-apis/bindings/#importing-env-as-a-global
import { env } from "cloudflare:workers";
export class MyContainer extends Container {
	defaultPort = 8080;
	sleepAfter = "10s";
	envVars = {
		WORKER_SECRET: env.WORKER_SECRET,
		ENV_VAR: env.ENV_VAR,
		// we can't set the secret store binding or KV values as defaults here, as getting their values is asynchronous
	};
}

この Container の各インスタンスは、起動時にこれらの変数とシークレットを環境変数として持ちます。

インスタンスごとに環境変数を設定する

インスタンスごとに環境変数を設定したい場合はどうすればよいでしょうか。

その場合は、startAndWaitForPorts() メソッドで、各インスタンスに環境変数を渡します。

export class MyContainer extends Container {
	defaultPort = 8080;
	sleepAfter = "10s";
}

export default {
	async fetch(request, env) {
		if (new URL(request.url).pathname === "/launch-instances") {
			let instanceOne = env.MY_CONTAINER.getByName("foo");
			let instanceTwo = env.MY_CONTAINER.getByName("bar");

			// Each instance gets a different set of environment variables

			await instanceOne.startAndWaitForPorts({
				startOptions: {
					envVars: {
						ENV_VAR: env.ENV_VAR + "foo",
						WORKER_SECRET: env.WORKER_SECRET,
						SECRET_STORE_SECRET: await env.SECRET_STORE.get(),
						KV_VALUE: await env.DEMO_KV.get("KV_VALUE"),
					},
				},
			});

			await instanceTwo.startAndWaitForPorts({
				startOptions: {
					envVars: {
						ENV_VAR: env.ENV_VAR + "bar",
						WORKER_SECRET: env.WORKER_SECRET,
						SECRET_STORE_SECRET: await env.SECRET_STORE.get(),
						KV_VALUE: await env.DEMO_KV.get("KV_VALUE"),
						// You can also read different KV keys for different instances
						INSTANCE_CONFIG: await env.DEMO_KV.get("instance-bar-config"),
					},
				},
			});
			return new Response("Container instances launched");
		}

		// ... etc ...
	},
};

コンテナで KV の値を読む

KV の値は、変更頻度は低いがコンテナから参照したい設定データに特に向いています。KV の操作は非同期なので、コンテナ起動時にランタイムで値を読む必要があります。

コンテナで KV を使うよくあるパターンは次のとおりです。

設定データ

export default {
	async fetch(request, env) {
		if (new URL(request.url).pathname === "/configure-container") {
			// Read configuration from KV
			const config = await env.DEMO_KV.get("container-config", "json");
			const apiUrl = await env.DEMO_KV.get("api-endpoint");

			let container = env.MY_CONTAINER.getByName("configured");

			await container.startAndWaitForPorts({
				startOptions: {
					envVars: {
						CONFIG_JSON: JSON.stringify(config),
						API_ENDPOINT: apiUrl,
						DEPLOYMENT_ENV: await env.DEMO_KV.get("deployment-env"),
					},
				},
			});

			return new Response("Container configured and launched");
		}
	},
};

フィーチャーフラグ

export default {
	async fetch(request, env) {
		if (new URL(request.url).pathname === "/launch-with-features") {
			// Read feature flags from KV
			const featureFlags = {
				ENABLE_FEATURE_A: await env.DEMO_KV.get("feature-a-enabled"),
				ENABLE_FEATURE_B: await env.DEMO_KV.get("feature-b-enabled"),
				DEBUG_MODE: await env.DEMO_KV.get("debug-enabled"),
			};

			let container = env.MY_CONTAINER.getByName("features");

			await container.startAndWaitForPorts({
				startOptions: {
					envVars: {
						...featureFlags,
						CONTAINER_VERSION: "1.2.3",
					},
				},
			});

			return new Response("Container launched with feature flags");
		}
	},
};

ビルド時の環境変数

最後に、Wrangler 設定の image_vars フィールドで、コンテナイメージのビルド時にだけ使えるビルド時環境変数も設定できます。