Import: tfstate/v2

The tfstate/v2 import provides access to a Terraform state.

The state is the data that Terraform has recorded about a workspace at a particular point in its lifecycle, usually after an apply. You can read more general information about how Terraform uses state here.

The data in the tfstate/v2 import is sourced from the JSON configuration file that is generated by the terraform show -json command. For more information on the file format, see the JSON Output Format page.

Configuration Overview

To configure the import, you must add the import to your configuration file and provide the path to the appropriate plan file.

import "plugin" "tfstate/v2" {
  config = {
    "path": "./path/to/plan.json"
  }
}

Import Overview

The tfstate/v2 import is structured as currently two collections, keyed in resource address and output name, respectively.

(tfstate/v2)
├── terraform_version (string)
├── resources
│   └── (indexed by address)
│       ├── address (string)
│       ├── module_address (string)
│       ├── mode (string)
│       ├── type (string)
│       ├── name (string)
│       ├── index (float (number) or string)
│       ├── provider_name (string)
│       ├── values (map)
│       ├── depends_on (list of strings)
│       ├── tainted (boolean)
│       └── deposed_key (string)
└── outputs
    └── (indexed by name)
        ├── name (string)
        ├── sensitive (boolean)
        └── value (value)

The collections are:

• resources - The state of all resources across all modules in the state.
• outputs - The state of all outputs from the root module in the state.

These collections are specifically designed to be used with the filter quantifier expression in Sentinel, so that one can collect a list of resources to perform policy checks on without having to write complex module traversal. As an example, the following code will return all aws_instance resource types within the state, regardless of what module they are in:

all_aws_instances = filter tfstate.resources as _, r {
    r.mode is "managed" and
        r.type is "aws_instance"
}

You can add specific attributes to the filter to narrow the search, such as the module address. The following code would return resources in a module named foo only:

all_aws_instances = filter tfstate.resources as _, r {
    r.module_address is "module.foo" and
        r.mode is "managed" and
        r.type is "aws_instance"
}

The terraform_version Value

The top-level terraform_version value in this import gives the Terraform version that recorded the state. This can be used to do version validation.

import "tfstate/v2" as tfstate
import "strings"

v = strings.split(tfstate.terraform_version, ".")
version_major = int(v[1])
version_minor = int(v[2])

main = rule {
    version_major is 12 and version_minor >= 19
}

The resources Collection

The resources collection is a collection representing all of the resources in the state, across all modules.

This collection is indexed on the complete resource address as the key.

An element in the collection has the following values:

• address - The absolute resource address - also the key for the collection's index.

• module_address - The address portion of the absolute resource address.

• mode - The resource mode, either managed (resources) or data (data sources).

• type - The resource type, example: aws_instance for aws_instance.foo.

• name - The resource name, example: foo for aws_instance.foo.

• index - The resource index. Can be either a number or a string.

• provider_name - The name of the provider this resource belongs to. This allows the provider to be interpreted unambiguously in the unusual situation where a provider offers a resource type whose name does not start with its own name, such as the googlebeta provider offering google_compute_instance.

  Note: Starting with Terraform 0.13, the provider_name field contains the full source address to the provider in the Terraform Registry. Example: registry.terraform.io/hashicorp/null for the null provider.

• values - An object (map) representation of the attribute values of the resource, whose structure depends on the resource type schema. When accessing proposed state through the planned_values collection of the tfplan/v2 import, unknown values will be omitted.

• depends_on - The addresses of the resources that this resource depends on.

• tainted - true if the resource has been explicitly marked as tainted in the state.

• deposed_key - Set if the resource has been marked deposed and will be destroyed on the next apply. This matches the deposed field in the resource_changes collection in the tfplan/v2 import.

The outputs Collection

The outputs collection is a collection of outputs from the root module of the state.

Note that no child modules are included in this output set, and there is no way to fetch child module output values. This is to encourage the correct flow of outputs to the recommended root consumption level.

The collection is indexed on the output name, with the following fields:

• name: The name of the output, also the collection key.
• sensitive: Whether or not the value was marked as sensitive in configuration.
• value: The value of the output.