Pulumi ESC: Integrate with Cloudflare

Overview

Pulumi ESC integrates with Cloudflare to help developers automatically manage configuration and secrets when running wrangler commands. Additionally, Pulumi ESC works with the Pulumi Cloudflare SDK to provide secrets to defined Cloudflare resources, such as Workers.

Manage secrets for Wrangler commands

Learn how to:

• Login to your Cloudflare account without having to locally set the CLOUDFLARE_API_TOKEN environment variable.
• Populate the .dev.vars file from ESC-stored secrets.
• Pass secrets stored in Pulumi ESC to your production Cloudflare Workers without these being directly in your shell.

Prerequisites

Ensure you have:

• installed Pulumi ESC
• installed Wrangler
• a valid and properly scoped Cloudflare API token
• a Pulumi Cloud account. You can sign up for an always-free, individual tier

1. Create an ESC Environment

Use the Pulumi ESC CLI to create and configure an Environment. Alternatively, to use the Pulumi Cloud console follow the console instructions.

esc login # if needed

## create a new ESC Environment
ESC_ENV=my-dev-environment
esc env init ${ESC_ENV}

Edit the Environment in your terminal:

esc env edit ${ESC_ENV}

Paste the contents below in the editor and replace the abc... API token and Account ID value with yours. Note: the API token is declared as a secret. Once the Environment is saved, Pulumi will encrypt its value and replace it with ciphertext.

values:
  environmentVariables:
    CLOUDFLARE_API_TOKEN:
      fn::secret: abc123abc123abc123abc123abc123
    CLOUDFLARE_ACCOUNT_ID: abc123abc123

Now that the Pulumi ESC Environment is created, it can be consumed in a variety of ways, such as running other shell commands without having to set the environment variables locally first.

The esc run command opens the Environment you previously created, sets the specified environment variables into a temporary environment, and then uses those environment variables in the context of the wrangler commands.

2. Use ESC with wrangler whoami

Log into your Cloudflare account without needing to manage the credentials directly in your shell:

# ensure you're currently not logged in
npx wrangler logout

# retrieve the esc environment and authenticate programmatically
esc run ${ESC_ENV} npx wrangler whoami

Because we are running wrangler in non-interactive mode, it requires a Cloudflare API token and account ID for authentication. The wrangler whoami retrieves details about the provided credentials.

For additional options and details, see esc run --help.

3. Use ESC to create your .dev.vars file

The .dev.vars file is located in the root of your wrangler project to define secrets used when running wrangler dev. Per Cloudflare documentation, the .dev.vars file should be formatted like a dotenv file.

Create a new ESC Environment:

ESC_ENV=my-dev-vars-environment
esc env init ${ESC_ENV}

Edit the environment in your terminal:

esc env edit ${ESC_ENV}

There are two options for managing the .dev.vars definition.

• Option 1: Utilize the --format export flag for flexibility. A dedicated Environment is required as the format flag does not support property paths Paste the contents below in the editor:

  values:
    environmentVariables:
      TOP_SECRET:
        fn::secret: "the moon is made of cheese"
  

  Generate the .dev.vars file:

  esc env open ${ESC_ENV} --format dotenv > .dev.vars
  

• Option 2: Use the files section to add a value. When the Environment is opened, the value is copied to a temporary file on your system, with the path set as an environment variable with the key name. Paste the contents below in the editor:

  values:
    environmentVariables:
      TOP_SECRET: "the moon is made of cheese"
    files: |
      DEV_VARS: TOP_SECRET=${environmentVariables.TOP_SECRET}    
  

  Generate the .dev.vars file:

  esc run -i ${ESC_ENV} -- sh -c 'cat $DEV_VARS > .dev.vars'
  

  For additional options and details, see esc run --help.

4. Use ESC with wrangler secret put

With Pulumi ESC you can centralize common secrets and then use Wrangler to pass them on to your Workers and other Cloudflare resources as needed:

Add a new value to your my-dev-environment Environment:

ESC_ENV=my-dev-environment
esc env set ${ESC_ENV} environementVariables.TOP_SECRET "aliens are real" --secret

Share the secret with your Worker.

esc run -i ${ESC_ENV} -- sh -c 'echo "$TOP_SECRET" | npx wrangler secret put TOP_SECRET'

Consume the secret in your Worker script. Here’s an example using TypeScript:

export interface Env {
  TOP_SECRET: string;
}
export default {
  async fetch(request, env, ctx): Promise<Response> {
    return new Response(`Did you know that "${env.TOP_SECRET}"?`);
  }
} satisfies ExportedHandler<Env>;

Using Infrastructure as Code (IaC) to manage Workers? See the next section to see how to leverage Pulumi ESC alongside.

Manage Cloudflare Worker Secrets in IaC

Pulumi ESC works hand-in-hand with Pulumi IaC to simplify configuration management.

Learn how to:

• Add an ESC Environment to your Pulumi stack
• Assign an ESC Secret to Cloudflare resources
• Consume the ESC Secret in a Worker script

Additional Prerequisites

In addition to the prerequisites above, ensure you have:

• installed Pulumi CLI
• installed a Pulumi-supported programming language

1. Create (or Modify) an ESC Environment

Use the Pulumi ESC CLI to create and configure an Environment. Alternatively, to use the Pulumi Cloud console follow the console instructions.

esc login # if needed

## create a new ESC Environment
ESC_ENV=my-pulumi-environment
esc env init ${ESC_ENV}

Paste the contents below in the editor and replace the abc... API token and Account ID value with yours. These values are to be consumed by a Pulumi program hence they are placed under the pulumiConfig section. See the syntax reference for more options.

values:
  pulumiConfig:
    CLOUDFLARE_API_TOKEN:
      fn::secret: abc123abc123abc123abc123abc123
    CLOUDFLARE_ACCOUNT_ID: abc123abc123
    TOP_SECRET:
      fn::secret: "aliens are real"

2. Add ESC to a Pulumi Stack

You’ll create a new stack to test the changes in isolation. Optionally, use an existing Stack.

Inside your Pulumi project directory, run:

pulumi stack init my-esc-stack
pulumi config env add ${ESC_ENV}

3. Assign an ESC Secret to a Worker Secret Binding

With the ESC Environment referenced in the Stack, you’ll be able to consume ESC values to assign them to a Secret Binding Input. Here is an example Pulumi program written in TypeScript:

import * as pulumi from "@pulumi/pulumi";
import * as cloudflare from "@pulumi/cloudflare";
import * as fs from "fs";

const config = new pulumi.Config();

// Create a Cloudflare WorkerScript with a secret binding
const workerScript = new cloudflare.WorkerScript("myWorkerScript", {
    name: "my-worker-script",
    content: fs.readFileSync("worker.ts", "utf8"),
    secretTextBindings: [
        {
            name: "TOP_SECRET",
            text: config.requireSecret("TOP_SECRET"),
        },
    ],
});

The secret binding configuration allows the Worker to consume the secret in the fetch handler. Here’s the contents of the worker.ts file.

export interface Env {
  TOP_SECRET: string;
}
export default {
  async fetch(request, env, ctx): Promise<Response> {
    return new Response(`Did you know that "${env.TOP_SECRET}"?`);
  }
}