• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Terraform Cloud

Skip to main content
  • Terraform Cloud
  • Plans and Features
  • Getting Started
  • Migrating to Terraform Cloud
    • Overview
      • Defining Policies
        • tfconfig
        • tfconfig/v2
        • tfplan
        • tfplan/v2
        • tfstate
        • tfstate/v2
        • tfrun
      • Policy Set VCS Repositories
      • Mocking Terraform Sentinel Data
      • Working With JSON Result Data
      • Using Sentinel with Terraform 0.12
    • Managing Policy Sets
    • Policy Results

  • Terraform Cloud Agents

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Terraform Cloud
  4. Policy Enforcement
  5. Sentinel Policies
  6. Imports
  7. tfstate/v2

Note: Sentinel policies are a paid feature, available as part of the Team & Governance upgrade package. Learn more about Terraform Cloud pricing here.

Note: This is documentation for the next version of the tfstate Sentinel import, designed specifically for Terraform 0.12. This import requires Terraform 0.12 or higher, and must currently be loaded by path, using an alias, example: import "tfstate/v2" as tfstate.

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

NOTE: Since Terraform Cloud currently only supports policy checks at plan time, the usefulness of this import is somewhat limited, as it will usually give you the state prior to the plan the policy check is currently being run for. Depending on your needs, you may find the planned_values collection in tfplan/v2 more useful, which will give you a predicted state by applying plan data to the data found here. The one exception to this rule is data sources, which will always give up to date data here, as long as the data source could be evaluated at plan time.

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.

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
}

NOTE: The above example will give errors when working with pre-release versions (example: 0.12.0beta1). Future versions of this import will include helpers to assist with processing versions that will account for these kinds of exceptions.

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.
Edit this page on GitHub

On this page

  1. Import: tfstate/v2
  2. Import Overview
  3. The terraform_version Value
  4. The resources Collection
  5. The outputs Collection
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)