opentofu/website/docs/language/settings/backends/configuration.mdx

---
sidebar_position: 1
description: >-
  Use the `backend` block to control where OpenTofu stores state. Learn about the available state backends, the backend block, initializing backends, partial backend configuration, changing backend configuration, and unconfiguring a backend.
---

# Backend Configuration

A backend defines where OpenTofu stores its [state](../../../language/state/index.mdx) data files.

OpenTofu uses persisted state data to keep track of the resources it manages. Most non-trivial OpenTofu configurations either integrate with [TACOS](../../../intro/tacos.mdx) (TF Automation and Collaboration Software) or use a backend to store state remotely. This lets multiple people access the state data and work together on that collection of infrastructure resources.

This page describes how to configure a backend by adding the [`backend` block](#using-a-backend-block) to your configuration.

## Available Backends

By default, OpenTofu uses a backend called [`local`](../../../language/settings/backends/local.mdx), which stores state as a local file on disk. You can also configure one of the built-in backends included in this documentation.

Some of these backends act like plain remote disks for state files, while others support locking the state while operations are being performed. This helps prevent conflicts and inconsistencies. The built-in backends listed are the only backends. You cannot load additional backends as plugins.

## Using a Backend Block

You do not need to configure a backend when using [TACOS](../../../intro/tacos.mdx) (TF Automation and Collaboration Software) because
it automatically manages state in the workspaces associated with your configuration. If your configuration includes a [`cloud` block](../../../language/settings/tf-cloud.mdx), it cannot include a `backend` block.

To configure a backend, add a nested `backend` block within the top-level
`terraform` block. The following example configures the `remote` backend.

```hcl
terraform {
  backend "remote" {
    organization = "example_corp"

    workspaces {
      name = "my-app-prod"
    }
  }
}
```

There are some important limitations on backend configuration:

- A configuration can only provide one backend block.
- A backend block cannot refer to values in the state or locals derived from the state (data source attributes).

### Credentials and Sensitive Data

Backends store state in a remote service, which allows multiple people to access it. Accessing remote state generally requires access credentials, since state data contains extremely sensitive information.

:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTofu will include these values in both the `.terraform` subdirectory and in plan files. This can leak sensitive credentials.
:::

OpenTofu writes the backend configuration in plain text in two separate files.
- The `.terraform/terraform.tfstate` file contains the backend configuration for the current working directory.
- All plan files capture the information in `.terraform/terraform.tfstate` at the time the plan was created. This helps ensure OpenTofu is applying the plan to correct set of infrastructure.

When applying a plan that you previously saved to a file, OpenTofu uses the backend configuration stored in that file instead of the current backend settings. If that configuration contains time-limited credentials, they may expire before you finish applying the plan. Use environment variables to pass credentials when you need to use different values between the plan and apply steps.

### Backend Types

The block label of the backend block (`"remote"`, in the example above) indicates which backend type to use. OpenTofu has a built-in selection of backends, and the configured backend must be available in the version of OpenTofu you are using.

The arguments used in the block's body are specific to the chosen backend type; they configure where and how the backend will store the configuration's state, and in some cases configure other behavior.

Some backends allow providing access credentials directly as part of the configuration for use in unusual situations, for pragmatic reasons. However, in normal use, we _do not_ recommend including access credentials as part of the backend configuration. Instead, leave those arguments completely unset and provide credentials using the credentials files or environment variables that are conventional for the target system, as described in the documentation for each backend.

Refer to the page for each backend type for full details and that type's configuration arguments.

### Default Backend

If a configuration includes no backend block, OpenTofu defaults to using the `local` backend, which stores state as a plain file in the current working directory.

## Initialization

When you change a backend's configuration, you must run `tofu init` again
to validate and configure the backend before you can perform any plans, applies,
or state operations.

After you initialize, OpenTofu creates a `.terraform/` directory locally. This directory contains the most recent backend configuration, including any authentication parameters you provided to the OpenTofu CLI. Do not check this directory into Git, as it may contain sensitive credentials for your remote backend.

The local backend configuration is different and entirely separate from the `terraform.tfstate` file that contains [state data](../../../language/state/index.mdx) about your real-world infrastruture. OpenTofu stores the `terraform.tfstate` file in your remote backend.

When you change backends, OpenTofu gives you the option to migrate
your state to the new backend. This lets you adopt backends without losing
any existing state.

:::warning Important
Before migrating to a new backend, we strongly recommend manually backing up your state by copying your `terraform.tfstate` file
to another location.
:::

## Partial Configuration

You do not need to specify every required argument in the backend configuration.
Omitting certain arguments may be desirable if some arguments are provided
automatically by an automation script running OpenTofu. When some or all of
the arguments are omitted, we call this a _partial configuration_.

With a partial configuration, the remaining configuration arguments must be
provided as part of [the initialization process](../../../cli/init/index.mdx).

There are several ways to supply the remaining arguments:

- **File**: A configuration file may be specified via the `init` command line.
  To specify a file, use the `-backend-config=PATH` option when running
  `tofu init`. If the file contains secrets it may be kept in
  a secure data store, such as [Vault](https://www.vaultproject.io/),
  in which case it must be downloaded to the local disk before running OpenTofu.

- **Command-line key/value pairs**: Key/value pairs can be specified via the
  `init` command line. Note that many shells retain command-line flags in a
  history file, so this isn't recommended for secrets. To specify a single
  key/value pair, use the `-backend-config="KEY=VALUE"` option when running
  `tofu init`.

- **Interactively**: OpenTofu will interactively ask you for the required
  values, unless interactive input is disabled. OpenTofu will not prompt for
  optional values.

If backend settings are provided in multiple locations, the top-level
settings are merged such that any command-line options override the settings
in the main configuration and then the command-line options are processed
in order, with later options overriding values set by earlier options.

The final, merged configuration is stored on disk in the `.terraform`
directory, which should be ignored from version control. This means that
sensitive information can be omitted from version control, but it will be
present in plain text on local disk when running OpenTofu.

When using partial configuration, OpenTofu requires at a minimum that
an empty backend configuration is specified in one of the root OpenTofu
configuration files, to specify the backend type. For example:

```hcl
terraform {
  backend "consul" {}
}
```

### File

A backend configuration file has the contents of the `backend` block as
top-level attributes, without the need to wrap it in another `tofu`
or `backend` block:

```hcl
address = "demo.consul.io"
path    = "example_app/terraform_state"
scheme  = "https"
```

`*.backendname.tfbackend` (e.g. `config.consul.tfbackend`) is the recommended
naming pattern. OpenTofu will not prevent you from using other names but following
this convention will help your editor understand the content and likely provide
better editing experience as a result.

### Command-line key/value pairs

The same settings can alternatively be specified on the command line as
follows:

```
$ tofu init \
    -backend-config="address=demo.consul.io" \
    -backend-config="path=example_app/terraform_state" \
    -backend-config="scheme=https"
```

The Consul backend also requires a Consul access token. Per the recommendation
above of omitting credentials from the configuration and using other mechanisms,
the Consul token would be provided by setting either the `CONSUL_HTTP_TOKEN`
or `CONSUL_HTTP_AUTH` environment variables. See the documentation of your
chosen backend to learn how to provide credentials to it outside of its main
configuration.

## Variables and Locals

You may use variables and locals in backend configurations (with restrictions). Backend configuration may not contain any references to data in the state or provider defined functions. All values must be able to be resolved during `tofu init` before the state is available.

:::danger Warning
We recommend against using variables to specify secrets or other sensitive data in your backend configuration. This can leak sensitive credentials if improperly configured.
:::

```hcl
locals {
	region = "us-east-1"
}

terraform {
	backend "s3" {
		region = local.region
	}
}
```

## Changing Configuration

You can change your backend configuration at any time. You can change
both the configuration itself as well as the type of backend (for example
from "consul" to "s3").

OpenTofu will automatically detect any changes in your configuration
and request a [reinitialization](../../../cli/init/index.mdx). As part of
the reinitialization process, OpenTofu will ask if you'd like to migrate
your existing state to the new configuration. This allows you to easily
switch from one backend to another.

If you're using multiple [workspaces](../../../language/state/workspaces.mdx),
OpenTofu can copy all workspaces to the destination. If OpenTofu detects
you have multiple workspaces, it will ask if this is what you want to do.

If you're just reconfiguring the same backend, OpenTofu will still ask if you
want to migrate your state. You can respond "no" in this scenario.

## Unconfiguring a Backend

If you no longer want to use any backend, you can simply remove the
configuration from the file. OpenTofu will detect this like any other
change and prompt you to [reinitialize](../../../cli/init/index.mdx).

As part of the reinitialization, OpenTofu will ask if you'd like to migrate
your state back down to normal local state. Once this is complete then
OpenTofu is back to behaving as it does by default.