From df5e9213101008e86cc52523ed3fcf30808ad1fc Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 14 Feb 2017 15:47:20 -0800 Subject: [PATCH] website: configuring backends --- website/source/docs/backends/config.html.md | 96 +++++++++++++++++++++ website/source/layouts/docs.erb | 4 +- 2 files changed, 98 insertions(+), 2 deletions(-) create mode 100644 website/source/docs/backends/config.html.md diff --git a/website/source/docs/backends/config.html.md b/website/source/docs/backends/config.html.md new file mode 100644 index 0000000000..ef4087b190 --- /dev/null +++ b/website/source/docs/backends/config.html.md @@ -0,0 +1,96 @@ +--- +layout: "docs" +page_title: "Backends: Configuration" +sidebar_current: "docs-backends-config" +description: |- + Terraform must initialize any configured backend before use. This can be done by simply running `terraform init`. +--- + +# Backend Configuration + +Backends are configured directly in Terraform files in the `terraform` +section. After configuring a backend, it has to be +[initialized](/docs/backends/init.html). + +Below, we show a complete example configuring the "consul" backend: + +``` +terraform { + backend "consul" { + address = "demo.consul.io" + path = "tfdocs" + } +} +``` + +You specify the backend type as a key to the `backend` stanza. Within the +stanza are backend-specific configuration keys. The list of supported backends +and their configuration is in the sidebar to the left. + +Only one backend may be specified and the configuration **may not contain +interpolations**. Terraform will validate this. + +## First Time Configuration + +When configuring a backend for the first time (moving from no defined backend +to explicitly configuring one), Terraform will give you the option to migrate +your state to the new backend. This lets you adopt backends without losing +any existing state. + +To be extra careful, we always recommend manually backing up your state +as well. You can do this by simply copying your `terraform.tfstate` file +to another location. The initialization process should create a backup +as well, but it never hurts to be safe! + +Configuring a backend for the first time is no different than changing +a configuration in the future: create the new configuration and run +`terraform init`. Terraform will guide you the rest of the way. + +## Partial Configuration + +You do not need to specify every required attribute in the configuration. +This may be desirable to avoid storing secrets (such as access keys) within +the configuration itself. We call this specifying only a _partial_ configuration. + +With a partial configuration, the remaining configuration is expected as +part of the [initialization](/docs/backends/init.html) process. There are +two ways to supply the remaining configuration: + + * **Interactively**: Terraform will interactively ask you for the required + values. Terraform will not ask you for optional values. + + * **File**: A configuration file may be specified via the command line. + This file can then be sourced via some secure means (such as + [Vault](https://www.vaultproject.io)). + +In both cases, the final configuration is stored on disk in the +".terraform" directory, which should be ignored from version control. + +This means that sensitive information can be omitted from version control +but it ultimately still lives on disk. In the future, Terraform may provide +basic encryption on disk so that values are at least not plaintext. + +## Changing Configuration + +You can change your backend configuration at any time. You can change +both the configuration itself as well as the type of backend (for example +from "consul" to "s3"). + +Terraform will automatically detect any changes in your configuration +and request a [reinitialization](/docs/backends/init.html). As part of +the reinitialization process, Terraform will ask if you'd like to migrate +your existing state to the new configuration. This allows you to easily +switch from one backend to another. + +If you're just reconfiguring the same backend, Terraform will still ask if you +want to migrate your state. You can respond "no" in this scenario. + +## Unconfiguring a Backend + +If you no longer want to use any backend, you can simply remove the +configuration from the file. Terraform will detect this like any other +change and prompt you to [reinitialize](/docs/backends/init.html). + +As part of the reinitialization, Terraform will ask if you'd like to migrate +your state back down to normal local state. Once this is complete then +Terraform is back to behaving as it does by default. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 8a00eff625..1dbebe78ba 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -469,8 +469,8 @@ Init - > - Usage + > + Configuration >