ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

website: attempt to clarify "terraform import" usage docs 

Based on feedback from #15569 that the previous example was too abstract
and did not give enough context about what each of the different arguments
mean and how they generalize to other resource types.
This commit is contained in:
Martin Atkins 2017-07-18 15:00:33 -07:00
parent 9a7ffbfb1b
commit da0aec1b32
1 changed files with 23 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
website/docs/import/usage.html.md
View File

@ -12,18 +12,23 @@ The `terraform import` command is used to import existing infrastructure.
The command currently can only import one resource at a time. This means 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 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 such as an AWS VPC and import all of it. This workflow will be improved in a
be able to do this. future version of Terraform.
To import a resource, first write a resource block for it in your To import a resource, first write a resource block for it in your
configuration, establishing the name by which it will be known in Terraform: configuration, establishing the name by which it will be known to Terraform:
``` ```
resource "aws_instance" "bar" { resource "aws_instance" "example" {
# ...instance configuration... # ...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 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. return to fill it in once the instance is imported.
@ -31,18 +36,22 @@ Now `terraform import` can be run to attach an existing instance to this
resource configuration: resource configuration:
```shell ```shell
$ terraform import aws_instance.bar i-abcd1234 $ terraform import aws_instance.example i-abcd1234
``` ```
The above command imports an AWS instance with the given ID and attaches This command locates the AWS instance with ID `i-abcd1234` and attaches
it to the name `aws_instance.bar`. You can also import resources into modules. its existing settings, as described by the EC2 API, to the name
See the [resource addressing](/docs/internals/resource-addressing.html) `aws_instance.example` in the Terraform state.
page for more details on the full range of addresses supported.
The ID given is dependent on the resource type being imported. For example, It is also possible to import to resources in child modules and to single
AWS instances use their direct IDs. However, AWS Route53 zones use the instances of a resource with `count` set. See
domain name itself. Console the resource documentation for details on what [_Resource Addressing_](/docs/internals/resource-addressing.html) for more
form of ID each resource expects. 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. 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 You can now run `terraform plan` to see how the configuration compares to
@ -61,5 +70,5 @@ configuration, so it is necessary to consult the import output and create
a `resource` block in configuration for each secondary resource. If this is 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. not done, Terraform will plan to destroy the imported objects on the next run.
If you want to rename or otherwise modify the imported resources, the If you want to rename or otherwise move the imported resources, the
[state management commands](/docs/commands/state/index.html) can be used. [state management commands](/docs/commands/state/index.html) can be used.