Outputs

The pulumi CLI and other ESC consumers conventionally assign specific semantics to certain top-level properties of an evaluated ESC environment (i.e. properties defined under the values section of the environment definition). These reserved properties shape the outputs an environment produces when it is opened: environment variables, temporary files, Pulumi IaC stack configuration, and Pulumi policy pack configuration.

environmentVariables

The environmentVariables reserved property contains values that should be exported as environment variables. For example, pulumi env run exports each key-value pair in the environmentVariables property as an environment variable that is accessible to the command to run.

This property is also used by Pulumi policy packs. When an ESC environment is attached to a policy pack in a policy group, environmentVariables are injected into the policy runtime as environment variables.

Properties

Example

values:
  environmentVariables:
    GREETING: Hello

Evaluated result

{
  "environmentVariables": {
    "GREETING": "Hello"
  }
}

Using pulumi env run

$ pulumi env run default/greet -- sh -c '${GREETING}, ${USER}!'
Hello, user!

Precedence

When an ESC consumer such as esc run runs a command, the values in environmentVariables are layered on top of the variables already present in your local (OS) environment. If a variable is defined in both places, the value from the environment takes precedence over the inherited local value.

For example, the default/greet environment above sets GREETING: Hello. Even if GREETING is already set in your shell, the environment’s value is used:

$ GREETING=from-shell esc run default/greet -- printenv GREETING
Hello

files

The files reserved property contains values that should be written to temporary files. For example, pulumi env run writes the contents of each property in the files property to a temporary file and exports the file’s path in the named environment variable that is accessible to the command to run.

Properties

Example

values:
  files:
    GREETING: Hello, ${context.pulumi.user.login}!
    BINARY:
      fn::fromBase64: ...

Evaluated result

{
  "files": {
    "GREETING": "Hello, user!",
    "BINARY": ...
  }
}

Using pulumi env run

$ pulumi env run default/greet -- sh -c 'echo ${GREETING} & cat ${GREETING}'
/tmp/tmp.iBApHfcsJ1
Hello, user!

pulumiConfig

The pulumiConfig reserved property contains values that should be exported as stack configuration for Pulumi IaC. See the Pulumi IaC integration guide for an overview.

Properties

Example

values:
  pulumiConfig:
    aws:region: us-west-2
    greeting: Hello

Evaluated result

{
  "pulumiConfig": {
    "aws:region": "us-west-2",
    "greeting": "Hello"
  }
}

Using pulumi config

Assuming a Pulumi IaC stack that is configured to use the environment above:

$ pulumi config
KEY                           VALUE
aws:region                    us-west-2
greeting                      Hello

Precedence

When a configuration key is defined both in an environment’s pulumiConfig and explicitly in a stack’s own configuration, the explicit stack configuration value takes precedence. Explicit stack configuration includes:

• Values written directly to Pulumi.<stack-name>.yaml under the config: block.
• Values set with pulumi config set, which writes to that same stack configuration file.

For example, given the environment above (which sets greeting: Hello), if the stack also sets the key explicitly:

$ pulumi config set greeting Hola

then the explicit value wins:

$ pulumi config
KEY                           VALUE
aws:region                    us-west-2
greeting                      Hola

For object values, the environment and stack configurations are deep-merged using JSON merge patch semantics: the two objects are combined key by key, and the stack’s value wins for any key defined in both. This deep-merge behavior is specific to pulumiConfig. It differs from how an object value declared as a project-level default in Pulumi.yaml combines with a stack-level value in Pulumi.<stack-name>.yaml: there the stack value replaces the project default outright rather than merging into it.

This precedence is separate from the rule that applies among multiple imported environments, where the last imported environment wins. See Imports for details.

policyConfig

The policyConfig reserved property contains values that should be exported as configuration for Pulumi policy packs. When an ESC environment is attached to a policy pack in a policy group, the values under policyConfig are made available to the policy pack at runtime.

Properties

Keys can use either format:

• policyName — when the ESC environment is associated with a single policy pack
• packName:policyName — to scope configuration to a specific pack, following the same namespacing pattern as pulumiConfig

Example

Without pack namespace

values:
  compliance:
    apiToken:
      fn::secret: xxxxxxxxxxxxxxxx

  policyConfig:
    cost-compliance:
      maxMonthlyCost: 5000
      apiEndpoint: https://compliance.example.com
      apiToken: ${compliance.apiToken}

Evaluated result

{
  "policyConfig": {
    "cost-compliance": {
      "maxMonthlyCost": 5000,
      "apiEndpoint": "https://compliance.example.com",
      "apiToken": "[secret]"
    }
  }
}

With pack namespace

values:
  policyConfig:
    my-compliance-pack:cost-compliance:
      maxMonthlyCost: 5000

Evaluated result

{
  "policyConfig": {
    "my-compliance-pack:cost-compliance": {
      "maxMonthlyCost": 5000
    }
  }
}