How to Import AWS RDS Instances into Terraform and Safely Manage Drift

Managing AWS resources through Terraform allows you to automate and version control your infrastructure, ensuring consistency and reproducibility. If you already have existing AWS RDS instances and want to start managing them with Terraform, you can import them into your Terraform state.

However, there’s a critical caution when importing existing resources: Do not apply the plan if it proposes to destroy any resources. Running an apply on such a plan can inadvertently destroy your infrastructure (e.g., deleting your RDS instances and causing data loss).

In this article, we’ll walk through the steps to import your AWS RDS instances into Terraform and how to ensure that no resources are destroyed during the process.

Prerequisites

Before you start, make sure you have the following:

1. Terraform: Install Terraform on your machine. You can find the installation guide here.
2. AWS Account: Ensure you have an active AWS account and the necessary IAM permissions to manage RDS resources.
3. AWS CLI: Set up AWS CLI and configure your credentials using aws configure.
4. Existing RDS Instances: The AWS RDS instances you want to import into Terraform should already be running.

What We’ll Do

1. Import your existing AWS RDS instances (MySQL and PostgreSQL) into Terraform.
2. Update your Terraform configuration to match the current state of the resources.
3. Safely manage drift to avoid accidental destruction of resources.

---

Step 1: Set Up Your Terraform Configuration

Before you import your RDS instances, you need to have a Terraform configuration that represents those resources. In the case of MySQL and PostgreSQL, your initial main.tf file might look like this:

resource "aws_db_instance" "mysql" {
  identifier = "mysql-db-instance"
  engine     = "mysql"
}

resource "aws_db_instance" "postgres" {
  identifier = "postgres-db-instance"
  engine     = "postgres"
}

This is a very basic configuration that specifies the identifier and engine for each RDS instance. You’ll be updating this configuration later to reflect the current state of your existing RDS resources.

---

Step 2: Import the RDS Instances

Now that you have a basic Terraform configuration, it’s time to import your existing RDS instances into Terraform's state.

Importing the Resources

To import an AWS RDS instance, use the following command:

terraform import aws_db_instance.<resource_name> <db_instance_identifier>

For example, if your MySQL RDS instance is named mysql-db-instance and your PostgreSQL RDS instance is named postgres-db-instance, run these commands:

1. For MySQL:

   terraform import aws_db_instance.mysql mysql-db-instance

1. For PostgreSQL:

   terraform import aws_db_instance.postgres postgres-db-instance

What Happens After Import?

When you import the resources, Terraform doesn’t automatically update your main.tf file to reflect the current state of the resources. It simply adds the resources to the state file, allowing Terraform to manage them going forward.

---

Step 3: Review the Plan and Check for Drift

After importing the resources, run the terraform plan command to compare the current state of your infrastructure with what’s defined in your configuration:

terraform plan

Important Warning: Don’t Apply if It Shows Resources to Destroy

This step is crucial: If the output of terraform plan suggests that Terraform will destroy any resources (for example, it shows that it plans to delete your RDS instances), DO NOT run terraform apply yet. Applying this plan will result in deleting your RDS instances, causing data loss and infrastructure destruction.

Instead, follow these steps:

Step 4: Resolve Drift Before Applying

If the plan shows that Terraform wants to destroy resources, it means there’s a drift between what’s defined in your Terraform configuration and the actual state of the resources in AWS. This can happen if your main.tf file is missing some resource attributes that are present in the actual configuration of the RDS instances.

Here’s how to handle it:

1. Review the Drift: Carefully examine the terraform plan output to see what will change. Terraform will indicate the differences between the configuration and the current state of the resource.

2. Update Your Configuration: Based on the drift, modify your main.tf configuration to reflect the actual state of the resources. For example, if the allocated_storage or instance_class of your MySQL database is different from what’s specified in the configuration, update the configuration file to match the actual settings in AWS.

Here’s an example of how you might update your configuration after examining the drift:

resource "aws_db_instance" "mysql" {
  identifier           = "mysql-db-instance"
  engine               = "mysql"
  instance_class       = "db.t3.micro"
  allocated_storage    = 20
  db_name              = "mydb_mysql"
  username             = "my_admin"
  password             = "mysecretpassword"
  parameter_group_name = "default.mysql8.0"
  multi_az             = false
  publicly_accessible  = false
  backup_retention_period = 7
  storage_type         = "gp2"
  storage_encrypted    = true
}

resource "aws_db_instance" "postgres" {
  identifier           = "postgres-db-instance"
  engine               = "postgres"
  instance_class       = "db.t3.micro"
  allocated_storage    = 20
  engine_version       = "16"
  db_name              = "mydb_postgres"
  username             = "my_admin"
  password             = "mysecretpassword"
  multi_az             = false
  publicly_accessible  = false
  parameter_group_name = "default.postgres16"
  backup_retention_period = 7
  storage_type         = "gp3"
  storage_encrypted    = true
}

1. Re-run terraform plan: After updating the configuration, run terraform plan again to ensure there are no proposed changes that would destroy resources. Terraform should now show that only updates will be applied, not deletions.

---

Step 5: Apply the Configuration

Once the configuration is updated and no resources are marked for destruction, you can safely apply the changes using:

terraform apply

Terraform will confirm that the resources are in sync with the state and apply any updates if necessary.

---

Final Considerations

• Backup Your Data: Before applying any changes to your RDS instances, make sure you have backup mechanisms in place, such as automated snapshots or manual backups, to avoid accidental data loss.
• Sensitive Data: Avoid hardcoding sensitive information such as passwords directly in your Terraform configuration. Instead, use Terraform variables and reference AWS Secrets Manager to securely manage secrets.
• Monitoring and Alerts: Set up monitoring and alerts for your RDS instances using AWS CloudWatch to ensure that your databases remain healthy and secure.

---

Conclusion

By importing your AWS RDS instances into Terraform, you can start managing them as part of your infrastructure as code. However, it’s crucial to carefully handle any drift between your configuration and the actual resource state. Always inspect the terraform plan output before running terraform apply to ensure no resources are accidentally destroyed. With proper care, you can safely manage your AWS RDS instances and other resources using Terraform.