Skip to main content
Oct 19-21 HashiConf Global is live. Join Now
Type '/' to Search

Use Configuration to Move Resources

This tutorial also appears in: Modules and State.

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 already existing infrastructure, your resource's 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, 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

This tutorial assumes that you are familiar with the standard Terraform workflow. If you are new to Terraform, complete the Get Started tutorials first.

For this tutorial, you will need:

»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

Initialize the directory.

$ terraform init
Initializing modules...

Initializing the backend...

Initializing provider plugins...
- Finding latest version of hashicorp/aws...
- Installing hashicorp/aws v3.67.0...
- Installed hashicorp/aws v3.67.0 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

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 initInitializing modules...
Initializing the backend...
Initializing provider plugins...- Finding latest version of hashicorp/aws...- Installing hashicorp/aws v3.67.0...- Installed hashicorp/aws v3.67.0 (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the providerselections it made above. Include this file in your version control repositoryso that Terraform can guarantee to make the same selections by default whenyou run "terraform init" in the future.
Terraform has been successfully initialized!
You may now begin working with Terraform. Try running "terraform plan" to seeany changes that are required for your infrastructure. All Terraform commandsshould 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, othercommands 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


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

Terraform will perform the following actions:

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

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

  # module.vpc.aws_eip.nat[0] will be created
##...
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


module.vpc.aws_vpc.this[0]: Creating...
##...

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

Outputs:

public_ip = "35.170.202.170"

$ terraform apply

Terraform used the selected providers to generate the following execution plan. Resource actions areindicated with the following symbols:  + create
Terraform will perform the following actions:
  # aws_instance.example will be created  + resource "aws_instance" "example" {      ##...    }
  # aws_security_group.sg_8080 will be created  + resource "aws_security_group" "sg_8080" {##...    }
  # module.vpc.aws_eip.nat[0] will be created##...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

module.vpc.aws_vpc.this[0]: Creating...##...
Apply complete! Resources: 22 added, 0 changed, 0 destroyed.
Outputs:
public_ip = "35.170.202.170"

Test your instance availability with the curl command.

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

$ curl $(terraform output -raw public_ip):8080Hello, 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]
-   user_data              = <<-EOF
-               #!/bin/bash
-               echo "Hello, World" > index.html
-               nohup busybox httpd -f -p 8080 &
-               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"]
-   }
- }
main.tf
- 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]-   user_data              = <<-EOF-               #!/bin/bash-               echo "Hello, World" > index.html-               nohup busybox httpd -f -p 8080 &-               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"]-   }- }

»Create compute module

Create a new modules directory with a compute subdirectory.

$ mkdir -p modules/compute

$ mkdir -p modules/compute

Change into the compute directory.

$ cd modules/compute

$ cd modules/compute

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

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

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]
  user_data              = <<-EOF
              #!/bin/bash
              echo "Hello, World" > index.html
              nohup busybox httpd -f -p 8080 &
              EOF
  tags = {
    Name = "terraform-learn-move-ec2"
  }
}
modules/compute/main.tf

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"}
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]  user_data              = <<-EOF              #!/bin/bash              echo "Hello, World" > index.html              nohup busybox httpd -f -p 8080 &              EOF  tags = {    Name = "terraform-learn-move-ec2"  }}

Then, 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
}
modules/compute/outputs.tf
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 ../security_group

$ mkdir ../security_group

Change into the security_group directory.

$ cd ../security_group

$ cd ../security_group

Create a new main.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
}

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"]
  }
}
modules/security_group/main.tf
variable "vpc_id" {  description = "ID of the VPC where to create security group"  type        = string}
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"]  }}

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
}
modules/security_group/outputs.tf
output "sg_id" {  description = "The security group ID passed from this module"  value       = aws_security_group.sg_8080.id}

»Update configuration with modules

Navigate to the root of your project directory.

$ cd ../..

$ cd ../..

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
}
main.tf
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 = aws_instance.example.public_ip
+ value = module.ec2_instance.public_ip
}
outputs.tf
output "public_ip" {  description = "The Public IP address used to access the instance"- value = aws_instance.example.public_ip+ 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 initInitializing 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

aws_security_group.sg_8080: Refreshing state... [id=sg-0a73d9e7b73f2c78a]
aws_instance.example: Refreshing state... [id=i-01724af2ebbc12d48]

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 = "35.170.202.170" -> null

$ terraform plan
aws_security_group.sg_8080: Refreshing state... [id=sg-0a73d9e7b73f2c78a]aws_instance.example: Refreshing state... [id=i-01724af2ebbc12d48]
Terraform used the selected providers to generate the following execution plan. Resource actions areindicated 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 = "35.170.202.170" -> null

Your module changes would delete and recreate your resources, which causes service interruptions in your infrastructure. 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
}
main.tf
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. Confirm your changes with yes after you ensure 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-01724af2ebbc12d48"
        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-0a73d9e7b73f2c78a"
        name                   = "terraform-learn-move-sg"
        tags                   = {}
        # (8 unchanged attributes hidden)
    }

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

