github.com/eliastor/durgaform@v0.0.0-20220816172711-d0ab2d17673e/website/docs/language/settings/backends/configuration.mdx (about)

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