ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
terraform/website/docs/cli/commands/refresh.html.md

64 lines
2.7 KiB
Markdown
Raw Normal View History

website: documenting the CLI
2014-07-24 18:02:10 +02:00
---
layout: "docs"
page_title: "Command: refresh"
sidebar_current: "docs-commands-refresh"
Add meta descriptions to all pages
2014-10-22 05:21:56 +02:00
description: |-
The `terraform refresh` command is used to reconcile the state Terraform knows about (via its state file) with the real-world infrastructure. This can be used to detect any drift from the last-known state, and to update the state file.
website: documenting the CLI
2014-07-24 18:02:10 +02:00
---
# Command: refresh
The `terraform refresh` command is used to reconcile the state Terraform
Fixing incorrect use of "it's" in docs.
2014-07-28 22:09:32 +02:00
knows about (via its state file) with the real-world infrastructure.
Fix a typo: The -> This
2014-10-16 18:16:52 +02:00
This can be used to detect any drift from the last-known state, and to
website: documenting the CLI
2014-07-24 18:02:10 +02:00
update the state file.
This does not modify infrastructure, but does modify the state file.
If the state is changed, this may cause changes to occur during the next
plan or apply.
## Usage
main: new global option -chdir This new option is intended to address the previous inconsistencies where some older subcommands supported partially changing the target directory (where Terraform would use the new directory inconsistently) where newer commands did not support that override at all. Instead, now Terraform will accept a -chdir command at the start of the command line (before the subcommand) and will interpret it as a request to direct all actions that would normally be taken in the current working directory into the target directory instead. This is similar to options offered by some other similar tools, such as the -C option in "make". The new option is only accepted at the start of the command line (before the subcommand) as a way to reflect that it is a global command (not specific to a particular subcommand) and that it takes effect _before_ executing the subcommand. This also means it'll be forced to appear before any other command-specific arguments that take file paths, which hopefully communicates that those other arguments are interpreted relative to the overridden path. As a measure of pragmatism for existing uses, the path.cwd object in the Terraform language will continue to return the _original_ working directory (ignoring -chdir), in case that is important in some exceptional workflows. The path.root object gives the root module directory, which will always match the overriden working directory unless the user simultaneously uses one of the legacy directory override arguments, which is not a pattern we intend to support in the long run. As a first step down the deprecation path, this commit adjusts the documentation to de-emphasize the inconsistent old command line arguments, including specific guidance on what to use instead for the main three workflow commands, but all of those options remain supported in the same way as they were before. In a later commit we'll make those arguments produce a visible deprecation warning in Terraform's output, and then in an even later commit we'll remove them entirely so that -chdir is the single supported way to run Terraform from a directory other than the one containing the root module configuration.
2020-09-02 00:45:12 +02:00
Usage: `terraform refresh [options]`
website: documenting the CLI
2014-07-24 18:02:10 +02:00
main: new global option -chdir This new option is intended to address the previous inconsistencies where some older subcommands supported partially changing the target directory (where Terraform would use the new directory inconsistently) where newer commands did not support that override at all. Instead, now Terraform will accept a -chdir command at the start of the command line (before the subcommand) and will interpret it as a request to direct all actions that would normally be taken in the current working directory into the target directory instead. This is similar to options offered by some other similar tools, such as the -C option in "make". The new option is only accepted at the start of the command line (before the subcommand) as a way to reflect that it is a global command (not specific to a particular subcommand) and that it takes effect _before_ executing the subcommand. This also means it'll be forced to appear before any other command-specific arguments that take file paths, which hopefully communicates that those other arguments are interpreted relative to the overridden path. As a measure of pragmatism for existing uses, the path.cwd object in the Terraform language will continue to return the _original_ working directory (ignoring -chdir), in case that is important in some exceptional workflows. The path.root object gives the root module directory, which will always match the overriden working directory unless the user simultaneously uses one of the legacy directory override arguments, which is not a pattern we intend to support in the long run. As a first step down the deprecation path, this commit adjusts the documentation to de-emphasize the inconsistent old command line arguments, including specific guidance on what to use instead for the main three workflow commands, but all of those options remain supported in the same way as they were before. In a later commit we'll make those arguments produce a visible deprecation warning in Terraform's output, and then in an even later commit we'll remove them entirely so that -chdir is the single supported way to run Terraform from a directory other than the one containing the root module configuration.
2020-09-02 00:45:12 +02:00
The `terraform refresh` command accepts the following options:
website: documenting the CLI
2014-07-24 18:02:10 +02:00
command: New -compact-warnings option When warnings appear in isolation (not accompanied by an error) it's reasonable to want to defer resolving them for a while because they are not actually blocking immediate work. However, our warning messages tend to be long by default in order to include all of the necessary context to understand the implications of the warning, and that can make them overwhelming when combined with other output. As a compromise, this adds a new CLI option -compact-warnings which is supported for all the main operation commands and which uses a more compact format to print out warnings as long as they aren't also accompanied by errors. The default remains unchanged except that the threshold for consolidating warning messages is reduced to one so that we'll now only show one of each distinct warning summary. Full warning messages are always shown if there's at least one error included in the diagnostic set too, because in that case the warning message could contain additional context to help understand the error.
2019-12-10 20:06:06 +01:00
* `-compact-warnings` - If Terraform produces any warnings that are not
accompanied by errors, show them in a more compact form that includes only
the summary messages.
update command docs
2017-04-04 19:48:59 +02:00
* `-input=true` - Ask for input for variables if not directly set.
* `-lock=true` - Lock the state file when locking is supported.
* `-lock-timeout=0s` - Duration to retry a state lock.
* `-no-color` - If specified, output won't contain any color.
command: Consistency implement and document parallelism default of 10 References: * https://github.com/hashicorp/terraform/blob/f4da82a023bf6db1fa8da24236882d874ff0a87e/command/command.go#L41 * https://github.com/hashicorp/terraform/blob/b9d8e96e0c7c52487e45eaab1aa6dacc39997b47/terraform/context.go#L149-L155
2019-03-06 15:25:36 +01:00
* `-parallelism=n` - Limit the number of concurrent operation as Terraform
[walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults
to 10.
docs: resource addressing
2015-04-01 01:48:54 +02:00
* `-target=resource` - A [Resource
website: CLI: Update links to moved docs pages
2021-01-19 22:43:01 +01:00
Address](/docs/cli/state/resource-addressing.html) to target. Operation will
docs: resource addressing
2015-04-01 01:48:54 +02:00
be limited to this resource and its dependencies. This flag can be used
multiple times.
core: docs for targeted operations
2015-03-27 23:24:15 +01:00
website: Docs sweep for lists & maps
2016-07-12 00:37:51 +02:00
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
can be set multiple times. Variable values are interpreted as
website: Language: Update links to moved pages
2021-01-15 23:13:53 +01:00
[literal expressions](/docs/language/expressions/types.html) in the
website: Fix numerous links with redirects or broken anchors These links largely still go somewhere useful, but they have some kind of issue revealed by our new link checker: - Some of them point to a stale URL that redirects, and can be updated to the new destination. - Some of them point to anchors that don't exist (anymore?) in the destination. - Some of them end up redirecting unnecessarily due to how the server handles directory URLs without trailing slashes. Sorry, I know that's pointless, just, humor me for the time being so we can get our CI green. 😭 In a couple cases, I've added invisible anchors to destination pages, either to preserve an old habit or because the current anchors kind of suck due to being particularly long or meandering.
2020-12-17 00:10:49 +01:00
Terraform language, so list and map values can be specified via this flag.
website: documenting the CLI
2014-07-24 18:02:10 +02:00
* `-var-file=foo` - Set variables in the Terraform configuration from
website: Language: Update links to moved pages
2021-01-15 23:13:53 +01:00
a [variable file](/docs/language/values/variables.html#variable-definitions-tfvars-files). If
Autoload only .auto.tfvars files
2017-06-22 03:22:07 +02:00
a `terraform.tfvars` or any `.auto.tfvars` files are present in the current
directory, they will be automatically loaded. `terraform.tfvars` is loaded
first and the `.auto.tfvars` files after in alphabetical order. Any files
specified by `-var-file` override any values set automatically from files in
the working directory. This flag can be used multiple times.
command: Reorganize docs of the local backend's legacy CLI options We have these funny extra options that date back to before Terraform even had remote state, which we've preserved along the way by most recently incorporating them as special-case overrides for the local backend. The documentation we had for these has grown less accurate over time as the details have shifted, and was in many cases missing the requisite caveats that they are only for the local backend and that backend configuration is the modern, preferred way to deal with the use-cases they were intended for. We always have a bit of a tension with this sort of legacy option because we want to keep them documented just enough to be useful to someone who finds an existing script/etc using them and wants to know what they do, but not to take up so much space that they might distract users from finding the modern alternative they should consider instead. As a compromise in that vein here I've created a new section about these options under the local backend documentation, which then gives us the space to go into some detail about the various behaviors and interactions and also to discuss their history and our recommended alternatives. I then simplified all of the other mentions of these in command documentation to just link to or refer to the local backend documentation. My hope then is that folks who need to know what these do can still find the docs, but that information can be kept out of the direct path of new users so they can focus on learning about remote backends instead. This is certainly not the most ideal thing ever, but it seemed like the best compromise between the competing priorities I described above.
2021-03-25 00:17:03 +01:00
For configurations using
[the `local` backend](/docs/language/settings/backends/local.html) only,
`terraform refresh` also accepts the legacy options
[`-state`, `-state-out`, and `-backup`](/docs/language/settings/backends/local.html#command-line-arguments).