Cloudflare Workers KV

To setup a state store, create a component of type . See this guide on how to create and apply a state store configuration.

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

To use this component, you must have a Workers KV namespace created in your Cloudflare account.

You can create a new Workers KV namespace in one of two ways:

  • Using the
    Make note of the “ID” of the Workers KV namespace that you can see in the dashboard. This is a hex string (for example 123456789abcdef8b5588f3d134f74ac)–not the name you used when you created it!

  • Using the Wrangler CLI:

    1. # Authenticate if needed with `npx wrangler login` first
    2. wrangler kv:namespace create <NAME>

    The output contains the ID of the namespace, for example:

    1. { binding = "<NAME>", id = "123456789abcdef8b5588f3d134f74ac" }

Configuring the Worker

Dapr can manage the Worker for you automatically, or you can pre-provision a Worker yourself. Pre-provisioning the Worker is the only supported option when running on workerd.

Important

Use a separate Worker for each Dapr component. Do not use the same Worker script for different Cloudflare Workers KV state store components, and do not use the same Worker script for different Cloudflare components in Dapr (e.g. the Workers KV state store and the Queues binding).

If you want to let Dapr manage the Worker for you, you will need to provide these 3 metadata options:

  • cfAccountID: ID of your Cloudflare account. You can find this in your browser’s URL bar after logging into the Cloudflare dashboard, with the ID being the hex string right after dash.cloudflare.com. For example, if the URL is https://dash.cloudflare.com/456789abcdef8b5588f3d134f74acdef, the value for cfAccountID is 456789abcdef8b5588f3d134f74acdef.
  • cfAPIToken: API token with permission to create and edit Workers and Workers KV namespaces. You can create it from the in the “My Profile” section in the Cloudflare dashboard:
    1. Click on “Create token”.
    2. Select the “Edit Cloudflare Workers” template.
    3. Follow the on-screen instructions to generate a new API token.

When Dapr is configured to manage the Worker for you, when a Dapr Runtime is started it checks that the Worker exists and it’s up-to-date. If the Worker doesn’t exist, or if it’s using an outdated version, Dapr will create or upgrade it for you automatically.

If you’d rather not give Dapr permissions to deploy Worker scripts for you, you can manually provision a Worker for Dapr to use. Note that if you have multiple Dapr components that interact with Cloudflare services via a Worker, you will need to create a separate Worker for each one of them.

To manually provision a Worker script, you will need to have Node.js installed on your local machine.

  1. Create a new folder where you’ll place the source code of the Worker, for example: daprworker.
  2. If you haven’t already, authenticate with Wrangler (the Cloudflare Workers CLI) using: npx wrangler login.
  3. Inside the newly-created folder, create a new wrangler.toml file with the contents below, filling in the missing information as appropriate:
  1. Copy the (pre-compiled and minified) code of the Worker in the worker.js file. You can do that with this command:
  1. # Set this to the version of Dapr that you're using
  2. DAPR_VERSION="release-1.10"
  3. curl -LfO "https://raw.githubusercontent.com/dapr/components-contrib/${DAPR_VERSION}/internal/component/cloudflare/workers/code/worker.js"
  1. Deploy the Worker using Wrangler:

Once your Worker has been deployed, you will need to initialize the component with these two metadata options:

  • workerName: Name of the Worker script. This is the value you set in the name property in the wrangler.toml file.
  • workerUrl: URL of the deployed Worker. The npx wrangler command will show the full URL to you, for example https://mydaprkv.mydomain.workers.dev.
  • All requests made by Dapr to the Worker are authenticated via a bearer token (technically, a JWT) which is signed with an Ed25519 key.
  • The bearer token is generated on each request and is valid for a brief period of time only (currently, one minute).

To let Dapr issue bearer tokens, and have your Worker validate them, you will need to generate a new Ed25519 key pair. Here are examples of generating the key pair using OpenSSL or the step CLI.

You can generate a new Ed25519 key pair with OpenSSL using:

If you don’t have the step CLI already, install it following the .

Next, you can generate a new Ed25519 key pair with the step CLI using:

  1. step crypto keypair \
  2.   public.pem private.pem \
  3.   --kty OKP --curve Ed25519 \
  4.   --insecure --no-password

Regardless of how you generated your key pair, with the instructions above you’ll have two files:

  • private.pem contains the private part of the key; use the contents of this file for the key property of the component’s metadata.
  • contains the public part of the key, which you’ll need only if you’re deploying a Worker manually (as per the instructions in the previoius section).

Warning

Additional notes

  • Note that Cloudflare Workers KV doesn’t guarantee strong data consistency. Although changes are visible immediately (usually) for requests made to the same Cloudflare datacenter, it can take a certain amount of time (usually up to one minute) for changes to be replicated across all Cloudflare regions.
  • This state store supports TTLs with Dapr, but the minimum value for the TTL is 1 minute.