Terraform
Project permissions
Project-level permissions apply to all workspaces within a specific project.
Background
If you are in an HCP Terraform organization, you can manage user access and permissions through teams. Refer to the following topics for information about setting permissions in HCP Terraform:
- Set permissions
- Organization permissions reference
- Workspace permissions reference
- Effective permissions provides information about competing permissions.
Project roles and permissions
A role is a preselected set of permissions that you can assign to a team.
The following table shows the permissions granted by each project role. Each role builds upon the previous level, with Admin granting the most comprehensive access.
Project admin
Each project has a group of permissions under the Admin role. This role grants permissions for the project and the workspaces that belong to that project.
Members of teams with Admin permissions for a project have general workspace permissions for every workspace in the project, and the ability to do the following:
- Read and update project settings.
- Delete the project.
- Move workspaces into or out of the project. This also requires project admin permissions for the source or destination project.
- Grant or revoke project permissions for visible teams. Project admins cannot view or manage access for teams that are secret, unless those admins are also organization owners.
- Admin access for all workspaces in this project, including the ability to:
- Create, read, update, and delete workspaces in this project.
- Initiate, cancel, or apply runs for workspaces in the project.
Project maintain
Assign the Maintain role when users are responsible for managing existing infrastructure in a single project. The role also grants the ability to create new workspaces in that project. Maintain access grants full control of everything in the project, including the following permissions:
- Read the project name.
- Admin access for all workspaces in this project, including the ability to:
- Create, read, update, and delete workspaces in this project.
- Initiate, cancel, or apply runs for workspaces in the project.
Project write
Assign the Write role when users are responsible for most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following permissions:
- Read the project name.
- Write access for all workspaces in this project, including the ability to:
- Read workspaces in this project.
- Initiate, cancel, or apply runs for workspaces in the project.
Project read
Assign the Read role to users who need to view information about the status and configuration of managed infrastructure but are not responsible for maintaining that infrastructure. Read access grants the permissions to:
- Read the project name.
- Read access for all workspaces in this project.
Custom project role
Custom permissions enable you to assign specific and granular permissions to a team. You can use custom permission sets to create task-focused permission sets and control sensitive information.
You can create a set of custom permissions using any of the permissions listed in the Project roles and permissions table.
Project access
The following table summarizes the available project access permissions. Click on a specific permission name to learn more about that permission level.
| Permission name | Description |
|---|---|
| Read | View information about the project including the name. |
| Update | Update the project name. |
| Delete | Delete the project. |
Read
Allows users to view information about the project including the name.
Update
Allows users to update the project name. This permission implies permission to read.
Delete
Allows users to delete the project. This permission implies permission to update and read.
Workspace management
The following table summarizes the available workspace management permissions within the project.
| Permission name | Description |
|---|---|
| Create workspaces | Create workspaces in the project. |
| Move workspaces | Move workspaces into or out of the project. |
| Delete workspaces | Delete workspaces in the project. |
Create workspaces
Allow users to create workspaces in the project. This grants read access to all workspaces in the project.
Move workspaces
Allows users to move workspaces out of the project. A user must have this permission on both the source and destination project to successfully move a workspace from one project to another.
Delete workspaces
Allows users to delete workspaces in the project.
Depending on the organization's settings, workspace admins may only be able to delete the workspace if it is not actively managing infrastructure. Refer to Deleting a Workspace With Resources Under Management for details.
Team management
The following table summarizes the available team management permissions for the project.
| Permission name | Description |
|---|---|
| None | No access to view teams assigned to the project. |
| Read | View teams assigned to the project for visible teams. |
| Manage | Set or remove project permissions for visible teams. |
None
No access to view teams assigned to the project.
Read
Allows users to see teams assigned to the project for visible teams.
Manage
Allows users to set or remove project permissions for visible teams. Project admins can not view or manage teams with Visibility set to Secret in their team settings unless they are also organization owners. Refer to Team visiblity for more information.
Run access
The following table summarizes the available run access permissions for workspaces within the project.
| Permission name | Description |
|---|---|
| Read | View information about workspace runs within the project. |
| Plan | Queue Terraform plans in workspaces within the project. |
| Apply | Approve and apply Terraform plans in workspaces within the project. |
Read
Allows users to view information about remote Terraform runs, including the run history, the status of runs, the log output of each stage of a run, and configuration versions associated with a run.
Plan
Allows users to queue Terraform plans in workspaces within the project, including both speculative plans and normal plans. Normal plans must be approved by a user with permission to apply runs. This permission implies permission to read.
Apply
Allows users to approve and apply Terraform plans, causing changes to real infrastructure. This permission implies permission to plan and read.
Variable access
The following table summarizes the available variable access permissions for workspaces within the project. Refer to Manage variables and variable sets for more information about variables.
| Permission name | Description |
|---|---|
| No access | No access to workspace variables within the project. |
| Read | View workspace variables within the project. |
| Read and write | Edit workspace variables within the project. |
No access
No access is granted to the values of Terraform variables and environment variables for workspaces within the project.
Read
Allows users to view the values of Terraform variables and environment variables for workspaces within the project. Note that variables marked as sensitive are write-only and can't be viewed by any user.
Read and write
Allows users to read and edit the values of variables in workspaces within the project.
Variable set access
The following table summarizes the available permissions for creating and managing sets of variables in the project. Refer to Manage variables and variable sets for more information about variable sets.
| Permission name | Description |
|---|---|
| None | No access to variable sets owned by the project. |
| Read | View variable sets owned by the project. |
| Manage | Create, update, and delete variable sets owned by the project. |
None
No access to variable sets owned by the project, but users can view variable sets that have been applied to the project and its workspaces if their Variable access permission is set to Read or Read and write .
Read
Allows users to view variable sets owned by this project.
Manage
Allows users to read, create, update, and delete variable sets owned by the project.
State access
The following table summarizes the available state access permissions for workspaces within the project. Refer to State to learn about state in Terraform.
| Permission name | Description |
|---|---|
| No access | No access to workspace state within the project. |
| Read outputs only | Access public outputs from workspace state within the project. |
| Read | Read complete state files from workspaces within the project. |
| Read and write | Create new state versions in workspaces within the project. |
No access
No access is granted to the state file from workspaces within the project.
Read outputs only
Allows users to access values in the workspace's most recent Terraform state that have been explicitly marked as public outputs. This permission is required to access the State Version Outputs API endpoint.
Read
Allows users to read complete state files from workspaces within the project. State files are useful for identifying infrastructure changes over time, but often contain sensitive information. This permission implies permission to read outputs only.
Read and write
Allows users to directly create new state versions in workspaces within the project. This permission is required for performing local runs when the workspace's execution mode is set to "local". This permission implies permission to read.
Other controls
The following table summarizes additional control permissions for the project.
| Permission name | Description |
|---|---|
| Download Sentinel mocks | Download data from runs for developing Sentinel policies. |
| Lock/unlock workspaces | Manually lock workspaces to prevent runs. |
| Manage workspace Run Tasks | Associate or dissociate run tasks with workspaces. |
Download Sentinel mocks
Allows users to download data from runs in workspaces within the project in a format that can be used for developing Sentinel policies. This run data is very detailed, and often contains unredacted sensitive information.
Refer to Generate mock Sentinel data with Terraform for more information about Sentinel mocks.
Lock/unlock workspaces
Allows users to manually lock workspaces within the project to temporarily prevent runs. When a workspace's execution mode is set to Local, enable the Lock/unlock workspaces permission to perform local CLI runs using the workspace's state.
Refer to Workspace settings for information about execution modes and locking workspaces.
Manage workspace Run Tasks
Allows users to associate or dissociate run tasks with workspaces within the project. HCP Terraform creates run tasks at the organization level, where you can manually associate or dissociate them with specific workspaces. Refer to Set up run task integrations for more information about run tasks.