diff --git a/content/terraform/v1.14.x (alpha)/data/cli-nav-data.json b/content/terraform/v1.14.x (alpha)/data/cli-nav-data.json index ab233710c0..3361f7a412 100644 --- a/content/terraform/v1.14.x (alpha)/data/cli-nav-data.json +++ b/content/terraform/v1.14.x (alpha)/data/cli-nav-data.json @@ -59,8 +59,12 @@ { "title": "Overview", "path": "import" }, { "title": "Import existing resources", "path": "import/usage" }, { - "title": "Reference", + "title": "import command reference", "href": "/cli/commands/import" + }, + { + "title": "query command reference", + "href": "/cli/commands/query" } ] }, @@ -281,6 +285,7 @@ "title": "providers schema", "href": "/cli/commands/providers/schema" }, + { "title": "query", "href": "/cli/commands/query" }, { "title": "refresh", "href": "/cli/commands/refresh" }, { "title": "show", "href": "/cli/commands/show" }, { "title": "state", "href": "/cli/commands/state" }, @@ -370,6 +375,7 @@ { "title": "providers schema", "path": "commands/providers/schema" } ] }, + { "title": "query", "path": "commands/query" }, { "title": "refresh", "path": "commands/refresh" }, { "title": "show", "path": "commands/show" }, { diff --git a/content/terraform/v1.14.x (alpha)/data/language-nav-data.json b/content/terraform/v1.14.x (alpha)/data/language-nav-data.json index ebc5f2c523..3011c7b5d8 100644 --- a/content/terraform/v1.14.x (alpha)/data/language-nav-data.json +++ b/content/terraform/v1.14.x (alpha)/data/language-nav-data.json @@ -30,7 +30,8 @@ { "title": "Overview", "path": "files" }, { "title": "Override files", "path": "files/override" }, { "title": "Dependency lock file", "path": "files/dependency-lock" }, - { "title": "Test files", "path": "files/tests" } + { "title": "Test files", "path": "files/tests" }, + { "title": "Query files", "path": "files/tfquery" } ] }, { @@ -191,11 +192,16 @@ { "title": "Import existing resources", "routes": [ - { "title": "Import a resource", "path": "import" }, - { - "title": "Generate resource configuration", - "path": "import/generating-configuration" - } + { "title": "Overview", "path": "import"}, + { + "title": "Import resources in bulk", + "path": "import/bulk" + }, + { "title": "Import a single resource", "path": "import/single-resource" }, + { + "title": "Generate configuration for single imports", + "path": "import/generating-configuration" + } ] }, { @@ -326,6 +332,32 @@ } ] }, + { + "title": "Query blocks", + "routes": [ + { + "title": "list", + "path": "block/tfquery/list", + "badge": { + "text": "BETA", + "type": "outlined", + "color": "neutral" + } + }, + { + "title": "locals", + "href": "/language/block/locals" + }, + { + "title": "provider", + "href": "/language/block/provider" + }, + { + "title": "variable", + "href": "/language/block/variable" + } + ] + }, { "title": "Meta-arguments", "path": "meta-arguments" diff --git a/content/terraform/v1.14.x (alpha)/docs/cli/commands/query.mdx b/content/terraform/v1.14.x (alpha)/docs/cli/commands/query.mdx new file mode 100644 index 0000000000..41f7333d2c --- /dev/null +++ b/content/terraform/v1.14.x (alpha)/docs/cli/commands/query.mdx @@ -0,0 +1,86 @@ +--- +page_title: locals block reference for `.tfquery.hcl` files +description: |- + Add the `locals` block to your `.tfquery.hcl` files define values to reuse within the local Terraform module. +--- + +# `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 + +```shell-session +$ 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](/terraform/language/import/bulk) for more information. + +## Flags + +- `-var '='`: 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](#set-input-variabls) + +- `-var-file=`: 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](#set-input-variabls) + +## Options + +- `-generate-config-out=`: 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](#generate-import-configuration) + +- `-json`: Instructs Terraform to print results to the console in JSON format. + - Data type: Boolean + - Example: [Generate import configuration](#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 passes sets the value of the `env` input variable to `prod`: + +```shell-session +$ terraform query -var 'env=prod' +``` + +Corresponding `tfquery.hcl` configuration: + +```hcl +list "aws_instance" "instances" { + provider = aws +} + +variable "env" { + type = string + default = "test" +} +``` + +The following command loads variable values defined in `my-vars.tfvars`: + +```shell-session +$ 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: + +```shell-session +$ terraform query -generate-config=to-import/file.tf +``` + +The following command prints `import` and `resource` blocks for the query results as JSON: + +```shell-session +$ terraform query -generate-config=file.tf -json +``` diff --git a/content/terraform/v1.14.x (alpha)/docs/language/block/tfquery/list.mdx b/content/terraform/v1.14.x (alpha)/docs/language/block/tfquery/list.mdx new file mode 100644 index 0000000000..d7d5804723 --- /dev/null +++ b/content/terraform/v1.14.x (alpha)/docs/language/block/tfquery/list.mdx @@ -0,0 +1,321 @@ +--- +page_title: list block reference for `.tfquery.hcl` files +description: |- + Add the `list` block to your `.tfquery.hcl` files to declare Terraform providers and configure them when querying existing infrastructure for resources to import. +--- + +# `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](/terraform/language/import/bulk) for information about querying and importing resources. + +@include 'beta.mdx' + +## Configuration model + +A `list` block supports the following configuration: + +- [`list "" "