Create a workspace

Once you have created an HCP Terraform account and created or joined an organization, you can start managing infrastructure with HCP Terraform. In this tutorial, you will create a CLI-driven workspace.

Prerequisites

While Terraform can provision resources on many different providers and connect with several popular version control systems (VCSs), this tutorial requires:

• an HCP Terraform account and organization
• Terraform v1.1+ installed locally and configured with your HCP Terraform token
• an AWS account
• a GitHub account

Clone a Github repository

Clone the example GitHub repository for this tutorial, which contains the Terraform configuration that defines an AWS EC2 instance and its attributes.

$ git clone https://github.com/hashicorp/learn-terraform.git

Change to the repository directory.

$ cd learn-terraform

Open the configuration in your code editor to review it. It contains Terraform configuration files, which define and expose information about your infrastructure:

• main.tf specifies the AWS provider, a provider plugin that Terraform will use to manage your AWS resources. The configuration defines an EC2 instance and uses a Terraform data source to access a machine image to use for the instance.
• variables.tf defines the input variables that are referenced in main.tf, which make the configuration customizable. You will define these variables in the HCP Terraform UI later on in this tutorial.
• outputs.tf defines the information about your infrastructure that HCP Terraform will display to you when it makes changes.
• terraform.tf defines version constraints for Terraform and the AWS provider and the cloud block for the HCP Terraform integration.

Update configuration

Open the terraform.tf file and update the name of the organization in the cloud block to your own HCP Terraform organization. You can find your organization name in the breadcrumbs of the HCP Terraform UI.

terraform {

  cloud {
    organization = "organization-name"

    workspaces {
      name = "learn-terraform"
    }
  }

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 3.28.0"
    }
  }

  required_version = ">= 1.1.0"
}

Create the workspace

This cloud block specifies which HCP Terraform organization and workspace to use for the operations in this working directory. When using the CLI-driven HCP Terraform workflow, running terraform init on configuration with a cloud block creates the HCP Terraform workspace specified in the block, if it does not already exist.

In your terminal, run terraform init to initialize the configuration and create your new HCP Terraform workspace.

$ terraform init
Initializing HCP Terraform...

Initializing provider plugins...
- Finding hashicorp/aws versions matching "~> 3.28.0"...
- Installing hashicorp/aws v3.28.0...
- Installed hashicorp/aws v3.28.0 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

HCP Terraform has been successfully initialized!

You may now begin working with HCP Terraform. Try running "terraform plan" to
see any changes that are required for your infrastructure.

If you ever set or change modules or Terraform Settings, run "terraform init"
again to reinitialize your working directory.

As part of the initialization process, Terraform created the new learn-terraform workspace in your HCP Terraform organization, configured for CLI-driven runs.

Every HCP Terraform workspace belongs to a project, which is a group of workspaces. When you create your workspace using this automated CLI workflow, HCP Terraform adds the workspace to your organization's Default project unless you set the project argument in your configuration's cloud block. Projects help you organize your workspaces into groups, making it easier to find workspaces in large HCP Terraform organizations.

Assign variable set to workspace

If you are not using a global variable set with your AWS credentials in your HCP Terraform organization, assign the variable set to your new workspace.

Navigate to your new learn-terraform workspace. Select Variables in the workspace's menu. Under Variable sets, click Apply variable set.

Select your AWS Credentials variable set, then click Apply variable set.

Your workspace can now use your AWS credentials. If you update the values of the variables in the variable set, those changes will propagate to this workspace and apply to all future runs.

Next Steps

In this tutorial, you updated a cloud block for your own HCP Terraform organization, created a CLI-driven HCP Terraform workspace, and configured it with a variable set.

Next, you will review, configure, and use your new workspace.