github.com/vtorhonen/terraform@v0.9.0-beta2.0.20170307220345-5d894e4ffda7/website/source/docs/backends/config.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Backends: Configuration"
     4  sidebar_current: "docs-backends-config"
     5  description: |-
     6    Backends are configured directly in Terraform files in the `terraform` section.
     7  ---
     8  
     9  # Backend Configuration
    10  
    11  Backends are configured directly in Terraform files in the `terraform`
    12  section. After configuring a backend, it has to be
    13  [initialized](/docs/backends/init.html).
    14  
    15  Below, we show a complete example configuring the "consul" backend:
    16  
    17  ```
    18  terraform {
    19    backend "consul" {
    20      address = "demo.consul.io"
    21      path    = "tfdocs"
    22    }
    23  }
    24  ```
    25  
    26  You specify the backend type as a key to the `backend` stanza. Within the
    27  stanza are backend-specific configuration keys. The list of supported backends
    28  and their configuration is in the sidebar to the left.
    29  
    30  Only one backend may be specified and the configuration **may not contain
    31  interpolations**. Terraform will validate this.
    32  
    33  ## First Time Configuration
    34  
    35  When configuring a backend for the first time (moving from no defined backend
    36  to explicitly configuring one), Terraform will give you the option to migrate
    37  your state to the new backend. This lets you adopt backends without losing
    38  any existing state.
    39  
    40  To be extra careful, we always recommend manually backing up your state
    41  as well. You can do this by simply copying your `terraform.tfstate` file
    42  to another location. The initialization process should create a backup
    43  as well, but it never hurts to be safe!
    44  
    45  Configuring a backend for the first time is no different than changing
    46  a configuration in the future: create the new configuration and run
    47  `terraform init`. Terraform will guide you the rest of the way.
    48  
    49  ## Partial Configuration
    50  
    51  You do not need to specify every required attribute in the configuration.
    52  This may be desirable to avoid storing secrets (such as access keys) within
    53  the configuration itself. We call this specifying only a _partial_ configuration.
    54  
    55  With a partial configuration, the remaining configuration is expected as
    56  part of the [initialization](/docs/backends/init.html) process. There are
    57  two ways to supply the remaining configuration:
    58  
    59    * **Interactively**: Terraform will interactively ask you for the required
    60      values. Terraform will not ask you for optional values.
    61  
    62    * **File**: A configuration file may be specified via the command line.
    63      This file can then be sourced via some secure means (such as
    64      [Vault](https://www.vaultproject.io)).
    65  
    66  In both cases, the final configuration is stored on disk in the
    67  ".terraform" directory, which should be ignored from version control.
    68  
    69  This means that sensitive information can be omitted from version control
    70  but it ultimately still lives on disk. In the future, Terraform may provide
    71  basic encryption on disk so that values are at least not plaintext.
    72  
    73  ## Changing Configuration
    74  
    75  You can change your backend configuration at any time. You can change
    76  both the configuration itself as well as the type of backend (for example
    77  from "consul" to "s3").
    78  
    79  Terraform will automatically detect any changes in your configuration
    80  and request a [reinitialization](/docs/backends/init.html). As part of
    81  the reinitialization process, Terraform will ask if you'd like to migrate
    82  your existing state to the new configuration. This allows you to easily
    83  switch from one backend to another.
    84  
    85  If you're using [state environments](/docs/state/environments.html),
    86  Terraform is able to copy all environments to the destination. If Terraform
    87  detects you have multiple states, it will ask if this is what you want to do.
    88  
    89  If you're just reconfiguring the same backend, Terraform will still ask if you
    90  want to migrate your state. You can respond "no" in this scenario.
    91  
    92  ## Unconfiguring a Backend
    93  
    94  If you no longer want to use any backend, you can simply remove the
    95  configuration from the file. Terraform will detect this like any other
    96  change and prompt you to [reinitialize](/docs/backends/init.html).
    97  
    98  As part of the reinitialization, Terraform will ask if you'd like to migrate
    99  your state back down to normal local state. Once this is complete then
   100  Terraform is back to behaving as it does by default.