ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #12366 from hashicorp/f-state-docs 

website: document state environments
This commit is contained in:
Mitchell Hashimoto 2017-03-02 08:51:48 -08:00 committed by GitHub
parent 45ca69e09f 44d7d2d5b8
commit d2f09d0db7
10 changed files with 320 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
website/source/assets/stylesheets/_docs.scss
View File

@ -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,

4
website/source/docs/backends/config.html.md
View File

@ -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.

39
website/source/docs/commands/env/delete.html.md vendored Normal file
View File

@ -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"!
```

21
website/source/docs/commands/env/index.html.md vendored Normal file
View File

@ -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 <subcommand> [options] [args]`
Please click a subcommand to the left for more information.

27
website/source/docs/commands/env/list.html.md vendored Normal file
View File

@ -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
```

50
website/source/docs/commands/env/new.html.md vendored Normal file
View File

@ -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.
```

31
website/source/docs/commands/env/select.html.md vendored Normal file
View File

@ -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"!
```

99
website/source/docs/state/environments.html.md Normal file
View File

@ -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.

38
website/source/layouts/commands-env.erb Normal file
View File

@ -0,0 +1,38 @@
<% wrap_layout :inner do %>
<% content_for :sidebar do %>
<div class="docs-sidebar hidden-print affix-top" role="complementary">
<ul class="nav docs-sidenav">
<li<%= sidebar_current("docs-home") %>>
<a href="/docs/commands/index.html">&laquo; Documentation Home</a>
</li>
<li<%= sidebar_current("docs-env-index") %>>
<a href="/docs/commands/env/index.html">env Command</a>
</li>
<li<%= sidebar_current(/^docs-env-sub/) %>>
<a href="#">Subcommands</a>
<ul class="nav nav-visible">
<li<%= sidebar_current("docs-env-sub-list") %>>
<a href="/docs/commands/env/list.html">list</a>
</li>
<li<%= sidebar_current("docs-env-sub-select") %>>
<a href="/docs/commands/env/select.html">select</a>
</li>
<li<%= sidebar_current("docs-env-sub-new") %>>
<a href="/docs/commands/env/new.html">new</a>
</li>
<li<%= sidebar_current("docs-env-sub-delete") %>>
<a href="/docs/commands/env/delete.html">delete</a>
</li>
</ul>
</li>
</ul>
</div>
<% end %>
<%= yield %>
<% end %>

12
website/source/layouts/docs.erb
View File

@ -79,6 +79,10 @@
<a href="/docs/commands/destroy.html">destroy</a>
</li>
<li<%= sidebar_current("docs-commands-env") %>>
<a href="/docs/commands/env/index.html">env</a>
</li>
<li<%= sidebar_current("docs-commands-fmt") %>>
<a href="/docs/commands/fmt.html">fmt</a>
</li>
@ -169,6 +173,10 @@
<a href="/docs/state/locking.html">Locking</a>
</li>
<li<%= sidebar_current("docs-state-env") %>>
<a href="/docs/state/environments.html">Environments</a>
</li>
<li<%= sidebar_current("docs-state-remote") %>>
<a href="/docs/state/remote.html">Remote State</a>
</li>
@ -233,7 +241,7 @@
<li<%= sidebar_current("docs-providers-do") %>>
<a href="/docs/providers/do/index.html">DigitalOcean</a>
</li>
<li<%= sidebar_current("docs-providers-dns") %>>
<a href="/docs/providers/dns/index.html">DNS</a>
</li>
@ -540,4 +548,4 @@
<% end %>
<%= yield %>
<% end %>
<% end %>