Pulumi Teams is how you grant people or groups access to your Pulumi stacks and projects.
Imagine you have a Pulumi project that deploys your entire application infrastructure. You’ve got a dev stack for local testing, a staging stack for pre-production, and a prod stack for live traffic. Now, you need your team to be able to deploy to dev and staging, but only a select few should have prod access. Pulumi Teams is the mechanism that enforces this separation of duties directly within Pulumi Cloud.
Let’s see it in action.
First, we need to create a "Team" in Pulumi Cloud. This team will be a container for our users and will be the entity we grant permissions to.
pulumi org team create --organization=<your-org-name> --name=<your-team-name>
For example:
pulumi org team create --organization=my-awesome-company --name=infra-engineers
Now, we need to add users to this team. You can add individual users by their Pulumi username.
pulumi org team add-member --organization=<your-org-name> --team=<your-team-name> --user=<pulumi-username>
Example:
pulumi org team add-member --organization=my-awesome-company --team=infra-engineers --user=alice
pulumi org team add-member --organization=my-awesome-company --team=infra-engineers --user=bob
Once users are in a team, we can grant that team permissions to specific projects or even individual stacks. This is where the access control really happens. Permissions are granted at the organization level, and then you can scope them down.
Let’s say we have a project named my-app-infra. We want the infra-engineers team to have the ability to deploy and update stacks within this project.
pulumi org grant --organization=<your-org-name> --team=<your-team-name> --project=<project-name> --permissions=update,deploy
Example:
pulumi org grant --organization=my-awesome-company --team=infra-engineers --project=my-app-infra --permissions=update,deploy
This command tells Pulumi Cloud: "The infra-engineers team can update and deploy to any stack within the my-app-infra project in the my-awesome-company organization."
You can also grant permissions to all projects within an organization:
pulumi org grant --organization=<your-org-name> --team=<your-team-name> --all-projects --permissions=read
Example:
pulumi org grant --organization=my-awesome-company --team=infra-engineers --all-projects --permissions=read
This allows the team to view the state and history of all projects, but not necessarily deploy to them.
The key levers you control are:
- Teams: Groupings of users.
- Permissions: The actions users in a team can perform (e.g.,
read,update,deploy,admin). - Scope: The target of the permissions – an entire organization, a specific project, or even a single stack (though stack-level permissions are less common and usually managed via project-level grants).
When a user attempts an operation, like pulumi up, Pulumi Cloud checks their team memberships and the permissions granted to those teams against the target stack. If the necessary permissions are present, the operation proceeds; otherwise, it’s denied.
It’s important to understand that permissions are additive. If a user is part of multiple teams, they inherit the combined permissions from all those teams for any given resource. For instance, if Alice is in infra-engineers (which has deploy on my-app-infra) and also in auditors (which has read on my-app-infra), Alice will have both deploy and read permissions on that project.
Pulumi also supports the concept of "service accounts" which are non-human entities (like CI/CD pipelines) that can be granted permissions through API tokens. These service accounts can also be added to teams, allowing you to manage access for automated deployments consistently.
The most granular permission you can grant is admin, which allows a team to manage permissions for other teams and users on a given project or stack. This is typically reserved for core platform or security teams.
The next step in managing your cloud infrastructure access is often implementing GitOps workflows, where your Git repository becomes the source of truth for infrastructure changes, and Pulumi integrates with this model.