Skip to main content
Sign in Dashboard Get started
  1. Docs
  2. Secrets & Configuration
  3. Guides
  4. Use with Pulumi IaC

Use Pulumi ESC with Pulumi IaC

    Consuming an ESC environment from a Pulumi IaC program is the most common way to use ESC. It lets you define configuration and secrets once in an environment and share them across every stack that imports it, instead of duplicating values in each Pulumi.<stack>.yaml file. It’s also how you give your stacks short-lived cloud credentials: rather than storing static access keys, an environment can generate temporary AWS, Azure, or GCP credentials on demand through OIDC.

    This section explains how the integration works, then points to task-focused guides for adopting ESC and migrating existing patterns to it.

    New to this? If you haven’t connected an environment to a stack yet, start with the ESC Get Started guide, which walks you through referencing an environment and exposing values through pulumiConfig. This section picks up from there.

    How the integration works

    Two pieces connect ESC to a Pulumi program:

    1. The environment block in your stack configuration file (Pulumi.<stack>.yaml) lists the environments the stack imports. Environments are merged in order, with later values overriding earlier ones:

      environment:
  - my-project/common
  - my-project/dev

    2. The pulumiConfig block inside an environment declares which values flow into your program as stack configuration. Anything you put under pulumiConfig becomes available through the standard Configuration API — config.get(), config.require(), and their secret variants:

      values:
  pulumiConfig:
    aws:region: us-west-2
    myApp:apiKey:
      fn::secret: super-secret-value

    Values wrapped in fn::secret arrive in your program as Pulumi IaC secrets: they’re masked in CLI output and encrypted in your stack’s state file, exactly as if you’d set them with pulumi config set --secret.

    ESC requires the Pulumi Cloud backend. Importing an environment into a stack works only for stacks that use Pulumi Cloud as their state backend. Stacks stored in self-managed backends (such as S3, Azure Blob Storage, or the local filesystem) can’t reference ESC environments.

    Guides

    Common patterns

    Once your stack imports an environment, these are the patterns you’ll reach for most often. Each links to its dedicated reference:

    • Dynamic cloud credentials. Generate short-lived AWS, Azure, or GCP credentials with OIDC instead of storing static keys, and share them across every stack and CI/CD context. See Dynamic login credentials and Configuring OIDC.
    • API keys and third-party secrets. Store a secret directly in an environment with fn::secret, or have ESC pull it at open time from an external store like AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, Vault, or 1Password. Where the value lives is a backend detail; either way it reaches your program the same way, as an ordinary Pulumi secret. See Dynamic secrets for the external-store providers.
    • Environment-specific configuration. Compose environments so shared values live in a common environment and each stack overrides only what it needs. See Importing environments.
    • Reading other stacks’ outputs. Import outputs from other Pulumi (or Terraform) stacks into an environment with the pulumi-stacks provider.
    When a key is set both in an environment’s pulumiConfig and explicitly in your stack configuration, the explicit stack value wins. See Precedence for the full rules.

    Manage imports with Automation API

    You can add, list, and remove a stack’s imported environments programmatically with Automation API. See Manage ESC resources with Automation API for the available methods, per-language support, and runnable examples.

    Next steps