diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss index ba2e00e063..76a7c80e06 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/backends/config.html.md b/website/source/docs/backends/config.html.md index 94334d3f7a..9673f45167 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. 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 0000000000..1a8af41133 --- /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 0000000000..cacf34286a --- /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 0000000000..97fff3b6b7 --- /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 0000000000..57549aa9b4 --- /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/select.html.md b/website/source/docs/commands/env/select.html.md new file mode 100644 index 0000000000..480e34454c --- /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/state/environments.html.md b/website/source/docs/state/environments.html.md new file mode 100644 index 0000000000..d2323d914d --- /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 select`, 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 +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 configurations 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/commands-env.erb b/website/source/layouts/commands-env.erb new file mode 100644 index 0000000000..41624e979f --- /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 932fc658d3..5f334a9c42 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -79,6 +79,10 @@ destroy + > + env + + > fmt @@ -169,6 +173,10 @@ Locking + > + Environments + + > Remote State @@ -233,7 +241,7 @@ > DigitalOcean - + > DNS @@ -540,4 +548,4 @@ <% end %> <%= yield %> -<% end %> \ No newline at end of file +<% end %>