mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-27 20:01:34 -05:00
6bed3008a5
It's been a long time since we gave this page an overhaul, and with our ongoing efforts to make plan and apply incorporate all of the side-effects that might need to be done against a configuration it seems like a good time for some restructuring in that vein. The starting idea here is to formally split the many "terraform plan" options into a few different categories: - Planning modes - Planning options - Other options The planning modes and options are the subset that are also accepted by "terraform apply" when it's running in its default mode of generating a plan and then prompting for interactive approval of it. This then allows us to avoid duplicating all of that information on the "terraform apply" page, and thus allows us to spend more words discussing each of them. This set of docs is intended as a fresh start into which we'll be able to more surgically add in the information about -refresh-only and -replace=... once we have those implemented. Consequently there are some parts of this which may seem a little overwraught for what it's currently describing; that's a result of my having prepared this by just deleting the -refresh-only and -replace=... content from our initial docs draft and submitted the result, in anticipation of re-adding the parts I've deleted here in the very near future in other commits.
69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "Command: refresh"
|
|
sidebar_current: "docs-commands-refresh"
|
|
description: |-
|
|
The `terraform refresh` command reads the current settings from all managed
|
|
remote objects and updates the Terraform state to match.
|
|
---
|
|
|
|
# Command: refresh
|
|
|
|
The `terraform refresh` command reads the current settings from all managed
|
|
remote objects and updates the Terraform state to match.
|
|
|
|
~> *Warning:* This command is deprecated, because its default behavior is
|
|
unsafe if you have misconfigured credentials for any of your providers.
|
|
See below for more information and recommended alternatives.
|
|
|
|
This won't modify your real remote objects, but it will modify the
|
|
[the Terraform state](/docs/language/state/).
|
|
|
|
You shouldn't typically need to use this command, because Terraform
|
|
automatically performs the same refreshing actions as a part of creating
|
|
a plan in both the
|
|
[`terraform plan`](./plan.html)
|
|
and
|
|
[`terraform apply`](./apply.html)
|
|
commands. This command is here primarily for backward compatibility, but
|
|
we don't recommend using it because it provides no opportunity to review
|
|
the effects of the operation before updating the state.
|
|
|
|
## Usage
|
|
|
|
Usage: `terraform refresh [options]`
|
|
|
|
This command is effectively an alias for the following command:
|
|
|
|
```
|
|
terraform apply -refresh-only -auto-approve
|
|
```
|
|
|
|
Consequently, it supports all of the same options as
|
|
[`terraform apply`](./apply.html) except that it does not accept a saved
|
|
plan file, it doesn't allow selecting a planning mode other than "refresh only",
|
|
and `-auto-approve` is always enabled.
|
|
|
|
Automatically applying the effect of a refresh is risky, because if you have
|
|
misconfigured credentials for one or more providers then the provider may
|
|
be misled into thinking that all of the managed objects have been deleted,
|
|
and thus remove all of the tracked objects without any confirmation prompt.
|
|
|
|
Instead, we recommend using the following command in order to get the same
|
|
effect but with the opportunity to review the the changes that Terraform has
|
|
detected before committing them to the state:
|
|
|
|
```
|
|
terraform apply -refresh-only
|
|
```
|
|
|
|
This alternative command will present an interactive prompt for you to confirm
|
|
the detected changes.
|
|
|
|
The `-refresh-only` option for `terraform plan` and `terraform apply` was
|
|
introduced in Terraform v1.0. For prior versions you must use
|
|
`terraform refresh` directly if you need this behavior, while taking into
|
|
account the warnings above. Wherever possible, avoid using `terraform refresh`
|
|
explicitly and instead rely on Terraform's behavior of automatically refreshing
|
|
existing objects as part of creating a normal plan.
|