d1b46e99bd
This introduces the terraform state list command to list the resources within a state. This is the first of many state management commands to come into 0.7. This is the first command of many to come that is considered a "plumbing" command within Terraform (see "plumbing vs porcelain": http://git.661346.n2.nabble.com/what-are-plumbing-and-porcelain-td2190639.html). As such, this PR also introduces a bunch of groundwork to support plumbing commands. The main changes: - Main command output is changed to split "common" and "uncommon" commands. - mitchellh/cli is updated to support nested subcommands, since terraform state list is a nested subcommand. - terraform.StateFilter is introduced as a way in core to filter/search the state files. This is very basic currently but I expect to make it more advanced as time goes on. - terraform state list command is introduced to list resources in a state. This can take a series of arguments to filter this down. Known issues, or things that aren't done in this PR on purpose: - Unit tests for terraform state list are on the way. Unit tests for the core changes are all there.
2.1 KiB
| layout | page_title | sidebar_current | description |
|---|---|---|---|
| docs | State | docs-state | Terraform stores state which caches the known state of the world the last time Terraform ran. |
State
Terraform stores the state of your managed infrastructure from the last time Terraform was run. By default this state is stored in a local file named "terraform.tfstate", but it can also be stored remotely, which works better in a team environment.
Terraform uses this local state to create plans and make changes to your infrastructure. Prior to any operation, Terraform does a refresh to update the state with the real infrastructure.
-> Note: Terraform currently requires the state to exist after Terraform has been run. Technically, at some point in the future, Terraform should be able to populate the local state file with the real infrastructure if the file didn't exist. But currently, Terraform state is a mixture of both a cache and required configuration and isn't optional.
Inspection and Modification
While the format of the state files are just JSON, direct file editing of the state is discouraged. Terraform provides the terraform state command to perform basic modifications of the state using the CLI.
The CLI usage and output of the state commands is structured to be friendly for Unix tools such as grep, awk, etc. Additionally, the CLI insulates users from any format changes within the state itself. The Terraform project will keep the CLI working while the state format underneath it may shift.
Finally, the CLI manages backups for you automatically. If you make a mistake modifying your state, the state CLI will always have a backup available for you that you can restore.
Format
The state is in JSON format and Terraform will promise backwards compatibility with the state file. The JSON format makes it easy to write tools around the state if you want or to modify it by hand in the case of a Terraform bug. The "version" field on the state contents allows us to transparently move the format forward if we make modifications.