diff --git a/website/source/docs/import/importability.html.md b/website/source/docs/import/importability.html.md new file mode 100644 index 000000000..324e4a7e8 --- /dev/null +++ b/website/source/docs/import/importability.html.md @@ -0,0 +1,22 @@ +--- +layout: "docs" +page_title: "Import: Resource Importability" +sidebar_current: "docs-import-importability" +description: |- + Each resource in Terraform must implement some basic logic to become + importable. As a result, not all Terraform resources are currently importable. +--- + +# Resource Importability + +Each resource in Terraform must implement some basic logic to become +importable. As a result, not all Terraform resources are currently importable. +If you find a resource that you want to import and Terraform reports +that it isn't importable, please report an issue. + +Converting a resource to be importable is also relatively simple, so if +you're interested in contributing that functionality, the Terraform team +would be grateful. + +To make a resource importable, please see the +[plugin documentation on writing a resource](/docs/plugins/provider.html). diff --git a/website/source/docs/import/index.html.md b/website/source/docs/import/index.html.md new file mode 100644 index 000000000..88a696498 --- /dev/null +++ b/website/source/docs/import/index.html.md @@ -0,0 +1,35 @@ +--- +layout: "docs" +page_title: "Import" +sidebar_current: "docs-import" +description: |- + 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. +--- + +# Import + +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. + +## Currently State Only + +The current implementation of Terraform import can only import resources +into the [state](/docs/state). It does not generate configuration. A future +version of Terraform will also generate configuration. + +Because of this, the behavior of importing resources into Terraform right now +is that after an import, if you run a `terraform plan`, Terraform views it +as an orphan (a resource with no configuration) and marks it for destruction. +After importing a resource you have to manually write configuration to match +the resource. + +While this may seem tedious, it still gives Terraform users an avenue for +importing existing resources. A future version of Terraform will fully generate +configuration significantly simplifying this process. diff --git a/website/source/docs/import/usage.html.md b/website/source/docs/import/usage.html.md new file mode 100644 index 000000000..8e22da3b1 --- /dev/null +++ b/website/source/docs/import/usage.html.md @@ -0,0 +1,51 @@ +--- +layout: "docs" +page_title: "Import: Usage" +sidebar_current: "docs-import-usage" +description: |- + The `terraform import` command is used to import existing infrastructure. +--- + +# Import Usage + +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. A future version of Terraform will +be able to do this. + +Using `terraform import` is simple. An example is shown below: + +``` +$ terraform import aws_instance.bar i-abcd1234 +... +``` + +The above command imports an AWS instance with the given ID to the +address `aws_instance.bar`. You can also import resources into modules. +See the [resource addressing](/docs/internals/resource-addressing.html) +page for more details on the full range of addresses supported. + +The ID given is dependent on the resource type being imported. For example, +AWS instances use their direct IDs. However, AWS Route53 zones use the +domain name itself. Reference the resource documentation for details on +what the ID it expects is. + +As a result of the above command, the resource is put into the state file. +If you run `terraform plan`, you should see Terraform plan your resource +for destruction. You now have to create a matching configuration so that +Terraform doesn't plan a destroy. + +## 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 security group imports +an `aws_security_group` but also one `aws_security_group_rule` for each rule. + +In this case, the name of the resource is shown as part of the import output. +You'll have to create a configuration for each resource imported. If you want +to rename the other imported resources, the +[state management commands](/docs/commands/state/index.html) should be used +to rename resources. diff --git a/website/source/docs/plugins/provider.html.md b/website/source/docs/plugins/provider.html.md index 558770f2d..163173f92 100644 --- a/website/source/docs/plugins/provider.html.md +++ b/website/source/docs/plugins/provider.html.md @@ -138,6 +138,10 @@ structure. This structure has the following fields: optional field is `Update`. If your resource doesn't support update, then you may keep that field nil. + * `Importer` - If this is non-nil, then this resource is + [importable](/docs/import/importability.html). It is recommended to + implement this. + The CRUD operations in more detail, along with their contracts: * `Create` - This is called to create a new instance of the resource. diff --git a/website/source/intro/getting-started/next-steps.html.markdown b/website/source/intro/getting-started/next-steps.html.markdown index bc0653944..1271c0fa5 100644 --- a/website/source/intro/getting-started/next-steps.html.markdown +++ b/website/source/intro/getting-started/next-steps.html.markdown @@ -25,3 +25,6 @@ As a next step, the following resources are available: featured configuration files, showing some of the possibilities with Terraform. +* [Import](/docs/import/index.html) - The import section of the documentation + covers importing existing infrastructure into Terraform. + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 7bca0707d..58eafba89 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -129,9 +129,26 @@ + > + Import + + + > State