Cloudflare Deployment

Darwinium is able to deploy its decisioning components as web workers at the routes defined in your Journey’s steps. Deployment can occur automatically when a build is pushed to your node’s git repo, or manually using Terraform or the Darwinium API.

This guide assumes that you have a Cloudflare account setup that is already providing CDN capabilities for the sites you wish Darwinium to protect, as well as a workers plan. Users of this guide are assumed to have knowledge of Cloudflare, and to have access to Cloudflare's dashboard (https://dash.cloudflare.com) with sufficient privileges to create new API tokens.

A typical Cloudflare deployment on a one-edge deployment device takes approximately 30 minutes to set up and validate under a standard configuration. Manual configuration involving terraform will take longer.

1. Enable Workers (Paid) on your Cloudflare Account

To ensure that Darwinium's workers are not subject to rate limiting, enable Cloudflare Workers (Paid) on your account.

In Cloudflare Dashboard:

1. In the left-hand sidebar, expand Compute and select Workers plans. (This was previously Workers & Pages > Plans.)
   

2. On the Workers plans page, select Paid and click Select plan.
3. Complete your payment details if not present already.
   

2. Get your organization’s Cloudflare Account ID, Zone ID

After setting up your site on Cloudflare, go to Domains > Overview and select the site you wish to deploy Darwinium onto.

On the zone Overview page, scroll to the bottom of the right-hand column to the API card. Your Zone ID and Account ID are both listed there, each with a copy button. Take note of both, as they will be needed later in the process.

Tip: the Account ID is also shown in the Account Details panel on Compute > Workers & Pages.

3. Create API tokens for Darwinium: Workers token

Two API tokens are required. One for Workers and another for KV Storage.

1. Click the person icon at the top right of the dashboard and select Profile.
   
2. In the left-hand navigation select API Tokens, then click Create Token.
   
3. In the API token templates list, click Use template next to Edit Cloudflare Workers.
   
   
4. Remove the permissions Darwinium does not need. The template now grants thirteen permissions by default. Delete every row except the five below, using the X button at the end of each row.
   

   Remove these eight: User Details (Read), Workers R2 Storage, Cloudflare Pages, Workers Builds Configuration, Workers Agents Configuration, Memberships (Read), Workers Observability, and Containers.

   Keep only these five:

   • Account: Workers KV Storage: Edit
   • Account: Workers Scripts: Edit
   • Zone: Workers Routes: Edit
   • Account: Account Settings: Read
   • Account: Workers Tail: Read

Your permissions list should end up looking like this:

5. Set Account Resources and Zone Resources to the account and zone(s) you are protecting. Optionally restrict Client IP Address Filtering.
6. Set a TTL for your token. This may vary depending on your organization’s security policy. Darwinium recommends setting a TTL between 6 months and 1 year.
   
7. Re-entering API tokens is your responsibility

   In order for the service to continue operating after the TTL, you will need to generate a new API key and enter it into darwinium’s settings

8. Click Continue to summary, then Create Token. Copy the token immediately — Cloudflare only displays it once.

Note: Cloudflare now shows a banner on this page recommending Account API Tokens instead of user-scoped tokens. A user token is deleted when that user is removed from the account, so consider an account token for production deployments.

4. Create API tokens for Darwinium: KV Storage token

Follow the same process as for Workers token above but permissions should be only set as

• Account: Workers KV Storage: Edit

5. Setup KV stores for Darwinium

KV stores are used to store Darwinium's critical state information at the edge. Darwinium requires 3 of these to work correctly. To set these up:

1. In the left-hand sidebar, expand Storage & databases and select Workers KV. (KV is no longer under the Workers menu.)
   
2. Click Create Instance at the top right.
   
3. Enter the namespace name and click Create.
   

   Repeat for all three:

   • DWN_LABEL
   • DWN_IDENT
   • DWN_DATA
4. Take note of the IDs of these 3 KVs - they will need to be entered into the darwinium cloudflare settings.

Note: Darwinium now stores the namespace IDs only, not their names. The names above still matter for your own identification in the Cloudflare dashboard, so keeping them is worth doing for supportability.

6. Enter configuration into Darwinium Node settings

In order to configure cloudflare settings for your node, you will need to be in a group that has permission to edit the given node's settings. This can be achieved by visiting the role management section of the administration section of the Darwinium portal.

1. Login to the darwinium portal, and select Administration > Nodes:
   
2. Select settings for the node you wish to configure:
   
3. Set CDN Vendor to Cloudflare, then enter the values you captured in steps 2-5.
   
   
   

   Portal field	Value to paste	Captured in
   Cloudflare Account - Worker > Account ID	your Cloudflare Account ID	step 2
   Cloudflare Account - Worker > API Token	the Workers token	step 3
   Cloudflare Account - KV Storage > Account Id	the same Account ID	step 2
   Cloudflare Account - KV Storage > API Token	the KV Storage token	step 4
   General Configuration > Zone ID	your Zone ID	step 2
   General Configuration > KV Namespace ID: Identities	ID of DWN_IDENT	step 5
   General Configuration > KV Namespace ID: Labels	ID of DWN_LABEL	step 5
   General Configuration > KV Namespace ID: Data	ID of DWN_DATA	step 5

   The KV Storage panel carries an in-product warning that its token should not have permission to deploy workers. That is the separate token created in step 4.

Declaring which hosts this target serves

Darwinium no longer asks you to list the hosts Cloudflare serves in the node settings. That mapping now lives in journeys.yaml in your git repo, which lets one node describe several targets — including a mix of CDN vendors — and map each to its own set of hosts.

Each entry under targets: carries a name, a type (the CDN vendor), an enabled flag, and a valid_host_list. Only hosts in the valid_host_list of a target whose type is cloudflare will be deployed as Cloudflare workers.

An entry in valid_host_list may be a hostname or an alias. Aliases are resolved per node under Node settings > Git / Journey Settings > Host Aliases, which lets the same journey configuration be promoted between environments while pointing at a different hostname in each.

See Hosts, Targets & Git Repo for the full reference.

7. Testing your Configuration

To test your deployment, it is recommended that you edit a journey, and create a step triggered by a GET request on one of your pages. Push this to your node's git repo and cloudflare deployment should commence shortly afterward.

See: Hosts, Targets & Git repo to make sure your node is ready for an Edge deployment.

You can confirm that routes have been set up for your journey's steps in two places. The clearest is the zone-level route list: select your site, then Workers Routes in the left-hand navigation. If deployment is successful, each route maps to a worker named after the journey step.

Alternatively, Compute > Workers & Pages lists every deployed worker with its route and recent request count.

8. Deployment when workers already exist

Darwinium accounts for when workers already exist on the routes it intends to deploy against.

When using Darwinium Deployment Manager, Darwinium will check all overlapping routes for the new ones intented to be deployed. The Darwinium worker does become the primary worker on the route, but it invokes the existing worker using service bindings. If a new deployment removes that Darwinium worker route, it looks at the service binding and repromotes the existing worker again.

When using webhook to manually deploy, those service bindings should be specified manually; see Controlling Darwinium Deployment and the example project.