How To Build a Database Instance with Terraform and AWS RDS

Shanky

Read more posts by this author.

One of Amazon Web Services (AWS)’s database products Amazon Relational Database Service (RDS) typically requires a lot of clicking around in the AWS Management Console. This effort can take several minutes and if you’re DevOps or simply need to automate the process, marrying Terraform and AWS RDS is a match made in heaven!

In this tutorial, you will learn, step-by-step, how to create a Terraform configuration for an AWS RDS instance and deploy it to the AWS cloud.

Let’s dive in!

Prerequisites

This post will be a step-by-step tutorial. If you’d like to follow along, ensure you have the following in place:

Building the Terraform AWS RDS Database Configuration

Terraform is an infrastructure as code tool that allows you to build, change, and version infrastructure safely and efficiently. Terraform uses different types of configuration files. Each file is written either in Hashicorp Control Language (HCL) or JSON. This tutorial will use HCL.

To create an AWS RDS instance with Terraform, this tutorial will use three different files which, when combined, will contain all of the instructions Terraform needs.

  • main.tf – The Terraform configuration file that will contain the Terraform resource declaration and variable placeholders for the RDS instance attributes.
  • vars.tf – A Terraform variables file containing all variables that main.tf will reference. Splitting configuration items into variables is a best practice especially if you make larger Terraform configurations.
  • provider.tf – A configuration file that defines the AWS provider. Terraform uses AWS providers to connect with Amazon account to manage or deploy/update dozens of AWS services.

Let’s get started and first create the Terraform configuration file that will create an AWS RDS database instance.

1. Open a terminal/console on your computer with Terraform installed.

2. Create a folder named ~/terraform-db-demo, then change (cd) the working directory to that folder. This folder will contain all of the configuration files you’ll be working with.

mkdir ~/terraform-db-demo
cd ~/terraform-db-demo

2. Copy and paste the configuration below in your favorite code editor, and save it as main.tf in the ~/terraform-db-demo directory. The main.tf file is a Terraform configuration file that contains all the resources that need to be provisioned.

You’ll see that the configuration file uses the aws_db_instance resource. This resource contains all of the instructions to make calls to AWS APIs to provision an RDS instance given a few attributes.

You’ll also notice many of the values start with var.. These values are placeholders for Terraform input variables which you’ll define actual values for in the next step.

resource "aws_db_instance" "default" {
# Allocating the storage for database instance.
  allocated_storage    = 10
# Declaring the database engine and engine_version
  engine               = var.engine
  engine_version       = var.engine_version
# Declaring the instance class
  instance_class       = var.instance_class
  name                 = var.name
# User to connect the database instance 
  username             = var.username
# Password to connect the database instance 
  password             = var.password
  parameter_group_name = var.parameter_group_name
}

4. Now, create another file inside ~/terraform-db-demo directory, name it vars.tf and paste the content below. This variables file is necessary to declare all of the variables you’ll be referencing in the main configuration file.

You’ll see that the main.tf configuration file created above references each of these variables below.

variable "engine" {}
variable "engine_version" {}     
variable "instance_class" {}
variable "name"  {}       
variable "username" {}  
variable "password" {} 
variable "parameter_group_name" {}

It is possible to include all configuration values in a single configuration file. To keep things clear and make it easier for developers and admins, it is important to break things up.

Create one more file inside the ~/terraform-db-demo directory, name it terraform.tfvars, and paste the code below. This variables file contains the values that Terraform will use to replace the variable references inside of the configuration file.

When Terraform creates this AWS RDS instance, the instance will be:

  • A MySQL v5.7 database
  • Running on a t3.micro engine
  • With an admin username of user1 with a password of password
  engine               = "mysql"
  engine_version       = "5.7"
  instance_class       = "db.t3.micro"
  name                 = "mydb"
  username             = "user1"
  password             = "password"
  parameter_group_name = "default.mysql5.7"

6. Finally, create one more file ~/terraform-db-demo directory, paste in the following code, and name it as provider.tf to define the AWS provider.

The tutorial will be creating resources in the us-east-2 region.

provider "aws" {
   region = "us-east-2"
 }

7. Now, verify all of the required files below are contained in the folder by running the tree command.

Terraform files that are required to run the terraform code
Terraform files that are required to run the terraform code

Creating the AWS RDS Instance with Terraform

Now that you have the Terraform configuration files ready to go, it’s time to initiate Terraform and create your first AWS RDS database instance!

To provision a Terraform configuration, Terraform typically uses a three-stage approach terraform init → terraform plan → terraform apply. Let’s walk through each stage now.

Assuming you’re still in the ~\terraform-db-demo directory:

1. Run the terraform init command in the same directory. The terraform init command initializes the plugins and providers which are required to work with AWS resources that need to be provisioned.

terraform init

If all goes well, you should see the message Terraform has been successfully initialized in the output, as shown below.

Running the terraform init command
Running the terraform init command

2. Now, run the terraform plan command. Terraform plan command gives you an overview of which resources will be provisioned in your infrastructure. You will also see every AWS resource Terraform intends to create.

terraform plan
Running the Terraform plan command
Running the Terraform plan command

3. Next, tell Terraform actually to provision the database instance using terraform apply. When you invoke terraform apply, Terraform will read the configuration (main.tf) and the other files to compile a configuration and then send that configuration up to AWS as instructions to build the database instance.

terraform apply

As you can see below Terraform has successfully created the database instance in the AWS account using Terraform.

Running the terraform apply command
Running the terraform apply command

Verifying the AWS RDS Was Created with Terraform

By now, you should have created the database instance with Terraform. Let’s verify by manually checking for the database instance in the AWS Management Console.

1. Open your favorite web browser and navigate to the AWS Management Console and log in.

2. While in the Console, click on the search bar at the top, search for RDS and click on the RDS menu item.

RDS
RDS

3. Once on the RDS page, click on DB Instances. You should see the DB instance created.

DB Instances
DB Instances

Below you can see that the mydb database instance has been successfully created!

mydb database instance created
mydb database instance created

If you dig in more, you’ll also see that the RDS instance has all of the same attributes as you had defined in your variables files.

  engine               = "mysql"
  engine_version       = "5.7"
  instance_class       = "db.t3.micro"
  name                 = "mydb"
  username             = "user1"
  password             = "password"
  parameter_group_name = "default.mysql5.7"

Conclusion

In this tutorial, you learned how to create your first database using Terraform and AWS RDS using the most widely used automation tool, Terraform.

Now that you have a database created on the AWS RDS, what do you plan to store in your newly created database?

Subscribe to Stay in Touch

Never miss out on your favorite ATA posts and our latest announcements!

Looks like you're offline!