• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform CLI

  • Overview
  • Basic CLI Features
    • Overview
    • init
    • get
    • Overview
    • plan
    • apply
    • destroy
    • Overview
    • login
    • logout
    • Overview
    • console
    • fmt
    • validate
    • 0.13upgrade
    • 0.12upgrade
    • Overview
    • graph
    • output
    • show
    • state list
    • state show
    • Overview
    • import
    • Usage Tips
    • Resource Importability
    • Overview
    • Resource Addressing
    • state
      • Overview
      • state list
      • state show
      • refresh
      • Overview
      • taint
      • untaint
      • Overview
      • state mv
      • state rm
      • state replace-provider
      • Overview
      • state pull
      • state push
      • force-unlock
    • Overview
      • Overview
      • workspace list
      • workspace select
      • workspace new
      • workspace delete
      • workspace show
    • Overview
    • Plugin Signing
    • providers
    • version
    • providers lock
    • providers mirror
    • providers schema
    • Overview
    • CLI Configuration
    • Environment Variables
    • Overview
    • Terraform Cloud Settings
    • Initializing and Migrating
    • Command Line Arguments
    • Running Terraform in Automation
    • GitHub Actions
    • Overview
    • apply
    • console
    • destroy
    • env
    • fmt
    • force-unlock
    • get
    • graph
    • import
    • init
    • login
    • logout
    • output
    • plan
    • providers
    • providers lock
    • providers mirror
    • providers schema
    • push (deprecated)
    • refresh
    • show
    • state
    • state list
    • state mv
    • state pull
    • state push
    • state replace-provider
    • state rm
    • state show
    • taint
    • test (deprecated)
    • untaint
    • validate
    • version
    • workspace
    • workspace list
    • workspace select
    • workspace new
    • workspace delete
    • workspace show
    • 0.12upgrade
    • 0.13upgrade
    • Overview
    • apply
    • console
    • destroy
    • env
    • fmt
    • force-unlock
    • get
    • graph
    • import
    • init
    • login
    • logout
    • output
    • plan
      • providers
      • providers lock
      • providers mirror
      • providers schema
    • push (deprecated)
    • refresh
    • show
      • state
      • state list
      • state mv
      • state pull
      • state push
      • state replace-provider
      • state rm
      • state show
    • taint
    • test (deprecated)
    • untaint
    • validate
    • version
      • workspace
      • workspace list
      • workspace select
      • workspace new
      • workspace delete
      • workspace show
    • 0.12upgrade
    • 0.13upgrade
    • APT Packages for Debian and Ubuntu
    • Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux

  • Terraform Internals

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Import Usage

Hands-on: Try the Import Terraform Configuration tutorial on HashiCorp Learn.

The terraform import command is used to import existing infrastructure.

The command currently can only import one resource at a time. This means you can't yet point Terraform import to an entire collection of resources such as an AWS VPC and import all of it. This workflow will be improved in a future version of Terraform.

Warning: Terraform expects that each remote object it is managing will be bound to only one resource address, which is normally guaranteed by Terraform itself having created all objects. If you import existing objects into Terraform, be careful to import each remote object to only one Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. For more information on this assumption, see the State section.

To import a resource, first write a resource block for it in your configuration, establishing the name by which it will be known to Terraform:

resource "aws_instance" "example" {
  # ...instance configuration...
}
resource "aws_instance" "example" {
  # ...instance configuration...
}

The name "example" here is local to the module where it is declared and is chosen by the configuration author. This is distinct from any ID issued by the remote system, which may change over time while the resource name remains constant.

If desired, you can leave the body of the resource block blank for now and return to fill it in once the instance is imported.

Now terraform import can be run to attach an existing instance to this resource configuration:

$ terraform import aws_instance.example i-abcd1234
$ terraform import aws_instance.example i-abcd1234

This command locates the AWS EC2 instance with ID i-abcd1234. Then it attaches the existing settings of the instance, as described by the EC2 API, to the name aws_instance.example of a module. In this example the module path implies that the root module is used. Finally, the mapping is saved in the Terraform state.

It is also possible to import to resources in child modules, using their paths, and to single instances of a resource with count or for_each set. See Resource Addressing for more details on how to specify a target resource.

The syntax of the given ID is dependent on the resource type being imported. For example, AWS instances use an opaque ID issued by the EC2 API, but AWS Route53 Zones use the domain name itself. Consult the documentation for each importable resource for details on what form of ID is required.

As a result of the above command, the resource is recorded in the state file. You can now run terraform plan to see how the configuration compares to the imported resource, and make any adjustments to the configuration to align with the current (or desired) state of the imported object.

»Complex Imports

The above import is considered a "simple import": one resource is imported into the state file. An import may also result in a "complex import" where multiple resources are imported. For example, an AWS network ACL imports an aws_network_acl but also one aws_network_acl_rule for each rule.

In this scenario, the secondary resources will not already exist in configuration, so it is necessary to consult the import output and create a resource block in configuration for each secondary resource. If this is not done, Terraform will plan to destroy the imported objects on the next run.

If you want to rename or otherwise move the imported resources, the state management commands can be used.

github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager