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

Create a Pulumi account at app.pulumi.com
Install the ESC CLI
- macOS
- Windows
- Linux

   brew update && brew install pulumi/tap/esc

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

Windows binary download

amd64

See the ESC installation docs for more options.

Create your first environment

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.
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:

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).

Select Save

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

ESC environment editor showing encrypted secret value and preview displayed as [secret] after saving

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
Dynamic login credentials - Generate short-lived cloud credentials using OIDC with AWS, Azure, GCP, and more

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

Advanced capabilities

Extend ESC with external secret providers and advanced OIDC configuration:

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