This document explains how to deploy an AWS RDS instance using Terraform. It includes a primary RDS instance with high availability across multiple availability zones and a read replica for increased read scalability. The setup also covers creating a VPC, subnets in three availability zones, an Internet Gateway, and routing for internet access.
Here are some quick video walkthroughs to help you get started with the project:
Get an overall understanding of the project and how each part ties together in this comprehensive walkthrough.
In this video, I walk you through the process of setting up your RDS instances using Terraform.
This video covers how to create a blue/green deployment for your RDS instances using the AWS CLI.
The setup is divided into two main parts:
-
RDS Setup: Managed in the
rds.tf
file, it includes a primary RDS instance with a standby in another availability zone for high availability, and a read replica in a third availability zone for scalability. -
Network Setup: Configured in the
vpc.tf
file, it includes a VPC with three subnets in different availability zones, an Internet Gateway for internet access, and routing configurations.
-
RDS Architecture
rds.tf
creates the RDS setup, including the primary instance, standby instance, and read replica. It also sets up a custom parameter group for writable green deployments, important for schema updates. -
VPC and Network Architecture
vpc.tf
manages the VPC setup, including the subnets, Internet Gateway, and their connections.
Before starting with the deployment process, you need to have Terraform and AWS CLI installed on your machine. Additionally, ensure that you have configured AWS CLI with your credentials and set the default region to us-east-1.
-
To install Terraform, follow the instructions on the official Terraform website.
-
For AWS CLI installation and initial setup, refer to the official AWS CLI documentation.
You'll need an AWS Access Key ID and Secret Access Key. Here's how to set them as environment variables:
Open a terminal and run these commands, replacing the placeholders with your actual credentials:
export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY_ID" export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_ACCESS_KEY"
If you specifically want to set or change the default region to us-east-1 for AWS CLI, you can do so by editing the AWS CLI configuration file directly or by running the configure command again:
aws configure set default.region us-east-1
This sets the default region for AWS CLI commands to us-east-1, ensuring that all operations you perform with AWS CLI and Terraform will target the US East (N. Virginia) region, unless otherwise specified.
- Clone this repository to your local machine to get started.
- Navigate to the project directory in your terminal. This is where you've cloned the repository. Run the following command to initialize the Terraform environment:
terraform init
- To see what Terraform plans to do before making any changes to your actual resources, run:
terraform plan
- If everything looks good, apply the changes by running:
terraform apply
- You will be prompted to confirm the action. Type yes to proceed.
After your infrastructure is set up with Terraform, you're ready to manage a blue-green deployment for your RDS instance. This process involves creating a new version of your database (the "green" environment) while keeping the old version (the "blue" environment) running. Eventually, you'll switch over to the "green" environment. Here's how to do it using the AWS CLI:
From the Terraform output, you'll need the ARN (Amazon Resource Name) of your primary RDS instance. This ARN uniquely identifies your "blue" environment's database instance. When you run terraform output -json
, look for the primary_db_arn
value. It should look something like this:
"primary_db_arn": {
"value": "arn:aws:rds:us-east-1:123456789:db:primary-instance"
}
With the ARN of your primary database instance, you're going to create a new deployment. This involves specifying a few parameters:
--blue-green-deployment-name
: A name for your blue-green deployment. This helps you identify it later.--source
: The ARN of your "blue" environment's database instance. This is what you identified inStep 1
.--target-engine-version
: The version of the database engine for the "green" environment.--target-db-parameter-group-name
: The name of the DB parameter group for the "green" environment. The value we need to set is the name of parameter group we created using Terraform (rds-allow-write
).
Here's how you use these parameters in the command:
aws rds create-blue-green-deployment \
--blue-green-deployment-name my-blue-green-deployment \
--source "arn:aws:rds:us-east-1:123456789:db:primary-instance" \
--target-engine-version "8.0.36" \
--target-db-parameter-group-name "rds-allow-write"
In this command, replace arn:aws:rds:us-east-1:123456789:db:primary-instance
with the actual ARN you got from the Terraform output.
Run the above command in your terminal. It will start the process of creating your "green" environment. The command will output information in JSON format, including a BlueGreenDeploymentIdentifier
. This identifier is crucial for the next steps, especially when you're ready to switch over to the "green" environment.
After your "green" environment is set up and ready, the next step is to switch over from the "blue" environment. This process involves using the AWS CLI to initiate the switchover, utilizing the BlueGreenDeploymentIdentifier
you received from creating the blue-green deployment.
When you created the blue-green deployment, the AWS CLI command output included a BlueGreenDeploymentIdentifier
. You need this identifier for the switchover process. It looks something like this in the command output:
{
"BlueGreenDeployment": {
"BlueGreenDeploymentIdentifier": "bgd-01abcdefg23456789",
...
}
}
Copy the BlueGreenDeploymentIdentifier
value (bgd-01abcdefg23456789
in this example).
With the BlueGreenDeploymentIdentifier
, you're ready to initiate the switchover. The AWS CLI command for this operation requires the following parameters:
--blue-green-deployment-identifier
: The identifier of the blue-green deployment you're switching over.--switchover-timeout
: The amount of time, in seconds, AWS RDS should wait for the switchover to complete before timing out. Here's the command structure:
aws rds switchover-blue-green-deployment \
--blue-green-deployment-identifier bgd-01abcdefg23456789 \
--switchover-timeout 600
Replace bgd-01abcdefg23456789
with your actual BlueGreenDeploymentIdentifier
.
Run the prepared command in your terminal. This command tells AWS RDS to start the process of switching your database connections from the "blue" environment to the "green" environment.
You can monitor the progress of the switchover in the AWS Management Console or by using additional AWS CLI commands to query the status of your blue-green deployment. It's crucial to ensure the switchover completes successfully and that your "green" environment is fully operational.