1--- 2layout: "language" 3page_title: "Backend Configuration - Configuration Language" 4--- 5 6# Backend Configuration 7 8 9Each Terraform configuration can specify a backend, which defines exactly where 10and how operations are performed, where [state](/docs/language/state/index.html) 11snapshots are stored, etc. Most non-trivial Terraform configurations configure 12a remote backend so that multiple people can work with the same infrastructure. 13 14## Using a Backend Block 15 16Backends are configured with a nested `backend` block within the top-level 17`terraform` block: 18 19```hcl 20terraform { 21 backend "remote" { 22 organization = "example_corp" 23 24 workspaces { 25 name = "my-app-prod" 26 } 27 } 28} 29``` 30 31There are some important limitations on backend configuration: 32 33- A configuration can only provide one backend block. 34- A backend block cannot refer to named values (like input variables, locals, or data source attributes). 35 36### Backend Types 37 38The block label of the backend block (`"remote"`, in the example above) indicates which backend type to use. Terraform has a built-in selection of backends, and the configured backend must be available in the version of Terraform you are using. 39 40The 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. 41 42Some 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 via the credentials files or environment variables that are conventional for the target system, as described in the documentation for each backend. 43 44See the list of backend types in the navigation sidebar for details about each supported backend type and its configuration arguments. 45 46### Default Backend 47 48If a configuration includes no backend block, Terraform defaults to using the `local` backend, which performs operations on the local system and stores state as a plain file in the current working directory. 49 50## Initialization 51 52Whenever a configuration's backend changes, you must run `terraform init` again 53to validate and configure the backend before you can perform any plans, applies, 54or state operations. 55 56When changing backends, Terraform will give you the option to migrate 57your state to the new backend. This lets you adopt backends without losing 58any existing state. 59 60To be extra careful, we always recommend manually backing up your state 61as well. You can do this by simply copying your `terraform.tfstate` file 62to another location. The initialization process should create a backup 63as well, but it never hurts to be safe! 64 65## Partial Configuration 66 67You do not need to specify every required argument in the backend configuration. 68Omitting certain arguments may be desirable if some arguments are provided 69automatically by an automation script running Terraform. When some or all of 70the arguments are omitted, we call this a _partial configuration_. 71 72With a partial configuration, the remaining configuration arguments must be 73provided as part of 74[the initialization process](/docs/cli/init/index.html). 75There are several ways to supply the remaining arguments: 76 77 * **File**: A configuration file may be specified via the `init` command line. 78 To specify a file, use the `-backend-config=PATH` option when running 79 `terraform init`. If the file contains secrets it may be kept in 80 a secure data store, such as 81 [Vault](https://www.vaultproject.io/), in which case it must be downloaded 82 to the local disk before running Terraform. 83 84 * **Command-line key/value pairs**: Key/value pairs can be specified via the 85 `init` command line. Note that many shells retain command-line flags in a 86 history file, so this isn't recommended for secrets. To specify a single 87 key/value pair, use the `-backend-config="KEY=VALUE"` option when running 88 `terraform init`. 89 90 * **Interactively**: Terraform will interactively ask you for the required 91 values, unless interactive input is disabled. Terraform will not prompt for 92 optional values. 93 94If backend settings are provided in multiple locations, the top-level 95settings are merged such that any command-line options override the settings 96in the main configuration and then the command-line options are processed 97in order, with later options overriding values set by earlier options. 98 99The final, merged configuration is stored on disk in the `.terraform` 100directory, which should be ignored from version control. This means that 101sensitive information can be omitted from version control, but it will be 102present in plain text on local disk when running Terraform. 103 104When using partial configuration, Terraform requires at a minimum that 105an empty backend configuration is specified in one of the root Terraform 106configuration files, to specify the backend type. For example: 107 108```hcl 109terraform { 110 backend "consul" {} 111} 112``` 113 114A backend configuration file has the contents of the `backend` block as 115top-level attributes, without the need to wrap it in another `terraform` 116or `backend` block: 117 118```hcl 119address = "demo.consul.io" 120path = "example_app/terraform_state" 121scheme = "https" 122``` 123 124The same settings can alternatively be specified on the command line as 125follows: 126 127``` 128$ terraform init \ 129 -backend-config="address=demo.consul.io" \ 130 -backend-config="path=example_app/terraform_state" \ 131 -backend-config="scheme=https" 132``` 133 134The Consul backend also requires a Consul access token. Per the recommendation 135above of omitting credentials from the configuration and using other mechanisms, 136the Consul token would be provided by setting either the `CONSUL_HTTP_TOKEN` 137or `CONSUL_HTTP_AUTH` environment variables. See the documentation of your 138chosen backend to learn how to provide credentials to it outside of its main 139configuration. 140 141## Changing Configuration 142 143You can change your backend configuration at any time. You can change 144both the configuration itself as well as the type of backend (for example 145from "consul" to "s3"). 146 147Terraform will automatically detect any changes in your configuration 148and request a [reinitialization](/docs/cli/init/index.html). As part of 149the reinitialization process, Terraform will ask if you'd like to migrate 150your existing state to the new configuration. This allows you to easily 151switch from one backend to another. 152 153If you're using multiple [workspaces](/docs/language/state/workspaces.html), 154Terraform can copy all workspaces to the destination. If Terraform detects 155you have multiple workspaces, it will ask if this is what you want to do. 156 157If you're just reconfiguring the same backend, Terraform will still ask if you 158want to migrate your state. You can respond "no" in this scenario. 159 160## Unconfiguring a Backend 161 162If you no longer want to use any backend, you can simply remove the 163configuration from the file. Terraform will detect this like any other 164change and prompt you to [reinitialize](/docs/cli/init/index.html). 165 166As part of the reinitialization, Terraform will ask if you'd like to migrate 167your state back down to normal local state. Once this is complete then 168Terraform is back to behaving as it does by default. 169