Roles

A role in Pulumi Cloud is the primary way to define what resources a principal (user, team, or machine token) can access and what they can do with them. Roles allow you to apply permission sets to a set of entities and assign this access to a principal.

Default roles

Pulumi Cloud provides several default roles that you can use to quickly get started:

Organization roles

Custom roles

You can create and manage custom roles to define more granular access controls for your organization. Custom roles combine entity access rules (direct, global, or tag-based) with an organization access level.

Creating custom roles

To create a custom role, you must be an organization admin.

Visit the Roles page under Settings to see your organization roles

.

To create a new role, click Create custom role. Provide a unique name and, optionally, a description to contextualize the role’s purpose.

A custom role can include any combination of the following entity access rule types, plus an organization access level.

Rule types

Direct entity access

Direct rules grant a permission set to individually selected entities. Choose the entity type (stack, environment, or insights account), select Select specific [type], then click Choose [type] to open a searchable list.

.

A dialog lists the entities in your organization. You can search by name to filter the list.

.

Check the entities to include in the rule, then click Confirm selection.

.

After confirming, click Save rule. The Entity Access section displays a table of all configured rules, and you can add more with Add rule.

Global entity access

Global rules apply a permission set to all entities of a given type within the organization. Choose the entity type and select Apply to all [type] to grant the chosen permission set across all current and future entities of that type.

Tag-based rules (ABAC)

Tag-based rules (also called ABAC — attribute-based access control) grant a permission set when a resource’s tags match defined conditions. Each rule has:

• Entity type — Stack, environment, or insights account.
• Tag conditions — One or more conditions on resource tags (e.g. tag env equals production, or tag team exists).
• Permission set — The permission set to grant when the conditions match a resource.

Why use them: Grant access to many resources at once by tag (e.g. all stacks with team=platform) without listing each resource individually. Useful for large organizations.

How it works: When evaluating access, Pulumi Cloud checks the user’s roles (and the roles of the teams they belong to). For each tag rule in those roles, it evaluates the resource’s tags against the rule’s conditions. If they match, the rule’s permission set is applied to that resource.

To configure a tag-based rule, choose the entity type and select Set conditions, then enter one or more tag key/value conditions and choose a permission set.

.

In the Pulumi Cloud UI and API, these rules may be labeled “tag rules” or “tag-based access control rules”; ABAC (attribute-based access control) is the general industry term.

Organization access sets the permission level for organization-level operations (e.g. creating stacks, managing billing, audit logs). This applies to the organization as a whole and is separate from the entity-based rules above.

.

When done, click Create role.

You can now assign this role to principals in your organization.

Managing custom roles

To update or delete a custom role, simply click on the ellipsis icon next to the role on the Roles page.

Role assignment

Roles can be assigned to organization access tokens, users, and teams. Effective permissions are the union of the user’s organization role and all roles assigned to the teams they belong to (composability).

Organization access tokens

Organization access tokens can be assigned one role (default or custom) that defines the token’s permissions across the organization.

Follow the process to create an organization token.

.

Choose a default or custom role to assign to the token.

.

The token’s access is limited to the permissions of that role within your organization.

Users

Each organization member has one organization role (Admin, Member, Billing Manager, or a custom role). When your organization has custom roles and Assign custom roles to users is enabled (in Settings > Access Management), admins can assign any custom role to individual members. Members who have the Member organization role and have not been given an explicit custom role use the organization default role if one is set; otherwise they use the built-in Member role.

Teams

When your organization has custom roles enabled, teams can have role assignments: one or more roles (default or custom). Team members receive the union of their own user role and all roles assigned to the teams they belong to. So team role assignments add on top of each member’s baseline role.

Best practices

When working with roles in Pulumi Cloud, consider these best practices:

1. Principle of least privilege: Assign only the scopes necessary for users to perform their tasks.
2. Role reusability: Design custom roles and permission sets in a way that maps to real-world concepts within your org, allowing for easy reuse.
3. Tag-based rules: Use tag-based rules to grant access to many resources by tag (e.g. team=platform) without listing each resource.
4. Regular review: Periodically schedule reviews of role assignments and scopes.
5. Documentation: Document the purpose and scopes of custom roles both internally and within the role’s metadata.

Related resources

• Teams
• Permission sets
• Scopes