Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Config and Secrets

Pulumi ESC: Environments, Secrets and OIDC Credentials

Learn Pulumi ESC (Environments, Secrets and Configuration): composable environments, imports, dynamic OIDC credentials for AWS, linking environments to stacks and using esc run.

Per-stack config files work well for one project. Real organizations have many projects and tools that need the same settings and credentials: the same database host, the same cloud login. Pulumi ESC (Environments, Secrets and Configuration) is a service in Pulumi Cloud for defining named, composable environments of configuration and secrets, and handing them to Pulumi stacks and other programs.

ESC is a hosted Pulumi Cloud feature plus the esc CLI, so it cannot run here. YAML and commands below are read-only; the stand-ins simulate environment composition and short-lived credentials in JavaScript.

What an environment is

An environment is a YAML document stored in Pulumi Cloud, with a name such as acme/aws-prod. It has:

  • values: static values and secrets;
  • imports: other environments to include;
  • special keys that expose values to consumers: environmentVariables, files, and pulumiConfig.
YAML
# acme/shop-common
values:
  appName: shop
  region: eu-central-1
  pulumiConfig:
    shop:region: ${region}
    shop:domain: shop.example.com
YAML
# acme/shop-prod
imports:
  - acme/shop-common
values:
  dbPassword:
    fn::secret: S3cr3t!pass          # stored encrypted
  pulumiConfig:
    shop:replicas: 4
    shop:dbPassword: ${dbPassword}

Later imports and local values override earlier ones, and objects are merged. Environments have their own access control and versions with tags such as latest and stable, so you can roll back or pin.

Using an environment from a stack

List the environment in the stack's configuration file:

YAML
# Pulumi.prod.yaml
environment:
  - acme/shop-prod
config:
  aws:region: eu-central-1

When you run pulumi up, the CLI opens the environment, and everything under pulumiConfig appears as ordinary stack config (secrets included, still marked secret). Values set directly in the stack file win over imported ones. Commands:

Terminal
pulumi config env add acme/shop-prod       # attach to the current stack
pulumi config env ls
pulumi config env rm acme/shop-prod

Dynamic credentials with OIDC

Long-lived cloud keys stored in CI are a liability. ESC can log in with OpenID Connect: Pulumi Cloud proves its identity to AWS, Azure or Google Cloud, and receives short-lived credentials. For AWS:

YAML
# acme/aws-prod
values:
  aws:
    login:
      fn::open::aws-login:
        oidc:
          roleArn: arn:aws:iam::111111111111:role/pulumi-esc
          sessionName: pulumi-esc
  environmentVariables:
    AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
    AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
    AWS_SESSION_TOKEN: ${aws.login.sessionToken}

On the AWS side, an IAM role trusts Pulumi's OIDC issuer for your organization, and its trust policy restricts which environments may assume it. The credentials expire after a short time (the default is about an hour). Attach acme/aws-prod to a stack and your program and the AWS provider receive the environment variables automatically, with no stored AWS keys anywhere.

Pulling secrets from other stores

fn::open::* providers fetch values at open time: AWS Secrets Manager, Azure Key Vault, Google Secret Manager, HashiCorp Vault, 1Password and more.

YAML
values:
  dbPassword:
    fn::open::aws-secrets:
      region: eu-central-1
      login: ${aws.login}
      get:
        db:
          secretId: prod/shop/db

The value is read when the environment opens, not stored in Pulumi.

The esc CLI

Terminal
esc env init acme/shop-prod            # create
esc env edit acme/shop-prod            # edit in your $EDITOR
esc env get acme/shop-prod             # show resolved values
esc env get acme/shop-prod --show-secrets
esc run acme/aws-prod -- aws s3 ls     # run any command with the environment's variables
esc open acme/shop-prod                # print resolved values as JSON

esc run is useful beyond Pulumi: scripts, Terraform or the AWS CLI can all pick up short-lived credentials without you copying keys.

When to use ESC versus stack config

Need Stack config ESC
One project, a few values Simple, in Git next to the code More than needed
Same values in many projects/stacks Copy-paste, drift Shared environments, one place
Cloud credentials in CI Long-lived keys Short-lived OIDC credentials
Access control on values Whoever can read the repo and decrypt Per-environment RBAC and audit log
Offline or self-managed backend only Works Requires Pulumi Cloud

If you use a self-managed backend only, you do not get ESC; fall back to your CI's OIDC login actions and per-stack config (CI/CD in later chapters).

Stand-in: composing environments

This stand-in merges imported environments in order, with later values overriding earlier ones, then maps pulumiConfig into stack config.

JS Stand-in: environment imports and overrides

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: short-lived credentials

JS Stand-in: credentials that expire

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a Pulumi ESC environment?

    Environments hold values, secrets and imports, and can feed stacks and other tools.
  2. 2. Why use OIDC login in an ESC environment?

    Credentials expire quickly, limiting damage if leaked.
  3. 3. How does a stack consume an environment?

    pulumiConfig values then appear as ordinary stack config.
  4. 4. Which command runs any program with an environment's variables?

    esc run opens the environment and injects environment variables for the command.

Summary

  • ESC environments are shared, versioned, access-controlled sets of values and secrets in Pulumi Cloud.
  • They compose through imports, and stacks attach them with environment:.
  • OIDC logins produce short-lived credentials for AWS, Azure and Google Cloud.
  • esc run gives any tool the environment's variables.
  • Use plain stack config for small projects and ESC when values and credentials are shared widely.

Next: Component Resources: Grouping Resources into Reusable Building Blocks