github.com/Kevinklinger/open_terraform@v0.11.12-beta1/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      scheme  = "https"
    22      path    = "example_app/terraform_state"
    23    }
    24  }
    25  ```
    26  
    27  You specify the backend type as a key to the `backend` stanza. Within the
    28  stanza are backend-specific configuration keys. The list of supported backends
    29  and their configuration is in the sidebar to the left.
    30  
    31  Only one backend may be specified and the configuration **may not contain
    32  interpolations**. Terraform will validate this.
    33  
    34  ## First Time Configuration
    35  
    36  When configuring a backend for the first time (moving from no defined backend
    37  to explicitly configuring one), Terraform will give you the option to migrate
    38  your state to the new backend. This lets you adopt backends without losing
    39  any existing state.
    40  
    41  To be extra careful, we always recommend manually backing up your state
    42  as well. You can do this by simply copying your `terraform.tfstate` file
    43  to another location. The initialization process should create a backup
    44  as well, but it never hurts to be safe!
    45  
    46  Configuring a backend for the first time is no different than changing
    47  a configuration in the future: create the new configuration and run
    48  `terraform init`. Terraform will guide you the rest of the way.
    49  
    50  ## Partial Configuration
    51  
    52  You do not need to specify every required argument in the backend configuration.
    53  Omitting certain arguments may be desirable to avoid storing secrets, such as
    54  access keys, within the main configuration. When some or all of the arguments
    55  are omitted, we call this a _partial configuration_.
    56  
    57  With a partial configuration, the remaining configuration arguments must be
    58  provided as part of
    59  [the initialization process](/docs/backends/init.html#backend-initialization).
    60  There are several ways to supply the remaining arguments:
    61  
    62    * **Interactively**: Terraform will interactively ask you for the required
    63      values, unless interactive input is disabled. Terraform will not prompt for
    64      optional values.
    65  
    66    * **File**: A configuration file may be specified via the `init` command line.
    67      To specify a file, use the `-backend-config=PATH` option when running
    68      `terraform init`. If the file contains secrets it may be kept in
    69      a secure data store, such as
    70      [Vault](https://www.vaultproject.io/), in which case it must be downloaded
    71      to the local disk before running Terraform.
    72  
    73    * **Command-line key/value pairs**: Key/value pairs can be specified via the
    74      `init` command line. Note that many shells retain command-line flags in a
    75      history file, so this isn't recommended for secrets. To specify a single
    76      key/value pair, use the `-backend-config="KEY=VALUE"` option when running
    77      `terraform init`.
    78  
    79  If backend settings are provided in multiple locations, the top-level
    80  settings are merged such that any command-line options override the settings
    81  in the main configuration and then the command-line options are processed
    82  in order, with later options overriding values set by earlier options.
    83  
    84  The final, merged configuration is stored on disk in the `.terraform`
    85  directory, which should be ignored from version control. This means that
    86  sensitive information can be omitted from version control, but it will be
    87  present in plain text on local disk when running Terraform.
    88  
    89  When using partial configuration, Terraform requires at a minimum that
    90  an empty backend configuration is specified in one of the root Terraform
    91  configuration files, to specify the backend type. For example:
    92  
    93  ```hcl
    94  terraform {
    95    backend "consul" {}
    96  }
    97  ```
    98  
    99  A backend configuration file has the contents of the `backend` block as
   100  top-level attributes, without the need to wrap it in another `terraform`
   101  or `backend` block:
   102  
   103  ```hcl
   104  address = "demo.consul.io"
   105  path    = "example_app/terraform_state"
   106  scheme  = "https"
   107  ```
   108  
   109  The same settings can alternatively be specified on the command line as
   110  follows:
   111  
   112  ```
   113  $ terraform init \
   114      -backend-config="address=demo.consul.io" \
   115      -backend-config="path=example_app/terraform_state" \
   116      -backend-config="scheme=https"
   117  ```
   118  
   119  ## Changing Configuration
   120  
   121  You can change your backend configuration at any time. You can change
   122  both the configuration itself as well as the type of backend (for example
   123  from "consul" to "s3").
   124  
   125  Terraform will automatically detect any changes in your configuration
   126  and request a [reinitialization](/docs/backends/init.html). As part of
   127  the reinitialization process, Terraform will ask if you'd like to migrate
   128  your existing state to the new configuration. This allows you to easily
   129  switch from one backend to another.
   130  
   131  If you're using multiple [workspaces](/docs/state/workspaces.html),
   132  Terraform can copy all workspaces to the destination. If Terraform detects
   133  you have multiple workspaces, it will ask if this is what you want to do.
   134  
   135  If you're just reconfiguring the same backend, Terraform will still ask if you
   136  want to migrate your state. You can respond "no" in this scenario.
   137  
   138  ## Unconfiguring a Backend
   139  
   140  If you no longer want to use any backend, you can simply remove the
   141  configuration from the file. Terraform will detect this like any other
   142  change and prompt you to [reinitialize](/docs/backends/init.html).
   143  
   144  As part of the reinitialization, Terraform will ask if you'd like to migrate
   145  your state back down to normal local state. Once this is complete then
   146  Terraform is back to behaving as it does by default.