Import Terraform configuration

Terraform supports bringing your existing infrastructure under its management. By importing resources into Terraform, you can consistently manage your infrastructure using a common workflow.

When you create new infrastructure with Terraform, you usually use the following workflow:

1. Write Terraform configuration that defines the infrastructure you want to create.

2. Review the Terraform plan to ensure the configuration will result in the expected infrastructure.

3. Apply the configuration to have Terraform create your infrastructure.

Terraform stores information about your infrastructure in a state file. To update your infrastructure, you first modify your configuration, and then use Terraform to plan and apply the required changes. Terraform uses the data in your state file to determine the changes it needs to make to your infrastructure.

As of Terraform 1.5, you can use configuration to import existing resources into your state file with the plan-and-apply workflow. You can still use the terraform import command, but configuration-driven import is safer, works with CICD pipelines, and allows you to preview the import operation before modifying state. You can also optionally use Terraform to generate an initial configuration for the resources you will import.

Using configuration to import resources involves the following steps:

1. Identify the existing infrastructure you will import.
2. Define an import block for the resources.
3. Run terraform plan to review the import plan and optionally generate configuration for the resources.
4. Prune generated configuration to only the required arguments.
5. Apply the configuration to bring the resource into your Terraform state file.

In this tutorial, you will create a Docker container with the Docker CLI. Then, you will declare an import block for the existing Docker container, use Terraform to generate configuration for the container, modify the generated configuration, and use the plan-and-apply workflow to bring the container under Terraform management.

Prerequisites

You can complete this tutorial using the same workflow with either Terraform Community Edition or HCP Terraform.

HCP Terraform is a platform that you can use to manage and execute your Terraform projects. It includes features like remote state and execution, structured plan output, workspace resource summaries, and more.

Select the HCP Terraform tab to complete this tutorial using HCP Terraform.

Create a Docker container

Create a container named hashicorp-learn using the latest NGINX image from Docker Hub, and publish that container's port 80 (HTTP) to your local host system's port 8080. You will import this container in this tutorial.

$ docker run --name hashicorp-learn --detach --publish "0.0.0.0:8080:80" nginx:latest
Unable to find image 'nginx:latest' locally
latest: Pulling from library/nginx
afb6ec6fdc1c: Pull complete
dd3ac8106a0b: Pull complete
8de28bdda69b: Pull complete
a2c431ac2669: Pull complete
e070d03fd1b5: Pull complete
Digest: sha256:883874c218a6c71640579ae54e6952398757ec65702f4c8ba7675655156fcca6
Status: Downloaded newer image for nginx:latest
e7ba41fd94e51c501533241e4cffd307fbda81c5b402c372d989c4578518d2e5

Use docker ps to verify that the container is running.

$ docker ps --filter="name=hashicorp-learn"
CONTAINER ID        IMAGE               COMMAND                  CREATED              STATUS              PORTS                  NAMES
e7ba41fd94e5        nginx:latest        "/docker-entrypoint.…"   About a minute ago   Up 59 seconds       0.0.0.0:8080->80/tcp   hashicorp-learn

Visit the address localhost:8080 in your web browser to see the NGINX default index page.

Now you have a Docker image and container to import into your project and manage with Terraform.

Initialize configuration

Now, clone the example repository for this tutorial.

$ git clone https://github.com/hashicorp-education/learn-terraform-import

Change to the repository directory.

$ cd learn-terraform-import

This directory organizes Terraform configuration across three files:

• terraform.tf configures the Terraform and provider versions
• main.tf configures the Docker provider
• docker.tf will contain the configuration you write as part of this tutorial

$ terraform init
Initializing the backend...
##...
Terraform has been successfully initialized!
You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.
If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

terraform {
  cloud {
    organization = "organization-name"
    workspaces {
      name = "learn-terraform-import"
    }
  }

  required_providers {
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 4.2.0"
    }
  }

  required_version = "~> 1.5"
}

$ terraform init
Initializing HCP Terraform...

Initializing provider plugins...
- Reusing previous version of kreuzwerker/docker from the dependency lock file
- Using previously-installed kreuzwerker/docker v4.2.0

HCP Terraform has been successfully initialized!

You may now begin working with HCP Terraform. Try running "terraform plan" to
see any changes that are required for your infrastructure.

If you ever set or change modules or Terraform Settings, run "terraform init"
again to reinitialize your working directory.