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!
Not a reader? Watch this related video tutorial!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:
- An Amazon Web Service (AWS) account.
- A code editor – Even though you can use any text editor to work with Terraform configuration files, you should consider Visual Studio (VS) Code as it understands the HCL Terraform language well.
- Terraform – This tutorial will use Terraform v0.14.9 running on Ubuntu 18.04.5 LTS, but any operating system with Terraform should work.
- Terraform authenticated to your AWS account
Building the Terraform and 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-demo2. 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
user1with a password ofpassword
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.
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 initIf all goes well, you should see the message Terraform has been successfully initialized in the output, as shown below.
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
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 applyAs you can see below Terraform has successfully created the database instance in the AWS account using Terraform.
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.
3. Once on the RDS page, click on DB Instances. You should see the DB instance created.
Below you can see that the mydb database instance has been successfully 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?
