pulumi/esc

Pulumi ESC (Environments, Secrets, and Configuration) for cloud applications and infrastructure.

Pulumi ESC (Environments, Secrets, and Configuration)

Pulumi ESC is a new product from Pulumi that manages and tames secrets and configuration complexity across all of your cloud infrastructure and application environments. Pulumi ESC introduces a new category of configuration-as-code product, motivated by our experience working with hundreds of Pulumi IaC customers to address their needs in managing secrets and configuration at scale within their Pulumi infrastructure and across other cloud applications and infrastructure projects.

Pulumi ESC enables teams to aggregate secrets and configuration from many sources, manage hierarchical collections of configuration and secrets ("environments"), and consume those configuration and secrets from a variety of different infrastructure and application services. Pulumi ESC works hand-in-hand with Pulumi IaC to simplify configuration management, but also works independently from Pulumi IaC, as a solution for managing environments, secrets and configuration for any application or infrastructure project.

For example, the Pulumi ESC CLI (esc) makes it possible to give your developers immediate, just-in-time authenticated and short-lived access to cloud credentials across any cloud provider with just a single command: esc run aws-staging -- aws s3 ls.

Pulumi ESC is offered as a managed service as part of Pulumi Cloud, and this repo contains the implementation of the following key components of the ESC offering:

1. The esc CLI: A CLI tool for managing and consuming environments, secrets and configuration using Pulumi ESC.
2. The Pulumi ESC evaluator: The core specification and implementation of the document format for defining environments, and the syntax and semantics for evaluating environments to produce a set of configuration and secrets.

Resources

• Getting Started
• Download and Install
• Documentation
• Community Slack

How Pulumi ESC works

1. Pulumi ESC enables you to define environments, which are collections of secrets and configuration. Each environment can be composed from multiple environments.
2. Pulumi ESC supports a variety of configuration and secrets sources, and it has an extensible plugin model that allows third-party sources.
3. Pulumi ESC has a rich API that allows for easy integration. Every value in an environment can be accessed from any execution environment.
4. Every environment can be locked down with RBAC, versioned, and audited.

Building the CLI Locally

You can build the CLI locally for testing by running:

$ make install

This will produce an esc binary in your GOBIN directory.

Why Pulumi ESC?

Pulumi ESC was designed to address a set of challenges that many infrastructure and application development teams face in managing configuration and secrets across their various environments:

• Secrets and Configuration Sprawl: Data in many systems. Challenging to audit. Lots of application-specific logic to acquire and compose configuration from multiple sources. Divergent solutions for Infrastructure and Application configuration.
• Duplication and Copy/Paste: Secrets are duplicated in many places. Frequently coupled to application/system-specific configuration stores.
• Too Many Long-lived Static Secrets: Long lived static credentials are over-used, exposing companies to significant security risk. Rotation is operationally challenging. Not all systems support direct integration with OIDC and other dynamic secrets provisioning systems.

Pulumi ESC was born to address these problems and needs head on. It does so through a few core design principles:

• Hierarchical and Composable: Environments contain collections of secrets and configuration, but can also import one or more other environments. Values can be overridden, interpolated from other values, and arbitrarily nested. This allows for flexible composition and reuse, and avoids copy paste.
• Any Secrets Provider: Support for dynamic configuration providers allow Pulumi ESC to integrate with secrets stored in any other provider. Organizations often use AWS Secrets Manager, Vault, Azure OIDC and/or 1Password plus many more sources of truth for their secrets and configuration. Pulumi ESC supports them all, providing a single interface to your configuration and secrets, no matter where their source of truth is. Pulumi ESC works with these tools to provide improved management of secrets and configuration.
• Consume from Anywhere: The esc CLI and the Pulumi ESC Rest API enables environments to be accessed from any application, infrastructure provider, automation system. At launch, first-class integrations are available with Pulumi IaC, local environment and .env files, GitHub Actions, and more.
• Auditable: Environments must be “opened” to compute and see the set of value they provide, and this action is recorded in audit logs, including a full record of how each value was sourced from within the hierarchy of environments that contributed to it.
• Authentication and RBAC: Pulumi ESC brokers access to secrets and configuration that live in other systems, and so authentication and granular RBAC are critical to ensure robust access controls across your organization. Pulumi ESC leverages the same Pulumi Cloud identity, RBAC, Teams, SAML/SCIM and scoped access tokens that are used for Pulumi IaC today, extending these all to managing access to Environments as well as Stacks.
• Configuration as Code: Environments are defined as YAML documents which can describe how to project and compose secrets and configuration, integrate dynamic configuration providers, and compute new configuration from other values (construing a URL from a DNS name, or concatenating multiple configuration values into a derived value). The incredible flexibility of a code-based approach over traditional point-and-click interfaces allows Pulumi ESC to offer rich expressiveness for managing complex configuration.
• Fully Managed: Pulumi ESC is offered as a fully managed cloud service in Pulumi Cloud (and Pulumi Cloud Self-hosted in the near future). The pulumi/esc project is open source, and contains the evaluation engine for environments, the esc CLI, and in the future, the extensible plugins for source and target integrations.

