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

• Data type: Block
• Default: None
• Example: Import a single resource

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

• Data type: Address
• Default: None
• Example: Import a single resource

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

• Data type: String
• Default: None
• Example: Import a single resource

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

• Data type: String
• Default: None
• Example: Import a single resource

for_each

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

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

import {
  for_each = {
    "<KEY>" = "<VALUE>"
  }
}

for_each is a meta-argument. Meta-arguments are built into the Terraform language and control how Terraform creates resources. Refer to the for_each reference for details about how the argument works.

provider

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

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

provider is a meta-argument. Meta-arguments are built into the Terraform language and control how Terraform creates resources. Refer to the provider reference for details about how the argument works.

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 in id argument or by specifying the set of identifying attributes in the identity argument.

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

resource "aws_s3_bucket" "this" {
  # …
}

import {
  to = aws_s3_bucket.bucket
  identity = {
    account_id = "622801496880"
    bucket     = "hjarui4t89efuh"
    region     = "us-east-1"
  }
}

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]
}