HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

You are viewing documentation for version v1.12.x. View latest version.

import block reference

The import block instructs Terraform to import existing infrastructure resources into Terraform. Refer to Import existing resources for more information.

Configuration model

An import block supports the following configuration:

  • import   block
    • to   address | required
    • id   string | mutually exclusive with identity
    • identity   map | mutually exclusive with id
    • for_each   map or set of strings
    • provider   reference

Complete configuration

The following module block includes all built-in arguments:

import {
  to = resource.type.address
  id = "cloud-provider-id"      # `id` is mutually exclusive with `identity` 
  identity = {                  # `identity` is mutually exclusive with `id`
    <ATTRIBUTE> = <VALUE>
  }   
  for_each = {                  # `for_each` accepts a map or a set of strings 
    <KEY> = <VALUE>
  }
  for_each = [                  # `for_each` accepts a map or a set of strings 
    "<VALUE>", 
    "<VALUE>"
  ]
  provider = provider-name.alias
}

Specification

An import block supports the following configuration.

import

The import block imports existing infrastructure resources into Terraform. You can add an import block to any Terraform configuration file, but we recommend either creating an imports.tf file for all import configurations or placing each import block beside the destination resource block. Refer to Import existing resources for more information.

import {
  to = TYPE.LABEL
  id = "<RESOURCE-ID>"
}

resource "<TYPE>" "<LABEL>" {
  # 
}

Summary

to

The to argument specifies the instance address to import the resource into.

import {
  to = <address>
}

The to argument must match the address of an existing resource block. Refer to Import resources for more information.

Summary

id

The id argument specifies the cloud provider's ID for the resource you want to import.

import {
  id = "<ID>"
}

You must specify a string or an expression that evaluates to a string. The ID must be known during the plan operation.

The value of the id argument depends on the type of resource you are importing. You can only import resources that are supported by the provider. For information on how to import a resource, refer to the provider documentation.

You cannot use the id argument and identity argument in the same import block.

Summary

identity

The identity argument specifies a set of attributes that uniquely identifies a resource. 

import {
  identity = {
    <KEY> = <VALUE>
  }
}

The keys of the identity argument are specific to the resource type and provider. You can only import resources that are supported by the provider. Refer to your provider documentation for details.

You cannot use the identity argument and id argument in the same import block.

Summary

for_each

The for_each meta-argument instructs Terraform to import similar resources without requiring separate configuration blocks.

import {
  for_each = [ "<VALUE>" ] 
  # . . .
}

The for_each meta-argument accepts a map or a set of strings and imports an instance for each item in that map or set and produces an each object. You can use the values stored in each.key and each.value for the id argument expression. You can also use them in index expressions in the to argument. This allows Terraform to import multiple instances of a resource configuration.

The inputs for the for_each argument must be known for the import plan operation to succeed. You cannot use a for_each argument when running terraform plan with the -generate-config-out option. Refer to Generate configuration for more information.

The for_each argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to Meta-arguments for more information.

Summary

provider

The provider meta-argument instructs Terraform to import resources according to the specified provider configuration.

import {
  # . . .
  provider = "<provider>.<alias>"
}

By default, Terraform automatically selects a provider based on the resource type, but you can configure multiple instances of the same provider with aliases and use a non-default configuration to import specific resources.

Use the <PROVIDER>.<ALIAS> syntax to reference a provider configuration in the provider argument.

The provider argument is a meta-argument, which is built into Terraform and controls the way that Terraform creates resources. Refer to Meta-arguments for more information.

Summary

Examples

The following examples show how to write configuration for common use cases.

Import a single resource

You can import an individual resource by specifying its ID with the id argument or by specifying the set of identifying attributes in the identity argument.

In the following example, Terraform imports example-bucket into a resource at aws_s3_bucket.this:

import {
    to = aws_s3_bucket.this
    id = "example-bucket"
}

resource "aws_s3_bucket" "this" {
  # …
}

Refer to the AWS provider documentation in the Terraform registry for more information about importing AWS instances.

Import multiple resources

In the following example, the for_each argument loops through the key-value pairs defined in the buckets map. For each pair, Terraform imports the S3 bucket into the aws_s3_bucket.this resource. The [each.key] index maps to the keys in locals block, such as aws_s3_bucket.this["staging"]. 

locals {
  buckets = {
    "staging" = "bucket1"
    "uat"     = "bucket2"
    "prod"    = "bucket3"
  }
}

import {
  for_each = local.buckets
  to = aws_s3_bucket.this[each.key]
  id = each.value
}

resource "aws_s3_bucket" "this" {
  for_each = local.buckets
}

In the following example, the for_each argument loops through the list of key-value pairs defined in the buckets list. For each set of key-value pair, Terraform imports an existing S3 bucket with the identifier each.value.id into the Terraform resource at module.group[each.value.group].aws_s3_bucket.this[each.value.key].

locals {
  buckets = [
    { 
      group = "one"
      key   = "bucket1"
      id    = "one_1"
    },
    {
      group = "one"
      key   = "bucket2"
      id    = "one_2"
    },
    {
      group = "two"
      key   = "bucket1"
      id    = "two_1"
    },
    {
      group = "two"
      key   = "bucket2"
      id    = "two_2"
    },
  ]
}

import {
  for_each = local.buckets
  id = each.value.id
  to = module.group[each.value.group].aws_s3_bucket.this[each.value.key]
}

Select an alternate provider configuration

In the following example, Terraform imports the AWS instance with the ID i-096fba6d03d36d262 to the aws_instance.web resource according to the east alias.

provider "aws" {
  region = "us-westl-1"
}

provider "aws" {
  alias  = "east"
  region = "us-east-1"
}

import {
  id = "i-096fba6d03d36d262"
  to = aws_instance.web
  provider = aws.east
}

resource "aws_instance" "web" {
  # ...
}
Edit this page on GitHub