github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/cli/import/usage.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Import: Usage"
     4  sidebar_current: "docs-import-usage"
     5  description: |-
     6    The `terraform import` command is used to import existing infrastructure.
     7  ---
     8  
     9  # Import Usage
    10  
    11  > **Hands-on:** Try the [Import Terraform Configuration](https://learn.hashicorp.com/tutorials/terraform/state-import?in=terraform/state&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
    12  
    13  The `terraform import` command is used to import existing infrastructure.
    14  
    15  The command currently can only import one resource at a time. This means
    16  you can't yet point Terraform import to an entire collection of resources
    17  such as an AWS VPC and import all of it. This workflow will be improved in a
    18  future version of Terraform.
    19  
    20  ~> Warning: Terraform expects that each remote object it is managing will be
    21  bound to only one resource address, which is normally guaranteed by Terraform
    22  itself having created all objects. If you import existing objects into Terraform,
    23  be careful to import each remote object to only one Terraform resource address.
    24  If you import the same object multiple times, Terraform may exhibit unwanted
    25  behavior. For more information on this assumption, see
    26  [the State section](/docs/language/state/index.html).
    27  
    28  To import a resource, first write a resource block for it in your
    29  configuration, establishing the name by which it will be known to Terraform:
    30  
    31  ```
    32  resource "aws_instance" "example" {
    33    # ...instance configuration...
    34  }
    35  ```
    36  
    37  The name "example" here is local to the module where it is declared and is
    38  chosen by the configuration author. This is distinct from any ID issued by
    39  the remote system, which may change over time while the resource name
    40  remains constant.
    41  
    42  If desired, you can leave the body of the resource block blank for now and
    43  return to fill it in once the instance is imported.
    44  
    45  Now `terraform import` can be run to attach an existing instance to this
    46  resource configuration:
    47  
    48  ```shell
    49  $ terraform import aws_instance.example i-abcd1234
    50  ```
    51  
    52  This command locates the AWS instance with ID `i-abcd1234`. Then it attaches
    53  the existing settings of the instance, as described by the EC2 API, to the
    54  name `aws_instance.example` of a module. In this example the module path
    55  implies that the root module is used. Finally, the mapping is saved in the
    56  Terraform state.
    57  
    58  It is also possible to import to resources in child modules, using their paths,
    59  and to single instances of a resource with `count` or `for_each` set. See
    60  [_Resource Addressing_](/docs/cli/state/resource-addressing.html) for more
    61  details on how to specify a target resource.
    62  
    63  The syntax of the given ID is dependent on the resource type being imported.
    64  For example, AWS instances use an opaque ID issued by the EC2 API, but
    65  AWS Route53 Zones use the domain name itself. Consult the documentation for
    66  each importable resource for details on what form of ID is required.
    67  
    68  As a result of the above command, the resource is recorded in the state file.
    69  You can now run `terraform plan` to see how the configuration compares to
    70  the imported resource, and make any adjustments to the configuration to
    71  align with the current (or desired) state of the imported object.
    72  
    73  ## Complex Imports
    74  
    75  The above import is considered a "simple import": one resource is imported
    76  into the state file. An import may also result in a "complex import" where
    77  multiple resources are imported. For example, an AWS network ACL imports
    78  an `aws_network_acl` but also one `aws_network_acl_rule` for each rule.
    79  
    80  In this scenario, the secondary resources will not already exist in
    81  configuration, so it is necessary to consult the import output and create
    82  a `resource` block in configuration for each secondary resource. If this is
    83  not done, Terraform will plan to destroy the imported objects on the next run.
    84  
    85  If you want to rename or otherwise move the imported resources, the
    86  [state management commands](/docs/cli/commands/state/index.html) can be used.