Manage secrets with Pulumi ESC

In this tutorial, you will receive step-by-step instructions on using Pulumi ESC (Environments, Secrets, and Configuration), which is a secure and robust secrets management solution.

The tutorial will walk you through how to develop with Wrangler while following security best practices.

Specifically, you will learn how to manage your CLOUDFLARE_API_TOKEN for logging in to your Cloudflare account, pass ESC-stored secrets to Workers, and programmatically load your .dev.vars file.

Note

You will provision resources that qualify under free tier offerings for both Pulumi Cloud and Cloudflare.

Before you begin

Ensure you have:

• A Cloudflare account. Sign up for a Cloudflare account ↗.
• A Pulumi Cloud account. Sign up for a Pulumi Cloud ↗.
• The Pulumi ESC CLI ↗ installed.
• A Wrangler project. To create one, follow the Create a New Worker project step.

Set up a new Environment

A Pulumi ESC Environment ↗, or Environment, is a YAML file containing configurations and secrets for your application and infrastructure. These can be accessed in several ways, including shell commands. All ESC Environments reside in your Pulumi Cloud account.

a. Log in to Pulumi Cloud

Use the Pulumi ESC CLI to log into your Pulumi Cloud account.

esc login

Logged in to pulumi.com as  ....

b. Create a new Environment

Note

Environment names must be unique within a Pulumi organization and may only contain alphanumeric characters, hyphens, underscores, and periods.

ESC_ENV=my-dev-environment
esc env init $ESC_ENV

Environment created.

Log into Cloudflare

Now that the Pulumi ESC Environment has been created, it can be consumed in various ways. For instance, to log into your Cloudflare account without needing to predefine credentials in your shell.

a. Add your credentials

By externally and securely storing your CLOUDFLARE_API_TOKEN, you can control access and rotate the token value. We will run wrangler in non-interactive mode, which requires:

• Your Cloudflare account ID
• A valid Cloudflare API token

Replace the placeholder 123abc with your corresponding values:

esc env set $ESC_ENV environmentVariables.CLOUDFLARE_ACCOUNT_ID 123abc
esc env set $ESC_ENV environmentVariables.CLOUDFLARE_API_TOKEN  123abc --secret

Note

The API token is declared as a secret. Once the Environment is saved, Pulumi will encrypt its value and replace it with ciphertext.

a. Log out

Ensure you’re not currently logged in to your Cloudflare account.

npx wrangler logout

Not logged in, exiting...

a. Log in

Pass ESC-stored Cloudflare credentials to Wrangler.

esc run ${ESC_ENV} npx wrangler whoami

Getting User settings...
👋 You are logged in with an API Token.

When you use the esc run command, it opens the Environment and sets the specified Environment variables into a temporary environment. After that, it uses those variables in the context of the wrangler command. This is especially helpful when running wrangler commands in a CI/CD environment but wanting to avoid storing credentials directly in your pipeline.

Add Worker secrets

Pulumi ESC centralizes secrets, and Wrangler can be used to pass them on to Workers and other Cloudflare resources. You will use the wrangler secret put command for this purpose.

a. Add a secret

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

b. Pass the secret to your Worker

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

By using an external secrets management solution, commonly used Worker secrets can be stored in a single shared Environment that is accessed by the relevant Workers. You can use shell commands with esc to incorporate scripting and integrate them into deployment pipelines or make commands. Use esc [command] --help for more information about the various commands available in the CLI.

Load .dev.vars

In this step, you will configure an Environment to load your .dev.vars file programmatically.

Note

The .dev.vars file is located in the root of your Wrangler project to define secrets used when running wrangler dev. For more information, refer to Local Development with Secrets.

With a dedicated ESC Environment to store all the .dev.vars secrets, you can use a dotenv export flag.

a. Create an Environment

E=my-devvars
esc env init $E

Environment created.

b. Add a secret

esc env set $E environmentVariables.TOP_SECRET  "the moon is made of cheese" --secret

c. Generate the .dev.vars file

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

As .dev.vars files may often contain secrets, they should not be committed to source control. Keeping these secrets externally ensures you can load them to a new development environment without any loss.

Next steps

You have configured Pulumi ESC Environments to load secrets for Wrangler commands, enhancing security during development with Wrangler. The externalized secrets are now reusable across Workers. Learn more about Pulumi ESC features and integrations ↗ or follow the Deploy a Worker with Pulumi tutorial.