Repository files navigation

NOTE: This repo contains only the documentation for the private BoltsOps Pro repo code.Original file:https://github.com/boltopspro/aurora-serverless/blob/master/README.mdThe docs are publish so they are available for interested customers.For access to the source code, you must be a paying BoltOps Pro subscriber.If are interested, you can contact us atcontact@boltops.com orhttps://www.boltops.com

This blueprint provisions a RDS Aurora Serverless Database Cluster.

• AutoScaling settings are configured with Parameters.
• Storage is encrypted by default.
• A managed DB Subnet Group can be created by configuringSubnetIds. Or you can use an existingDBSubnetGroupName.
• Can create an optional managed Route53 records that point to the cluster endpoint.
• Cluster Parameters can be configured with code.
• For a standard RDS Database, refer to theRDS Blueprint. You might also be interested in theaurora blueprint.

1. Add blueprint to Gemfile
2. Configure: configs/aurora-serverless values
3. Deploy blueprint

Add the blueprint to your lono project'sGemfile.

gem"aurora-serverless",git:"git@github.com:boltopspro/aurora-serverless.git"

Use thelono seed command to generate a starter config params files.

LONO_ENV=development lono seed aurora-serverlessLONO_ENV=production  lono seed aurora-serverless

The files inconfig/aurora-serverless folder will look something like this:

configs/aurora-serverless/├── params│   ├── development.txt│   └── production.txt└── variables    ├── development.rb    └── production.rb

Configure theconfigs/aurora-serverless/params andconfigs/aurora-serverless/variables files. The parameters required:MasterUsername,MasterUserPassword, andVpcId. Example:

configs/aurora-serverless/params/development.txt:

MasterUsername=myuserMasterUserPassword=mypasswordVpcId=vpc-111

Use thelono cfn deploy command to deploy.

LONO_ENV=development lono cfn deploy aurora-serverless --sure --no-waitLONO_ENV=production  lono cfn deploy aurora-serverless --sure --no-wait

It takes about 15m to deploy the aurora-serverless DB instance. Times may vary.

If you are using One AWS Account, use these commands instead:One Account.

TheEngine,EngineVersion,ClusterParameterGroupFamily,DBInstanceClass parameters must be a valid combination.

A managed DB Parameter Group is also created based on theClusterParameterGroupFamily parameter and@cluster_parameter_group_parameters variable.@cluster_parameter_group_parameters must contain at least 1 parameter value. Here's a table with tested example values:

Each particular database engine is different and has its own configuration values. Refer to each databases's docs to find out what you can set. Here are some useful docs:

• Database Engine Versions for Amazon Aurora PostgreSQL
• How do I change the time zone of my Amazon RDS DB instance?
• Choosing the DB Instance Class

You can also configure theScalingConfiguration with parameters. Example:

configs/aurora-serverless/params/development.txt:

AutoPause=trueMaxCapacity=16MinCapacity=2SecondsUntilAutoPause=300

You must also provide eitherDBSubnetGroupName orSubnetIds. Only provide only one, not both.

By Providing theSubnetIds parameter only the blueprint will create a managedAWS::RDS::DBSubnetGroup resource in the same custom VPC. Example:

VpcId=vpc-111SubnetIds=subnet-111,subnet-222

It is recommended to run the database in a private data subnet. Thereference-architecturevpc blueprint is has aPrivateDBSubnetGroup db subnet group contains the private subnets. A quick way to get the VPC and subnet values is from the VPC CloudFormation Outputs. Here's an example of the development VPC.

If you are not using the reference architecture and you do not have a Db Subnet Group, specifyingSubnetIds will create aAWS::RDS::DBSubnetGroup for you.

To assign existing security groups to the RDS database useVpcSecurityGroupIds. Example:

VpcSecurityGroupIds=sg-111,sg-222

If not set, then the blueprint will create and a managed Security Group and assign it to the RDS database.

It is recommended to use a Private HostedZone to create a pretty endpoint for the DBCluster Endpoint. Example:

DnsName=dbcluster.private.HostedZoneName=private.

SeveralAWS::RDS::DBCluster properties are configurable withParameters. Properties that are not configurable with Parameters are configured withVariables. The@cluster_properties variable allows you to override any property. Example:

@cluster_properties={port:3306,character_set_name:"utf8_unicode_ci",}

The blueprint is written so that Variables take higher precedence than Parameters.

Using CloudFormation to provision RDS databases has some pros and cons.

• The main pro is that the infrastructure is codified and reproducible.
• The main con is that CloudFormation canreplace your database entirely, and you'll lose your data!

Depending on theAWS::RDS::Instance property property that is changed, CloudFormationreplaces the database entirely. You have to look for "Update requires: Replacement". This is dangerously easy to forget.

An excellent way to provide a guard rail against accidental replacement is to set theDBClusterIdentifier parameter. If you change any property that requires replacement, then the CloudFormation stack update will immediately fail, because RDS won't be able to create another database with the sameDBClusterIdentifier.

Another technique you can use to prevent an accidental replacement is only to use CloudFormation for the initial provisioning of the database. Afterward, you'll modify the RDS DB with the API or Console only. Yet another way to provide a guard rail is to enableDeletionProtection=true. This prevents the current database from being deleted. However, it deletion happens as part of the CloudFormation cleanup step, so it takes longer for the rollback to finish.