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

     1  ---
     2  page_title: Import - Generating Configuration
     3  description: >-
     4    Generate configuration and manage existing resources with Terraform using configuration-driven import.
     5  ---
     6  
     7  # Generating configuration
     8  
     9  ~> **Experimental:** Configuration generation is available in Terraform v1.5 as an experimental feature. Later minor versions may contain changes to the formatting of generated configuration and behavior of the `terraform plan` command using the `-generate-config-out` flag.
    10  
    11  Terraform can generate code for the resources you define in [`import` blocks](/terraform/language/import) that do not already exist in your configuration. Terraform produces HCL to act as a template that contains Terraform's best guess at the appropriate value for each resource argument.
    12  
    13  Starting with Terraform's generated HCL, we recommend iterating to find your ideal configuration by removing some attributes, adjusting the value of others, and rearranging `resource` blocks into files and modules as appropriate.
    14  
    15  To generate configuration, run `terraform plan` with the `-generate-config-out` flag and supply a new file path. Do not supply a path to an existing file, or Terraform throws an error.
    16  
    17  ```shell
    18  $ terraform plan -generate-config-out=generated_resources.tf
    19  ```
    20  
    21  If any resources targeted by an `import` block do not exist in your configuration, Terraform then generates and writes configuration for those resources in `generated_resources.tf`.
    22  
    23  ## Workflow
    24  
    25  The workflow for generating configuration is similar to the [`import` block workflow](/terraform/language/import#plan-and-apply-an-import), with the extra step of generating configuration during the planning stage. You can then review and modify the generated configuration before applying. 
    26  
    27  ### 1. Add the `import` block
    28  
    29  Add an `import` block to your configuration. This `import` block can be in a separate file (e.g., `import.tf`) or an existing configuration file.
    30  
    31  ```hcl
    32  import {
    33    to = aws_iot_thing.bar
    34    id = "foo"
    35  }
    36  ```
    37  
    38  The import block's `to` argument points to the address a `resource` will have in your state file. If a resource address in your state matches an `import` block's `to` argument, Terraform attempts to import into that resource. In future planning, Terraform knows it doesn't need to generate configuration for resources that already exist in your state.
    39  
    40  The import block's `id` argument uses that resource's [import ID](/terraform/language/import#import-id).
    41  
    42  If your configuration does not contain other resources for your selected provider, you must add a `provider` block to inform Terraform which provider it should use to generate configuration. Otherwise, Terraform displays an error if it can not determine which provider to use.
    43  If you add a new `provider` block to your configuration, you must run `terraform init` again.
    44  
    45  ### 2. Plan and generate configuration
    46  
    47  To instruct Terraform to generate configuration for the `import` blocks you defined, run `terraform plan` with the `-generate-config-out=` flag and a new file path. Terraform displays its plan for importing your resource and the file where Terraform generated configuration based on this plan. 
    48  
    49  ```shell
    50  $ terraform plan -generate-config-out=generated.tf
    51  
    52  aws_iot_thing.bar: Preparing import... [id=foo]
    53  aws_iot_thing.bar: Refreshing state... [id=foo]
    54  
    55  Terraform will perform the following actions:
    56  
    57    # aws_iot_thing.bar will be imported
    58    # (config will be generated)
    59      resource "aws_iot_thing" "bar" {
    60          arn               = "arn:aws:iot:eu-west-1:1234567890:thing/foo"
    61          attributes        = {}
    62          default_client_id = "foo"
    63          id                = "foo"
    64          name              = "foo"
    65          version           = 1
    66      }
    67  
    68  Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.
    69  
    70  ╷
    71  │ Warning: Config generation is experimental
    72  │ 
    73  │ Generating configuration during import is currently experimental, and the generated configuration format may change in future versions.
    74  ╵
    75  
    76  ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
    77  
    78  Terraform has generated configuration and written it to generated.tf. Please review the configuration and edit it as necessary before adding it to version control.
    79  ```
    80  
    81  ### 3. Review generated configuration
    82  
    83  The example above instructs Terraform to generate configuration in a file named `generated.tf`. The below code is an example of a `generated.tf` file.
    84  
    85  ```hcl
    86  resource aws_iot_thing "bar" {
    87    name = "foo"
    88  }
    89  ```
    90  
    91  Review the generated configuration and update it as needed. You may wish to move the generated configuration to another file, add or remove resource arguments, or update it to reference input variables or other resources in your configuration. 
    92  
    93  ### 4. Apply
    94  
    95  Run `terraform apply` to import your infrastructure.
    96  
    97  ```shell
    98  $ terraform apply
    99  
   100  aws_iot_thing.bar: Preparing import... [id=foo]
   101  aws_iot_thing.bar: Refreshing state... [id=foo]
   102  
   103  Terraform will perform the following actions:
   104  
   105    # aws_iot_thing.bar will be imported
   106      resource "aws_iot_thing" "bar" {
   107          arn               = "arn:aws:iot:eu-west-1:1234567890:thing/foo"
   108          attributes        = {}
   109          default_client_id = "foo"
   110          id                = "foo"
   111          name              = "foo"
   112          version           = 1
   113      }
   114  
   115  Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.
   116  aws_iot_thing.bar: Importing... [id=foo]
   117  aws_iot_thing.bar: Import complete [id=foo]
   118  
   119  Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.
   120  
   121  ```
   122  
   123  Commit your new resource configuration to your version control system.
   124  
   125  ## Limitations
   126  
   127  ### Conflicting resource arguments
   128  
   129  Terraform generates configuration for importable resources during a plan by requesting values for resource attributes from the provider. For certain resources with complex schemas, Terraform may not be able to construct a valid configuration from these values.
   130  
   131  Terraform will display an error like the one below if it does not receive values for resource attributes while generating configuration.
   132  
   133  ```shell
   134  $ terraform plan -generate-config-out=generated.tf
   135  ╷
   136  │ Error: Conflicting configuration arguments
   137  │ 
   138  │   with aws_instance.ubuntu,
   139  │   on g.tf line 20, in resource "aws_instance" "ubuntu":
   140  │   20:   ipv6_address_count                   = 0
   141  │ 
   142  │ "ipv6_address_count": conflicts with ipv6_addresses
   143  ╵
   144  ```
   145  
   146  In the example above, Terraform still generates configuration and writes it to `generated.tf`. This error stems from a conflict between the `ipv6_address_count` and `ipv6_addresses` arguments. The resource supports both of these arguments, but you must choose only one when configuring the resource. You could fix the error by removing one of these two arguments, then running `terraform plan` again to check that there are no further issues.