Organize workspaces with projects

Terraform Cloud projects let you organize your workspaces into groups. You can structure your projects based on your organization's resource usage and ownership patterns, such as teams, business units, or services. With Terraform Cloud Standard Edition, you can give teams access to groups of workspaces using projects.

Projects make it easier to scope and assign workspace access, reducing the likelihood of permissions errors. Instead of manually visiting each workspace and adding the necessary teams to it, you can group related workspaces into projects, and grant teams access to the entire project. This helps teams manage the workspaces they are responsible for while making it easier for organization owners to follow the principle of least privilege.

You can specify project-level scope for variable sets. Apply variable sets to a specific project to automatically associate the variables with all current and future workspaces in the project, without having to select workspaces individually. For example, you can scope a credentials variable set to a project for a specific team, business unit, or service, to avoid leaking the values to workspaces that do not need them. You can also apply policy sets at a project level, helping you consistently enforce your organization's governance standards on all workspaces in the project.

In this tutorial, you will create two projects and scope access to the projects to different teams. You will also review the interaction of different permissions relating to projects.

Prerequisites

This tutorial assumes that you are familiar with the Terraform and Terraform Cloud workflows. If you are new to Terraform, complete the Get Started tutorials first. If you are new to Terraform Cloud, complete the Terraform Cloud Get Started tutorials first.

In order to complete this tutorial, you will need the following:

• A Terraform Cloud account with the Standard edition.
• Organization owner permissions for this account.

Create projects

Every workspace in a Terraform Cloud organization must belong to exactly one project. By default, any new workspace you create will exist in your organization's Default Project. Terraform Cloud automatically creates this project for every organization. You can rename it, but you cannot delete it.

Once your organization has multiple projects, you can choose which project to create a new workspace in and move existing workspaces to other projects.

Navigate to your organization's Projects & workspaces landing page. Click New in the top right corner and select Project in the dropdown menu.

Enter Platform as the project name, then click Create.

Next, follow the same workflow to create another project named Application.

If the project drawer is not already open, click the left chevron next to Workspaces to review the projects in your organization. Terraform Cloud now lists your projects. Since you are an organization owner, you can view all of the projects. Non-owner users need either project admin permissions or organization-wide Manage Projects & Workspaces permissions to access all the projects in your organization. You will review the interactions of these permissions later in this tutorial.

Once you create a project, you could create and associate variable sets with the project. All current and future workspaces in the project will automatically access the variable set. For more information, see the Variable Sets documentation.

Create workspaces in projects

Click the New button again, but this time select Workspace. Select the CLI-driven workflow.

Name your new workspace learn-terraform-projects-app. Because your organization now contains multiple projects and you have access to all of them, you can select which project to add this new workspace to.

Select the Application project for this new workspace, then click Create workspace.

Return to the Projects & workspaces page and follow the workflow again to create another CLI-driven workspace named learn-terraform-projects-networking, this time under the Platform project.

Filter and move workspaces

When you select a project, Terraform Cloud filters the workspaces list to only display workspaces within that project. On the Projects & workspaces page, select the Application project in your project drawer. Terraform Cloud now lists only the learn-terraform-projects-app workspace.

You could move a workspace to a different project from the Projects & workspaces page by hovering over the workspace you wanted to move, clicking on the ellipses (...) button that appears, and selecting Change project.

You could also move a workspace to another project at any time from the workspace's general settings page.

Create teams

By using projects to define access permissions, you can scope the resources a user can interact with in Terraform Cloud. Projects give team members permissions to safely create and manage only the workspaces they need without giving them access to all workspaces in your Terraform Cloud organization, helping you follow least privilege principles.

Under your Terraform Cloud Organization settings navigate to Teams. Create a new team named platform. Under both Project permissions and Workspace permissions, select None. Do not add any additional permissions.

Now, create another team named application with the same permissions settings.

From the team creation and settings pages, you can only set organization-wide permissions. You must grant permissions to specific workspaces and projects from their respective settings pages. By setting no access in the team settings, members of this team will only have access to the projects or workspaces that you explicitly add them to.

Designing your team privileges this way lets you avoid giving overly-permissive, organization-wide privileges to users who do not need them.

Manage project permissions

You can specify custom permissions for a project, or assign one of four fixed permission sets:

• Admin lets team members fully administer the project and all workspaces in it. They can read, modify, and delete the project, create new workspaces in the project, move workspaces into or out of the project, and manage project access for teams that are visible to them.
• Maintain lets team members create and manage workspaces within a project, and provision infrastructure within those workspaces. They cannot delete the project, manage its permissions, or move workspaces into or out of the project.
• Write lets team members provision infrastructure within a project's workspaces, but not manage the workspaces or project.
• Read lets team members read the project name and details for any workspaces in that project. This permission set could be useful for other teams that need to reference infrastructure resource data, but not manage the resources themselves.

Return to the Projects & workspaces page and open the project drawer. Hover over the Application project and click the edit button that appears.

From this page, you can update a project name, manage project access, and delete a project. Click + Add team.

In this scenario, you will assign project permissions in a way that lets teams use projects and their workspaces to manage infrastructure without making them responsible for the project itself.

Select the application team from the dropdown menu. Select the Maintain permissions set , then click Assign permissions.

Next, grant the platform team admin privileges for the Application project.

These settings enable a self-service model: the application can manage infrastructure within the project, and only the platform team can administer the project and manage its permissions.

Next, navigate to the Platform project settings page and grant the platform team Admin privileges. The application team will not have access to the workspaces in the project, and will not even be able to see that the project or workspaces exist.

Review access implications

When using projects to define access permissions, remember that workspace, project, and organization-wide permissions can overlap.

Organization-wide permissions supersede the scoped privileges defined on specific workspaces and projects. Teams with the Manage Workspaces organization permission can manage all workspaces, but can only create workspaces within the default project. Teams with Manage all projects & workspaces permissions can manage projects they do not have explicit permissions for. When auditing who has access to a specific project or workspace, do not forget to include users who have organization-level permissions.

The projects and workspaces a user has access to can affect their ability to manage cross-workspace interactions, such as remote state sharing and run triggers. Access permissions will affect a user's ability to manage cross-workspace settings, but not run behavior itself.

In this tutorial, the application team cannot share state for the application workspace with any of the workspaces in the Platform project. However, the platform team can enable state sharing from their workspaces to application workspaces because they have access to both projects. Members of the application team would then be able to create successful Terraform runs in their workspaces.

Access to another workspace's state lets users read all data about that workspace's resources, even if they do not have explicit organization, project, or workspace level access. For this reason we recommend using provider-specific data sources instead of the remote state data source wherever possible.

Clean up projects and workspaces

You can only delete empty Terraform Cloud projects.

Navigate to the learn-terraform-projects-app workspace's settings page and delete the workspace.

Now, delete the learn-terraform-projects-networking workspace.

Navigate to the Platform settings page from the project drawer. Under Delete project, click Delete. Click Delete again to confirm the operation.

Repeat these steps to delete the Application project.

Next steps

In this tutorial, you created Terraform Cloud projects and scoped their access to specific teams in your Terraform Cloud organization. You learned how to manage projects and workspaces and reviewed the interaction of workspace, project, and organization-wide permissions.

To learn more about how Terraform Cloud can help you enforce access guardrails and cloud operation best practices, review the following resources:

• Learn how to detect infrastructure drift and enforce OPA policies in Terraform Cloud
• Learn how to use Terraform Cloud run tasks and HCP Packer to ensure machine image compliance.
• Learn how to enable no-code Terraform provisioning
• Review the interaction of workspace, project, and organization-wide permissions in Terraform Cloud.