Skip to content

Add deployments executorRootPath and PULUMI_ENV docs #17830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
rgharris wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

Add deployments executorRootPath and PULUMI_ENV docs #17830

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8a3d4d4
Add deployments executorRootPath and PULUMI_ENV docs
rgharris Feb 26, 2026
c0e64f1
fix: heading case and missing comma in executor root path docs
CamSoper Mar 6, 2026
fafdced
fix: remove PULUMI_ENV_FILE story from deployment settings docs
rgharris Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions content/docs/deployments/deployments/using/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,14 @@ Using a custom image may result in slower execution due to time spent pulling th
Additionally, we only support static credentials in custom executor images.
{{% /notes %}}

## Custom executor root path {#custom-executor-root-path}

By default, the deployment executor uses `/` as its root working directory. You can override this by setting a custom executor root path, which changes the base directory used by the executor for all file operations during the deployment.

This is primarily useful when running with non-root users in a [custom executor image](#custom-executor-images), where the default `/` directory may not be writable. For example, setting the root path to `/tmp` allows deployments to run under a non-root security context.

The custom executor root path can be configured through the UI under **Advanced Settings**, via the [REST API](/docs/reference/cloud-rest-api/deployments/#executorcontext) (`executorContext.executorRootPath`), or as code with the [Pulumi Cloud provider](/registry/packages/pulumiservice/api-docs/deploymentsettings/) (`executorContext.executorRootPath`).

## Open ID Connect (OIDC)

Pulumi Deployments supports OIDC for authenticating with cloud providers. This enables your deployments to access your cloud resources without storing static credentials in Pulumi Cloud.
Expand Down Expand Up @@ -186,14 +194,16 @@ These can be overridden or extended by configuring custom environment variables:

Environment variables can be persisted between pre-run commands and the final pulumi deployment by appending them to the file on the file system named `PULUMI_ENV`.

By default, this file is `/PULUMI_ENV`. If you configure a [custom executor root path](#custom-executor-root-path), Deployments sets `PULUMI_ENV_FILE` to `<executorRootPath>/PULUMI_ENV` and uses that file instead.

Example Usage:

```bash
export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
echo GOOGLE_OAUTH_ACCESS_TOKEN=$GOOGLE_OAUTH_ACCESS_TOKEN >> /PULUMI_ENV
echo GOOGLE_OAUTH_ACCESS_TOKEN=$GOOGLE_OAUTH_ACCESS_TOKEN >> "${PULUMI_ENV_FILE:-/PULUMI_ENV}"
```

Running `env` in a subsequent pre-run command will show the environment variable and it should be usable by scripts or your pulumi program.
{{% notes type="info" %}}
If `/PULUMI_ENV` does not work, and you are on self hosted, you can look for the following message in the logs to get the location: `Loading PULUMI_ENV from`.
If persisting variables does not work, look for this log message to confirm the path being used: `Loading PULUMI_ENV from`.
{{% /notes %}}
10 changes: 10 additions & 0 deletions content/docs/reference/cloud-rest-api/deployments/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1056,6 +1056,15 @@ or with credentials:
}
```

or with a custom root path:

```json
{
"executorImage": "myregistry.azurecr.io/myimage:latest",
"executorRootPath": "/tmp"
}
```

#### Properties

| Name | Type | Description |
Expand All @@ -1065,6 +1074,7 @@ or with credentials:
| `executorImage.credentials` | object | **Optional.** Credentials for private registry. |
| `executorImage.credentials.username` | string | **Required when credentials are provided.** Username for authentication. |
| `executorImage.credentials.password` | Secret | **Required when credentials are provided.** Password for authentication. |
| `executorRootPath` | string | **Optional.** Override the default root path (`/`) used by the deployment executor. Useful when running with non-root users (e.g., set to `/tmp`). This also changes where `PULUMI_ENV` is read and written (`<executorRootPath>/PULUMI_ENV`). |

### GitHub

Expand Down
Loading