Create a Workspace

Once you have created a Terraform Cloud account and created or joined an organization, you can start managing infrastructure with Terraform Cloud. 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:

• a Terraform Cloud account and organization
• Terraform v1.1+ installed locally and configured with your Terraform Cloud 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-cloud.git

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

Change to the repository directory.

$ cd learn-terraform-cloud

$ cd learn-terraform-cloud

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 Terraform Cloud UI later on in this tutorial.
• outputs.tf defines the information about your infrastructure that Terraform Cloud will display to you when it makes changes.
• versions.tf defines version constraints for Terraform and the AWS provider and the cloud block for the Terraform Cloud integration.

»Update configuration

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

terraform {

  cloud {
    organization = "organization-name"

    workspaces {
      name = "learn-terraform-cloud"
    }
  }

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

  required_version = ">= 1.1.0"
}

terraform {

  cloud {
    organization = "organization-name"

    workspaces {
      name = "learn-terraform-cloud"
    }
  }

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

  required_version = ">= 1.1.0"
}

»Create the workspace

This cloud block specifies which Terraform Cloud organization and workspace to use for the operations in this working directory. When using the CLI-driven Terraform Cloud workflow, running terraform init on configuration with a cloud block creates the Terraform Cloud 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 Terraform Cloud workspace.

$ terraform init
Initializing Terraform Cloud...

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.

Terraform Cloud has been successfully initialized!

You may now begin working with Terraform Cloud. 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.

$ terraform init
Initializing Terraform Cloud...

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.

Terraform Cloud has been successfully initialized!

You may now begin working with Terraform Cloud. 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-cloud workspace in your Terraform Cloud organization, configured for CLI-driven runs.

»Assign variable set to workspace

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

Navigate to your new learn-terraform-cloud 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 Terraform Cloud organization, created a CLI-driven Terraform Cloud workspace, and configured it with a variable set. Read more about Terraform Cloud workspaces in the documentation.

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