From aeb3d1879fe7c43aea187524291692d9892673eb Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 1 Mar 2017 17:06:31 -0800 Subject: [PATCH 1/4] website: document state environments --- .../source/docs/state/environments.html.md | 99 +++++++++++++++++++ website/source/layouts/docs.erb | 8 +- 2 files changed, 105 insertions(+), 2 deletions(-) create mode 100644 website/source/docs/state/environments.html.md diff --git a/website/source/docs/state/environments.html.md b/website/source/docs/state/environments.html.md new file mode 100644 index 000000000..02fa109f6 --- /dev/null +++ b/website/source/docs/state/environments.html.md @@ -0,0 +1,99 @@ +--- +layout: "docs" +page_title: "State: Environments" +sidebar_current: "docs-state-env" +description: |- + Terraform stores state which caches the known state of the world the last time Terraform ran. +--- + +# State Environments + +An environment is a state namespace, allowing a single folder of Terraform +configurations to manage multiple distinct infrastructure resources. + +Terraform state determines what resources it manages based on what +exists in the state. This is how `terraform plan` determines what isn't +created, what needs to be updated, etc. The full details of state can be +found on the [purpose page](/docs/state/purpose.html). + +Environments are a way to create multiple states that contain +their own data so a single set of Terraform configurations can manage +multiple distinct sets of resources. + +## Using Environments + +Terraform starts with a single environment named "default". This +environment is special both because it is the default and also because +it cannot ever be deleted. If you've never explicitly used environments, then +you've only ever worked on the "default" environment. + +Environments are managed with the `terraform env` set of commands. To +create a new environment and switch to it, you can use `terraform env new`, +to switch environments you can use `terraform env switch`, etc. + +For example, creating an environment: + +``` +$ terraform env create bar +Created and switched to environment "bar"! + +You're now on a new, empty environment. Environments isolate their state, +so if you run "terraform plan" Terraform will not see any existing state +for this configuration. +``` + +As the command says, if you run `terraform plan`, Terraform will not see +any existing resources that existed on the default (or any other) environment. +**These resources still physically exist,** but are managed by another +Terraform environment. + +## Best Practices + +An environment alone **should not** be used to manage the difference between +development, staging, and production. While it is technically possible, it is +much more manageable and safe to use multiple independently managed Terraform +modules linked together with +[terraform_remote_state](/docs/providers/terraform/d/remote_state.html) +data sources. + +The [terraform_remote_state](/docs/providers/terraform/d/remote_state.html) +resource accepts an `environment` name to target. Therefore, you can link +together multiple independently managed Terraform modules with the same +environment easily. But, they can also have different environments. + +While environments are available to all, +[Terraform Enterprise](https://www.hashicorp.com/products/terraform/) +provides an interface and API for managing sets of configurations linked +with `terraform_remote_state` and viewing them all as a single environment. + +Environments alone are useful for isolating a set of resources to test +changes during development. For example, it is common to associate a +branch in a VCS with an environment so new features can be developed +without affecting the default environment. + +Future Terraform versions and environment enhancements will enable +Terraform to track VCS branches with an environment to help verify only certain +branches can make changes to a Terraform environment. + +## Environments Internals + +Environments are technically equivalent to renaming your state file. They +aren't any more complex than that. Terraform wraps this simple notion with +a set of protections and support for remote state. + +For local state, Terraform stores the state environments in a folder +`terraform.state.d`. This folder should be committed to version control +(just like local-only `terraform.tfstate`). + +For [remote state](/docs/state/remote.html), the environments are stored +directly in the configured [backend](/docs/backends). For example, if you +use [Consul](/docs/backends/types/consul.html), the environments are stored +by suffixing the state path with the environment name. + +The important thing about environment internals is that environments are +meant to be a shared resource. They aren't a private, local-only notion +(unless you're using purely local state and not committing it). + +The "current environment" name is stored only locally in the ignored +`.terraform` directory. This allows multiple team members to work on +different environments concurrently. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 932fc658d..2e329633b 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -169,6 +169,10 @@ Locking + > + Environments + + > Remote State @@ -233,7 +237,7 @@ > DigitalOcean - + > DNS @@ -540,4 +544,4 @@ <% end %> <%= yield %> -<% end %> \ No newline at end of file +<% end %> From d892b436f584581d5a8998222d5c9922b9b10433 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 1 Mar 2017 21:50:08 -0800 Subject: [PATCH 2/4] website: document env CLI --- website/source/assets/stylesheets/_docs.scss | 1 + .../source/docs/commands/env/delete.html.md | 39 +++++++++++++++ .../source/docs/commands/env/index.html.md | 21 ++++++++ website/source/docs/commands/env/list.html.md | 27 ++++++++++ website/source/docs/commands/env/new.html.md | 50 +++++++++++++++++++ .../source/docs/commands/env/switch.html.md | 31 ++++++++++++ .../source/docs/state/environments.html.md | 4 +- website/source/layouts/commands-env.erb | 38 ++++++++++++++ website/source/layouts/docs.erb | 4 ++ 9 files changed, 213 insertions(+), 2 deletions(-) create mode 100644 website/source/docs/commands/env/delete.html.md create mode 100644 website/source/docs/commands/env/index.html.md create mode 100644 website/source/docs/commands/env/list.html.md create mode 100644 website/source/docs/commands/env/new.html.md create mode 100644 website/source/docs/commands/env/switch.html.md create mode 100644 website/source/layouts/commands-env.erb diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index ba2e00e06..76a7c80e0 100755 --- a/website/source/assets/stylesheets/_docs.scss +++ b/website/source/assets/stylesheets/_docs.scss @@ -7,6 +7,7 @@ body.page-sub{ } body.layout-backend-types, +body.layout-commands-env, body.layout-commands-state, body.layout-alicloud, body.layout-archive, diff --git a/website/source/docs/commands/env/delete.html.md b/website/source/docs/commands/env/delete.html.md new file mode 100644 index 000000000..1a8af4113 --- /dev/null +++ b/website/source/docs/commands/env/delete.html.md @@ -0,0 +1,39 @@ +--- +layout: "commands-env" +page_title: "Command: env delete" +sidebar_current: "docs-env-sub-delete" +description: |- + The terraform env delete command is used to create a delete state environment. +--- + +# Command: env delete + +The `terraform env delete` command is used to delete an existing environment. + +## Usage + +Usage: `terraform env delete [NAME]` + +This command will delete the specified environment. + +To delete an environment, it must already exist, it must be empty, and +it must not be your current environment. If the environment +is not empty, Terraform will not allow you to delete it without the +`-force` flag. + +If you delete a non-empty state (via force), then resources may become +"dangling". These are resources that Terraform no longer manages since +a state doesn't point to them, but still physically exist. This is sometimes +preferred: you want Terraform to stop managing resources. Most of the time, +however, this is not intended so Terraform protects you from doing this. + +The command-line flags are all optional. The list of available flags are: + +* `-force` - Delete the state even if non-empty. Defaults to false. + +## Example + +``` +$ terraform env delete example +Deleted environment "example"! +``` diff --git a/website/source/docs/commands/env/index.html.md b/website/source/docs/commands/env/index.html.md new file mode 100644 index 000000000..cacf34286 --- /dev/null +++ b/website/source/docs/commands/env/index.html.md @@ -0,0 +1,21 @@ +--- +layout: "commands-env" +page_title: "Command: env" +sidebar_current: "docs-env-index" +description: |- + The `terraform env` command is used to manage state environments. +--- + +# Env Command + +The `terraform env` command is used to manage +[state environments](/docs/state/environments.html). + +This command is a nested subcommand, meaning that it has further subcommands. +These subcommands are listed to the left. + +## Usage + +Usage: `terraform env [options] [args]` + +Please click a subcommand to the left for more information. diff --git a/website/source/docs/commands/env/list.html.md b/website/source/docs/commands/env/list.html.md new file mode 100644 index 000000000..97fff3b6b --- /dev/null +++ b/website/source/docs/commands/env/list.html.md @@ -0,0 +1,27 @@ +--- +layout: "commands-env" +page_title: "Command: env list" +sidebar_current: "docs-env-sub-list" +description: |- + The terraform env list command is used to list all created state environments. +--- + +# Command: env list + +The `terraform env list` command is used to list all created state environments. + +## Usage + +Usage: `terraform env list` + +The command will list all created environments. The current environment +will have an asterisk (`*`) next to it. + +## Example + +``` +$ terraform env list + default +* development + mitchellh-test +``` diff --git a/website/source/docs/commands/env/new.html.md b/website/source/docs/commands/env/new.html.md new file mode 100644 index 000000000..57549aa9b --- /dev/null +++ b/website/source/docs/commands/env/new.html.md @@ -0,0 +1,50 @@ +--- +layout: "commands-env" +page_title: "Command: env new" +sidebar_current: "docs-env-sub-new" +description: |- + The terraform env new command is used to create a new state environment. +--- + +# Command: env new + +The `terraform env new` command is used to create a new state +environment. + +## Usage + +Usage: `terraform env new [NAME]` + +This command will create a new environment with the given name. This +environment must not already exist. + +If the `-state` flag is given, the state specified by the given path +will be copied to initialize the state for this new environment. + +The command-line flags are all optional. The list of available flags are: + +* `-state=path` - Path to a state file to initialize the state of this environment. + +## Example: Create + +``` +$ terraform env new example +Created and switched to environment "example"! + +You're now on a new, empty environment. Environments isolate their state, +so if you run "terraform plan" Terraform will not see any existing state +for this configuration. +``` + +## Example: Create from State + +To create a new environment from a pre-existing state path: + +``` +$ terraform env new -state=old.terraform.tfstate example +Created and switched to environment "example"! + +You're now on a new, empty environment. Environments isolate their state, +so if you run "terraform plan" Terraform will not see any existing state +for this configuration. +``` diff --git a/website/source/docs/commands/env/switch.html.md b/website/source/docs/commands/env/switch.html.md new file mode 100644 index 000000000..9b7ecb9be --- /dev/null +++ b/website/source/docs/commands/env/switch.html.md @@ -0,0 +1,31 @@ +--- +layout: "commands-env" +page_title: "Command: env switch" +sidebar_current: "docs-env-sub-switch" +description: |- + The terraform env switch command is used to switch state environments. +--- + +# Command: env switch + +The `terraform env switch` command is used to switch to a different +environment that is already created. + +## Usage + +Usage: `terraform env switch [NAME]` + +This command will switch to another environment. The environment must +already be created. + +## Example + +``` +$ terraform env list + default +* development + mitchellh-test + +$ terraform env switch default +Switch to environment "default"! +``` diff --git a/website/source/docs/state/environments.html.md b/website/source/docs/state/environments.html.md index 02fa109f6..cc6545451 100644 --- a/website/source/docs/state/environments.html.md +++ b/website/source/docs/state/environments.html.md @@ -52,13 +52,13 @@ Terraform environment. An environment alone **should not** be used to manage the difference between development, staging, and production. While it is technically possible, it is much more manageable and safe to use multiple independently managed Terraform -modules linked together with +configurations linked together with [terraform_remote_state](/docs/providers/terraform/d/remote_state.html) data sources. The [terraform_remote_state](/docs/providers/terraform/d/remote_state.html) resource accepts an `environment` name to target. Therefore, you can link -together multiple independently managed Terraform modules with the same +together multiple independently managed Terraform configurations with the same environment easily. But, they can also have different environments. While environments are available to all, diff --git a/website/source/layouts/commands-env.erb b/website/source/layouts/commands-env.erb new file mode 100644 index 000000000..2dbf2e1ea --- /dev/null +++ b/website/source/layouts/commands-env.erb @@ -0,0 +1,38 @@ +<% wrap_layout :inner do %> + <% content_for :sidebar do %> + + <% end %> + + <%= yield %> +<% end %> diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 2e329633b..5f334a9c4 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -79,6 +79,10 @@ destroy + > + env + + > fmt From 4b1dc53cc127f9459ad9dbcd21613eebafb83e42 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 1 Mar 2017 21:51:40 -0800 Subject: [PATCH 3/4] website: env switch => select --- .../source/docs/commands/env/select.html.md | 31 +++++++++++++++++++ .../source/docs/commands/env/switch.html.md | 31 ------------------- .../source/docs/state/environments.html.md | 2 +- website/source/layouts/commands-env.erb | 4 +-- 4 files changed, 34 insertions(+), 34 deletions(-) create mode 100644 website/source/docs/commands/env/select.html.md delete mode 100644 website/source/docs/commands/env/switch.html.md diff --git a/website/source/docs/commands/env/select.html.md b/website/source/docs/commands/env/select.html.md new file mode 100644 index 000000000..480e34454 --- /dev/null +++ b/website/source/docs/commands/env/select.html.md @@ -0,0 +1,31 @@ +--- +layout: "commands-env" +page_title: "Command: env select" +sidebar_current: "docs-env-sub-select" +description: |- + The terraform env select command is used to select state environments. +--- + +# Command: env select + +The `terraform env select` command is used to select to a different +environment that is already created. + +## Usage + +Usage: `terraform env select [NAME]` + +This command will select to another environment. The environment must +already be created. + +## Example + +``` +$ terraform env list + default +* development + mitchellh-test + +$ terraform env select default +Switched to environment "default"! +``` diff --git a/website/source/docs/commands/env/switch.html.md b/website/source/docs/commands/env/switch.html.md deleted file mode 100644 index 9b7ecb9be..000000000 --- a/website/source/docs/commands/env/switch.html.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: "commands-env" -page_title: "Command: env switch" -sidebar_current: "docs-env-sub-switch" -description: |- - The terraform env switch command is used to switch state environments. ---- - -# Command: env switch - -The `terraform env switch` command is used to switch to a different -environment that is already created. - -## Usage - -Usage: `terraform env switch [NAME]` - -This command will switch to another environment. The environment must -already be created. - -## Example - -``` -$ terraform env list - default -* development - mitchellh-test - -$ terraform env switch default -Switch to environment "default"! -``` diff --git a/website/source/docs/state/environments.html.md b/website/source/docs/state/environments.html.md index cc6545451..d2323d914 100644 --- a/website/source/docs/state/environments.html.md +++ b/website/source/docs/state/environments.html.md @@ -29,7 +29,7 @@ you've only ever worked on the "default" environment. Environments are managed with the `terraform env` set of commands. To create a new environment and switch to it, you can use `terraform env new`, -to switch environments you can use `terraform env switch`, etc. +to switch environments you can use `terraform env select`, etc. For example, creating an environment: diff --git a/website/source/layouts/commands-env.erb b/website/source/layouts/commands-env.erb index 2dbf2e1ea..41624e979 100644 --- a/website/source/layouts/commands-env.erb +++ b/website/source/layouts/commands-env.erb @@ -17,8 +17,8 @@ list - > - switch + > + select > From 44d7d2d5b8da5d79a6e367339e23305ed9aa7482 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Wed, 1 Mar 2017 21:54:47 -0800 Subject: [PATCH 4/4] website: update backends changing state env behavior --- website/source/docs/backends/config.html.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/website/source/docs/backends/config.html.md b/website/source/docs/backends/config.html.md index 94334d3f7..9673f4516 100644 --- a/website/source/docs/backends/config.html.md +++ b/website/source/docs/backends/config.html.md @@ -82,6 +82,10 @@ 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 using [state environments](/docs/state/environments.html), +Terraform is able to copy all environments to the destination. If Terraform +detects you have multiple states, it will ask if this is what you want to do. + 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.