list block reference

The list block defines a query that reads existing infrastructure and returns resources that you can import to your Terraform workspace. You can only add list blocks to configuration files with .tfquery.hcl extensions. This topic provides reference information about configuring list blocks in .tfquery.hcl files. Refer to Import existing resources in bulk for information about querying and importing resources.

Configuration model

A list block supports the following configuration:

• list "<TYPE>" "<LABEL>" block
  • provider   reference | required
  • count number   | mutually exclusive with for_each
  • for_each   map or set of strings | mutually exclusive with count
  • include_resource boolean
  • limit number | 100
  • config block
    • provider-specific arguments | refer to your provider documentation

Complete configuration

The following list block includes all supported built-in arguments:

list "<TYPE>" "<LABEL>" {
  provider = <provider>.<alias>
  count = <number> # `count` and `for_each` are mutually exclusive
  for_each [ # `for_each` and `count` are mutually exclusive
    <KEY> = <VALUE>
  ]
  include_resource = <false>
  limit = 100
  config {
    <provider-specific arguments> # refer to your provider documentation
  }
}

Specification

A list block supports the following configuration.

list "<TYPE>" "<LABEL>"

You must set the following arguments for every list block:

• TYPE: Specifies the type of resource you want to query. Refer to the provider documentation for the available resource types.
• LABEL: Specifies a name for the specific list block. The label must be unique in the current directory. Use the list.<label>.<attribute> syntax to reference the list block. Refer to References to Named Values and Resource naming for expression syntax and label recommendations.

provider

The provider argument is required. It specifies which provider configuration Terraform uses to query infrastructure.

list "<TYPE>" "<LABEL>" {
  provider = <provider>
}

provider is a meta-argument. Meta-arguments are built into the Terraform language and control how Terraform creates resources. Refer to the provider reference for details about how the argument works.

count

The count meta-argument instructs Terraform to perform multiple queries using the same configuration.

list "<TYPE>" "<LABEL>" {
  count = <number>
}

count is a meta-argument. Meta-arguments are built into the Terraform language and control how Terraform creates resources. Refer to the count reference for details about how the argument works.

for_each

The for_each meta-argument instructs Terraform to create similar lists of query results without requiring separate configuration blocks for each list.

list "<TYPE>" "<LABEL>" {
  for_each = [ "<VALUE>" ]
  # . . .
}

list "<TYPE>" "<LABEL>" {
  for_each = {
    "<KEY>" = "<VALUE>"
  }
}

for_each is a meta-argument. Meta-arguments are built into the Terraform language and control how Terraform creates resources. Refer to the for_each reference for details about how the argument works.

include_resource

The include_resource argument directs Terraform to include all information about a resource in the response.

list "<TYPE>" "<LABEL>" {
  include_resource  = <boolean>
}

By default, Terraform returns the resource identity in the response, but you can set the include_resource argument to true so that the provider returns full resource objects.

Summary

Data type: Boolean Default: None

limit

The limit argument specifies the maximum number of results returned by the query.

list "<TYPE>" "<LABEL>" {
  limit  = <number>
}

You can specify a reference value that resolves to a number. The default value is 100.

When the number of results reaches the specified limit, Terraform breaks the connection to the provider and stops reporting results.

Summary

• Data type: Number
• Default: 100

config

The config block defines configuration, such as filters, tags, or other provider-specific attriubtes, to define query parameters.

list "<TYPE>" "<LABEL>" {
  config {
    <provider-specific configuration>
  }
}

Refer to your provider documentation for supported arguments and values.

Summary

• Data type: Block
• Default: None

Examples

The following examples show how to write configuration for common use cases.

Select an alternate provider configuration

In the following example, Terraform queries for google_compute_instance resources using the provider configuration with the europe alias.

provider "google" {
  region = "us-central1"
}

provider "google" {
  alias  = "europe"
  region = "europe-west1"
}

list "google_compute_instance" "example" {
  provider = google.europe
  # ...
}

Create multiple lists of query results

You can use either count or the for_each block to create multiple lists of query results. The count argument is most suitable for creating multiple lists that are identical or nearly identical. The for_each argument is most suitable for creating multiple lists based on attributes defined in a map or set.

variable "subnet_ids" {
  type = list(string)
}

list "aws_instance" "server" {
   provider = aws
   count = length(var.subnet_ids)
}

list "azurerm_resource_group" "rg" {
   provider = aws
   for_each = tomap({
      a_group       = "eastus"
      another_group = "westus2"
   })
}

list "aws_iam_user" "the-accounts" {
   provider = aws
   for_each = toset(["Todd", "James", "Alice", "Dottie"])
}

Reference a list block

In the following example, the include_resource argument is set to true in the list.aws_instance.web block. As a result, the query returns complete resource state information to the list of results for web. This lets the list.aws_instance.web-bu block reference the length attribute from web as the value for its count argument.

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

list "aws_instance" "web-bu" {
  provider = concept

  config {
    count = list.aws_instance.web.data[0].state.length
  }
}