esc's Issues

Add support for tags

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

It would be helpful to include first-class tag support as part of the ESC definition. I'm picturing something like a tags section that supports key/value pairs.

Example:

imports:
  - foo
  - bar

tags:
  org: acme-corp
  environment: staging

values:
  object:
    array: [ "hello", "world" ]

Affected area/feature

cli: document the behavior of `--` in `esc env run`

-- instructs the arg parser to stop parsing flags. Users need this in esc env run when the command to run includes -- flags. We should mention this in the help text.

We should also investigate catching flag errors from the arg parser and emitting better help text.

cli: do not lose changes in `esc env edit` when the result is invalid

esc env edit loses changes if the new environment definition is not valid. This is bad. A simple approach to fixing this would be to retain the temporary file used for the edits and reopen it after displaying errors if the new definition is not valid.

[gha] Add command dispatch to pulumi/docs to update latest-version

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

As part of the release process, we need to update the pulumi.com/esc/latest-version page. We can copy the process used by the pulumi CLI:

1. Add a dispatch workflow which uses pulumictl to send the version reference to a specified workflow in pulumi/docs. pulumi/pulumictl#73 adds the required support.
2. Either extend the existing docs workflow or add another one specific to esc that is keyed off the event dispatch from step 1. This workflow will update static/esc/latest-version in the docs repo.
3. Extend the release workflow for pulumi/esc to include the dispatch workflow after the goreleaser steps are complete.

Affected area/feature

get.pulumi.com based installers?

cli: support persisted environment selection

The esc CLI currently has no notion of an ambiently-selected environment. This can make some commands fairly verbose, as the environment name must be explicitly specified. We should consider supporting an ambient + persistent environment selection.

Add a table-based UI for creating and editing environments

Today we have a document-based editor for environments inside Pulumi Cloud.

We would like to also offer a path-based editor using a more traditional table based UX. This would allow a simple opoint-and-click interface for editing environments.

The fundamental data model is still a document, but this editor can represent that document via a path-based UI. This leverages and surfaces similar model for path-based access to environments as with the esc env get and esc env set commands.

Here's a sketch of the expected user interface:

Evaluate environments concurrently

At the moment environments are evaluated serially in depth-first order. This could be problematic for environments with a large number of fn::opens that perform I/O. We could speed things up by evaluating fn::opens concurrently.

Initial implementation

Add the initial implementation of the environments evaluator and its interfaces.

Add environment to stack config from command line

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

I can't see anything in the docs around adding environments to the stack config from the command line.

Something like pulumi env add {environment name} which just adds it to the array of environments (and the corresponding pulumi env rm {environment name})

Affected area/feature

eval: reserve the `context` top-level key

We'd like to reserve this for information passed in to the evaluator.

Flesh out README

OSS release

This epic tracks open-sourcing this repository.

Tasks

Beta Give feedback

1. Flesh out README #71
   kind/enhancement resolution/fixed +2
   
2. Issues for major coming features
3. CI/CD integration
4. esc CLI releases
5. godoc for libraries
6. Publish to homebrew tap #73
   kind/enhancement resolution/fixed +2
   
7. LICENSE header reviews #74
   kind/enhancement resolution/fixed +2
   
