Docs Home Pulumi IaC Pulumi ESC Pulumi Insights Pulumi IDP Pulumi Cloud Packages Tutorials
  1. Docs
  2. Pulumi Cloud
  3. Identity & access management
  4. Role-Based Access Control (RBAC)
  5. Roles

Roles

    Custom roles and permissions are currently an Early Access feature. To be granted access to this feature, please reach out to our sales team.

    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 permissions 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

    Role
    		Description
    AdminFull access to all organization resources and settings. Can manage members, roles, and organization-wide configurations.
    MemberBasic access to view organization resources and participate in stack operations. Cannot modify organization settings. Default access for members to organization entities can be controlled via the Access management page under Settings.
    Billing ManagerAccess to view and manage billing information. Cannot modify other organization settings or resources.

    Custom Roles

    Custom roles are only available to organizations using Pulumi Enterprise Edition and Pulumi Business Critical Edition. To learn more about editions visit the pricing page.

    You can create and manage custom roles to define more granular access controls for your organization. Custom roles allow you to:

    • Bundle specific permissions for different resource types
    • Control access to like resources or groups of resources

    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

    View all organization roles.

    To create a new role, click Create custom role

    Create a role page.

    You will need to provide a unique name for the role. Optionally, but recommended, you can provide a description to contextualize the role and its purpose.

    Providing a name and description for the role.

    You can assign permissions to the role to be applied globally across all RBAC entities of a specific type, or to individual entities (specific stacks, environments, or insights accounts).

    You’ll first see the option to assign permissions to entities globally within the org:

    Assigning a global permission to the role.

    You can also select Add Pulumi entities to assign permissions to specific entities. You’ll be able to search for stacks, environments, or insights accounts within your org and assign existing permissions of their entity type to the entity.

    Assigning permissions to two stacks.

    When done, click Create role. You should be taken back to the Roles page, where you will see your new role:

    Your role has been created, visible here on the Roles page.

    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

    Currently, roles can be assigned to organization tokens. When early access has ended for this feature, you will be able to assign roles to teams or individual users in your organization.

    Assigning a role to an organization token

    Organization tokens can be assigned both default and custom roles to narrow their scope within your organization.

    Follow the process to create an organization token.

    Create an organization access token, a role field is available.

    Note that you will have the ability to provide a role. Choose a default or custom role to assign to it.

    Assign a role to your organization token.

    Proceed with creating the token. The access token you have created will be narrowed in scope according to the permissions of the role within your organization.

    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 permissions in a way that maps to real-world concepts within your org, allowing for easy reuse.
    3. Regular Review: Periodically schedule reviews of role assignments and scopes.
    4. Documentation: Document the purpose and scopes of custom roles both internally and within the role’s metadata.