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.

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.

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.

1. In the Terraform Cloud UI, open the MyApp Dev workspace.
2. Navigate to Variables → Environment Variables.
3. Add the following entries:

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

• Terraform Cloud Get Started
• Terraform CLI Options
• Terraform Cloud Variables