website: basic docs on import

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

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.

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.

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.

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

website/source/layouts/docs.erb

@@ -129,9 +129,26 @@
 				</ul>
 				</li>
 
+				<li<%= sidebar_current(/^docs-import/) %>>
+					<a href="/docs/import/index.html">Import</a>
+					<ul class="nav">
+						<li<%= sidebar_current("docs-import-usage") %>>
+							<a href="/docs/import/usage.html">Usage</a>
+						</li>
+
+						<li<%= sidebar_current("docs-import-importability") %>>
+							<a href="/docs/import/importability.html">Resource Importability</a>
+						</li>
+					</ul>
+				</li>
+
 				<li<%= sidebar_current(/^docs-state/) %>>
 					<a href="/docs/state/index.html">State</a>
 					<ul class="nav">
+						<li<%= sidebar_current("docs-state-import") %>>
+							<a href="/docs/state/import.html">Import Existing Resources</a>
+						</li>
+
 						<li<%= sidebar_current("docs-state-remote") %>>
 							<a href="/docs/state/remote/index.html">Remote State</a>
 						</li>