Get Started with Pulumi ESC

Pulumi ESC (Environments, Secrets, and Configuration) is a centralized secrets and configuration management service. In this quick start, you’ll create your first environment, store a secret, and retrieve it programmatically.

Prerequisites

1. Create a Pulumi account at app.pulumi.com
2. Install the ESC CLI

brew update && brew install pulumi/tap/esc

curl -fsSL https://get.pulumi.com/esc/install.sh | sh

See the ESC installation docs for more options.

Create your first environment

1. Log in to the ESC CLI:

esc login

You’ll be prompted to log in via your browser or with an access token. Follow the instructions to authenticate.

1. Create an environment in the Pulumi Cloud console:

   1. Open Pulumi Cloud and log in
   2. Select Environments in the left navigation
   3. Select + Create Environment
   4. Choose New Environment
   5. For Project name, enter: my-project
   6. For Environment name, enter: dev
   7. Select Create Environment

   

   Your environment is now created and ready to store configuration and secrets.

Store configuration and secrets

Add both plaintext configuration and encrypted secrets to your environment:

1. In the Environment definition editor, erase the contents and replace them with the following YAML:

   values:
     region: us-west-2
     apiKey:
       fn::secret: demo-secret-123
   

   This defines two values: region (a plaintext value) and apiKey (a secret value, denoted with fn::secret).

   

2. Select Save

   Watch what happens: ESC automatically encrypts the secret value. The plaintext demo-secret-123 is replaced with an encrypted value.

   

Retrieve your configuration and secrets

Open your environment to retrieve all values, including decrypted secrets:

esc env open my-project/dev

You should see output like:

{
  "apiKey": "demo-secret-123",
  "region": "us-west-2"
}

You’ve created an environment, stored configuration and secrets, and retrieved them interactively with the CLI. Notice that the secret is automatically decrypted when you open the environment.

What’s next?

Core workflows

Now that you’ve created your first environment, explore these essential guides:

• Integrate with Pulumi IaC - Use ESC environments in your infrastructure code to centralize secrets across all stacks
• Managing secrets - Store, organize, and retrieve secrets using the CLI and console
• Running commands with esc run - Inject secrets into any command or script as environment variables
• Importing environments - Compose environments to share configuration across teams and projects

New to Pulumi IaC? Start with the Pulumi IaC Get Started guide first.

Advanced capabilities

Extend ESC with dynamic credentials and external secret providers:

• Dynamic login credentials - Generate short-lived cloud credentials using OIDC with AWS, Azure, GCP, and more
• Dynamic secrets - Pull secrets from external providers like AWS Secrets Manager, Azure Key Vault, and 1Password
• Configuring OIDC - Deep dive into OpenID Connect configuration and trust relationships

Learn the fundamentals

• Concepts - Understand how ESC works under the hood