terraform query command

The terraform query command queries existing infrastructure for resources according to the tfquery.hcl file so that you can import them into your Terraform workspace.

Usage

$ terraform query [flags] [options]

Description

When you run the terraform query command, Terraform checks the current configuration directory for files with a .tfquery.hcl extension. Then, Terraform queries remote infrastructure for resources that match the list blocks defined in the query file and prints the results to the terminal. You can also add the -generate-config-out flag to generate configuration that you can use to import the resources. Refer to Import resources in bulk for more information.

When you run queries remotely in HCP Terraform, HCP Terraform can evaluate policies against configuration generated from the discovered resources. Configure a Terraform policy set to apply to your workspace or add the -policies flag to specify policy directories. Refer to Evaluate policy on queried resources for setup instructions and examples.

Flags

• -policies=<PATH>: Selects an existing policy-set directory in the uploaded configuration for HCP Terraform to evaluate against discovered resources. Repeat this flag to include multiple directories. --policies=<PATH> is an equivalent spelling. HCP Terraform automatically evaluates applicable workspace policy sets even when you omit this flag. To supply full resource data without writing a .tf file, set include_resource = true in your list blocks. Resource identities alone are insufficient policy input.

  • Data type: Path
  • Example: Evaluate policies

• -var '<INPUT-VARIABLE>=<VALUE>': Specifies a key-value pair that sets an input variable defined in the tfquery.hcl configuration. You can use this flag more than once to set additional input variables.

  • Data type: String.
  • Example: Set input variables

• -var-file=<FILENAME>: Specifies a file containing input variable values, in addition to the default terraform.tfvars and *.auto.tfvars files.

  • Data type: Filename
  • Example: Set input variables

Options

• -generate-config-out=<PATH/TO/OUTPUT>: Instructs Terraform to generate import and resource blocks for results so that you can import them. Terraform writes the configuration to a new file. The file must not already exist. When used with the -json option, Terraform generates the configuration as part of the JSON output instead of writing it to a file.

  • Data type: Path
  • Example: Generate import configuration

• -json: Instructs Terraform to print results to the console in JSON format.

  • Data type: Boolean
  • Example: Generate import configuration

• -no-color: Terraform prints monochrome results.

  • Data type: Boolean

Examples

The following examples show how to use the command for common use cases.

Set input variables

The following command sets the value of the env input variable to prod:

$ terraform query -var 'env=prod'

Corresponding tfquery.hcl configuration:

list "aws_instance" "instances" {
  provider = aws
}

variable "env" {
  type = string
  default = "test"
}

The following command loads variable values defined in my-vars.tfvars:

$ terraform query -var-file=my-vars.tfvars

Generate import configuration

The following command generates import and resource blocks for the query results to a file in the to-import directory:

$ terraform query -generate-config-out=to-import/file.tf

The following command prints import and resource blocks for the query results as JSON:

$ terraform query -generate-config-out=file.tf -json

Evaluate policies

The following command runs a remote query and evaluates policies in the ./policies directory against discovered resources. HCP Terraform evaluates policies against configuration generated from the discovered resources and reports results in the remote query log. Refer to Evaluate policy on queried resources for setup instructions and a full walkthrough.

$ terraform query -policies=./policies