github.com/terramate-io/tf@v0.0.0-20230830114523-fce866b4dfcd/website/docs/language/import/index.mdx (about)

     1  ---
     2  page_title: Import - Configuration Language
     3  description: >-
     4    Import and manage existing resources with Terraform using configuration-driven import.
     5  ---
     6  
     7  # Import
     8  
     9  -> **Note:** Import blocks are only available in Terraform v1.5.0 and later.
    10  
    11  ~> **Experimental:** While we do not expect to make backwards-incompatible changes to syntax, the `-generate-config-out` flag and how Terraform processes imports during the plan stage and generates configuration may change in future releases.
    12  
    13  Use the `import` block to import existing infrastructure resources into Terraform, bringing them under Terraform's management. Unlike the `terraform import` command, configuration-driven import using `import` blocks is predictable, works with CICD pipelines, and lets you preview an import operation before modifying state.
    14  
    15  Once imported, Terraform tracks the resource in your state file. You can then manage the imported resource like any other, updating its attributes and destroying it as part of a standard resource lifecycle.
    16  
    17  The `import` block records that Terraform imported the resource and did not create it. After importing, you can optionally remove import blocks from your configuration or leave them as a record of the resource's origin.
    18  
    19  ## Syntax
    20  
    21  You can add an `import` block to any Terraform configuration file. A common pattern is to create an `imports.tf` file, or to place each `import` block beside the `resource` block it imports into.
    22  
    23  ```hcl
    24  import {
    25    to = aws_instance.example
    26    id = "i-abcd1234"
    27  }
    28  
    29  resource "aws_instance" "example" {
    30    name = "hashi"
    31    # (other resource arguments...)
    32  }
    33  ```
    34  
    35  The above `import` block defines an import of the AWS instance with the ID "i-abcd1234" into the `aws_instance.example` resource in the root module.
    36  
    37  The `import` block has the following arguments:
    38   - `to` - The instance address this resource will have in your state file.
    39   - `id` - A string with the [import ID](#import-id) of the resource.
    40   - `provider` (optional) - An optional custom resource provider, see [The Resource provider Meta-Argument](/terraform/language/meta-arguments/resource-provider) for details.
    41  
    42  If you do not set the `provider` argument, Terraform attempts to import from the default provider. 
    43  
    44  ### Import ID
    45  
    46  The import block requires you to provide the `id` argument with a literal string of your resource's import ID. Terraform needs this import ID to locate the resource you want to import.
    47  
    48  The identifier you use for a resource's import ID is resource-specific. You can find the required ID in the [provider documentation](https://registry.terraform.io/browse/providers) for the resource you wish to import.
    49  
    50  ## Plan and apply an import
    51  
    52  Terraform processes the `import` block during the plan stage. Once a plan is approved, Terraform imports the resource into its state during the subsequent apply stage.
    53  
    54  To import a resource using `import` blocks, you must:
    55  1. Define an `import` block for the resource(s).
    56  1. Add a corresponding `resource` block to your configuration , or [generate configuration](/terraform/language/import/generating-configuration) for that resource.
    57  1. Run `terraform plan` to review how Terraform will import the resource(s).
    58  1. Apply the configuration to import the resources and update your Terraform state.
    59  
    60  > **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.
    61  
    62  The `import` block is [_idempotent_](https://en.wikipedia.org/wiki/Idempotence), meaning that applying an import action and running another plan will not generate another import action as long as that resource remains in your state.
    63  
    64  Terraform only needs to import a given resource once. Attempting to import a resource into the same address again is a harmless no-op. You can remove `import` blocks after completing the import or safely 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, see [Refactoring](/terraform/language/modules/develop/refactoring).
    65  
    66  ## Resource configuration
    67  
    68  Before importing, you must add configuration for every resource you want Terraform to import. Otherwise, Terraform throws an error during planning, insisting you add resource configuration before it can successfully import. You can create resource configuration manually or [generate it using Terraform](/terraform/language/import/generating-configuration). 
    69  
    70  We recommend writing a `resource` block if you know what most of the [resource's arguments](/terraform/language/resources/syntax#resource-arguments) will be. For example, your configuration may already contain a similar resource whose configuration you can copy and modify.
    71  
    72  We recommend [generating configuration](/terraform/language/import/generating-configuration) when importing multiple resources or a single complex resource that you do not already have the configuration for.
    73  
    74  ### Add a `resource` block
    75  
    76  Add a `resource` block for the resource to import. The resource address must match the import block's `to` argument. 
    77  
    78  ```hcl
    79  import {
    80    to = aws_instance.example
    81    id = "i-abcd1234"
    82  }
    83  
    84  resource "aws_instance" "example" {
    85    name = "renderer"
    86  }
    87  ```
    88  
    89  ### Generate configuration
    90  
    91  Terraform can generate HCL for resources that do not already exist in configuration. 
    92  For more details, see [Generating Configuration](/terraform/language/import/generating-configuration).
    93  
    94  ## Examples
    95  
    96  The following example demonstrates how to import into a module.
    97  
    98  ```hcl
    99  import {
   100    to = module.instances.aws_instance.example
   101    id = "i-abcd1234"
   102  }
   103  ```
   104  
   105  The below example shows how to import a resource that includes [`count`](/terraform/language/meta-arguments/count).
   106  
   107  ```hcl
   108  import {
   109    to = aws_instance.example[0]
   110    id = "i-abcd1234"
   111  }
   112  ```
   113  
   114  
   115  The below example shows how to import a resource that includes [`for_each`](/terraform/language/meta-arguments/for_each).
   116  ```hcl
   117  import {
   118    to = aws_instance.example["foo"]
   119    id = "i-abcd1234"
   120  }
   121  ```
   122  
   123  Finally, the below example demonstrates how to import from a custom resource provider.
   124  
   125  ```hcl
   126  provider "aws" {
   127    alias = "europe"
   128    region = "eu-west-1"
   129  }
   130  
   131  import {
   132    provider = aws.europe
   133    to = aws_instance.example["foo"]
   134    id = "i-abcd1234"
   135  }
   136  ```