Use Configuration to Move Resources

As your Terraform configuration grows in complexity, updating resources becomes more risky: an update to one resource may cause unintended changes to other parts of your infrastructure. One way to address this is to refactor your existing Terraform code into separate modules. In addition to limiting the scope of potential changes, modules help abstract your resources, making your configuration easier to understand.

When you create modules from existing infrastructure, your resource IDs will change. Because of this, you must let Terraform know that you intend to move resources rather than replace them, or Terraform will destroy and recreate your resources with the new ID. In previous versions of Terraform, you would use the terraform state mv command to individually move your resources to their new module address so Terraform can correctly track the infrastructure.

The moved configuration block allows you to track your resource moves in the configuration itself. With the moved configuration block, you can plan, preview, and validate resource moves, enabling you to safely refactor your configuration.

In this tutorial, you will create several AWS resources in a single configuration file and then divide them into compute and security group modules. Then, you will use the moved block to refactor your configuration and update resource IDs, and review the corresponding state changes before you apply the new configuration.

»Prerequisites

You can complete this tutorial using the same workflow with either Terraform OSS or Terraform Cloud. Terraform Cloud 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 Terraform Cloud tab to complete this tutorial using Terraform Cloud.

»Clone the example configuration

Clone the example repository for this tutorial.

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

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

Change to the repository directory.

$ cd learn-terraform-move

$ cd learn-terraform-move

This configuration contains a VPC module, a security group that allows ingress HTTP traffic on port 8080, and an EC2 instance that uses the security group. Later in this tutorial, you will move these resources into separate modules to make your configuration more manageable.

»Initialize and apply the configuration

$ 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 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.

After Terraform initializes, apply the configuration and approve the run by typing yes at the prompt.

$ terraform apply

## ...

Plan: 22 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + public_ip = (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

##...

Apply complete! Resources: 22 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "18.217.55.179"

$ terraform apply

## ...

Plan: 22 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + public_ip = (known after apply)

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

##...

Apply complete! Resources: 22 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "18.217.55.179"

Test your instance availability with the curl command.

$ curl $(terraform output -raw public_ip):8080
Hello World

$ curl $(terraform output -raw public_ip):8080
Hello World

In the next section, you will refactor your configuration into modules.

»Refactor your configuration

In this example, you have a small number of resources to manage. However, an operational environment may consist of many more resources and be difficult to manage in a single configuration file. By organizing these resources into modules, your configuration becomes ​​flexible, reusable, and composable.

In your main.tf file, remove the AMI data source, the instance resource, and security group resource.

- data "aws_ami" "ubuntu" {
-   most_recent = true
- 
-   filter {
-     name   = "name"
-     values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"]
-   }
- 
-   filter {
-     name   = "virtualization-type"
-     values = ["hvm"]
-   }
- 
-   owners = ["099720109477"] # Canonical
- }

- resource "aws_instance" "example" {
-   ami                         = data.aws_ami.ubuntu.id
-   subnet_id                   = module.vpc.public_subnets[0]
-   instance_type               = "t2.micro"
-   vpc_security_group_ids      = [aws_security_group.sg_8080.id]
-   associate_public_ip_address = true
-   
-   user_data                   = <<-EOF
-               #!/bin/bash
-               apt-get update
-               apt-get install -y apache2
-               sed -i -e 's/80/8080/' /etc/apache2/ports.conf
-               echo "Hello World" > /var/www/html/index.html
-               systemctl restart apache2
-               EOF
-   tags = {
-     Name = "terraform-learn-move-ec2"
-   }
- }

- resource "aws_security_group" "sg_8080" {
-   vpc_id = module.vpc.vpc_id
-   name   = "terraform-learn-move-sg"
-   ingress {
-     from_port   = "8080"
-     to_port     = "8080"
-     protocol    = "tcp"
-     cidr_blocks = ["0.0.0.0/0"]
-   }
-   // connectivity to ubuntu mirrors is required to run `apt-get update` and `apt-get install apache2`
-   egress {
-     from_port   = 0
-     to_port     = 0
-     protocol    = "-1"
-     cidr_blocks = ["0.0.0.0/0"]
-   }
- }

- data "aws_ami" "ubuntu" {
-   most_recent = true
- 
-   filter {
-     name   = "name"
-     values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"]
-   }
- 
-   filter {
-     name   = "virtualization-type"
-     values = ["hvm"]
-   }
- 
-   owners = ["099720109477"] # Canonical
- }

- resource "aws_instance" "example" {
-   ami                         = data.aws_ami.ubuntu.id
-   subnet_id                   = module.vpc.public_subnets[0]
-   instance_type               = "t2.micro"
-   vpc_security_group_ids      = [aws_security_group.sg_8080.id]
-   associate_public_ip_address = true
-   
-   user_data                   = <<-EOF
-               #!/bin/bash
-               apt-get update
-               apt-get install -y apache2
-               sed -i -e 's/80/8080/' /etc/apache2/ports.conf
-               echo "Hello World" > /var/www/html/index.html
-               systemctl restart apache2
-               EOF
-   tags = {
-     Name = "terraform-learn-move-ec2"
-   }
- }

- resource "aws_security_group" "sg_8080" {
-   vpc_id = module.vpc.vpc_id
-   name   = "terraform-learn-move-sg"
-   ingress {
-     from_port   = "8080"
-     to_port     = "8080"
-     protocol    = "tcp"
-     cidr_blocks = ["0.0.0.0/0"]
-   }
-   // connectivity to ubuntu mirrors is required to run `apt-get update` and `apt-get install apache2`
-   egress {
-     from_port   = 0
-     to_port     = 0
-     protocol    = "-1"
-     cidr_blocks = ["0.0.0.0/0"]
-   }
- }

»Create compute module

Create a new modules directory with a compute subdirectory.

$ mkdir -p modules/compute

$ mkdir -p modules/compute

Create a new main.tf file in the compute directory and add the following configuration.

data "aws_ami" "ubuntu" {
  most_recent = true

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }

  owners = ["099720109477"] # Canonical
}


