github.com/paybyphone/terraform@v0.9.5-0.20170613192930-9706042ddd51/website/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  ```hcl
    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  a few 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    * **Command-line key/value pairs**: Key/value pairs in the format of
    67      `key=value` can be specified as part of the init command. Note that
    68      many shells retain command-line flags in a history file, so this isn't
    69      recommended for secrets.
    70  
    71  In all cases, the final configuration is stored on disk in the
    72  ".terraform" directory, which should be ignored from version control.
    73  
    74  This means that sensitive information can be omitted from version control
    75  but it ultimately still lives on disk. In the future, Terraform may provide
    76  basic encryption on disk so that values are at least not plaintext.
    77  
    78  When using partial configuration, Terraform requires at a minimum that
    79  an empty backend configuration is in the Terraform files. For example:
    80  
    81  ```hcl
    82  terraform {
    83    backend "consul" {}
    84  }
    85  ```
    86  
    87  This minimal requirement allows Terraform to detect _unsetting_ backends.
    88  We cannot accept the backend type on the command-line because while it is
    89  technically possible, Terraform would then be unable to detect if you
    90  want to unset your backend (and move back to local state).
    91  
    92  ## Changing Configuration
    93  
    94  You can change your backend configuration at any time. You can change
    95  both the configuration itself as well as the type of backend (for example
    96  from "consul" to "s3").
    97  
    98  Terraform will automatically detect any changes in your configuration
    99  and request a [reinitialization](/docs/backends/init.html). As part of
   100  the reinitialization process, Terraform will ask if you'd like to migrate
   101  your existing state to the new configuration. This allows you to easily
   102  switch from one backend to another.
   103  
   104  If you're using [state environments](/docs/state/environments.html),
   105  Terraform is able to copy all environments to the destination. If Terraform
   106  detects you have multiple states, it will ask if this is what you want to do.
   107  
   108  If you're just reconfiguring the same backend, Terraform will still ask if you
   109  want to migrate your state. You can respond "no" in this scenario.
   110  
   111  ## Unconfiguring a Backend
   112  
   113  If you no longer want to use any backend, you can simply remove the
   114  configuration from the file. Terraform will detect this like any other
   115  change and prompt you to [reinitialize](/docs/backends/init.html).
   116  
   117  As part of the reinitialization, Terraform will ask if you'd like to migrate
   118  your state back down to normal local state. Once this is complete then
   119  Terraform is back to behaving as it does by default.