github.com/pulumi/terraform@v1.4.0/website/docs/language/state/purpose.mdx (about) 1 --- 2 page_title: State 3 description: >- 4 Terraform must store state about your managed infrastructure and 5 configuration. This state is used by Terraform to map real world resources to 6 your configuration, keep track of metadata, and to improve performance for 7 large infrastructures. 8 --- 9 10 # Purpose of Terraform State 11 12 State is a necessary requirement for Terraform to function. It is often 13 asked if it is possible for Terraform to work without state, or for Terraform 14 to not use state and just inspect real world resources on every run. This page 15 will help explain why Terraform state is required. 16 17 As you'll see from the reasons below, state is required. And in the scenarios 18 where Terraform may be able to get away without state, doing so would require 19 shifting massive amounts of complexity from one place (state) to another place 20 (the replacement concept). 21 22 ## Mapping to the Real World 23 24 Terraform requires some sort of database to map Terraform config to the real 25 world. For example, when you have a resource `resource "aws_instance" "foo"` in your 26 configuration, Terraform uses this mapping to know that the resource `resource "aws_instance" "foo"` 27 represents a real world object with the instance ID `i-abcd1234` on a remote system. 28 29 For some providers like AWS, Terraform could theoretically use something like 30 AWS tags. Early prototypes of Terraform actually had no state files and used 31 this method. However, we quickly ran into problems. The first major issue was 32 a simple one: not all resources support tags, and not all cloud providers 33 support tags. 34 35 Therefore, for mapping configuration to resources in the real world, 36 Terraform uses its own state structure. 37 38 Terraform expects that each remote object is bound to only one resource instance in the configuration. 39 If a remote object is bound to multiple resource instances, the mapping from configuration to the remote 40 object in the state becomes ambiguous, and Terraform may behave unexpectedly. Terraform can guarantee 41 a one-to-one mapping when it creates objects and records their identities in the state. 42 When importing objects created outside of Terraform, you must make sure that each distinct object 43 is imported to only one resource instance. 44 45 ## Metadata 46 47 Alongside the mappings between resources and remote objects, Terraform must 48 also track metadata such as resource dependencies. 49 50 Terraform typically uses the configuration to determine dependency order. 51 However, when you delete a resource from a Terraform configuration, Terraform 52 must know how to delete that resource from the remote system. Terraform can see that a mapping exists 53 in the state file for a resource not in your configuration and plan to destroy. However, since 54 the configuration no longer exists, the order cannot be determined from the 55 configuration alone. 56 57 To ensure correct operation, Terraform retains a copy of the most recent set 58 of dependencies within the state. Now Terraform can still determine the correct 59 order for destruction from the state when you delete one or more items from 60 the configuration. 61 62 One way to avoid this would be for Terraform to know a required ordering 63 between resource types. For example, Terraform could know that servers must be 64 deleted before the subnets they are a part of. The complexity for this approach 65 quickly explodes, however: in addition to Terraform having to understand the 66 ordering semantics of every resource for every _provider_, Terraform must also 67 understand the ordering _across providers_. 68 69 Terraform also stores other metadata for similar reasons, such as a pointer 70 to the provider configuration that was most recently used with the resource 71 in situations where multiple aliased providers are present. 72 73 ## Performance 74 75 In addition to basic mapping, Terraform stores a cache of the attribute 76 values for all resources in the state. This is the most optional feature of 77 Terraform state and is done only as a performance improvement. 78 79 When running a `terraform plan`, Terraform must know the current state of 80 resources in order to effectively determine the changes that it needs to make 81 to reach your desired configuration. 82 83 For small infrastructures, Terraform can query your providers and sync the 84 latest attributes from all your resources. This is the default behavior 85 of Terraform: for every plan and apply, Terraform will sync all resources in 86 your state. 87 88 For larger infrastructures, querying every resource is too slow. Many cloud 89 providers do not provide APIs to query multiple resources at once, and the 90 round trip time for each resource is hundreds of milliseconds. On top of this, 91 cloud providers almost always have API rate limiting so Terraform can only 92 request a certain number of resources in a period of time. Larger users 93 of Terraform make heavy use of the `-refresh=false` flag as well as the 94 `-target` flag in order to work around this. In these scenarios, the cached 95 state is treated as the record of truth. 96 97 ## Syncing 98 99 In the default configuration, Terraform stores the state in a file in the 100 current working directory where Terraform was run. This is okay for getting 101 started, but when using Terraform in a team it is important for everyone 102 to be working with the same state so that operations will be applied to the 103 same remote objects. 104 105 [Remote state](/language/state/remote) is the recommended solution 106 to this problem. With a fully-featured state backend, Terraform can use 107 remote locking as a measure to avoid two or more different users accidentally 108 running Terraform at the same time, and thus ensure that each Terraform run 109 begins with the most recent updated state.