Changes to Outputs:
  - public_ip = "35.170.202.170" -> null

You can apply this plan to save these new output values to the Terraform state, without changing any real
infrastructure.

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.

$ 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-01724af2ebbc12d48"        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-0a73d9e7b73f2c78a"        name                   = "terraform-learn-move-sg"        tags                   = {}        # (8 unchanged attributes hidden)    }
Plan: 0 to add, 0 to change, 0 to destroy.
Changes to Outputs:  - public_ip = "35.170.202.170" -> null
You can apply this plan to save these new output values to the Terraform state, without changing any realinfrastructure.
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.

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 "vpc" {
+ module "learn_vpc" {

##...

module "ec2_instance" {
  source = "./modules/compute"
  security_group = module.security_group.id
- subnet_id = module.vpc.public_subnets
+ subnet_id = module.learn_vpc.public_subnets
 }

module "security_group" {
   source = "./modules/security_group"
-  vpc_id = module.vpc.vpc_id
+  vpc_id = module.learn_vpc.vpc_id
}
main.tf
- module "vpc" {+ module "learn_vpc" {
##...
module "ec2_instance" {  source = "./modules/compute"  security_group = module.security_group.id- subnet_id = module.vpc.public_subnets+ subnet_id = module.learn_vpc.public_subnets }
module "security_group" {   source = "./modules/security_group"-  vpc_id = module.vpc.vpc_id+  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
}
main.tf
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 2.21.0 for learn_vpc...
- learn_vpc in .terraform/modules/learn_vpc

$ terraform initInitializing modules...Downloading registry.terraform.io/terraform-aws-modules/vpc/aws 2.21.0 for learn_vpc...- learn_vpc in .terraform/modules/learn_vpc

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

$ terraform apply
module.learn_vpc.aws_eip.nat[0]: Refreshing state... [id=eipalloc-089cc4bc9935b6d9c]
##...
# module.vpc.aws_vpc.this[0] has moved to module.learn_vpc.aws_vpc.this[0]
    resource "aws_vpc" "this" {
        id                               = "vpc-09bdd5beb19d8adb4"
        tags                             = {
            "Environment" = "dev"
            "Name"        = "example-vpc"
            "Terraform"   = "true"
        }
        # (15 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.

$ terraform applymodule.learn_vpc.aws_eip.nat[0]: Refreshing state... [id=eipalloc-089cc4bc9935b6d9c]##...# module.vpc.aws_vpc.this[0] has moved to module.learn_vpc.aws_vpc.this[0]    resource "aws_vpc" "this" {        id                               = "vpc-09bdd5beb19d8adb4"        tags                             = {            "Environment" = "dev"            "Name"        = "example-vpc"            "Terraform"   = "true"        }        # (15 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.

Note: We strongly recommend you retain all moved blocks in your configuration as a record of your changes. Removing a moved block plans to delete that existing resource instead of moving it.

»Clean up your resources

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

$ terraform destroy
module.learn_vpc.aws_route.private_nat_gateway[0]: Refreshing state... [id=r-rtb-0d9e8330edbc822fe1080289494]

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

Terraform will perform the following actions:

  # module.ec2_instance.aws_instance.example will be destroyed
  - resource "aws_instance" "example" {
##...
    }


  # module.learn_vpc.aws_vpc.this[0] will be destroyed
  - resource "aws_vpc" "this" {
##...
    }

  # module.security_group.aws_security_group.sg_8080 will be destroyed
  - resource "aws_security_group" "sg_8080" {
##...
    }

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 destroymodule.learn_vpc.aws_route.private_nat_gateway[0]: Refreshing state... [id=r-rtb-0d9e8330edbc822fe1080289494]
Terraform used the selected providers to generate the following execution plan. Resource actions areindicated with the following symbols:  - destroy
Terraform will perform the following actions:
  # module.ec2_instance.aws_instance.example will be destroyed  - resource "aws_instance" "example" {##...    }

  # module.learn_vpc.aws_vpc.this[0] will be destroyed  - resource "aws_vpc" "this" {##...    }
  # module.security_group.aws_security_group.sg_8080 will be destroyed  - resource "aws_security_group" "sg_8080" {##...    }
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.

»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:

stdin: is not a tty