diff --git a/src/content/docs/containers/examples/env-vars-and-secrets.mdx b/src/content/docs/containers/examples/env-vars-and-secrets.mdx
index 973b59f9cf1faf9..30f0b9e6390050b 100644
--- a/src/content/docs/containers/examples/env-vars-and-secrets.mdx
+++ b/src/content/docs/containers/examples/env-vars-and-secrets.mdx
@@ -16,17 +16,21 @@ Secrets can be passed into a Container by using [Worker Secrets](/workers/config
or the [Secret Store](/secrets-store/integrations/workers/), then passing them into the Container
as environment variables.
-These examples show the various ways to pass in secrets and environment variables. In each, we will
+KV values can be passed into a Container by using [Workers KV](/kv/), then reading
+the values and passing them into the Container as environment variables.
+
+These examples show the various ways to pass in secrets, KV values, and environment variables. In each, we will
be passing in:
- the variable `"ENV_VAR"` as a hard-coded environment variable
- the secret `"WORKER_SECRET"` as a secret from Worker Secrets
- the secret `"SECRET_STORE_SECRET"` as a secret from the Secret Store
+- the value `"KV_VALUE"` as a value from Workers KV
-In practice, you may just use one of the methods for storing secrets, but
-we will show both for completeness.
+In practice, you may just use one of the methods for storing secrets and data, but
+we will show all methods for completeness.
-## Creating secrets
+## Creating secrets and KV data
First, let's create the `"WORKER_SECRET"` secret in Worker Secrets:
@@ -47,12 +51,26 @@ the `"SECRET_STORE_SECRET"` secret to it:
args="secrets-store secret create demo --name SECRET_STORE_SECRET --scopes workers --remote"
/>
+Next, let's create a KV namespace called `DEMO_KV` and add a key-value pair:
+
+
+
+
+
For full details on how to create secrets, see the [Workers Secrets documentation](/workers/configuration/secrets/)
-and the [Secret Store documentation](/secrets-store/integrations/workers/).
+and the [Secret Store documentation](/secrets-store/integrations/workers/). For KV setup, see the [Workers KV documentation](/kv/).
-## Adding a secrets binding
+## Adding bindings
-Next, we need to add bindings to access our secrets and environment variables
+Next, we need to add bindings to access our secrets, KV values, and environment variables
in Wrangler configuration.
@@ -69,6 +87,12 @@ in Wrangler configuration.
"store_id": "demo",
"secret_name": "SECRET_STORE_SECRET"
}
+ ],
+ "kv_namespaces": [
+ {
+ "binding": "DEMO_KV",
+ "id": ""
+ }
]
// rest of the configuration...
}
@@ -79,8 +103,8 @@ in Wrangler configuration.
Note that `"WORKER_SECRET"` does not need to be specified in the Wrangler config file, as it is automatically
added to `env`.
-Also note that we did not configure anything specific for environment variables
-or secrets in the _container-related_ portion of the Wrangler configuration file.
+Also note that we did not configure anything specific for environment variables,
+secrets, or KV values in the _container-related_ portion of the Wrangler configuration file.
## Using `envVars` on the Container class
@@ -95,7 +119,7 @@ export class MyContainer extends Container {
envVars = {
WORKER_SECRET: env.WORKER_SECRET,
ENV_VAR: env.ENV_VAR,
- // we can't set the secret store binding as a default here, as getting the secret value is asynchronous
+ // we can't set the secret store binding or KV values as defaults here, as getting their values is asynchronous
};
}
```
@@ -129,6 +153,7 @@ export default {
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"),
},
},
});
@@ -136,9 +161,12 @@ export default {
await instanceTwo.startAndWaitForPorts({
startOptions: {
envVars: {
- ENV_VAR: env.ENV_VAR + "foo",
- WORKER_SECRET: env.ANOTHER_WORKER_SECRET,
- SECRET_STORE_SECRET: await env.OTHER_SECRET_STORE.get(),
+ 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"),
},
},
});
@@ -150,6 +178,70 @@ export default {
};
```
+## Reading KV values in containers
+
+KV values are particularly useful for configuration data that changes infrequently but needs to be accessible to your containers. Since KV operations are asynchronous, you must read the values at runtime when starting containers.
+
+Here are common patterns for using KV with containers:
+
+### Configuration data
+
+```js
+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");
+ }
+ },
+};
+```
+
+### Feature flags
+
+```js
+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");
+ }
+ },
+};
+```
+
## Build-time environment variables
Finally, you can also set build-time environment variables that are only available when building the container image via the `image_vars` field in the Wrangler configuration.