Integrate ESC with Pulumi IaC

This guide covers advanced patterns for integrating Pulumi ESC with your Pulumi IaC projects to centralize configuration and secrets across all your stacks.

Prerequisites

• Pulumi CLI installed
• Pulumi account created
• An existing Pulumi project (or create one with pulumi new)
• An ESC environment referenced from your stack (see Get Started)

Common patterns

Using dynamic cloud credentials

To share AWS OIDC credentials across multiple stacks, configure your ESC environment to generate short-lived credentials:

values:
  aws:
    login:
      fn::open::aws-login:
        oidc:
          roleArn: arn:aws:iam::123456789012:role/pulumi-deployment-role
          sessionName: pulumi-session
  pulumiConfig:
    aws:region: ${aws.login.region}
  environmentVariables:
    AWS_ACCESS_KEY_ID: ${aws.login.accessKeyId}
    AWS_SECRET_ACCESS_KEY: ${aws.login.secretAccessKey}
    AWS_SESSION_TOKEN: ${aws.login.sessionToken}

This pattern works everywhere Pulumi runs: locally, in CI/CD, Pulumi Deployments, and GitHub Actions. Similar patterns are available for Azure (fn::open::azure-login) and GCP (fn::open::gcp-login).

Learn more in Dynamic login credentials and Configuring OIDC.

Managing API keys and secrets

Pull third-party API keys from external secret stores:

values:
  pulumiConfig:
    myApp:datadogApiKey:
      fn::secret:
        fn::open::azure-secrets:
          login: ${azure.login}
          get:
            secretId: https://my-keyvault.vault.azure.net/secrets/datadog-api-key

Learn more in Dynamic secrets.

Environment-specific configuration

Compose environments to share common configuration while overriding values per environment:

# common environment
values:
  pulumiConfig:
    myApp:instanceType: t3.micro
    myApp:replicas: 1

# production environment (imports common)
imports:
  - common
values:
  pulumiConfig:
    myApp:instanceType: t3.large  # override for production
    myApp:replicas: 3              # override for production

Learn more in Importing environments.

Convert existing stack config to an ESC environment

To convert your existing stack config to a new ESC environment, use the Pulumi CLI:

pulumi config env init

See the pulumi config env init reference for more information.

Automation API integration

You can manage a stack’s imported environments with Automation API in Node, Go, and Python. The following methods are supported:

• addEnvironments(...): Append environments to your Pulumi stack’s import list.
• listEnvironments(): Retrieve the environments currently imported into your stack.
• removeEnvironment(environment): Remove a specific environment from your stack’s import list.

Accessing Pulumi stack outputs

You can read outputs from other Pulumi stacks into an ESC environment with the pulumi-stacks provider.

Next steps

• Dynamic login credentials - Generate dynamic cloud credentials with OIDC
• Dynamic secrets - Pull from AWS, Azure, GCP secret stores
• Importing environments - Compose configuration hierarchies