terraform/website/docs/cli/import/index.mdx

---
page_title: Import
description: >-
  Terraform can import and manage existing infrastructure. This can help you
  transition your infrastructure to Terraform.
---

# Import

> **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.

Terraform is able to import existing infrastructure. This allows you take
resources you've created by some other means and bring it under Terraform
management.

This is a great way to slowly transition infrastructure to Terraform, or
to be able to be confident that you can use Terraform in the future if it
potentially doesn't support every feature you need today.

~> 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](/language/state).

## Currently State Only

The current implementation of Terraform import can only import resources
into the [state](/language/state). It does not generate configuration. A future
version of Terraform will also generate configuration.

Because of this, prior to running `terraform import` it is necessary to write
manually a `resource` configuration block for the resource, to which the
imported object will be mapped.

While this may seem tedious, it still gives Terraform users an avenue for
importing existing resources.

## Terraform Cloud

When you use Terraform on the command line with Terraform Cloud, many commands (e.g., `apply`) run inside your Terraform Cloud environment. However, the `import` command runs locally, so it will not have access to information from Terraform Cloud. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in Terraform Cloud.
website: basic docs on import 2016-05-18 20:47:41 +02:00			`---`
migrate docs to mdx 2021-12-15 03:41:17 +01:00			`page_title: Import`
			`description: >-`
			`Terraform can import and manage existing infrastructure. This can help you`
			`transition your infrastructure to Terraform.`
website: basic docs on import 2016-05-18 20:47:41 +02:00			`---`

			`# Import`

website: Update all Learn crosslinks (#26442) * website: Update all Learn crosslinks The URL structure on Learn recently changed, so it's time to update some URLs. Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> 2020-10-02 20:02:59 +02:00			`> 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.`
website: Add links to relevant Learn guides in several docs pages (#25718) Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> 2020-07-31 22:16:35 +02:00
website: basic docs on import 2016-05-18 20:47:41 +02:00			`Terraform is able to import existing infrastructure. This allows you take`
			`resources you've created by some other means and bring it under Terraform`
			`management.`

			`This is a great way to slowly transition infrastructure to Terraform, or`
			`to be able to be confident that you can use Terraform in the future if it`
			`potentially doesn't support every feature you need today.`

website: Documentation about the one-to-one object binding assumption Terraform's design assumes that each remote object in Terraform's care is bound to one resource instance and one alone. If the same object is bound to multiple instances then confusing behavior will often result, such as two resource configurations competing to update a single object, or objects being "left behind" when all existing Terraform deployments are destroyed. This assumption was previously only implied, though. This change is an attempt to be more explicit about it, although these are additions to some older documentation sections that have not been revised for some time and so this is just a best effort to make this information discoverable without getting drawn into a full-on reorganization of these sections. While revising this there were some particular oddities that I decided to revise while I was there, but I'll leave a fuller revision of this older content for a later commit when we have more time to review it in greater detail. 2020-08-01 00:22:50 +02:00			`~> 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`
migrate docs to mdx 2021-12-15 03:41:17 +01:00			`[the State section](/language/state).`
website: Documentation about the one-to-one object binding assumption Terraform's design assumes that each remote object in Terraform's care is bound to one resource instance and one alone. If the same object is bound to multiple instances then confusing behavior will often result, such as two resource configurations competing to update a single object, or objects being "left behind" when all existing Terraform deployments are destroyed. This assumption was previously only implied, though. This change is an attempt to be more explicit about it, although these are additions to some older documentation sections that have not been revised for some time and so this is just a best effort to make this information discoverable without getting drawn into a full-on reorganization of these sections. While revising this there were some particular oddities that I decided to revise while I was there, but I'll leave a fuller revision of this older content for a later commit when we have more time to review it in greater detail. 2020-08-01 00:22:50 +02:00
website: basic docs on import 2016-05-18 20:47:41 +02:00			`## Currently State Only`

			`The current implementation of Terraform import can only import resources`
migrate docs to mdx 2021-12-15 03:41:17 +01:00			`into the [state](/language/state). It does not generate configuration. A future`
website: basic docs on import 2016-05-18 20:47:41 +02:00			`version of Terraform will also generate configuration.`

command: require resource to be in config before import Previously we encouraged users to import a resource and _then_ write the configuration block for it. This ordering creates lots of risk, since for various reasons users can end up subsequently running Terraform without any configuration in place, which then causes Terraform to want to destroy the resource that was imported. Now we invert this and require a minimal configuration block be written first. This helps ensure that the user ends up with a correlated resource config and state, protecting against any inconsistency caused by typos. This addresses #11835. 2017-05-17 03:26:20 +02:00			Because of this, prior to running `terraform import` it is necessary to write
			manually a `resource` configuration block for the resource, to which the
website: "map" a real resource to configuration, not "attach" (#17912) In the terraform state documentation the verb "map" is widely used to describe the relationship between an item in the state and in the real world whereas the verb "attach" is not used anywhere. 2019-03-23 00:10:44 +01:00			`imported object will be mapped.`
website: basic docs on import 2016-05-18 20:47:41 +02:00
			`While this may seem tedious, it still gives Terraform users an avenue for`
Removing the "future version will... We fully intend to do this, but this vague statement is no longer helpful. Will update when we have something more concrete. 2020-05-21 02:44:43 +02:00			`importing existing resources.`
Add link to new Terraform Import guide on learn platform 2020-06-29 17:38:46 +02:00
More mentions of remote backend 2021-12-21 23:51:06 +01:00			`## Terraform Cloud`
website: Terraform import and remote backends (#26241) * Put link to tutorial in its own section, call it a tutorial instead of guide, and use new canonical URL. * Mention limitations of using import with a remote backed * Typo fix Co-authored-by: Nick Fagerlund <nick.fagerlund@gmail.com> 2020-09-29 01:03:15 +02:00
Update website/docs/cli/import/index.mdx Co-authored-by: Nick Fagerlund <nick.fagerlund@gmail.com> 2022-01-26 17:41:57 +01:00			When you use Terraform on the command line with Terraform Cloud, many commands (e.g., `apply`) run inside your Terraform Cloud environment. However, the `import` command runs locally, so it will not have access to information from Terraform Cloud. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in Terraform Cloud.