8. Ship 0.5.0 #75
   kind/engineering resolution/fixed +2
   
9. Flip to public #76
   kind/engineering resolution/fixed +2
   
10. get.pulumi.com based installers? #72
    kind/engineering resolution/fixed +2
    
11. Manual integration test full E2E on Mac, Linux and Windows #78
    kind/engineering resolution/fixed +2
    

`apply` command to directly overwrite an environment

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

I'd like to apply my environment YAML file kubectl-style, e.g.:

pulumi env apply my-org/my-env -f environment.yaml

Ideally, I would also like it to create the environment if not already created.

Affected area/feature

cli: fix newline in `esc env` usage

Needs a line break after contents.

cli: refactor command tree

This is the tree we want:

• esc
  • login
  • logout
  • version
  • open
  • run
  • env
    • open
    • run
    • ls
    • init
    • edit
    • get
    • set
    • rm

This is close to what we have, but with the addition of the open and run commands at top-level. These will be aliases for esc env open/esc env run, respectively.

providers: allow output schema to be parameterized based on inputs

Particularly useful for refining optional properties to required properties depending on the input values.

cli: document that `get`/`set` paths ~refer to physical YAML nodes, not logical esc nodes

e.g. consider this environment definition:

values:
  aws:
    creds:
      fn::open::aws-login:
        oidc:
          roleArn: some-arn
          sessionName: name
  environmentVariables:
    AWS_ACCESS_KEY_ID: ${aws.creds.accessKeyId}
    AWS_SECRET_ACCESS_KEY: ${aws.creds.secretAccessKey}
    AWS_SESSION_TOKEN: ${aws.creds.sesstionToken}

The path aws.creds["fn::open::aws-login"].oidc.roleArn refers to the role ARN on line 6. A "logical" path might be aws.creds.inputs.oidc.roleArn or aws.creds.inputs.roleArn.

cli: fix help text for `esc env edit`

Replace "Opens an environment for editing" with "Edits an environment's definition"

cli: make `-x` the default for `esc env get`

Or replace -x with --format, and make the default format the "explain" view.

[environments] CLI help typo

https://github.com/pulumi/pulumi-service/issues/13780

consider adding a `fromBase64` function

cli: add a `--secret` flag to `esc env set`

