Interpolations and References

Interpolations and references are additional syntactical constructs that ESC layers on top of YAML to allow users to reuse properties to construct new values.

References take the form ${property-path}. References may appear alone or embedded within strings. The former case is referred to as a bare reference; the latter is an interpolation.

Property paths

Property paths–used throughout the Pulumi ecosystem–are JavaScript-inspired expressions that refer to properties within JSON-like values.

The syntax supports both dot notation and bracket notation. For keys that contain special characters (i.e. [, ], ", or .) or begin with a digit, bracket notation is required.

Binding references

In the context of ESC, references either refer to properties in the evaluated environment in which they are contained or to built-in properties.

Interpolations and references are early-bound: each reference is evaluated within the context of the environment in which it is contained. This allows the author of an environment definition to reliably predict the form of the value referred to by a reference.

Early binding contrasts with late binding, which would evaluate references within the context of the top-level environment and its entire import stack. ESC does not currently support late-bound references.

Bare references

Bare references evaluate to a copy of the referenced value.

Example

values:
  user:
    name: Real Name
    login: user-login
  user-copy: ${user}

Evaluated result

{
  "user": {
    "name": "Real Name",
    "login": "user-login"
  },
  "user-copy": {
    "name": "Real Name",
    "login": "user-login"
  }
}

Interpolations

Interpolations evaluate to the string representation of the referenced value.

Example

values:
  user:
    name: Real Name
    login: user-login
  greeting: Hello, ${user.name}!

Evaluated result

{
  "user": {
    "name": "Real Name",
    "login": "user-login"
  },
  "greeting": "Hello, Real Name!"
}

Built-in properties

In addition to referencing properties defined within an environment, references can access several built-in properties: information about the user evaluating an environment (context), other environments in the organization (environments), and imported environments (imports).

context

The context built-in property provides information about the user evaluating an ESC environment. It exposes the login of the requesting user at context.pulumi.user.login and the login of their organization at context.pulumi.organization.login.

values:
  greeting: Hello, ${context.pulumi.organization.login}/${context.pulumi.user.login}!

environments

The environments built-in property provides access to other environments within the same organization. This allows the selective use of values from other environments without explicitly importing them. Reference a value as ${environments.<project>.<environment>.<property-path>}.

values:
  other: Hello, ${environments.app.dev.name}!

imports

The imports built-in property provides access to imported environments, including those that are imported without participating in the merge stack (merge: false). For details on importing environments, see Imports.

imports:
  - app/dev: { merge: false }
values:
  other: Hello, ${imports["app/dev"].name}!