mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-04-22 21:02:08 -04:00
6f35c2847b
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.
97 lines
3.6 KiB
Markdown
97 lines
3.6 KiB
Markdown
---
|
|
layout: "language"
|
|
page_title: "Backend Type: local"
|
|
sidebar_current: "docs-backends-types-enhanced-local"
|
|
description: |-
|
|
Terraform can store the state remotely, making it easier to version and work with in a team.
|
|
---
|
|
|
|
# local
|
|
|
|
**Kind: Enhanced**
|
|
|
|
The local backend stores state on the local filesystem, locks that
|
|
state using system APIs, and performs operations locally.
|
|
|
|
## Example Configuration
|
|
|
|
```hcl
|
|
terraform {
|
|
backend "local" {
|
|
path = "relative/path/to/terraform.tfstate"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Data Source Configuration
|
|
|
|
```hcl
|
|
data "terraform_remote_state" "foo" {
|
|
backend = "local"
|
|
|
|
config = {
|
|
path = "${path.module}/../../terraform.tfstate"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration variables
|
|
|
|
The following configuration options are supported:
|
|
|
|
* `path` - (Optional) The path to the `tfstate` file. This defaults to
|
|
"terraform.tfstate" relative to the root module by default.
|
|
* `workspace_dir` - (Optional) The path to non-default workspaces.
|
|
|
|
## Command Line Arguments
|
|
|
|
~> This section describes legacy features that we've preserved for backward
|
|
compatibility but that we no longer recommend. See below for more details.
|
|
|
|
For configurations that include a `backend "local"` block or that default to
|
|
the local backend by not specifying a backend at all, most commands that either
|
|
read or write state snapshots from the backend accept the following
|
|
additional arguments:
|
|
|
|
* `-state=FILENAME` - overrides the state filename when _reading_ the prior
|
|
state snapshot.
|
|
* `-state-out=FILENAME` - overrides the state filename when _writing_ new state
|
|
snapshots.
|
|
|
|
If you use `-state` without also using `-state-out` then Terraform will
|
|
use the `-state` filename for both `-state` and `-state-out`, which means
|
|
Terraform will overwrite the input file if it creates a new state snapshot.
|
|
* `-backup=FILENAME` - overrides the default filename that the local backend
|
|
would normally choose dynamically to create backup files when it writes new
|
|
state.
|
|
|
|
If you use `-state` without also using `-backup` then Terraform will use
|
|
the `-state` filename as a filename prefix for generating a backup filename.
|
|
You can use `-backup=-` (that is, set the filename to just the ASCII
|
|
dash character) to disable the creation of backup files altogether.
|
|
|
|
These three options are preserved for backward-compatibility with earlier
|
|
workflows that predated the introduction of built-in remote state, where
|
|
users would write wrapper scripts that fetch prior state before running
|
|
Terraform and then save the new state after Terraform exits, in which case
|
|
the three arguments would typically all be paths within a temporary
|
|
directory used just for one operation.
|
|
|
|
Because these old workflows predate the introduction of the possibility of
|
|
[multiple workspaces](/docs/language/state/workspaces.html), setting them
|
|
overrides Terraform's usual behavior of selecting a different state filename
|
|
based on the selected workspace. If you use all three of these options then
|
|
the selected workspace has no effect on which filenames Terraform will select
|
|
for state files, and so you'll need to select different filenames yourself if
|
|
you wish to keep workspace state files distinct from one another.
|
|
|
|
These three options have no effect for configurations that have a different
|
|
backend type selected.
|
|
|
|
We do not recommend using these options in new systems, even if you are running
|
|
Terraform in automation. Instead,
|
|
[select a different backend which supports remote state](./) and configure it
|
|
within your root module, which ensures that everyone working on your
|
|
configuration will automatically retrieve and store state in the correct shared
|
|
location without any special command line options.
|