Summary
We need to update the OIDC documentation to reflect a recent change in the Pulumi Cloud Console UI and to more strongly steer users toward ESC OIDC instead of the legacy Deployments OIDC.
Background
The legacy OpenID Connect section in a stack's Deployment Settings is now hidden by default for orgs that haven't already set up Deployments OIDC. New users are steered to ESC OIDC instead of the older, error-prone Deployments OIDC config.
Deployments OIDC has been a footgun: because AWS won't allow unifying/customizing the audience claim, configuring it instead of ESC has repeatedly caused confusing claims-handling issues for customers. ESC OIDC is the right path for almost everyone.
The Deployments OIDC UI still appears automatically in the two cases that legitimately need it:
- The stack already has Deployments OIDC configured — existing config is never hidden or made uneditable.
- The org uses customer-managed deployment runners (agent pools), which can't rely on ESC OIDC (e.g. restricted-network setups).
Notes on the change:
- Console UX only — no API / CLI / Pulumi Service Provider behavior change.
- Gated by a LaunchDarkly flag; the two safety-net cases above are computed backend-side.
- Self-hosted: the section is always shown, unaffected.
What to update
A recent PR already made the "prefer ESC OIDC" guidance clearer in the docs, but we now need to update the docs specifically for the UI behavior change:
- Document that Deployments OIDC is legacy and that ESC OIDC is the recommended default for configuring OIDC with Pulumi.
- Explain that the Deployments OIDC settings section is now hidden by default in the Console and only surfaces for the two edge cases listed above.
- Make clear Deployments OIDC is only needed for edge cases (existing configs, and customer-managed deployment runners / agent pools that can't use ESC OIDC).
- Note that self-hosted installations always show the section.
References
Summary
We need to update the OIDC documentation to reflect a recent change in the Pulumi Cloud Console UI and to more strongly steer users toward ESC OIDC instead of the legacy Deployments OIDC.
Background
The legacy OpenID Connect section in a stack's Deployment Settings is now hidden by default for orgs that haven't already set up Deployments OIDC. New users are steered to ESC OIDC instead of the older, error-prone Deployments OIDC config.
Deployments OIDC has been a footgun: because AWS won't allow unifying/customizing the audience claim, configuring it instead of ESC has repeatedly caused confusing claims-handling issues for customers. ESC OIDC is the right path for almost everyone.
The Deployments OIDC UI still appears automatically in the two cases that legitimately need it:
Notes on the change:
What to update
A recent PR already made the "prefer ESC OIDC" guidance clearer in the docs, but we now need to update the docs specifically for the UI behavior change:
References