HashiCorp : Terraform Cloud
Advanced Topics
Targeting Resource for Replacement with Terraform Cloud
In this guide, you'll learn how to replace a single resource in a Terraform Cloud workspace—connected to a Version Control System (VCS)—without touching your code or Git history. We demonstrate how to inject the -replace
flag into Terraform Cloud runs by using workspace environment variables.
Overview of the Terraform Cloud Workspace
You have multiple workspaces—DevOps, AWS MyApp Dev, Prod, and Staging—all linked to their respective Git branches. The screenshot below shows the Terraform Cloud dashboard with workspace names, run statuses, linked repositories, and last update times.
Configuring Terraform CLI for Terraform Cloud
Even with a VCS-connected workspace, you can run terraform init
and terraform plan
locally by pointing your CLI to Terraform Cloud:
terraform {
cloud {
organization = "Mastering-Terraform-Cloud"
workspaces {
name = "devops-aws-myapp-dev"
}
}
}
After cloning the clumsy_bird
repo and checking out the development
branch (tied to the MyApp Dev workspace), initialize and plan:
$ terraform init
$ terraform plan
# No changes. Your infrastructure matches the configuration.
Note
Local plan
and init
commands work because Terraform Cloud is acting as your remote backend.
Local Apply Is Blocked for VCS-Connected Workspaces
Attempting terraform apply
on a VCS-connected workspace will result in an error:
$ terraform apply
Error: Apply not allowed for workspaces with a VCS connection
A workspace that is connected to a VCS requires the VCS-driven workflow to ensure that the VCS remains the single source of truth.
Warning
Terraform Cloud disallows local apply
on VCS workspaces. All changes must flow through your Git repository.
Using -replace
to Recreate Specific Resources
Terraform’s -replace
flag lets you target explicit resources for recreation:
$ terraform apply -replace=aws_instance.clumsy_bird
You can confirm the resource exists in state:
$ terraform state list
aws_instance.clumsy_bird
aws_eip.clumsy_bird
...
module.vpc.aws_vpc.this[0]
Since local apply
is blocked, we’ll inject these flags into Terraform Cloud runs.
Injecting CLI Arguments via Environment Variables
Terraform Cloud lets you define environment variables for each run phase. We’ll configure TF_CLI_ARGS_plan
and TF_CLI_ARGS_apply
to include -replace
.
- In the Terraform Cloud UI, open the MyApp Dev workspace.
- Navigate to Variables → Environment Variables.
- Add the following entries:
Variable Name | Value | Purpose |
---|---|---|
TF_CLI_ARGS_plan | -replace=aws_instance.clumsy_bird -input=false | Automatically replace the instance during plan |
TF_CLI_ARGS_apply | -replace=aws_instance.clumsy_bird -auto-approve -input=false | Bypass approval and replace on apply |
After saving, your workspace’s environment variables list should appear similar to this:
Triggering the Terraform Cloud Run
Now, start a new run from the Terraform Cloud UI. During Plan and Apply, Terraform Cloud automatically applies your -replace
flags:
You’ll see the plan mark two resources for destruction and recreation, plus one change. After Apply completes, the targeted instance and its related resources have been replaced—with no Git commits.
Conclusion
By using TF_CLI_ARGS_plan
and TF_CLI_ARGS_apply
environment variables in Terraform Cloud, you can inject CLI flags (such as -replace
) into runs on VCS-connected workspaces. This method lets you force resource replacement without altering your Terraform configuration or committing changes to Git.
References
Watch Video
Watch video content
Practice Lab
Practice lab