added usage docs

Author: trujillo-adam

content/terraform/v1.14.x (alpha)/data/language-nav-data.json

@@ -192,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"
+        }
     ]
   },
   {

content/terraform/v1.14.x (alpha)/docs/language/import/bulk.mdx

@@ -0,0 +1,129 @@
+---
+page_title: Import existing resources in bulk
+description: Learn how to query existing infrastructure for unmanaged resources so you can import them into Terraform in bulk
+---
+
+# Import existing resources in bulk
+
+You can configure queries that instruct Terraform to search your existing infrastructure for unmanaged resources. Terraform can also generate configuration for importing the resources it finds so that you can import them to your Terraform workspace in bulk. For information about importing single resources or small batches of resources, refer to [Import single resources](/terraform/language/import/single-resource) for instructions.
+
+## Introduction
+
+For organizations with large sets of infrastructure resources, manually identifying and importing them is tedious and labor intensive, even when using third-party tools or custom scripts. To alleviate this burden, you can write HCL-based queries and run them with the Terraform CLI to retrieve unmanaged resources so that you can import them in bulk. 
+
+Complete the following steps to find and import resources in bulk:
+
+- Search for resources: Create `list` blocks to search for existing resources.
+- Generate configuration: Use the Terraform command to generate `resource` and `import` blocks for importing the resources. The configuration also includes the resource ID.
+- Import resources: Copy the generated configuration into your main.tf file and run a `terraform apply` command to import the resources.
+- After importing resources, you can remove the generated configuration or keep it as an historical record.
+
+### Resource identity
+
+Terraform uniquely identifies resources according to either the ID assigned by the cloud provider or a collection of specific attributes defined by the provider. For example, the `s3_bucket` resource available in the AWS provider uniquely identifies buckets according to the following attributes:
+
+- `account_id`
+- `bucket`
+- `region`  
+
+Refer to your provider documentation for information about resource identities. 
+
+## Requirements
+
+Terraform v1.12 or newer is required to uniquely ID resources according the resource identity. For v1.11 and older, Terraform uses the cloud provider ID attribute. 
+
+## Define a query
+
+To search for resources, you must create a standard `.tf` configuration and a `.tfquery.hcl` configuration. 
+
+### Standard configurations
+
+If your `.tf` configuration does not already have a `required_providers` block, add it so that Terraform can install all provider plugins required to create and manage resources specified in the configuration. Refer to the [`required_providers` reference](/terraform/language/block/terraform#required_providers) for details on how to configure this block.
+
+### Query configurations
+
+Create a file with a `.tfquery.hcl` extension and add `list` blocks to define queries that read existing infrastructure and return lists of unmanaged resources. 
+
+Each `list` block requires an inline argument that specifies the type of resource you are querying. The type is specific to your provider. The block also requires an inline argument that declares a local name for the list of results returned by the query. Refer to the [`list` block reference](/terraform/language/block/tfquery/list) for configuration details.  
+
+The following example defines a `list` block named `prod` that queries `aws_instances`:
+
+```hcl
+list "aws_instance" "prod" {
+  # . . .
+}
+```
+
+Add the following arguments to your `list` block:
+
+- `provider`: This argument is required. It specifies which provider configuration Terraform should use to perform the query. The `list` block retrieves the provider configuration from the [`terraform` block](/terraform/language/block/terraform) in your `main.tf` configuration, but you can declare a `provider` block in your query file with an alternate configuration and reference it in the `provider` argument in your `list` block. 
+
+- `config`: Add the `config` block to your `list` block and define provider-specific arguments to build your query. Refer to your provider documentation for supported arguments and values.  
+
+- `include_resource`: By default, Terraform retrieves only resource identities, but you can set the `include_resource` argument to `true` so that Terraform can also retrieve all available resource attributes. To reference resource attributes retrieved by the list block, you must enable the `include_resource` argument. Setting this argument to `true` may affect performance.  
+
+- `limit`: By default, Terraform retrieves up to 100 resources per query, but you can use the `limit` argument to specify a higher or lower number of results.
+
+The `list` block also supports several Terraform **meta-arguments**, which are arguments built into Terraform configuration language that configure how Terraform creates and manages infrastructure objects. For example, you can use the `count` meta-argument to create multiple instances of the resource list returned by the query. Refer to [Meta-arguments](/terraform/language/meta-arguments) for more information.
+
+The following example queries AWS for `aws_instance` resources that match {. . .} and returns complete resource information for the first 50 results:
+
+```hcl
+list "aws_instance" "prod" {
+  include_resource = true
+  limit = 50
+  config {
+    TBD
+  }
+}
+```
+
+### Parameterize your query configuration
+
+You can parameterize your `.tfquery.hcl` file so that you can reuse it with a different set of inputs. Refer to [Set configuration parameters](/terraform/language/parameterize) for instructions on how to parameterize configurations.
+
+Add the following blocks to your query file to parameterize the configuration:
+
+- `variable`: Add the `variable` block to your query file to define variables that people who run the query configuration can provide at runtime. Refer to the [`variable` block reference](/terraform/language/block/variable) for configuration details.
+- `locals`: Add the `locals` block to your query file to define temporary variables scoped to the query configuration. Refer to the [`locals` block reference](/terraform/language/block/locals) for configuration details.
+
+### Specify a custom provider configuration
+
+The query file checks the `main.tf` configuration for provider configurations, but you can also declare one or more `provider` blocks in the query configuration file to define alternate provider configurations. To use one of the alternate provider configurations, add the [`provider` argument](#provider) to your `list` block and reference the name of the provider configuration.  Refer to the [`provider` block reference](/terraform/language/block/provider) for information about how to configure `provider` blocks.
+
+## Query the infrastructure
+
+Run the [`terraform query` command](/terraform/cli/commands/query) to retrieve the resource types specified in your `list` blocks. The command prints the results to your console. By default, each result includes the following information:
+
+- Reference to the `list` block that queried for resources formatted as `list.<type>.<label>`.
+- Identity of a discovered resource.   
+
+The provider may also include other information, such as a description of the resource. Refer to your provider documentation for details.
+
+The number of results depends on the provider, as well as any query constraints you configured in the query configuration file.
+
+To generate machine-readable results, you can include the `-json` flag:
+
+```shell-session
+$ terraform query -json
+```
+
+## Generate configuration for importing results
+
+To generate configuration, run the [`terraform query` command](/terraform/cli/commands/query) and add the `-generate-config-out` flag. The flag expects a path where Terraform stores the generated configuration as a file named `generated.tf`. The `generated.tf` file contains the `resource` and `import` blocks, including resource identities, necessary for importing results.
+
+The following example generates configuration to the working directory:
+
+```shell-session
+$ terraform query -generate-config-out=generated.tf
+```
+ 
+After generating the results file, you must remove the file before rerunning the command to generate a new results file. Rerunning the command when a `generated.tf` already exists at the specified path results in an error. 
+
+## Import resources
+
+Copy the `import` and `resource` blocks from the `generated.tf` file to your `main.tf` configuration and run the [`terraform apply` command](/terraform/cli/commands/apply) to import the resources.  
+  
+## Next steps
+
+After importing your resources, you can discard the query configuration file and the `generated.tf` file, but we recommend keeping them as a historical record.

content/terraform/v1.14.x (alpha)/docs/language/import/index.mdx

@@ -1,175 +1,24 @@
 ---
-page_title: Import existing resources into Terraform state
-description: Learn how to import existing resources into Terraform state so that you can manage them as code 
+page_title: Import resources overview
+description: Learn about importing existing infrastructure resources to your Terraform workspace using the bulk import workflow or the single-resource import workflow
 ---
 
-# Import an existing resource
+# Import resources overview
 
-You can import existing infrastructure resources into your Terraform state so that you can begin managing them using Terraform. This page describes how to write Terraform configuration for importing resources, which lets you import multiple resources at the same time and review the import as part of your Terraform workflow. 
+If you have existing infrastructure resources, you can import them to your Terraform workspace so that you can begin managing the resources as code. 
 
-> **Hands-on:** Try the [State Import](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
+## Workflows
 
-
-## Overview
-
-When you import existing infrastructure into state, you must also define the Terraform configuration corresponding to that resource to manage the rest of its lifecycle. You can manually write all of the configuration or use the Terraform CLI to generate configuration for resources your are importing. When you import resources, Terraform pulls all of the resource's attributes into the state file, but you do not need to define all of them in the `resource` block. 
-
-We recommend manually writing the `resource` block when you know how to configure all or most of the resource's arguments. Use generated configuration when importing multiple resources or a single complex resource that you do not already have the configuration for.
-
-This page describes how to manually write all of your import configuration. Refer to [Generate configuration](/terraform/language/import/generating-configuration) for instructions on how to generate the configuration.
-
-Complete the following steps to import resources:
-
-1. Define a destination resource configuration for each resource you want to import. 
-1. Add a corresponding `import` block for each existing resource you want to import. 
-1. Run `terraform plan` and verify that the import plan meets your needs. 
-1. Apply the configuration to import the resources and update your Terraform state.
-
-You can remove `import` blocks from your configuration after importing resources, but we recommend keeping them as an historical artifact. Refer to [Post import tasks](#post-import-tasks) for more information.
-
-## Define a destination resource 
-
-Terraform reconciles your configuration and state to create an execution plan. As a result, you must define a `resource` block for any resource in state to prevent Terraform from destroying it. The only required arguments to the `resource` block for an imported resource are the inline resource type and resource label, which form the Terraform state address. 
-
-The following example resource is the destination for an AWS instance with a resource address of `aws_instance.example`:
-
-```hcl
-resource "aws_instance" "example" {
-  name = "renderer"
-}
-```
-
-You should include provider-specific resource arguments that have non-default values to prevent Terraform from destroying the imported resource on the next apply operation. Terraform uses default values for arguments you do not include in the `resource` block. If Terraform assigns default values, but the existing resource has non-default attributes, the resource in state will not match the actual infrastructure, and Terraform will plan to update the resource on the next apply operation. Refer to the provider documentation for information about which arguments the resource you are importing supports.
-
-
-### Configure Terraform arguments
-
-You can include [meta-arguments](/terraform/language/meta-arguments) to modify how Terraform manages your resources once imported into state. Meta-arguments are Terraform-specific arguments that establish explicit dependencies between resources and prevent destructive operations. Refer the [`resource` block reference](/terraform/language/block/resource) for details about Terraform meta-arguments you can define. 
-
-## Define an `import` block
-
-Add an `import` block and specify the ID of an existing resource and [destination resource address](#define-a-destination-resource) to import to. Cloud providers use different methods of identifying resources. As a result, the ID depends on your cloud vendor and the kind of resource you are importing. Refer to the provider documentation for the resource you want to import for details.
-
-Use the following syntax to configure the `import` block: 
+Importing unmanaged resources to your workspace requires an `import` block that specifies the unique infrastructure resource ID to import. The block also declares an address for the imported resource in state. Additionally, you must create a destination `resource` block that matches the address declared in the `import` block. The `resource` block represents the resource in the configuration. 
 
-```hcl
-import {
-  to = TYPE.LABEL
-  id = "<RESOURCE-ID>"
-}
-
-resource "<TYPE>" "<LABEL>" {
-  # ...
-}
-```
-
-The `to` argument is the destination resource address, which is formed from the resource type and label. 
-
-The `id` argument is an identifier specific to your cloud provider.
-
-Refer to the [`import` block reference](/terraform/language/block/import) for details.
-
-
-### Import multiple instances
-
-You can configure the destination `resource` block to manage multiple instances of resource using the `count` and `for_each` [meta-arguments](/terraform/language/meta-arguments). You can add a parameter to the value of the `to` argument to specify which instance of the destination resource to import to. 
-
-For example, the `count` block in the destination `resource` block configuration instructs Terraform to import a set number of resource instances. As a result, you can include an index to the `to` argument value to specify which instance to import the resource to. 
-
-In the following example, Terraform imports the resource into the instance at the `0` index:
-
-```hcl
-import {
-  to = aws_instance.example[0]
-  id = "i-abcd1234"
-}
-
-resource "aws_instance" "example {
-  count = 2
-  #. . .
-}
-```
-
-When the destination `resource` block contains a `for_each` argument, Terraform loops through a set of key-value pairs and imports an instance for each pair. In the following example, Terraform imports the resource into the instance with a `env` key:
-
-```hcl
-import {
-  to = aws_instance.example["env"]
-  id = "i-abcd1234"
-}
-
-resource "aws_instance" "example" {
-  ami           = "ami-12345678"   
-  instance_type = "t2.micro"
-  for_each = { 
-    env = "staging"
-    geo = "us"
-  }
-  # . . .
-}
-```
-
-### Import using a custom resource provider
-
-By default, Terraform automatically selects the default provider configuration based on the resource type, but you can configure multiple instances of the same provider with aliases and use a non-default provider configuration to import specific resources. In the following example, Terraform imports to a destination `resource` block that contains multiple instances according to the `europe` provider configuration:
-
-```hcl
-provider "aws" {
-  alias = "europe"
-  region = "eu-west-1"
-}
-
-import {
-  provider = aws.europe
-  to = aws_instance.example["env"]
-  id = "i-abcd1234"
-}
-
-resource "aws_instance" "example" {
-  provider = aws.europe
-  for_each = {
-    env = "staging"
-    geo = "us"
-  }
-}
-```
-
-### Import to a module
-
-When the destination `resource` block is in another module, add the `module.<MODULE-NAME>` prefix to the resource address. In the following example, Terraform imports a resource into a `resource` block in the `instances` module:
-
-
-<CodeBlockConfig filename="main.tf">
-
-```hcl
-import {
-  to = module.instances.aws_instance.example
-  id = "i-abcd1234"
-}
-```
-
-</CodeBlockConfig>
-
-The following resource appears in the module address specified with the `to` argument in the `import` block:
-
-<CodeBlockConfig filename="instances/main.tf">
-
-```hcl
-resource "aws_instance" "example" {
-  # . . .
-}
-```
-
-</CodeBlockConfig>
-
-## Plan and apply an import
+You can import single resources or small batches of resources or create queries to discover large sets of unmanaged resources to import them in bulk.
 
-After configuring the destination `resource` block and the `import` block, run `terraform plan` and review the proposed plan. If Terraform proposes any unexpected changes to the resource, update its configuration until it matches your intended settings. When satisfied with the plan, run `terraform apply` to import the resources and update your state. 
+### Import resources in bulk
 
-When you apply a configuration with `import` blocks, Terraform records that it imported the resources and that it did not create them. 
+When you need to identify and import large sets of infrastructure resources, you can define queries as HCL, add the results to your Terraform configuration, and use the `terraform apply` command to import the discovered resources into your workspace. Refer to [Import resources in bulk](/terraform/language/import/bulk) for more information.  
 
-Because the `import` block is idempotent, applying an import action and running another plan does not generate another import action as long as that resource remains in your state. Furthermore, attempting to import a resource into the same address more than once has no impact. 
+### Import individual resources
 
-## Post import tasks
+The workflow for importing single resources or small batches of resources works best when you can easily access unique infrastructure resource IDs and other attributes from your cloud provider. In this workflow, manually write `import` and `resource` blocks and run the `terraform apply` command to import the resources. 
 
-You can either remove `import` blocks after you've imported them or leave them in your configuration as a record of the resource's origin for future module maintainers. For more information on maintaining configurations over time, refer to [Refactoring](/terraform/language/modules/develop/refactoring).
+Alternatively, you can write only the `import` block and run the `terraform apply` command with the `generate-config` flag to generate the `resource` blocks. Refer to [Import a single resource](/terraform/language/import/single) for more information.