Terraform State Management: Importing Existing Infrastructure

When adopting Infrastructure as Code (IaC) with Terraform, you'll often encounter existing infrastructure that wasn't provisioned by Terraform. To bring this infrastructure under Terraform's management, you need to import it into your Terraform state. This process ensures Terraform can track, update, and manage your resources effectively.

Why Import Existing Infrastructure?

There are several compelling reasons to import existing infrastructure:

<ul><li>Adopting IaC Gradually: Transitioning to Terraform without a complete re-provisioning of all infrastructure.</li><li>Managing Legacy Resources: Bringing manually created or previously managed resources under Terraform's control.</li><li>Disaster Recovery & State Reconciliation: Ensuring your Terraform state accurately reflects the current state of your infrastructure, especially after manual changes or failures.</li><li>Consistency and Auditability: Establishing a single source of truth for your infrastructure's configuration and lifecycle.</li></ul>

The `terraform import` Command

Terraform provides a dedicated command,

code

terraform import

, to facilitate this process. The basic syntax is:

<code>terraform import [options] <resource_type>.<resource_name> <resource_id></code>

Let's break down the components:

`resource_type.resource_name` maps the existing resource to a Terraform resource block.

You need to define a corresponding Terraform resource block in your configuration that matches the type of the resource you're importing (e.g., aws_instance, google_compute_instance). The resource_name is the logical name you'll use within your Terraform configuration to refer to this resource.

The resource_type must exactly match the Terraform resource type (e.g., aws_instance, azurerm_virtual_machine, google_compute_instance). The resource_name is the local name you assign to this resource within your Terraform configuration files (e.g., web_server, database_instance). This name is crucial for referencing the imported resource in other parts of your Terraform code.

`resource_id` is the unique identifier of the resource in the cloud provider.

The resource_id is a provider-specific identifier that uniquely identifies the resource in your cloud environment. This is not the same as the Terraform resource name.

The resource_id is the unique identifier of the resource as it exists in the target cloud provider's API. For example, an AWS EC2 instance ID might look like i-0123456789abcdef0, an Azure resource ID is a long, hierarchical string, and a Google Cloud resource ID is often a project/zone/name combination. You can typically find this ID in the cloud provider's console or via their CLI tools.

The Import Process: A Step-by-Step Guide

Loading diagram...

Here's a typical workflow for importing a resource:

1. Identify the Existing Resource: Determine the specific resource you want to import and find its unique ID in your cloud provider's environment.

2. Write a Terraform Resource Block: Create a corresponding resource block in your

code

.tf

files. This block should define the resource's type and a logical name. Crucially, do not include any configuration arguments yet. The

code

terraform import

command will populate the state file, but it won't write the configuration to your

code

.tf

files.

The initial resource block should be minimal, often just defining the type and name, as the import command populates the state, not the configuration file.

3. Run

code

terraform init

: Ensure your Terraform environment is initialized.

4. Execute

code

terraform import

: Run the import command with the correct resource type, name, and the resource's ID.

5. Verify the State: After a successful import, Terraform will update your

code

terraform.tfstate

file. You can inspect this file (or use

code

terraform state show .

) to confirm the resource has been imported correctly.

6. Generate Configuration (Optional but Recommended): The import command only updates the state. To manage the resource going forward, you need to write the corresponding configuration in your

code

.tf

files. You can use

code

terraform state show .

to see the current attributes in the state and then manually write them into your configuration file. Some providers offer tools or community scripts to help generate this configuration automatically.

Important Considerations and Best Practices

<ul><li>Provider Support: Not all Terraform providers and resource types support the `import` command. Check the provider's documentation.</li><li>Resource Dependencies: Importing resources with complex dependencies can be challenging. It's often best to import resources in an order that respects their dependencies.</li><li>State Drift: After importing, perform a `terraform plan` to identify any differences between your configuration and the imported state. You'll likely need to update your configuration to match the imported state.</li><li>Idempotency: Ensure your written configuration is idempotent, meaning applying it multiple times has the same effect as applying it once.</li><li>Batch Imports: For importing multiple resources, consider scripting the `terraform import` commands.</li></ul>

The terraform import command is a bridge between existing infrastructure and Infrastructure as Code. It populates the Terraform state file with the current attributes of a resource, allowing Terraform to manage it. However, it does not automatically generate the corresponding Terraform configuration code. You must manually write or generate the .tf files that describe the imported resource's desired state.

📚

Text-based content

Library pages focus on text content

Example: Importing an AWS EC2 Instance

Let's say you have an existing AWS EC2 instance with the ID

code

i-0123456789abcdef0

that you want to manage with Terraform.

1. Define the resource block in

code

main.tf

:

<code>resource "aws_instance" "my_existing_server" {

Configuration will be added after import

}</code>

2. Run the import command:

<code>terraform import aws_instance.my_existing_server i-0123456789abcdef0</code>

3. Verify and update configuration: After a successful import, use

code

terraform state show aws_instance.my_existing_server

to see its attributes. Then, populate your

code

aws_instance.my_existing_server

block with the necessary arguments (e.g.,

code

ami

code

instance_type

code

tags

). Finally, run

code

terraform plan

to ensure your configuration matches the state.

Learning Resources

Terraform Import Documentation(documentation)

The official HashiCorp documentation for the `terraform import` command, detailing its syntax and usage.

Importing Existing Infrastructure - Terraform Official Guide(tutorial)

A step-by-step tutorial from HashiCorp on how to import existing infrastructure into Terraform state.

Terraform Import: A Practical Guide(blog)

A blog post from HashiCorp that provides practical advice and common scenarios for using `terraform import`.

AWS Provider - Import(documentation)

Specific documentation for importing AWS resources using the Terraform AWS provider, including supported resources.

AzureRM Provider - Import(documentation)

Details on how to import Azure resources with the Terraform AzureRM provider, outlining supported resource types and methods.

Google Cloud Provider - Import(documentation)

Information on importing Google Cloud resources using the Terraform Google provider, covering its capabilities and limitations.

Terraform Import: Best Practices and Pitfalls(blog)

A blog post discussing common challenges and best practices when importing infrastructure into Terraform.

Understanding Terraform State(video)

A video explaining the fundamentals of Terraform state, which is crucial for understanding the import process.

Terraform Import Workflow Example (YouTube)(video)

A practical video demonstration of importing an AWS resource into Terraform state.

Terraform Import - Stack Overflow(wikipedia)

A collection of community questions and answers related to Terraform import, offering solutions to common problems.

Importing Existing Infrastructure into Terraform State

Terraform State Management: Importing Existing Infrastructure

Why Import Existing Infrastructure?

The `terraform import` Command

`resource_type.resource_name` maps the existing resource to a Terraform resource block.

`resource_id` is the unique identifier of the resource in the cloud provider.

The Import Process: A Step-by-Step Guide

Important Considerations and Best Practices

Example: Importing an AWS EC2 Instance

Configuration will be added after import

Learning Resources