Use this as a shorthand for `esc env set [env] [path] '{"fn::secret": ...}'

esc login not working

What happened?

When I try to run the esc login command, it returns an error:

$ esc login
Error: not currently logged in

Example

Just try and run the esc login command

Output of pulumi about

CLI          
Version      3.88.0
Go Version   go1.21.1
Go Compiler  gc

Plugins
NAME          VERSION
azure         5.52.0
azure-native  2.11.0
azuread       5.42.0
python        unknown

Host     
OS       amazon
Version  2
Arch     x86_64

This project is written in python: executable='/home/ec2-user/environment/azure-oidc/venv/bin/python3' version='3.7.16'

Current Stack: v-torian-pulumi-corp/azure-oidc/dev

TYPE                                                                                         URN
pulumi:pulumi:Stack                                                                          urn:pulumi:dev::azure-oidc::pulumi:pulumi:Stack::azure-oidc-dev
pulumi:providers:azure-native                                                                urn:pulumi:dev::azure-oidc::pulumi:providers:azure-native::default
pulumi:providers:azuread                                                                     urn:pulumi:dev::azure-oidc::pulumi:providers:azuread::default_5_42_0
pulumi:providers:azure-native                                                                urn:pulumi:dev::azure-oidc::pulumi:providers:azure-native::default_2_11_0
azure-native:resources:ResourceGroup                                                         urn:pulumi:dev::azure-oidc::azure-native:resources:ResourceGroup::resourceGroup
azuread:index/application:Application                                                        urn:pulumi:dev::azure-oidc::azuread:index/application:Application::oidc-app-registration
azuread:index/applicationFederatedIdentityCredential:ApplicationFederatedIdentityCredential  urn:pulumi:dev::azure-oidc::azuread:index/applicationFederatedIdentityCredential:ApplicationFederatedIdentityCredential::federatedIdentityCredential


Found no pending operations associated with dev

Backend        
Name           pulumi.com
URL            https://app.pulumi.com/v-torian-pulumi-corp
User           v-torian-pulumi-corp
Organizations  v-torian-pulumi-corp, zephyr, pulumi
Token type     personal

Dependencies:
NAME                 VERSION
pip                  23.2.1
pulumi-azure         5.52.0
pulumi-azure-native  2.11.0
pulumi-azuread       5.42.0
setuptools           68.0.0
wheel                0.41.2

Pulumi locates its logs in /tmp by default

Additional context

No response

Contributing

Vote on this issue by adding a 👍 reaction.
To contribute a fix for this issue, leave a comment (and link to your pull request, if you've opened one already).

Support Pulumi IaC stack reference configuration provider

We've had several requests to support reading in a Pulumi IaC stack reference from within an environment. This would enable easily consuming infrastructure metadata (subnet IDs, IP addresses, DNS names, etc) from your Pulumi programs in a centrally managed way.

Ship `0.5.0`

Panic when listing environments when not logged in

What happened?

When not logged in (so no credentials.json file, ran 'pulumi env ls'. Got the following:

Pulumi Version:   v3.88.0
Go Version:       go1.21.2
Go Compiler:      gc
Architecture:     amd64
Operating System: darwin
Panic:            runtime error: invalid memory address or nil pointer dereference

goroutine 1 [running]:
runtime/debug.Stack()
        /usr/local/Cellar/go/1.21.2/libexec/src/runtime/debug/stack.go:24 +0x5e
main.panicHandler(0xc001cbff07)
        /private/tmp/pulumi-20231010-4719-17hymnh/pkg/cmd/pulumi/main.go:35 +0x45
panic({0x102265ae0?, 0x104427f60?})
        /usr/local/Cellar/go/1.21.2/libexec/src/runtime/panic.go:914 +0x21f
github.com/pulumi/esc/cmd/esc/cli.(*escCommand).getCachedClient(0xc000a66dc0, {0x102e97910, 0x1044aebc0})
        /Users/brew/Library/Caches/Homebrew/go_mod_cache/pkg/mod/github.com/pulumi/[email protected]/cmd/esc/cli/login.go:150 +0x76
github.com/pulumi/esc/cmd/esc/cli.newEnvLsCmd.func1(0xc00146de00?, {0x1044aebc0?, 0x0?, 0x0?})
        /Users/brew/Library/Caches/Homebrew/go_mod_cache/pkg/mod/github.com/pulumi/[email protected]/cmd/esc/cli/env_ls.go:29 +0x4b
github.com/spf13/cobra.(*Command).execute(0xc001466300, {0x1044aebc0, 0x0, 0x0})
        /Users/brew/Library/Caches/Homebrew/go_mod_cache/pkg/mod/github.com/spf13/[email protected]/command.go:940 +0x87c
github.com/spf13/cobra.(*Command).ExecuteC(0xc001ea6f00)
        /Users/brew/Library/Caches/Homebrew/go_mod_cache/pkg/mod/github.com/spf13/[email protected]/command.go:1068 +0x3a5
github.com/spf13/cobra.(*Command).Execute(...)
        /Users/brew/Library/Caches/Homebrew/go_mod_cache/pkg/mod/github.com/spf13/[email protected]/command.go:992
main.main()
        /private/tmp/pulumi-20231010-4719-17hymnh/pkg/cmd/pulumi/main.go:56 +0x58

Example

n/a

Output of pulumi about

CLI          
Version      3.88.0
Go Version   go1.21.2
Go Compiler  gc

Plugins
NAME    VERSION
aws     5.42.0
awsx    1.0.5
docker  3.6.1
nodejs  unknown

Host     
OS       darwin
Version  14.0
Arch     x86_64

This project is written in nodejs: executable='/Users/piers/.nvm/versions/node/v18.12.1/bin/node' version='v18.12.1'

Backend        
Name           pulumi.com
URL            https://app.pulumi.com
User           Unknown
Organizations  
Token type     personal

Dependencies:
NAME            VERSION
@pulumi/pulumi  3.87.0
@types/node     16.18.58
@pulumi/aws     5.42.0
@pulumi/awsx    1.0.5

Pulumi locates its logs in /var/folders/69/3w1gr05s2pq36wn49bhyknym0000gn/T/ by default
warning: Failed to get information about the current stack: No current stack

Additional context

No response

Contributing

Vote on this issue by adding a 👍 reaction.
To contribute a fix for this issue, leave a comment (and link to your pull request, if you've opened one already).

Support pinning reference to environments to specific versions.

Today, any reference to an environment implicitly references the latest edit to that environment. This has some benefits as it makes it easy to make a change one place and have it picked up elsewhere without forcing all consumers to also change, but also makes it harder to ensure that a given consumer can be in control of when it adopts new configuration from an environment.

We would like to add support for specifying versions as part of an environment reference - for example:

# Pulumi.staging.yaml
environment:
  - aws-staging@v5

A number of design questions we need to address:

• Are versions incremented every time an environment is saved? Or is there a tagging mechanism (like Docker) where users can explicitly specify these versions/tags/labels?
• Can a version/tag/label change, or are these truly immutable?
• Is there an implicit latest which is used by default?
• Can these versioned references be used in all positions where an environment is referenced?
• Do we support git hash or tag?
• Likely too complicated but interesting: Do we support wildcards for semver? like import: - aws-staging@5.* or package management - aws-staging<=6 (admittedly seems like overkill)

Manual integration test full E2E on Mac, Linux and Windows

schema: validation fails silently for `Never`

When validating a value (and likely a schema) against the Never schema, validation fails silently. We should instead issue an error.

syntax: `fn::open`

We want to replace fn::open with fn::<provider-name> for brevity.

Publish to homebrew tap

Support version controlling environments

Today, environments are stored and versioning within Pulumi Cloud. We know there are cases where users would like to be able to author and version their environments via source-controlled code files.

There are two options we are exploring for this:

1. Enabling the Pulumi Cloud Pulumi Provider to define and manage the desired state of Environments via a Pulumi IaC program. This would offer a way to write code (in Pulumi IaC) to manage the lifecycle of environments across an organization (and to detect and manage drift via pulumi refresh).
2. Providing a mode where environments are authored locally (in source controlled Git repo), and pushed up to Pulumi ESC as part of a "deployment" process of some sort directly.

We may ultimately want/need to provide both of these.

Add application-level SDKs for Python, JavaScript, Go, .NET and more

Pulumi ESC can already be accessed from application code via REST API and the CLI. But there are many use cases where it is useful to consume configuration from Pulumi ESC directly from within application code.

We plan to do this by offering native SDKs for TypeScript, Python, Go and .NET.

As part of designing these SDKs, we have a few goals:

1. The ability to authenticate to Pulumi ESC (initially using a Pulumi Access Token, int he future using additional application-level authentication methods)
2. The ability to open an environment to get back a set of configuration values.
3. The ability to watch an environment to get a callback invoked when that environment changes.

Here's a conceptual sketch of what this might look like:

import * as esc from ‘pulumi-esc’;

const env = new esc.Environment(...);
const config = env.open("shopping-service-production");
env.watch("shopping-service-production", config => …);

Support for 1Password configuration provider

We've had many asks to support pulling credentials out of 1Password. Doing this would enable 1Password to be the source of truth, but to pulll required values down on-demand, and authenticated at the time of access, instead of copy-pasting values out of 1Password into other configuration systems.

This is currently dependent on REST API/SDK for accessing 1Password data via an application token.

Add support for Pulumi ESC in a GitHub Action

It would be great to allow Pulumi ESC environments to be pulled into GitHub Actions via a custom action - either the Pulumi action, or a new one specific to ESC. This would allow injecting configuration and secrets into an Action from Pulumi ESC, without the need to copy/paste it into GitHub Actions Secrets directly. This would structurally be similar to e.g. https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_github.html or https://github.com/hashicorp/vault-action.

esc login and CLI docs indicating support for self-hosted backends

What happened?

When attempting to troubleshoot the esc login command, I tried passing the URL like below:

$ esc login https://app.pulumi.com/
Error: https://app.pulumi.com/ is not a valid self-hosted backend, use `esc login` without arguments to log into the Pulumi Cloud backend

Also in the ESC CLI docs state:

By default, this will log in to the managed Pulumi Cloud backend. If you prefer to log in to a self-hosted Pulumi Cloud backend, specify a URL. For example, run

$ pulumi login https://api.pulumi.acmecorp.com
to log in to a self-hosted Pulumi Cloud running at the api.pulumi.acmecorp.com domain.

My understanding is that this feature isn't available yet(?)

If it isn't available yet, I don't think the CLI or the docs should indicate otherwise.

Example

$ esc login https://app.pulumi.com/
Error: https://app.pulumi.com/ is not a valid self-hosted backend, use `esc login` without arguments to log into the Pulumi Cloud backend

Output of pulumi about

N/A

Additional context

No response

Contributing

Vote on this issue by adding a 👍 reaction.
To contribute a fix for this issue, leave a comment (and link to your pull request, if you've opened one already).

Support for "syncing" or "pushing" to external systems

While the esc CLI and REST APIs can be used today to pull configuration down into many existing places where environments will be consumed, there are also many systems that store their configuration in more “walled gardens” which would need to be pushed into for optimal usability.

For example, pushing configuration values into a CI/CD system’s configuration system to avoid needing to copy/paste configuration and secrets manually into their UI.

We want ESC to offer a “push”/”sync” option that can be configured to inject configuration from an environment into such systems directly, so that you can still benefit from the usability of their native configuration systems, without having to take on the problems of configuration sprawl, long-lived static secrets and duplication and copy/paste of secrets.

We anticipate this supporting things like GitHub Actions env secrets, and many other similar use cases.

mistyping env name results in opaque error

We should return a better error if someone mistypes the env name

cli: silence errors from Cobra

or don't print errors ourselves. right now everything is duplicated.

Flip to public

consider adding a `fromJSON` function

awssecretsmanager recommends storing a json blob as the secret but only returns a string. we need a way to get the object from the json.

Improve 405 error message

When I open an environment I get the following:

$esc open demo/esc-staging
Error: [405]

We should include what failed as part of evaluating the environment.

LICENSE header reviews

Support for CloudFlare Workers Secrets configuration provider

We have heard asks for support for pulling configuration and secrets from CloudFlare Workers Secrets. Doing this would enable CloudFlare Workers Secrets to be the source of truth, but to pull required values down on-demand, and authenticated at the time of access, instead of copy-pasting values out of 1Password into other configuration systems.

cli: support a `dotenv` output format

see e.g. https://www.npmjs.com/package/dotenv for format details

cli: consider running all commands passed to `esc env run` in a subshell

q: which of these commands prints the AWS access key ID?

> esc env run dev echo $AWS_ACCESS_KEY_ID
> esc env run dev echo \$AWS_ACCESS_KEY_ID
> esc env run dev echo '$AWS_ACCESS_KEY_ID'
> esc env run dev 'bash -c "echo $AWS_ACCESS_KEY_ID"'

a: only the final command.

• In the first command, $AWS_ACCESS_KEY_ID is expanded by the user's shell before esc is even run, so we can't do much there.
• In the second and third commands, the environment variable is not expanded by the shell b/c it is single-quoted or escaped, but b/c esc invokes echo directly, it is not expanded by echo: envvar expansion is a function of shells, and echo is not a shell.
• In the final command, the bash invocation sees the raw $AWS_ACCESS_KEY_ID and expands it prior to invoking echo, so echo prints the access key ID.

The behavior of the second and third commands is arguably unexpected. We should consider running the command passed to esc env run in a subshell by default.

direnv support

Hello!

• Vote on this issue by adding a 👍 reaction
• If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

Consider supporting direnv, a popular shell extension that loads an .envrc file to modify the default environment upon entering a given directory. There are also VSCode, Emacs and other extensions available to respect the .envrc files automatically for files and processes under a given folder.

How would esc support look like? There should be a way to reference esc in the .envrc files. Perhaps esc could simply export env variables in shell syntax.

Affected area/feature

cli: add a `logout` command

• When sharing creds with pulumi, should log both out
• When not sharing creds, should only log out esc

Include property paths in diagnostics

There are scenarios in which we want to report diagnostics without referencing the YAML source. In these cases, we would like to report locations as paths. Diagnostics need to include this information.