Run Modes and Options
Terraform Cloud runs support many of the same modes and options available in the Terraform CLI.
Plan and Apply (Standard)
The default run mode of Terraform Cloud is to perform a plan and then apply it. If you have enabled auto-apply, a successful plan applies immediately. Otherwise, the run waits for user confirmation before applying.
- CLI: Use
terraform apply
(without providing a saved plan file). - API: Create a run without specifying any options that select a different mode.
- UI: From the workspace's overview page, click + New run, and then choose Plan and apply (standard) as the run type.
- VCS: When a workspace is connected to a VCS repository, Terraform Cloud automatically starts a standard plan and apply when you add new commits to the selected branch of that repository.
Destroy Mode
Destroy mode instructs Terraform to create a plan which destroys all objects, regardless of configuration changes.
- CLI: Use
terraform plan -destroy
orterraform destroy
- API: Use the
is-destroy
option. - UI: Use a workspace's Destruction and Deletion settings page.
Plan Only/Speculative Plan
This option creates a speculative plan. The speculative plan shows a set of possible changes and checks them against Sentinel policies, but Terraform can not apply this plan.
You can create speculative plans with a different Terraform version than the one currently selected for a workspace. This lets you check whether your configuration is compatible with a newer Terraform version without changing the workspace settings.
Plan-only runs ignore the per-workspace run queue. Plan-only runs can proceed even if another run is in progress, can not become the workspace's current run, and do not block progress on a workspace's other runs.
- API: Set the
plan-only
option totrue
and specify an available terraform version using theterraform-version
field. - UI: From the workspace's overview page, click + New run, and then choose Plan only as the run type.
- VCS: When a workspace is connected to a VCS repository, Terraform Cloud automatically starts a speculative plan when someone opens a pull request (or merge request) against the selected branch of that repository. The pull/merge request view in your VCS links to the speculative plan, and you can also find it in the workspace's run list.
Allow Empty Apply
A no-operation (empty) apply enables Terraform Cloud to apply a run from a plan that contains no infrastructure changes. During apply, Terraform can upgrade the state version if required. You can use this option to upgrade the state in your Terraform Cloud workspace to a new Terraform version. Only some Terraform versions require this, most notably 0.13.
To make such upgrades easier, empty apply runs will always auto-apply if their plan contains no changes.
Warning: Terraform Cloud cannot guarantee that a plan in this mode will produce no changes. We recommend checking the plan for drift before proceeding to the apply stage.
- API: Set the
allow-empty-apply
field totrue
. - UI: From the workspace's overview page, click + New run, and then choose Allow empty apply as the run type.
Refresh-Only Mode
Hands-on: Try the Use Refresh-Only Mode to Sync Terraform State tutorial.
Version note: Refresh-only support requires a workspace using at least Terraform CLI v0.15.4.
Refresh-only mode instructs Terraform to create a plan that updates the Terraform state to match changes made to remote objects outside of Terraform. This is useful if state drift has occurred and you want to reconcile your state file to match the drifted remote objects. Applying a refresh-only run does not result in further changes to remote objects.
- CLI: Use
terraform plan -refresh-only
orterraform apply -refresh-only
. - API: Use the
refresh-only
option. - UI: From the workspace's overview page, click + New run, and then choose Refresh state as the run type.
Skipping Automatic State Refresh
The -refresh=false
option is used in normal planning mode to skip the default behavior of refreshing Terraform state before checking for configuration changes.
- CLI: Use
terraform plan -refresh=false
orterraform apply -refresh=false
. - API: Use the
refresh
option.
Replacing Selected Resources
Version note: Replace support requires a workspace using at least Terraform CLI v0.15.2.
The replace option instructs Terraform to replace the object with the given resource address.
- CLI: Use
terraform plan -replace=ADDRESS
orterraform apply -replace=ADDRESS
. - API: Use the
replace-addrs
option.
Targeted Plan and Apply
Resource Targeting is intended for exceptional circumstances only and should not be used routinely.
- CLI: Use
terraform plan -target=ADDRESS
orterraform apply -target=ADDRESS
. - API: Use the
target-addrs
option.
The usual caveats for targeting in local operations imply some additional limitations on Terraform Cloud features for remote plans created with targeting:
Sentinel policy checks for targeted plans will see only the selected subset of resource instances planned for changes in the
tfplan
import and thetfplan/v2
import, which may cause an unintended failure for any policy that requires a planned change to a particular resource instance selected by its address.Cost Estimation is disabled for any run created with
-target
set, to prevent producing a misleading underestimate of cost due to resource instances being excluded from the plan.
You can disable or constrain use of targeting in a particular workspace using a Sentinel policy based on the tfrun.target_addrs
value.
Generating Configuration
Version note: Support for import
blocks and generating configuration requires a workspace using at least Terraform CLI v1.5.0.
When using import
blocks to import existing resources, Terraform can automatically generate configuration during the plan for any imported resources that don't have an existing resource
block. This option is enabled by default for runs started from the UI or from a VCS webhook.
- CLI: Use
terraform plan -generate-config-out=generated.tf
. - API: Use the
allow-config-generation
option.
You can find generated configuration displayed in the plan UI. If you're using the CLI workflow, Terraform will write generated configuration to the file you specify when running terraform plan
.
Once Terraform has generated configuration for you, you'll need to review it, incorporate it in your Terraform configuration (including committing it to version control), then run another plan. If you try to directly apply a plan with generated configuration, the run will error.