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 specifies which provider configuration Terraform uses to query infrastructure.

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

Terraform does not implicitly use the default provider configuration when querying resources. As a result, the provider argument is required.

You can create multiple provider configurations and use a non-default configuration for specific queries. Refer to the provider block reference for information about defining alternate provider configurations.

Use the <PROVIDER>.<ALIAS> syntax to reference a provider configuration in the provider argument. Refer to Select an alternate provider configuration for an example of how to reference a specific provider configuration.

The provider argument is a meta-argument, which is built into Terraform and controls the way that Terraform queries resources. Refer to Meta-arguments for more information.

Summary

• Data type: Reference
• Default: None
• The provider argument is required
• Example: Select an alternate provider configuration

count

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

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

The value must be a whole number. You can reference variables or local values and use expressions to compute the value, but the value must resolve to a whole number.

In blocks where count is set, Terraform exposes an additional count object. You can reference the object to modify the configuration of each list of query results. The count object has an index attribute starting from 0.

To refer to an individual list of query results, use the list.<TYPE>.<NAME>[INDEX] syntax. For example, list.aws_instance.server[0] refers to the first list of query results for the aws_instance resource named server.

The count argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to Meta-arguments for more information.

Summary

• Data type: Number.
• Default: None.
• Example: Create multiple lists of query results.

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>"
  }
}

The for_each meta-argument accepts a map or a set of strings and creates a list of query results for each item in that map or set. Each list is associated with a distinct infrastructure object. Terraform creates, updates, or destroys each list when applying changes to the configuration.

You can use pure functions, such as toset() and tomap(), to create a map or set for use in the for_each argument. Whether iterating over the keys of a map or set of strings, all must be known values. Otherwise, Terraform prints an error message that for_each has dependencies that it cannot determine before applying the configuration.

Keys in the for_each argument cannot be the result of or rely on the result of impure functions, including uuid, bcrypt, or timestamp, because Terraform defers evaluating impure functions during the main evaluation step.

The for_each argument does not implicitly convert lists or tuples to sets. To declare lists of query results based on a nested data structure or combinations of elements from multiple data structures, you can use Terraform expressions and functions to derive a suitable value. Refer to the following examples for more information:

• Transform a multi-level nested structure into a flat list.
• Combine collections to produce a list of element combinations.

You cannot use sensitive values, such as sensitive input variables, sensitive outputs, or sensitive resource attributes, as arguments in for_each. Terraform uses the value in for_each to identify the list of query results and always discloses it in UI output, so sensitive values are not allowed. Terraform returns an error if you attempt to use sensitive values as for_each arguments.

If you transform a value containing sensitive data into an argument for use in for_each, be aware that most functions in Terraform will return a sensitive result if given an argument with any sensitive content. In many cases, you can achieve similar results with a for expression. For example, to call keys(local.map) where local.map is an object with sensitive values, but non-sensitive keys, you can create a value to pass to for_each using toset([for k,v in local.map : k]).

Refer to Manage sensitive data for more information.

The for_each argument exposes an each object that you can reference within the same block to modify specific lists of query results. The object has the following attributes:

• each.key: Map key or list member that corresponds to list.
• each.value: Map value that corresponds to a list.

Use the list.<TYPE>.<NAME>[<KEY>] syntax to access an instance of a resource created using for_each. For example, list.azurerm_resource_group.rg["a_group"] refers to a list of query results for the azurrm_resource_group resource named rg created from the a_group key.

The for_each argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to Meta-arguments for more information.

Summary

• Data type: Map or set of strings.
• Default: None.
• Example: Create multiple lists of query results.

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
  }
}