resource "aws_instance" "example" {
  ami                         = data.aws_ami.ubuntu.id
  subnet_id                   = var.public_subnets[0]
  instance_type               = "t2.micro"
  vpc_security_group_ids      = [var.security_group]
  associate_public_ip_address = true
  
  user_data                   = <<-EOF
              #!/bin/bash
              apt-get update
              apt-get install -y apache2
              sed -i -e 's/80/8080/' /etc/apache2/ports.conf
              echo "Hello World" > /var/www/html/index.html
              systemctl restart apache2
              EOF
  tags = {
    Name = "terraform-learn-move-ec2"
  }
}

data "aws_ami" "ubuntu" {
  most_recent = true

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }

  owners = ["099720109477"] # Canonical
}


resource "aws_instance" "example" {
  ami                         = data.aws_ami.ubuntu.id
  subnet_id                   = var.public_subnets[0]
  instance_type               = "t2.micro"
  vpc_security_group_ids      = [var.security_group]
  associate_public_ip_address = true
  
  user_data                   = <<-EOF
              #!/bin/bash
              apt-get update
              apt-get install -y apache2
              sed -i -e 's/80/8080/' /etc/apache2/ports.conf
              echo "Hello World" > /var/www/html/index.html
              systemctl restart apache2
              EOF
  tags = {
    Name = "terraform-learn-move-ec2"
  }
}

Then, create a new variables.tf file to capture your variables. You will declare variables that you can use to configure the module.

variable "security_group" {
 description = "The security groups assigned to this instance"
}

variable "public_subnets" {
  description = "The public subnet IDs assigned to this instance for IP address assignment"
}

variable "security_group" {
 description = "The security groups assigned to this instance"
}

variable "public_subnets" {
  description = "The public subnet IDs assigned to this instance for IP address assignment"
}

Finally, create a new outputs.tf file to capture your instance IP address. You will use this output to pass as a variable into another module.

output "public_ip" {
  description = "The Public IP address used to access the instance"
  value       = aws_instance.example.public_ip
}

output "public_ip" {
  description = "The Public IP address used to access the instance"
  value       = aws_instance.example.public_ip
}

This is a modified version of the initial Terraform configuration for the EC2 instance.

»Create security group module

Next, create a new directory for your security_group module.

$ mkdir -p modules/security_group

$ mkdir -p modules/security_group

Create a new main.tf file in the security_group directory and add the following configuration.

