Terraform
Collaborate using HCP Terraform
In the previous tutorials in this collection, you used Terraform to create, manage, and destroy infrastructure from your local machine. Managing your Terraform workspaces from your local machine creates a single point of failure, and makes it difficult to collaborate on infrastructure projects with your team.
HCP Terraform allows you to collaborate on infrastructure projects within your organization. It provides a secure remote execution environment, letting you collaboratively manage changes to your infrastructure. It also securely stores your Terraform state and variables, including API tokens and access keys. The Terraform CLI integrates with HCP Terraform, so you can trigger remote runs from your local machine.
In this tutorial, you will migrate your local workspace to HCP Terraform and use the CLI-driven workflow to trigger runs. HCP Terraform also supports provisioning your infrastructure using an API-driven workflow, or the VCS-driven workflow, which triggers runs for any changes to a configured repository.
Prerequisites
To follow this tutorial you will need:
- The Terraform CLI (1.2.0+) installed.
- The AWS CLI installed.
- 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. - The configuration and infrastructure from the previous tutorials tutorials in this collection.
Create resources
In the previous tutorial, you
destroyed the infrastructure you created with Terraform. Apply your
configuration again to recreate your workspace's infrastructure. Respond to the
confirmation prompt with a yes.
$ terraform apply
data.aws_ami.ubuntu: Reading...
data.aws_ami.ubuntu: Read complete after 1s [id=ami-0026a04369a3093cc]
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:
# module.vpc.aws_default_network_acl.this[0] will be created
+ resource "aws_default_network_acl" "this" {
+ arn = (known after apply)
+ default_network_acl_id = (known after apply)
+ id = (known after apply)
+ owner_id = (known after apply)
##...
Plan: 15 to add, 0 to change, 0 to destroy.
Do you want to perform these actions?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
module.vpc.aws_vpc.this[0]: Creating...
module.vpc.aws_vpc.this[0]: Still creating... [10s elapsed]
module.vpc.aws_vpc.this[0]: Creation complete after 13s [id=vpc-07b6253940b170243]
## ...
module.vpc.aws_route_table_association.public[0]: Creating...
module.vpc.aws_subnet.private[1]: Creation complete after 4s [id=subnet-0daa2b4c37d3d9bd1]
module.vpc.aws_route_table_association.private[0]: Creating...
module.vpc.aws_route_table_association.private[1]: Creating...
module.vpc.aws_route_table_association.public[0]: Creation complete after 0s [id=rtbassoc-0f3b7ed7e1f49d2a1]
module.vpc.aws_route_table_association.private[0]: Creation complete after 0s [id=rtbassoc-01e3f044ca6bb5fe0]
module.vpc.aws_route_table_association.private[1]: Creation complete after 0s [id=rtbassoc-0647d3c7904113d60]
Apply complete! Resources: 15 added, 0 changed, 0 destroyed.
Now that you have re-created your VPC and related resources, migrate your local workspace's state to HCP Terraform.
Sign up for HCP Terraform
You will need an HCP Terraform account to complete this tutorial. Visit HCP Terraform and follow the prompts to create an HCP Terraform account. If you already have an HCP Terraform account, you can use it for this tutorial instead of creating a new one.
When you sign up with HCP Terraform, you will receive an email asking you to confirm your email address. When you click the link to confirm your email address, HCP Terraform will send you to the Organizations page. Click Create organization and create your new organization by following the prompts.
Log into HCP Terraform
Next, log into your HCP Terraform account with the Terraform CLI by running
terraform login in your terminal.
$ terraform login
Terraform will request an API token for app.terraform.io using your browser.
If login is successful, Terraform will store the token in plain text in
the following file for use by subsequent commands:
/Users/YOU/.terraform.d/credentials.tfrc.json
Do you want to proceed?
Only 'yes' will be accepted to confirm.
Enter a value:
Respond to the confirmation prompt with a yes and Terraform will open a
browser window to allow you to create an API token.
Enter a value: yes
---------------------------------------------------------------------------------
Terraform must now open a web browser to the tokens page for app.terraform.io.
If a browser does not open this automatically, open the following URL to proceed:
https://app.terraform.io/app/settings/tokens?source=terraform-login
---------------------------------------------------------------------------------
Generate a token using your browser, and copy-paste it into this prompt.
Terraform will store the token in plain text in the following file
for use by subsequent commands:
/Users/YOU/.terraform.d/credentials.tfrc.json
Token for app.terraform.io:
Enter a value:
Follow the workflow in your browser to generate an API token. Then, paste the API token into your terminal when Terraform prompts you to do so. Terraform will not print your token to the screen when you paste it. For more detail on logging in to HCP Terraform, follow the Authenticate the CLI with HCP Terraform tutorial.
Enter a value:
Retrieved token for user YOU
---------------------------------------------------------------------------------
-
----- -
--------- --
--------- - -----
--------- ------ -------
------- --------- ----------
---- ---------- ----------
-- ---------- ----------
Welcome to HCP Terraform! - ---------- -------
--- ----- ---
Documentation: terraform.io/docs/cloud -------- -
----------
----------
---------
-----
-
New to HCP Terraform? Follow these steps to instantly apply an example configuration:
$ git clone https://github.com/hashicorp/tfc-getting-started.git
$ cd tfc-getting-started
$ scripts/setup.sh
Connect workspace to HCP Terraform
In order to connect your workspace to HCP Terraform, you will need to update your configuration and re-initialize your workspace from the command line. HCP Terraform workspaces work like local Terraform workspaces, but execute Terraform operations and store your state within HCP Terraform. HCP Terraform also supports grouping your workspaces into projects to more easily manage their access and settings.
Update configuration
Update the terraform block in terraform.tf to add a cloud block that
connects your local workspace to HCP Terraform.
terraform.tf
terraform {
cloud {
organization = "your-organization-name"
workspaces {
project = "Learn Terraform"
name = "learn-terraform-aws-get-started"
}
}
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.92"
}
}
required_version = ">= 1.2.0"
}
Replace your-organization-name with your organization name, which you can find
in the HCP Terraform portal.
Migrate to HCP Terraform
Now that you have configured your HCP Terraform integration, run terraform
init to re-initialize your configuration and copy your state to HCP Terraform.
Respond to the confirmation prompt with yes to confirm the migration.
$ terraform init
Initializing HCP Terraform...
Do you wish to proceed?
As part of migrating to HCP Terraform, Terraform can optionally copy
your current workspace state to the configured HCP Terraform workspace.
Answer "yes" to copy the latest state snapshot to the configured
HCP Terraform workspace.
Answer "no" to ignore the existing state and just activate the configured
HCP Terraform workspace with its existing state, if any.
Should Terraform migrate your existing state?
Enter a value: yes
Initializing modules...
Initializing provider plugins...
- Reusing previous version of hashicorp/aws from the dependency lock file
- Using previously-installed hashicorp/aws v5.98.0
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.
When you run terraform init after adding a cloud block to your
configuration, Terraform creates the new project and workspace if they don't
already exist, or uses the existing project and workspace if they already exist.
Configure AWS credentials
The terraform init step created the Learn Terraform project and the
learn-terraform-aws-get-started workspace in your HCP Terraform organization.
In order for HCP Terraform to authenticate with the AWS provider and provision
your resources, you will need to configure your workspace with your AWS
credentials.
Navigate to your learn-terraform-aws-get-started workspace in HCP Terraform
and go to the workspace's Variables page. Under Workspace Variables, add
your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as Environment
Variables, making sure to mark them as Sensitive.
Apply configuration
Now update and apply your configuration with HCP Terraform. Uncomment the
configuration for your EC2 instance in main.tf.
main.tf
resource "aws_instance" "app_server" {
ami = data.aws_ami.ubuntu.id
instance_type = var.instance_type
vpc_security_group_ids = [module.vpc.default_security_group_id]
subnet_id = module.vpc.private_subnets[0]
tags = {
Name = var.instance_name
}
}
Also uncomment the output value in outputs.tf.
outputs.tf
output "instance_hostname" {
description = "Private DNS name of the EC2 instance."
value = aws_instance.app_server.private_dns
}
Now, run terraform apply to trigger a run in HCP Terraform. Terraform executes
the plan and apply runs remotely in HCP Terraform and streams the output to your
terminal window. Respond to the confirmation prompt with a yes to instruct HCP
Terraform to provision your infrastructure.
$ terraform apply
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.
Preparing the remote apply...
To view this run in a browser, visit:
https://app.terraform.io/app/your-organization-name/learn-terraform-aws-get-started/runs/run-abCDEFghijkLMnopY
Waiting for the plan to start...
## ...
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
+ create
Terraform will perform the following actions:
# aws_instance.app_server will be created
+ resource "aws_instance" "app_server" {
+ ami = "ami-0e847e970c9565775"
+ arn = (known after apply)
## ...
Plan: 1 to add, 0 to change, 0 to destroy.
Changes to Outputs:
+ instance_hostname = (known after apply)
Do you want to perform these actions in workspace "learn-terraform-aws-get-started"?
Terraform will perform the actions described above.
Only 'yes' will be accepted to approve.
Enter a value: yes
aws_instance.app_server: Creating...
aws_instance.app_server: Still creating... [10s elapsed]
aws_instance.app_server: Creation complete after 13s [id=i-0be76e73004969a35]
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
Outputs:
instance_hostname = "ip-10-0-1-111.us-west-2.compute.internal"
Terraform now stores your workspace's state remotely in HCP Terraform. Visit the URL Terraform prints out to view the run within HCP Terraform. With the CLI-driven workflow, you can execute Terraform commands from your local machine, and HCP Terraform will execute them and stream the output to your CLI. You can also review the results of plan and apply runs and configure your workspace in HCP Terraform.
Destroy workspace
Destroy the resources you provisioned in this tutorial by running terraform
destroy. Respond to the confirmation prompt with a yes to instruct HCP
Terraform to destroy all of the resources it manages in your workspace.
$ terraform destroy
Running apply in HCP Terraform. Output will stream here. Pressing Ctrl-C
will cancel the remote apply if it's still pending. If the apply started it
will stop streaming the logs, but will not stop the apply running remotely.
Preparing the remote apply...
To view this run in a browser, visit:
https://app.terraform.io/app/your-organization-name/learn-terraform-aws-get-started/runs/run-zvFXqwertyUIOPab
Waiting for the plan to start...
Terraform v1.12.0
on linux_amd64
Initializing plugins and modules...
## ...
Plan: 0 to add, 0 to change, 16 to destroy.
Changes to Outputs:
- instance_hostname = "ip-10-0-1-111.us-west-2.compute.internal" -> null
Do you really want to destroy all resources in workspace "learn-terraform-aws-get-started"?
Terraform will destroy all your managed infrastructure, as shown above.
There is no undo. Only 'yes' will be accepted to confirm.
Enter a value: yes
module.vpc.aws_default_security_group.this[0]: Destroying... [id=sg-014b478a2b1cd316e]
module.vpc.aws_route_table_association.public[0]: Destroying... [id=rtbassoc-0f3b7ed7e1f49d2a1]
module.vpc.aws_route_table_association.private[1]: Destroying... [id=rtbassoc-0647d3c7904113d60]
module.vpc.aws_default_network_acl.this[0]: Destroying... [id=acl-0fafc47f15e7c59f5]
module.vpc.aws_route.public_internet_gateway[0]: Destroying... [id=r-rtb-0956189f24b1a92ae1080289494]
module.vpc.aws_route_table_association.private[0]: Destroying... [id=rtbassoc-01e3f044ca6bb5fe0]
module.vpc.aws_default_route_table.default[0]: Destroying... [id=rtb-0a78b66d2a9e3e4d7]
## ...
aws_instance.app_server: Still destroying... [id=i-069c5ad5f53ba2ce2, 01m20s elapsed]
aws_instance.app_server: Still destroying... [id=i-069c5ad5f53ba2ce2, 01m30s elapsed]
aws_instance.app_server: Destruction complete after 1m33s
module.vpc.aws_subnet.private[1]: Destroying... [id=subnet-0daa2b4c37d3d9bd1]
module.vpc.aws_subnet.private[0]: Destroying... [id=subnet-0c30a4ca611a967c3]
module.vpc.aws_subnet.private[0]: Destruction complete after 0s
module.vpc.aws_subnet.private[1]: Destruction complete after 1s
module.vpc.aws_vpc.this[0]: Destroying... [id=vpc-0a3754c28c3d86167]
module.vpc.aws_vpc.this[0]: Destruction complete after 0s
Destroy complete! Resources: 16 destroyed.
Next, delete your workspace by navigating to your
learn-terraform-aws-get-started workspace's Settings > Destruction and
Deletion tab in HCP Terraform. Click the Delete from HCP Terraform
button, then follow the prompts to delete your workspace.
You can also delete your project by navigating to its Settings page, clicking the Delete button, and following the prompts.
Interactive terminal
You can learn how to create your infrastructure without setting up a cloud account in our interactive terminal.
Launch Terminal
This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.
Next steps
In these tutorials, you learned how to install the Terraform CLI, use it to create, manage and destroy infrastructure, and how to migrate your workspace to HCP Terraform. As your infrastructure operations mature, HCP Terraform allows you to collaborate with your team, store your state and variables securely, and integrateswith your version control system to manage your Terraform configurations.
For more hands-on experience with the Terraform configuration language, managing resources, or importing existing infrastructure, review the following resources.
Configuration Language - Get more familiar with variables, outputs, dependencies, meta-arguments, and other language features to write more sophisticated Terraform configurations.
Modules - Organize and re-use Terraform configuration with modules.
- Learn how to manage other AWS resources with Terraform.
For a hands-on introduction to the HCP Terraform VCS-driven workflow, follow the HCP Terraform getting started tutorials.