terraform/website/docs/commands/import.html.md

170 lines
6.5 KiB
Markdown
Raw Normal View History

2016-05-18 20:56:51 +02:00
---
layout: "docs"
page_title: "Command: import"
sidebar_current: "docs-commands-import"
description: |-
The `terraform import` command is used to import existing resources into Terraform.
---
# Command: 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.
2016-05-18 20:56:51 +02:00
The `terraform import` command is used to
[import existing resources](/docs/import/index.html)
into Terraform.
## Usage
Usage: `terraform import [options] ADDRESS ID`
Import will find the existing resource from ID and import it into your Terraform
state at the given ADDRESS.
ADDRESS must be a valid [resource address](/docs/internals/resource-addressing.html).
Because any resource address is valid, the import command can import resources
into modules as well as directly into the root of your state.
2016-05-18 20:56:51 +02:00
ID is dependent on the resource type being imported. For example, for AWS
instances it is the instance ID (`i-abcd1234`) but for AWS Route53 zones
it is the zone ID (`Z12ABC4UGMOZ2N`). Please reference the provider documentation for details
2016-05-18 20:56:51 +02:00
on the ID format. If you're unsure, feel free to just try an ID. If the ID
is invalid, you'll just receive an error message.
~> 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](/docs/state/).
2016-05-18 20:56:51 +02:00
The command-line flags are all optional. The list of available flags are:
* `-backup=path` - Path to backup the existing state file. Defaults to
the `-state-out` path with the ".backup" extension. Set to "-" to disable
backups.
* `-config=path` - Path to directory of Terraform configuration files that
configure the provider for import. This defaults to your working directory.
If this directory contains no Terraform configuration files, the provider
must be configured via manual input or environmental variables.
2016-05-18 20:56:51 +02:00
* `-input=true` - Whether to ask for input for provider configuration.
2017-04-04 19:48:59 +02:00
* `-lock=true` - Lock the state file when locking is supported.
2016-05-18 20:56:51 +02:00
2017-04-04 19:48:59 +02:00
* `-lock-timeout=0s` - Duration to retry a state lock.
* `-no-color` - If specified, output won't contain any color.
2016-05-18 20:56:51 +02:00
* `-parallelism=n` - Limit the number of concurrent operation as Terraform
[walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults
to 10.
* `-provider=provider` - **Deprecated** Override the provider configuration to
use when importing the object. By default, Terraform uses the provider specified
in the configuration for the target resource, and that is the best behavior in most cases.
* `-state=path` - Path to the source state file to read from. Defaults to the
configured backend, or "terraform.tfstate".
2017-04-04 19:48:59 +02:00
* `-state-out=path` - Path to the destination state file to write to. If this
isn't specified the source state file will be used. This can be a new or
existing path.
2017-04-04 19:48:59 +02:00
* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
can be set multiple times. Variable values are interpreted as
[literal expressions](/docs/configuration/expressions/types.html) in the
Terraform language, so list and map values can be specified via this flag.
This is only useful with the `-config` flag.
* `-var-file=foo` - Set variables in the Terraform configuration from
a [variable file](/docs/configuration/variables.html#variable-definitions-tfvars-files). If
2017-06-22 03:22:07 +02:00
a `terraform.tfvars` or any `.auto.tfvars` files are present in the current
directory, they will be automatically loaded. `terraform.tfvars` is loaded
first and the `.auto.tfvars` files after in alphabetical order. Any files
specified by `-var-file` override any values set automatically from files in
the working directory. This flag can be used multiple times. This is only
useful with the `-config` flag.
backend: Validate remote backend Terraform version When using the enhanced remote backend, a subset of all Terraform operations are supported. Of these, only plan and apply can be executed on the remote infrastructure (e.g. Terraform Cloud). Other operations run locally and use the remote backend for state storage. This causes problems when the local version of Terraform does not match the configured version from the remote workspace. If the two versions are incompatible, an `import` or `state mv` operation can cause the remote workspace to be unusable until a manual fix is applied. To prevent this from happening accidentally, this commit introduces a check that the local Terraform version and the configured remote workspace Terraform version are compatible. This check is skipped for commands which do not write state, and can also be disabled by the use of a new command-line flag, `-ignore-remote-version`. Terraform version compatibility is defined as: - For all releases before 0.14.0, local must exactly equal remote, as two different versions cannot share state; - 0.14.0 to 1.0.x are compatible, as we will not change the state version number until at least Terraform 1.1.0; - Versions after 1.1.0 must have the same major and minor versions, as we will not change the state version number in a patch release. If the two versions are incompatible, a diagnostic is displayed, advising that the error can be suppressed with `-ignore-remote-version`. When this flag is used, the diagnostic is still displayed, but as a warning instead of an error. Commands which will not write state can assert this fact by calling the helper `meta.ignoreRemoteBackendVersionConflict`, which will disable the checks. Those which can write state should instead call the helper `meta.remoteBackendVersionCheck`, which will return diagnostics for display. In addition to these explicit paths for managing the version check, we have an implicit check in the remote backend's state manager initialization method. Both of the above helpers will disable this check. This fallback is in place to ensure that future code paths which access state cannot accidentally skip the remote version check.
2020-11-13 22:43:56 +01:00
* `-ignore-remote-version` - When using the enhanced remote backend with
Terraform Cloud, continue even if remote and local Terraform versions differ.
This may result in an unusable Terraform Cloud workspace, and should be used
with extreme caution.
2016-05-18 20:56:51 +02:00
## Provider Configuration
Terraform will attempt to load configuration files that configure the
provider being used for import. If no configuration files are present or
no configuration for that specific provider is present, Terraform will
prompt you for access credentials. You may also specify environmental variables
to configure the provider.
The only limitation Terraform has when reading the configuration files
is that the import provider configurations must not depend on non-variable
inputs. For example, a provider configuration cannot depend on a data
source.
As a working example, if you're importing AWS resources and you have a
configuration file with the contents below, then Terraform will configure
the AWS provider with this file.
```hcl
variable "access_key" {}
variable "secret_key" {}
provider "aws" {
access_key = "${var.access_key}"
secret_key = "${var.secret_key}"
}
```
2016-05-18 20:56:51 +02:00
## Example: Import into Resource
2016-05-18 20:56:51 +02:00
This example will import an AWS instance into the `aws_instance` resource named `foo`:
2016-05-18 20:56:51 +02:00
```shell
2016-05-18 20:56:51 +02:00
$ terraform import aws_instance.foo i-abcd1234
```
## Example: Import into Module
2016-05-18 20:56:51 +02:00
The example below will import an AWS instance into the `aws_instance` resource named `bar` into a module named `foo`:
2016-05-18 20:56:51 +02:00
```shell
2016-05-18 20:56:51 +02:00
$ terraform import module.foo.aws_instance.bar i-abcd1234
```
## Example: Import into Resource configured with count
The example below will import an AWS instance into the first instance of the `aws_instance` resource named `baz` configured with
[`count`](/docs/configuration/meta-arguments/count.html):
```shell
$ terraform import 'aws_instance.baz[0]' i-abcd1234
```
## Example: Import into Resource configured with for_each
The example below will import an AWS instance into the `"example"` instance of the `aws_instance` resource named `baz` configured with
[`for_each`](/docs/configuration/meta-arguments/for_each.html):
Linux, Mac OS, and UNIX:
```shell
$ terraform import 'aws_instance.baz["example"]' i-abcd1234
```
PowerShell:
```shell
$ terraform import 'aws_instance.baz[\"example\"]' i-abcd1234
```
Windows `cmd.exe`:
```shell
$ terraform import aws_instance.baz[\"example\"] i-abcd1234
```