Terraform
Organize workspaces with projects and variable sets
In the previous tutorial, you created a workspace and assigned variable values so that your Terraform runs can authenticate to your cloud provider. As your infrastructure operations scale, you may need to use multiple workspaces to effectively manage your resources.
Projects let you organize your workspaces into groups so that you can manage their access, variables, and settings collectively. To manage variables across workspaces in bulk, you can create variable sets and assign them to your projects. When you update a variable in a set, the change propagates to every workspace and project you assigned the variable set to.
In this tutorial, you will create a project and move your workspace into it. Then, you will create a new variable set and assign it to the new project.
Prerequisites
To follow this tutorial, you will need:
- An HCP Terraform account and organization
- An AWS account and associated
credentials
that allow you to create resources in the
us-west-2region, including an EC2 instance, VPC, and security groups. - A GitHub account.
- The
learn-hcp-terraformworkspace you created in the previous tutorial.
Create new project
Log in to HCP Terraform, then click Projects in the left navigation panel. This page lists all of the projects in your organization. If you recently created this organization, you may only see one project named Default Project.
To create a new project, click the New project button in the top-right corner. Name the project Learn Terraform, then click Create.
After you create your project, HCP Terraform shows you the project overview page. From this page, you can see which workspaces are in the project and access the project's settings.
Create variable set
Next you will create a new variable set and assign it to the project.
From your project overview page, click Settings, then click Variable sets. Click Create project variable set to create a new project-scoped variable set.
Tip
In this tutorial, you create a project-scoped variable set. You can also create variable sets that apply to every project and workspace in the organization. Refer to the create variable sets documentation for more information.
Name the variable set learn-aws. Under Variable set scope, choose Apply to the entire project. Then, under Variables, create two new variables.
| Category | Key | Value | Sensitive |
|---|---|---|---|
| Environment | AWS_ACCESS_KEY_ID | Your AWS secret ID | Disabled |
| Environment | AWS_SECRET_ACCESS_KEY | Your AWS secret key | Enabled |
After you create both variables, click Create variable set. Because you assigned this variable set to the entire project, every workspace in the project will automatically access these two environment variables, allowing your workspaces to authenticate to AWS.
Move workspace to new project
Next, move your workspace to the new project. Return to your organization overview page, click Workspaces, then choose your learn-hcp-terraform workspace.
From your workspace overview page, click Settings in the left navigation panel, click the drop-down under Project, and choose your Learn Terraform project. Scroll to the bottom of the page and click Save settings.
HCP Terraform applies the variable values according to precedence. Your workspace inherits the variables you defined in your project's variable set, but workspace variables override variables in a project variable set.
Because you no longer need to define your AWS credentials as workspace variables, remove them from your workspace. Click the learn-hcp-terraform link in the top-left to return to your workspace overview, then click Variables.
Open the ellipses menu (...) for the AWS_ACCESS_KEY_ID variable, then click Delete. Confirm that you want to delete this variable when prompted. Repeat this process for the AWS_SECRET_ACCESS_KEY variable.
Verify that your workspace uses the project's variable set by starting a new plan-only run. In the top-right corner, click New run, click the drop-down under Run type, then choose Plan only. Click Start to begin the new run.
Ensure that the plan-only operation completes successfully. Though you did not update your configuration, Terraform still needs to authenticate with AWS to gather information about your virtual machine. This validates that your workspace now uses the project's variable set to set the AWS environment variables.
Next steps
In this tutorial, you created a new project to organize workspaces, then you created a new variable set with your AWS credentials. You assigned this variable set to the project, so that every workspace in the project has access to the credentials. You also moved your workspace to the new project and deleted the workspace-specific variables to verify that it uses the project's variable set.
By organizing your workspaces into projects and using variable sets, you can enable infrastructure operations in new workspaces without needing to manage variables and credentials in each individual workspace.
Continue to the next tutorial to learn how to link workspaces together, share outputs, and trigger runs in one workspace from another.