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.
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.
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.
Use the Pulumi ESC CLI to log into your Pulumi Cloud account.
esc loginLogged in to pulumi.com as ....ESC_ENV=wrangler/my-dev-environmentesc env init $ESC_ENVEnvironment created.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.
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 123abcesc env set $ESC_ENV environmentVariables.CLOUDFLARE_API_TOKEN 123abc --secretEnsure you're not currently logged in to your Cloudflare account.
npx wrangler logoutNot logged in, exiting...Pass ESC-stored Cloudflare credentials to Wrangler.
esc run ${ESC_ENV} npx wrangler whoamiGetting 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.
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.
esc env set ${ESC_ENV} environementVariables.TOP_SECRET "aliens are real" --secretesc 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.
In this step, you will configure an Environment to load your .dev.vars file programmatically.
With a dedicated ESC Environment to store all the .dev.vars secrets, you can use a dotenv export flag.
E=wrangler/my-devvarsesc env init $EEnvironment created.esc env set $E environmentVariables.TOP_SECRET "the moon is made of cheese" --secretesc env open ${E} --format dotenv > .dev.varsAs .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.
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.