Evaluate policy on queried resources

This topic describes how to evaluate policies against resources discovered during Terraform searches. Refer to the terraform query command reference for information about command syntax and flags.

Introduction

Use the terraform query command to search existing infrastructure for resources that are not yet managed by Terraform. Refer to Import resources in bulk for more information about the import workflow.

You can also connect your workspace to HCP Terraform or Terraform Enterprise to run queries remotely in the platform. Running queries remotely lets you evaluate policies against configuration generated from the discovered resources.

Workflow

To evaluate policies on queried resources:

• Define policies on the Terraform policy framework and group them into sets.
• Configure HCP Terraform or Terraform Enterprise so that the platform can access resource data necessary for generating policy input. You must also specify the execution mode and enable policy evaluation.
• Provide HCP Terraform or Terraform Enterprise with credentials that allow the platform to read resources you query.

Define policies

Define a set of policies for the Terraform policy framework scoped to your workspace. Refer to Policy enforcement for more information about policy frameworks, creating policies, and creating policy sets.

Alternatively, you can specify policy directories with the -policies flag at runtime.

Configure HCP Terraform or Terraform Enterprise

HCP Terraform and Terraform Enterprise need full resource data to generate policy input. Set include_resource = true in your list blocks to supply that data without writing a .tf file. Alternatively, use -generate-config-out to request full resource data and write generated resource and import blocks to your workstation. For queries started in the UI, select Generate starter configuration. The additional resource reads can increase query duration.

The -policies flag alone does not request resource data or enable configuration generation. Resource identities alone are insufficient policy input.

Set the workspace's execution mode to Remote or Agent. Agents enable the query operation by default. Refer to HCP Terraform agents.

Use an organization with Terraform policy and Search policy evaluation enabled, including access to policy enforcement and versioned policy sets. Refer to Search policy requirements.

Configure credentials for HCP Terraform or Terraform Enterprise

Configure provider credentials in the workspace with permission to read the resources you query. Refer to Provide credentials for more information.

For example, add the following cloud block and provider requirement to main.tf. Replace ORGANIZATION_NAME and WORKSPACE_NAME with your organization and workspace names:

terraform {
  cloud {
    organization = "ORGANIZATION_NAME"

    workspaces {
      name = "WORKSPACE_NAME"
    }
  }

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.0.0"
    }
  }
}

Define queries

Your provider must support listing resources that you want to search for. The following example configures the AWS provider to use a version that supports listing aws_instance resources. The query appears in an instances.tfquery.hcl file:

provider "aws" {
  region = "us-east-2"
}

list "aws_instance" "example" {
  provider         = aws
  include_resource = true
}

Initialize the directory

Run the terraform init command to install the provider version and connect to HCP Terraform or Terraform Enterprise. Refer to initialize the working directory for more information.

Run the remote query

Run the terraform query command to search for resources.

$ terraform query

HCP Terraform automatically evaluates applicable Terraform policy sets configured for your workspace, including inherited project and organization-wide assignments. Query-time policy evaluation does not evaluate Sentinel or OPA policies. When you run remote queries, HCP Terraform also evaluates policies that you specify with the -policies flag.

To supply an explicit policy source, use the -policies flag to select a directory in your configuration that contains your policies. For this example, create a policies directory and add the following resource policy to policies/instance-type.policy.hcl. Refer to Write policies for policy syntax and inputs.

policy {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

resource_policy "aws_instance" "instance_type" {
  enforcement_level = "advisory"

  enforce {
    condition     = attrs.instance_type == "t3.micro"
    error_message = "Use t3.micro instances."
  }
}

Run the remote query and explicitly specify the policy directory. You can exclude the -policies flag if your HCP Terraform or Terraform Enterprise workspace is configured to evaluate a set of policies. The include_resource = true setting supplies policy input without writing a .tf file:

$ terraform query -policies=./policies

To evaluate policies and write importable configuration, use an output file that does not exist:

$ terraform query -policies=./policies -generate-config-out=generated.tf

The -generate-config-out option instructs HCP Terraform to request full resource data and generate configuration. Use it as an alternative to setting include_resource = true in your list blocks when you also want to write an importable configuration file.

To evaluate policies from multiple existing directories, repeat the flag. For example:

$ terraform query -policies=./policies/security -policies=./policies/tagging

Explicit policy directories must exist in your working directory so Terraform includes them in the configuration uploaded to HCP Terraform. The paths must satisfy the Queries API path restrictions. These policies are independent of policies that HCP Terraform applies to your workspace from configured policy sets. Refer to Search and import resources in HCP Terraform for the UI workflow and automatic-policy opt-out control.

Inspect policy results

When HCP Terraform evaluates policies from workspace policy sets or the -policies flag against discovered resources, the remote query log includes policy summaries. The terminal output shows the evaluated-policy count and groups resource outcomes under Policy results for each list block:

For detailed policy results and diagnostics, inspect the Policy evaluation details in the HCP Terraform UI or retrieve the query log using log-read-url from the Queries API.

Query-time policy results are informational, including failures of mandatory policies. They do not block import or replace plan-time enforcement. Missing resource configuration produces an Unknown result, and generated input can omit relationships or attributes that policies need. A query with no failing policies does not establish that all resources pass policy evaluation during plan and apply operations. Review the results and generated configuration before continuing with the import workflow.