terraform/website/docs/language/settings/backends/local.mdx

96 lines
3.5 KiB
Plaintext

---
page_title: 'Backend Type: 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](/language/state/workspaces), 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](/language/settings/backends) 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.