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’s Team & Governance tier, 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.

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 Get Started collection 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 Team & Governance tier.
• 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.

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 Project & workspace permissions, select No access. 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

Terraform Cloud offers two project 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.
• 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.

Select the application team from the dropdown menu. In the Admin permissions set box, click Assign permissions, then click Save.

Platform teams may need access to the services other teams manage. Grant the platform team admin privileges for the Application project as well.

With these settings, both the application and platform team can manage the project and its workspaces.

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.