resource "aws_security_group" "sg_8080" {
  vpc_id      = var.vpc_id
  name = "terraform-learn-move-sg"
  ingress {
    from_port   = "8080"
    to_port     = "8080"
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

resource "aws_security_group" "sg_8080" {
  vpc_id      = var.vpc_id
  name = "terraform-learn-move-sg"
  ingress {
    from_port   = "8080"
    to_port     = "8080"
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

Then, create a new variables.tf file in the security_group directory and add the following configuration.

variable "vpc_id" {
  description = "ID of the VPC where to create security group"
  type        = string
}

variable "vpc_id" {
  description = "ID of the VPC where to create security group"
  type        = string
}

Next, create a new outputs.tf file to capture your security group ID. You will pass this output value as an input variable into another module.

output "sg_id" {
  description = "The security group ID passed from this module"
  value       = aws_security_group.sg_8080.id
}

output "sg_id" {
  description = "The security group ID passed from this module"
  value       = aws_security_group.sg_8080.id
}

»Update configuration with modules

Open the main.tf file and add the new module blocks to the end of your configuration.

module "ec2_instance" {
  source          = "./modules/compute"
  security_group = module.security_group.sg_id
  public_subnets  = module.vpc.public_subnets
}

module "security_group" {
  source = "./modules/security_group"
  vpc_id    = module.vpc.vpc_id
}

module "ec2_instance" {
  source          = "./modules/compute"
  security_group = module.security_group.sg_id
  public_subnets  = module.vpc.public_subnets
}

module "security_group" {
  source = "./modules/security_group"
  vpc_id    = module.vpc.vpc_id
}

Save your changes.

Update the outputs.tf file in the root directory.

output "public_ip" {
  description = "The Public IP address used to access the instance"
  value       = module.ec2_instance.public_ip
}

output "public_ip" {
  description = "The Public IP address used to access the instance"
  value       = module.ec2_instance.public_ip
}

»Review planned changes

Next, reinitialize your configuration to install the newly created modules.

$ terraform init
Initializing modules...
- ec2_instance in modules/compute
- security_group in modules/security_group

##...

$ terraform init
Initializing modules...
- ec2_instance in modules/compute
- security_group in modules/security_group

##...

Now that Terraform recognizes the module directory structure, generate a plan to observe the changes.

$ terraform plan
##...
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create
  - destroy

Terraform will perform the following actions:

  # aws_instance.example will be destroyed
  # (because aws_instance.example is not in configuration)
  - resource "aws_instance" "example" {
      ##...
    }

  # aws_security_group.sg_8080 will be destroyed
  # (because aws_security_group.sg_8080 is not in configuration)
  - resource "aws_security_group" "sg_8080" {
      ##...
    }

  # module.ec2_instance.aws_instance.example will be created
  + resource "aws_instance" "example" {
      ##...
    }

  # module.security_group.aws_security_group.sg_8080 will be created
  + resource "aws_security_group" "sg_8080" {
      ##...
    }

Plan: 2 to add, 0 to change, 2 to destroy.

Changes to Outputs:
  ~ public_ip = "18.119.128.83" -> (known after apply)

$ terraform plan
##...
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create
  - destroy

Terraform will perform the following actions:

  # aws_instance.example will be destroyed
  # (because aws_instance.example is not in configuration)
  - resource "aws_instance" "example" {
      ##...
    }

  # aws_security_group.sg_8080 will be destroyed
  # (because aws_security_group.sg_8080 is not in configuration)
  - resource "aws_security_group" "sg_8080" {
      ##...
    }

  # module.ec2_instance.aws_instance.example will be created
  + resource "aws_instance" "example" {
      ##...
    }

  # module.security_group.aws_security_group.sg_8080 will be created
  + resource "aws_security_group" "sg_8080" {
      ##...
    }

Plan: 2 to add, 0 to change, 2 to destroy.

Changes to Outputs:
  ~ public_ip = "18.119.128.83" -> (known after apply)

Your module changes would delete and recreate your resources, which could cause service interruptions. In the next section, you will use Terraform's moved block to refactor your configuration to use modules without destroying the existing resources.

»Move your resources with the moved configuration block

In previous versions of Terraform, you had to refactor your existing infrastructure manually, by using terraform state mv to rename your resources in your project's state to match the changes to your configuration.

With the moved configuration block, you can inform Terraform about all resource address changes in your configuration. Terraform also validates those changes to provide you with clearer operational output and you can safely review plans before applying.

In your root main.tf file, add moved configuration blocks for each of the resources you moved into modules in the previous step.

moved {
  from = aws_instance.example
  to = module.ec2_instance.aws_instance.example
}

moved {
  from = aws_security_group.sg_8080
  to = module.security_group.aws_security_group.sg_8080
}

moved {
  from = aws_instance.example
  to = module.ec2_instance.aws_instance.example
}

moved {
  from = aws_security_group.sg_8080
  to = module.security_group.aws_security_group.sg_8080
}

Re-apply your configuration to move your resources into your new modules and update the resource IDs. Confirm your changes with yes after you verify that Terraform will move your resources instead of replacing them.

$ terraform apply
##...
Terraform will perform the following actions:

  # aws_instance.example has moved to module.ec2_instance.aws_instance.example
    resource "aws_instance" "example" {
        id                                   = "i-04783269f41a67c2e"
        tags                                 = {
            "Name" = "terraform-learn-move-ec2"
        }
        # (28 unchanged attributes hidden)
        # (5 unchanged blocks hidden)
    }

  # aws_security_group.sg_8080 has moved to module.security_group.aws_security_group.sg_8080
    resource "aws_security_group" "sg_8080" {
        id                     = "sg-027d48bb42bc66a16"
        name                   = "terraform-learn-move-sg"
        tags                   = {}
        # (8 unchanged attributes hidden)
    }

Plan: 0 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "18.119.128.83"

$ terraform apply
##...
Terraform will perform the following actions:

  # aws_instance.example has moved to module.ec2_instance.aws_instance.example
    resource "aws_instance" "example" {
        id                                   = "i-04783269f41a67c2e"
        tags                                 = {
            "Name" = "terraform-learn-move-ec2"
        }
        # (28 unchanged attributes hidden)
        # (5 unchanged blocks hidden)
    }

  # aws_security_group.sg_8080 has moved to module.security_group.aws_security_group.sg_8080
    resource "aws_security_group" "sg_8080" {
        id                     = "sg-027d48bb42bc66a16"
        name                   = "terraform-learn-move-sg"
        tags                   = {}
        # (8 unchanged attributes hidden)
    }

Plan: 0 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "18.119.128.83"

Your instance and security group IDs changed but the resources themselves have not.

»Rename and move a resource

You can also use the moved configuration block to rename existing resources. In the root of your configuration, open the main.tf file.

Rename your vpc module, and update the references to it in the rest of your configuration.

module "learn_vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "3.14.0"

  ##...
}

module "ec2_instance" {
  source         = "./modules/compute"
  security_group = module.security_group.sg_id
  public_subnets = module.learn_vpc.public_subnets
}

module "security_group" {
  source = "./modules/security_group"
  vpc_id = module.learn_vpc.vpc_id
}

module "learn_vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "3.14.0"

  ##...
}

module "ec2_instance" {
  source         = "./modules/compute"
  security_group = module.security_group.sg_id
  public_subnets = module.learn_vpc.public_subnets
}

module "security_group" {
  source = "./modules/security_group"
  vpc_id = module.learn_vpc.vpc_id
}

Add the moved block for your VPC changes at the bottom of the file.

moved {
  from = module.vpc
  to   = module.learn_vpc
}

moved {
  from = module.vpc
  to   = module.learn_vpc
}

Run terraform init to update your VPC module's name.

$ terraform init
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/vpc/aws 3.14.0 for learn_vpc...
- learn_vpc in .terraform/modules/learn_vpc

$ terraform init
Initializing modules...
Downloading registry.terraform.io/terraform-aws-modules/vpc/aws 3.14.0 for learn_vpc...
- learn_vpc in .terraform/modules/learn_vpc

Apply your changes. Confirm your changes with yes after you verify there are no resource changes.

$ terraform apply
##...
Plan: 0 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes


Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "18.119.128.83"

$ terraform apply
##...
Plan: 0 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes


Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "18.119.128.83"

»Clean up your resources

Remove the infrastructure you created in this tutorial. Respond to the confirmation prompt with a yes.

$ terraform destroy
##...

Plan: 0 to add, 0 to change, 22 to destroy.

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

##...

Destroy complete! Resources: 22 destroyed.

$ terraform destroy
##...

Plan: 0 to add, 0 to change, 22 to destroy.

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value: yes

##...

Destroy complete! Resources: 22 destroyed.

If you used Terraform Cloud for this tutorial, after destroying your resources, delete the learn-terraform-move workspace from your Terraform Cloud organization.

»Next steps

In this tutorial, you created an EC2 instance and supporting networking resources. Then, you refactored your Terraform configuration into modules. Finally, you used the moved configuration block to safely update the resource IDs.

For more information on modules and state, review the following resources:

• Review the Terraform Documentation on the moved configuration block. Learn to use the moved configuration block with resources containing the for_each or count functions.
• Follow the Build and Use a Local Module tutorial to review how to create a module.
• Follow the Manage Resources in Terraform State tutorial to learn other methods for updating your state file.
• Follow the Manage Resource Lifecycle tutorial and use the different lifecycle management options available in Terraform to prevent resource deletion.