What is Terraform state?

Brendan Thompson • 30 January 2023 • 5 min read

What is Terraform state exactly and what does it do? If we consider the below diagram which shows us all the Parts of Terraform State is the final piece of the flow. This is where every action we perform in Terraform records its results. It allows us to store a representation of our environments and the resources within those environments. This is incredibly helpful not only for engineering purposes but also security and governance as it gives us a way to track change and understand the current state of play. State is at the core of Terraform and is one thing that sets it apart from other Infrastructure-as-Code (IaC) solutions.

Parts of Terraform - State

Figure 1 — Parts of Terraform - State


So when we create a virtual machine or a network a JSON representation of the resource is created in our state file. For this post, we don't care where that state file is located only that it exists.

Let's have a look at what an empty state file looks like:

{
  "version": 4,
  "terraform_version": "1.3.2",
  "serial": 1,
  "lineage": "af5370f0-30e4-5e77-0819-b893a4ac6d13",
  "outputs": {},
  "resources": [],
  "check_results": []
}

Let's walk through the components:

Let's have a look at some of these objects in further detail below.

Outputs

Below we can see that the outputs object in our state file now has a single object hello. This object contains the value and the type of the output and no additional information.

{
  ...
  "outputs": {
    "hello": {
      "value": "world",
      "type": "string"
    }
  },
  ...
}

The Terraform code below is what was used to produce that output object in our state file.

locals {
  value = "world"
}

output "hello" {
  value = local.value
}

So for every output that we create in Terraform a new object will be produced for us in our state file. Now, with an output, there are a few more properties that we can set; sensitive and description. It might surprise you to know that of those two only sensitive is stored in state and only when it's true, the description is purely for us engineers to read.

Resources

{
  ...
  "resources": [
    {
      "mode": "managed",
      "type": "scratch_string",
      "name": "this",
      "provider": "provider[\"registry.terraform.io/brendanthompson/scratch\"]",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "description": null,
            "id": "2a1a55c6-9f70-11ed-826a-aacb117da4fa",
            "in": "world"
          },
          "sensitive_attributes": [],
          "dependencies": [
            "module.string.random_string.this"
          ]
        }
      ]
    },
    {
      "module": "module.string",
      "mode": "managed",
      "type": "random_string",
      "name": "this",
      "provider": "provider[\"registry.terraform.io/hashicorp/random\"]",
      "instances": [
        {
          "schema_version": 2,
          "attributes": {
            ...
          },
          "sensitive_attributes": []
        }
      ]
    }
  ],
  ...
}

As you can see there are a few more attributes associated with our resources when they're written to state.

Check Results

The final piece we will talk about is the checked_results array, this tells us about any custom configuration checks we might be using in our Terraform.

{
  ...
  "check_results": [
    {
      "object_kind": "output",
      "config_addr": "output.hello",
      "status": "pass",
      "objects": [
        {
          "object_addr": "output.hello",
          "status": "pass"
        }
      ]
    }
  ]
}

Closing Out

In this article, we have gone through what state is, and the components of the state file itself. This should help you better understand what is going on when we run the different phases of Terraform. Terraform State allows us to have a point-in-time view of our infrastructure which allows us to do powerful things such as comparing our desired state (our code), to our perceived state (the state file) to reality (the resources within the platform/service). This can be surmised by the below diagram.

Phases of State

Figure 2 — Phases of State




Brendan Thompson

Principal Cloud Engineer

Discuss on Twitter