Deployment Permissions
This page explains how permissions work in Pulumi Deployments and how to configure them for your deployment needs.
Default Deployment Permissions
By default, the permissions that are granted to a deployment depend on how the deployment is being invoked:
- If the deployment is created via the REST API or by using the Actions buttons in the Pulumi Cloud console, it is granted the permissions of the user that has executed the action.
- If a deployment is created because of a
git push
or a pull request, it uses an ephemeral stack token that has admin permissions on only the stack itself, but nothing else.
Permissions Impact
The permission model has the following practical implications:
If your organization has default stack permissions set to
NONE
, then any deployment created by agit push
or a pull request will not be able to access any Stack References, and will fail if it tries to do so.If your organization has default environment permissions set to
NONE
, then any deployment created by agit push
or a pull request will not be able to access any ESC Environments that are listed in the stack’s configuration file.
Granting Additional Permissions
If you want to change the permissions that are granted to a deployment, you can do so by setting the PULUMI_ACCESS_TOKEN
environment variable to a token with the desired permissions in the stack’s deployment settings.
This token can be an individual, team, or organization token, and it will grant the deployment the permissions that are associated with the token. If this environment variable is set, it will be used regardless of how the deployment was created (REST API, git push
, etc.).
Minimum Required Token Permissions
If using an individual or team token, the token must have at minimum:
WRITE
access to the stack that is being deployedREAD
access to any stacks from which Stack References are being usedOPEN
access to any ESC environment that is listed in the stack’s configuration file, including any environments that are imported transitively
Using ESC with Deployments
For enhanced security and simplified credential management, we recommend configuring your stack to use Pulumi ESC for cloud credentials and ensuring the Deployment has an appropriately scoped Pulumi token.
This approach offers several advantages:
- Dynamic, short-lived credentials instead of long-lived static credentials
- Fine-grained control over credential scope and permissions
- Centralized credential management
- Reduced risk of credential exposure
- Complete audit trail of credential usage
Configuring ESC for Deployments
- Create an ESC environment with the appropriate cloud provider credentials
- Reference this environment in your Pulumi stack configuration
- Create a Pulumi access token with the appropriate permissions (as described above)
- Add this token as the
PULUMI_ACCESS_TOKEN
environment variable in your deployment settings
For more information on setting up ESC environments, see the ESC documentation.
You can use ESC with pre-run commands in Deployments by prefixing each command with pulumi env run
. For example:
pulumi env run my-aws-env -- aws s3 ls
This executes the aws s3 ls
command with credentials from your my-aws-env
ESC environment.
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.