Organize workspaces with projects

HCP Terraform 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 HCP Terraform 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. You can also use projects to control which version control repositories your workspaces have access to. These features help 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 HCP Terraform workflows. If you are new to Terraform, complete the Get Started tutorials first. If you are new to HCP Terraform, complete the HCP Terraform Get Started tutorials first.

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

• An HCP Terraform account with the Standard edition.
• Organization owner permissions for this account.

Create projects

Every workspace in an HCP Terraform organization must belong to exactly one project. By default, any new workspace you create will exist in your organization's Default Project. HCP Terraform 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 landing page. Click + New Project.

Enter Platform as the project name, then click Create.

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

Return to the Projects landing page to review the projects in your organization. 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 all Projects permissions to administer all of the projects in your organization. You will review the interactions of these permissions later in this tutorial.

Once you create a project, you can 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

Navigate to your organization's Workspaces landing page. Click the New dropdown and select Workspace. Select the Application project for this new workspace, then click Create.

Select the CLI-Driven Workflow.

Name your new workspace learn-terraform-projects-app.

Return to the 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

You can filter workspaces on the Workspaces page by project. On the Workspaces page, open the project drawer and select the Application project. HCP Terraform now lists only the learn-terraform-projects-app workspace.

You can move a workspace to a different project from the Workspaces page by hovering over the workspace you want to move, clicking on the ellipses (...) button that appears, and selecting Change project.

You can 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 HCP Terraform. Projects give team members permissions to safely create and manage only the workspaces they need without giving them access to all workspaces in your HCP Terraform organization, helping you follow least privilege principles.

Under your HCP Terraform organization's Settings landing page, 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 page. Find the Application project and click on the ellipses (...) button in the Actions column, the select Edit project.

From this page, you can update a project name, manage project access, and delete a project. Select Team access from the left navigation pane, then + 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 team 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 all Workspaces organization permission can manage all workspaces, but can only create workspaces within the default project. Teams with both the Manage all projects and Manage all workspaces permissions can manage projects and workspaces 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 HCP Terraform 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 HCP Terraform projects and scoped their access to specific teams in your HCP Terraform 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 HCP Terraform 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 HCP Terraform
• Learn how to use HCP Terraform 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 HCP Terraform.